source/developer-guide/introduction/Conventions.html - sis-site - Git at Google

 <?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE html>

 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   <head>
     <title>Conventions</title>
     <meta charset="UTF-8"/>
     <link rel="stylesheet" type="text/css" href="../book.css"/>
   </head>
   <body>
     <!--
       Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
       by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
     -->
     <section>
       <header>
         <h2 id="Conventions">Typographic and naming conventions</h2>
       </header>
       <p>
         The elements defined in a computer language, such as classes and methods in Java or elements in an <abbr>XML</abbr> document,
         appear in monospaced font in this document.
         In order to facilitate an understanding of the relationships between Apache <abbr>SIS</abbr> and the standards,
         these elements are also represented using the following colour codes:
       </p>
       <ul>
         <li>
           Elements in blue are defined in an <abbr title="International Organization for Standardization">ISO</abbr>
           or <abbr title="Open Geospatial Consortium">OGC</abbr> standard other than GeoAPI.
         </li>
         <li>
           Elements in green are Java element defined in GeoAPI.
         </li>
         <li>
           Elements in brown are defined in Apache <abbr title="Spatial Information System">SIS</abbr>.
         </li>
         <li>
           Elements left in black are either defined elsewhere (for example the standard Java library),
           or there is simply no emphasis on that element for the discussion.
         </li>
       </ul>
       <p>
         For example to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>),
         <code class="OGC">SC_ProjectedCRS</code> is an <abbr>UML</abbr> and <abbr>XML</abbr> element defined by the <abbr>ISO</abbr> 19111 standard.
         Then <code class="GeoAPI">org.opengis.referencing.crs.<b>ProjectedCRS</b></code> is the implementation-neutral GeoAPI interface derived from that standard,
         and <code class="SIS">org.apache.sis.referencing.crs.<b>DefaultProjectedCRS</b></code> is the implementation class provided by Apache SIS.
       </p><p>
         Apache SIS implements most GeoAPI interfaces by a classes of the same name than the interface
         but prefixed by <code>Abstract</code>, <code>Default</code> or <code>General</code> word.
         The <code>General</code> prefix is sometimes used instead of <code>Default</code>
         to indicate that alternative implementations are available for some specific cases.
         For example the <code class="GeoAPI">Envelope</code> interface is implemented by at least two Apache SIS classes:
         <code class="SIS">GeneralEnvelope</code> and <code class="SIS">Envelope2D</code>.
         The first implementation can represent envelopes with any number of dimensions
         while the second implementation is specialized for two-dimensional envelopes.
       </p><p>
         Apache SIS classes prefixed by <code>Abstract</code> should not (in principle) be instantiated.
         Users should instantiate a non-abstract subclass instead.
         However many <abbr>SIS</abbr> classes are only conceptually abstract,
         without <code>abstract</code> Java keyword in class definition.
         Such classes can be instantiated by a <code>new AbstractXXX(…)</code> statement despite being conceptually abstract.
         Such instantiations should be avoided, but are nevertheless permitted in last resort when it is not possible to determine the exact subtype.
       </p>
       <p>
         Text in gray boxes, like below (click to expand), are for information purpose only and can be ignored.
       </p>
       <details>
         <summary>Note about the definition of terms</summary>
         <article id="ChosenTerms">
           <header>
             <h2>Source of term definitions</h2>
           </header>
           <p>
             Standards sometimes favour the application of certain generic terms to particular contexts,
             which may differ from the context in which other communities use these terms.
             For example, the terms <i>domain</i> and <i>range</i> may apply to arbitrary mathematical functions in order to designate
             a set of possible values of inputs and outputs respectively.
             The <abbr>ISO</abbr> 19123 standard applies these terms to <code>CV_Coverage</code> objects,
             seen as functions in which the <i>domain</i> is the set of spatio-temporal coordinates encompassed by the data,
             and the <i>range</i> is the set of values encompassed.
           </p><p>
             However the functions to which above terms are applied by <abbr>ISO</abbr> standards are not the same as the functions to which they are applied by other libraries.
             For example <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>’s <abbr title="Network Common Data Form">netCDF</abbr> library
             applies these terms instead to the function for converting pixel indices (its <i>domain</i>) to spatial-temporal coordinates (its <i>range</i>).
             Thus the <abbr>UCAR</abbr> library’s <i>range</i> may be the <i>domain</i> of <abbr>ISO</abbr> 19123.
           </p><p>
             The Apache <abbr>SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr>OGC</abbr> and <abbr>ISO</abbr> norms.
             Particular care must be taken, however, with the interfaces between <abbr>SIS</abbr> and certain other external libraries,
             in order to reduce the risk of confusion.
           </p>
         </article>
       </details>
     </section>
   </body>
 </html>
	<?xml version="1.0" encoding="UTF-8" ?>
	<!DOCTYPE html>

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<title>Conventions</title>
	<meta charset="UTF-8"/>
	<link rel="stylesheet" type="text/css" href="../book.css"/>
	</head>
	<body>
	<!--
	Content below this point is copied in "/asf-staging/book/en/developer-guide.html" file
	by the `org.apache.sis.internal.book.Assembler` class in `sis-build-helper` module.
	-->
	<section>
	<header>
	<h2 id="Conventions">Typographic and naming conventions</h2>
	</header>
	<p>
	The elements defined in a computer language, such as classes and methods in Java or elements in an <abbr>XML</abbr> document,
	appear in monospaced font in this document.
	In order to facilitate an understanding of the relationships between Apache <abbr>SIS</abbr> and the standards,
	these elements are also represented using the following colour codes:
	</p>
	<ul>
	<li>
	Elements in blue are defined in an <abbr title="International Organization for Standardization">ISO</abbr>
	or <abbr title="Open Geospatial Consortium">OGC</abbr> standard other than GeoAPI.
	</li>
	<li>
	Elements in green are Java element defined in GeoAPI.
	</li>
	<li>
	Elements in brown are defined in Apache <abbr title="Spatial Information System">SIS</abbr>.
	</li>
	<li>
	Elements left in black are either defined elsewhere (for example the standard Java library),
	or there is simply no emphasis on that element for the discussion.
	</li>
	</ul>
	<p>
	For example to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>),
	<code class="OGC">SC_ProjectedCRS</code> is an <abbr>UML</abbr> and <abbr>XML</abbr> element defined by the <abbr>ISO</abbr> 19111 standard.
	Then <code class="GeoAPI">org.opengis.referencing.crs.<b>ProjectedCRS</b></code> is the implementation-neutral GeoAPI interface derived from that standard,
	and <code class="SIS">org.apache.sis.referencing.crs.<b>DefaultProjectedCRS</b></code> is the implementation class provided by Apache SIS.
	</p><p>
	Apache SIS implements most GeoAPI interfaces by a classes of the same name than the interface
	but prefixed by <code>Abstract</code>, <code>Default</code> or <code>General</code> word.
	The <code>General</code> prefix is sometimes used instead of <code>Default</code>
	to indicate that alternative implementations are available for some specific cases.
	For example the <code class="GeoAPI">Envelope</code> interface is implemented by at least two Apache SIS classes:
	<code class="SIS">GeneralEnvelope</code> and <code class="SIS">Envelope2D</code>.
	The first implementation can represent envelopes with any number of dimensions
	while the second implementation is specialized for two-dimensional envelopes.
	</p><p>
	Apache SIS classes prefixed by <code>Abstract</code> should not (in principle) be instantiated.
	Users should instantiate a non-abstract subclass instead.
	However many <abbr>SIS</abbr> classes are only conceptually abstract,
	without <code>abstract</code> Java keyword in class definition.
	Such classes can be instantiated by a <code>new AbstractXXX(…)</code> statement despite being conceptually abstract.
	Such instantiations should be avoided, but are nevertheless permitted in last resort when it is not possible to determine the exact subtype.
	</p>
	<p>
	Text in gray boxes, like below (click to expand), are for information purpose only and can be ignored.
	</p>
	<details>
	<summary>Note about the definition of terms</summary>
	<article id="ChosenTerms">
	<header>
	<h2>Source of term definitions</h2>
	</header>
	<p>
	Standards sometimes favour the application of certain generic terms to particular contexts,
	which may differ from the context in which other communities use these terms.
	For example, the terms <i>domain</i> and <i>range</i> may apply to arbitrary mathematical functions in order to designate
	a set of possible values of inputs and outputs respectively.
	The <abbr>ISO</abbr> 19123 standard applies these terms to <code>CV_Coverage</code> objects,
	seen as functions in which the <i>domain</i> is the set of spatio-temporal coordinates encompassed by the data,
	and the <i>range</i> is the set of values encompassed.
	</p><p>
	However the functions to which above terms are applied by <abbr>ISO</abbr> standards are not the same as the functions to which they are applied by other libraries.
	For example <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>’s <abbr title="Network Common Data Form">netCDF</abbr> library
	applies these terms instead to the function for converting pixel indices (its <i>domain</i>) to spatial-temporal coordinates (its <i>range</i>).
	Thus the <abbr>UCAR</abbr> library’s <i>range</i> may be the <i>domain</i> of <abbr>ISO</abbr> 19123.
	</p><p>
	The Apache <abbr>SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr>OGC</abbr> and <abbr>ISO</abbr> norms.
	Particular care must be taken, however, with the interfaces between <abbr>SIS</abbr> and certain other external libraries,
	in order to reduce the risk of confusion.
	</p>
	</article>
	</details>
	</section>
	</body>
	</html>