Modified: sis/site/trunk/content/book/en/developer-guide.html URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/en/developer-guide.html?rev=1814367&r1=1814366&r2=1814367&view=diff ============================================================================== --- sis/site/trunk/content/book/en/developer-guide.html [UTF-8] (original) +++ sis/site/trunk/content/book/en/developer-guide.html [UTF-8] Sun Nov 5 18:04:55 2017 @@ -1,16 +1,15 @@ -<?xml version="1.0" encoding="UTF-8"?> +<?xml version="1.0" encoding="UTF-8" standalone="no"?><!-- -<!-- Licensed to the Apache Software Foundation (ASF) http://www.apache.org/licenses/LICENSE-2.0 This is an automatically generated file. DO NOT EDIT. See the files in the ../../../book/ directory instead. ---> -<!DOCTYPE html> +--><!DOCTYPE html SYSTEM "about:legacy-compat"> <html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en"> + <head> <title>Introduction to Apache SIS</title> <meta charset="UTF-8"/> @@ -30,8 +29,6 @@ Partially translated by <i>Christina Hou <li><a href="#Standards">Standards and norms</a><ul> <li><a href="#ConceptualModels">Sources of conceptual models used by Apache SIS</a></li> <li><a href="#GeoAPI">From conceptual models to Java interfaces: GeoAPI</a><ul> -<li><a href="#UML-annotation">Explicit mapping given by @UML annotations</a></li> -<li><a href="#MappingToJDK">Implicit mapping to standard JDK</a></li> <li><a href="#GeoAPI-implementation">Implementations provided by Apache SIS</a></li></ul></li> <li><a href="#AboutBook">Conventions used in this guide</a><ul> <li><a href="#CodeColors">Code colors</a></li></ul></li></ul></li> @@ -80,20 +77,25 @@ Partially translated by <i>Christina Hou <li><a href="#Locale.ROOT">Locale.ROOT convention</a></li> <li><a href="#UnicodePoint">Treatment of characters</a><ul> <li><a href="#Whitespaces">Blank spaces interpretation</a></li></ul></li></ul></li></ul></li> -<li><a href="#Annexes">Annexes</a><ul> +<li><a href="#GeoAPI-details">GeoAPI relationship with standards</a><ul> +<li><a href="#GeoAPI-modules">GeoAPI modules</a></li> +<li><a href="#SpecificationToInterfaces">From OGC specifications to Java interfaces</a><ul> +<li><a href="#UML-annotation">Explicit mapping given by @UML annotations</a></li> +<li><a href="#MappingToJDK">Implicit mapping to standard JDK</a></li></ul></li> <li><a href="#ReduceDependency">Reduce direct dependency to Apache SIS</a><ul> <li><a href="#UML-annotation-indep">Mapping given by @UML annotations</a></li> <li><a href="#ServiceLoader">Fetching implementations of GeoAPI interfaces</a><ul> -<li><a href="#GeoAPI-simple">Defining custom implementations</a></li></ul></li></ul></li> +<li><a href="#GeoAPI-simple">Defining custom implementations</a></li></ul></li></ul></li></ul></li> <li><a href="#Tests">Test suites</a><ul> +<li><a href="#GeoAPI-conformance">GeoAPI conformance</a><ul> <li><a href="#GeoAPI-validators">Instance validations</a></li> -<li><a href="#GeoAPI-tests">Executing pre-defined tests</a></li></ul></li> +<li><a href="#GeoAPI-tests">Executing pre-defined tests</a></li></ul></li></ul></li> <li><a href="#DesignNotes">Design notes</a><ul> <li><a href="#AffineTransform">Affine transform</a><ul> <li><a href="#AffineTransformAPI">Integration with graphical libraries</a></li></ul></li> <li><a href="#MatrixLibrary">Specificities of a matrix library for GIS</a><ul> <li><a href="#NonSquareMatrix">What to do with non-square matrices (and why)</a></li> -<li><a href="#MatrixLibrarySummary">Apache SIS matrix library</a></li></ul></li></ul></li></ul></li> +<li><a href="#MatrixLibrarySummary">Apache SIS matrix library</a></li></ul></li></ul></li> </ul> </nav> @@ -108,6 +110,8 @@ Partially translated by <i>Christina Hou + + <section> <header> <h1 id="Standards"><span class="section-number">1.</span> Standards and norms</h1> @@ -116,8 +120,6 @@ Partially translated by <i>Christina Hou <nav>In this chapter:<ul class="toc"> <li><a href="#ConceptualModels">Sources of conceptual models used by Apache SIS</a></li> <li><a href="#GeoAPI">From conceptual models to Java interfaces: GeoAPI</a><ul> -<li><a href="#UML-annotation">Explicit mapping given by @UML annotations</a></li> -<li><a href="#MappingToJDK">Implicit mapping to standard JDK</a></li> <li><a href="#GeoAPI-implementation">Implementations provided by Apache SIS</a></li></ul></li> <li><a href="#AboutBook">Conventions used in this guide</a><ul> <li><a href="#CodeColors">Code colors</a></li></ul></li></ul></nav> @@ -437,12 +439,6 @@ Finally, GeoAPI packages will be introdu <td/> <td><code class="SIS">org.apache.sis.io.wkt</code></td> </tr><tr> -<td><abbr>ISO</abbr> 13249</td> -<td/> -<td><i><abbr>SQL</abbr> spatial</i></td> -<td/> -<td/> -</tr><tr> <td/> <td><s><abbr>OGC</abbr> 01-009</s></td> <td><s><i>Coordinate Transformation Services</i></s></td> @@ -456,6 +452,24 @@ Finally, GeoAPI packages will be introdu <td><code class="SIS">org.apache.sis.coverage</code></td> </tr><tr> <td/> +<td><abbr>OGC</abbr> 10-092</td> +<td><i>NetCDF binary encoding: classic and 64-bit offset format</i></td> +<td/> +<td><code class="SIS">org.apache.sis.storage.netcdf</code></td> +</tr><tr> +<td/> +<td><abbr>OGC</abbr> 14-084</td> +<td><i>Moving features Comma Separated Values (CSV) encoding</i></td> +<td/> +<td><code class="SIS">org.apache.sis.storage</code></td> +</tr><tr> +<td><abbr>ISO</abbr> 13249</td> +<td/> +<td><i><abbr>SQL</abbr> spatial</i></td> +<td/> +<td/> +</tr><tr> +<td/> <td><abbr>SLD</abbr></td> <td><i>Styled Layer Descriptor</i></td> <td><code class="GeoAPI">org.opengis.style</code></td> @@ -603,541 +617,134 @@ This version was the first to be deploye </article> </details> -<p>GeoAPI interfaces are sometime generated from other files provided by <abbr>OGC</abbr>, like <abbr title="XML Schema Definition">XSD</abbr> files. -But there is always a manual revision, and often modifications compared to automatically generated Java files. -Deviations from the standards are documented in each affected class and method. -Each mention of a deviation is also collected on a <a href="http://www.geoapi.org/3.0/javadoc/departures.html";>single page</a> in order to provide an overview. -Since these deviations blur the relationships between the standards and certain Java interfaces, -the correspondence between these languages is explained by <code class="GeoAPI">@UML</code> annotations and property files described in the following section. +<p id="GeoAPI-core"> +GeoAPI is composed of many modules. +The <code class="GeoAPI">geoapi</code> and <code class="GeoAPI">geoapi-pending</code> modules +provide interfaces derived from <abbr title="Unified Modeling Language">UML</abbr> schemas of international standards. +The conceptual model will be explained in detail in the chapters describing Apache <abbr title="Spatial Information System">SIS</abbr> implementation. +However, we can get an overview of its content by consulting the page listing the mapping between +<a href="http://www.geoapi.org/3.0/javadoc/content.html";>GeoAPI methods and the standards where they come from</a>. +Those modules and the mapping between GeoAPI and international standards are described in more details <a href="#SpecificationToInterfaces">in annex</a>. </p> -<details> -<summary>More about the reasons for manual definition of Java interfaces</summary> -<article id="SpecificationToInterfaces"> + + +<h3 id="GeoAPI-implementation"><span class="section-number">1.2.1.</span> Implementations provided by Apache SIS</h3> +<p> +Apache SIS implements most GeoAPI interfaces by a class of the same name than the interface +but prefixed by “<code>Abstract</code>”, “<code>Default</code>” or “<code>General</code>”. +Apache SIS classes prefixed by “<code>Default</code>” can be instantiated directly by a +<code>new DefaultXXX(…)</code> statement or by a call to the <code>createXXX(…)</code> method in a factory. +</p> +<div class="example"><b>Example:</b> to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>): +<ul> +<li><code class="GeoAPI">org.opengis.referencing.crs.ProjectedCRS</code> is the GeoAPI interface derived from ISO 19111 standard, and</li> +<li><code class="SIS">org.apache.sis.referencing.crs.DefaultProjectedCRS</code> is the implementation provided by Apache SIS.</li> +</ul> +An instance can be created by: +<ul> +<li><code>ProjectedCRS crs = new DefaultProjectedCRS(…)</code>, ou</li> +<li><code>ProjectedCRS crs = CRSFactory.createProjectedCRS(…)</code>.</li> +</ul> +Both approaches expect the same arguments (omitted in this example for brevity). +</div> +<p> +In the default Apache SIS configuration, using <code class="GeoAPI">CRSFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code> +is almost the same except that <code class="GeoAPI">Factory</code> may return existing instances instead than creating new instances, +and that exceptions thrown in case of invalid arguments are different types. +In more advanced configurations, using <code class="GeoAPI">Factory</code> reduces the +<a href="#ServiceLoader">direct dependencies toward Apache SIS</a> +and allows inversion of control. +</p><p> +The “<code>General</code>” prefix is sometime used instead than “<code>Default</code>” +to indicate that alternative implementations are available for some specific cases. +For example the <code>Envelope</code> interface is implemented by at least two Apache SIS classes: +<code class="SIS">GeneralEnvelope</code> and <code>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. +But many SIS 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 +– but not by <code class="GeoAPI">Factory</code> – despite being conceptually abstract. +However such instantiations should be done only in last resort, when it is not possible to determine the exact subtype. +</p> +</section> + + +<section> <header> -<h2>From <abbr title="Open Geospatial Consortium">OGC</abbr> specifications to Java interfaces</h2> +<h2 id="AboutBook"><span class="section-number">1.3.</span> Conventions used in this guide</h2> </header> <p> -It is possible to automatically generate Java interfaces <abbr>OGC</abbr> standards using existing tools. -One of the most commonly-used approaches is to transform <a href="http://schemas.opengis.net/gml/3.3/";><abbr title="XML Schema Definition">XSD</abbr> schemas</a> -into Java interfaces using command line utility <code>xjc</code>. -As this utility is included in most Java distributions (it is one of the <a href="http://jaxb.java.net";><abbr>JAXB</abbr></a> tools), -this approach is favoured by many projects found on the Internet. -Other approaches use tools integrated into the Eclipse Development Environment, -which is based on <abbr title="Unified Modeling Language">UML</abbr> schemas rather than <abbr>XSD</abbr> ones. +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 functions in order to designate +a set of possible values of inputs and outputs respectively. +But the functions to which they are applied by certain <abbr>ISO</abbr> standards are not the same as the functions to which they are applied by other libraries. +For example, <abbr>ISO</abbr> 19123 applies these terms to <code class="OGC">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. +But <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 of 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> -A similar approach was attempted in the early days of the GeoAPI project, but was quickly abandoned. -We favor a manual approach for the following reasons: +The Apache <abbr title="Spatial Information System">SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr title="Open Geospatial Consortium">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> -<ul> -<li> + + + +<h3 id="CodeColors"><span class="section-number">1.3.1.</span> Code colors</h3> <p> -Some <abbr>XSD</abbr> schemas are much more verbose than the original <abbr>UML</abbr> schemas. -Converting from <abbr>XSD</abbr> schemas introduces — at least in the case of metadata — -almost double the number of interfaces actually defined by the standard, without adding any new features. -<abbr>XSD</abbr> schemas also define attributes specific to <abbr>XML</abbr> documents (<code class="OGC">id</code>, -<code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), that do not exist in the original <abbr>UML</abbr> diagrams, -and which we do not necessarily wish to expose in a Java <abbr title="Application Programming Interface">API</abbr>. -Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common. +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 order to facilitate an understanding of the relationships between Apache <abbr title="Spatial Information System">SIS</abbr> and the standards, these elements are also represented using the following colour codes: </p> -<div class="example"><p><b>Example:</b> -<abbr>XSD</abbr> metadata schemas insert a <code class="OGC"><gmd:CI_Citation></code> element -inside a <code class="OGC"><gmd:citation></code>, -a <code class="OGC"><gmd:CI_OnlineResource></code> element inside a <code class="OGC"><gmd:onlineResource></code>, -and so on for the hundreds of classes defined by <abbr>ISO</abbr> 19115 standard. -This redundancy is certainly not necessary in a Java program. -</p></div> -</li> +<ul> <li> -<p> -<abbr>OGC</abbr> standards use different naming conventions than Java. -In particular, the names of almost all <abbr>OGC</abbr> classes begin with a two-letter prefix, -such as <code class="OGC">MD_Identifier</code>. -This prefixes fulfill the same role as package names in Java. -GeoAPI adapts this practice by using interface names without prefixes and placing these interfaces in packages corresponding to the prefixes, -but with more descriptive names. -Occasionally we also change the names; for example, to avoid acronyms, or to conform to an established convention such as JavaBeans. -</p> -<div class="example"><p><b>Example:</b> -The <abbr>OGC</abbr> class <code class="OGC">MD_Identifier</code> becomes the -<code class="GeoAPI">Identifier</code> interface in the <code class="GeoAPI">org.opengis.metadata</code> package. -The <abbr>OGC</abbr> class <code class="OGC">SC_CRS</code> becomes the <code class="GeoAPI">CoordinateReferenceSystem</code> interface, -and the <code class="OGC">usesDatum</code> association becomes a <code class="GeoAPI">getDatum()</code> method, -rather than the “<code>getUsesDatum()</code>” that would result from an automatic conversion tool. -We do not allow programs to blindly apply rules that ignore the conventions of the community whose schemas we translate. -</p></div> +Elements defined in the <abbr title="Open Geospatial Consortium">OGC</abbr> standard +or the <abbr title="International Organization for Standardization">ISO</abbr> standard appear in blue. +Example: <code class="OGC">CD_Ellipsoid</code>. </li> <li> -<p> -The standards may contain structures that do not have a direct equivalent in Java, -such as unions similar to what we would find in C/C++. -The strategy used to obtain an equivalent feature in Java depends on the context: -multiple inheritance of interfaces, modification of the hierarchy, or simply omitting the union. -These decisions are made case-by-case based on a needs analysis. -</p> -<div class="example"><p><b>Example:</b> -<abbr>ISO</abbr> 19111 standard defines different types of coordinate systems, such as spherical, cylindrical, polar or Cartesian. -It then defines several <em>subsets</em> of these types of coordinate systems systems. -These subsets, represented by unions, serve to specify that a class may only be associated with a particular type of coordinate system. -For example, a union of types may be associated with an image, named <code class="OGC">CS_ImageCS</code>, -which can only contain <code class="OGC">CS_CartesianCS</code> and <code class="OGC">CS_AffineCS</code>. -In this case, we get the desired effect in Java through a modification of the hierarchy of classes: -we define the <code class="GeoAPI">CartesianCS</code> interface as a specialization of <code class="GeoAPI">AffineCS</code>, -which is semantically correct. -But it is not possible to apply a similar strategy to other unions without violating the semantics. -</p></div> +Elements defined in GeoAPI appear in green. +Example: <code class="GeoAPI">Ellipsoid</code>. </li> <li> -<p> -Several specifications overlap. -GeoAPI performs the work of integration by replacing some duplicate structures with references to equivalent structures from the standards that best represent them. -</p> -<div class="example"><p><b>Example:</b> -<abbr>ISO</abbr> 19115:2003 standard, which defines metadata structures, -also attempts to describe a few structures representing coordinate reference systems (<abbr title="Coordinate Reference System">CRS</abbr>). -Yet these are also the focus of another standard: <abbr>ISO</abbr> 19111. -At the same time, <abbr>ISO</abbr> 19111:2007 states in section 3 that it reuses all of the elements of -<abbr>ISO</abbr> 19115:2003 except <code class="OGC">MD_CRS</code> and its components. -GeoAPI interfaces reduce the redundancy by applying the exclusion recommended by <abbr>ISO</abbr> 19111 to the entire project. -</p></div> +Elements defined in Apache <abbr title="Spatial Information System">SIS</abbr> appear in brown. +Example: <code class="SIS">DefaultEllipsoid</code>. </li> <li> -<p> -The complexity of some standards have increased for historical reasons rather than technical ones, related to the standardization process. -GeoAPI reduces the technical debt by designing interfaces with each element in its proper place, -regardless of the chronological order in which the standards were published. -</p> -<div class="example"><p><b>Example:</b> -<abbr>ISO</abbr> 19115-2 standard is an extension of <abbr>ISO</abbr> 19115-1 standard, adding image metadata structures. -These metadata were defined in a separate standard because they were not yet ready when the first part of the standard was published. -As it was not possible for administrative reasons to add attributes to already-published classes, -the new attributes were added in a sub-class bearing almost the same name. -Thus, <abbr>ISO</abbr> 19115-2 defines the class <code class="OGC">MI_Band</code>, -which extends the class <code class="OGC">MD_Band</code> from <abbr>ISO</abbr> 19115-1 by adding attributes that would have appeared -directly in the parent class if there were ready on time. -In GeoAPI, we have chosen to “repair” these anomalies by fusing these two classes into a single interface. -</p></div> +Other elements, such as those in standard Java, are left in black. +Example: <code>String</code>. </li> </ul> -</article> -</details> - -<p id="GeoAPI-core"> -GeoAPI is composed of many modules. -The <code class="GeoAPI">geoapi</code> and <code class="GeoAPI">geoapi-pending</code> modules -provide interfaces derived from <abbr>UML</abbr> schemas of international standards. -The conceptual model will be explained in detail in the chapters describing Apache <abbr title="Spatial Information System">SIS</abbr> implementation. -However, we can get an overview of its content by consulting the page listing the mapping between -<a href="http://www.geoapi.org/3.0/javadoc/content.html";>GeoAPI methods and the standards where they come from</a>. +<p> +Text in gray boxes are for information purpose only and can be ignored. </p> +</section> +</section> -<details> -<summary>More about GeoAPI modules</summary> -<article id="GeoAPI-modules"> -<h2>GeoAPI modules</h2> + +<section> +<header> +<h1 id="DataAccess"><span class="section-number">2.</span> Geospatial data access</h1> +<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Standards">Previous chapter</a></div><div class="next-chapter"><a href="#Coverage">Next chapter</a> ➡</div></div></nav> +</header> +<nav>In this chapter:<ul class="toc"/></nav> <p> -The GeoAPI project consists of a standardized part (<code class="GeoAPI">geoapi</code>) -and an experimental part (<code class="GeoAPI">geoapi-pending</code>). -As these two parts are mutually exclusive, users must take care not to mix them in the same project. -This separation is guaranteed for all projects that depend only on the Maven central repository -(including the final versions of Apache <abbr title="Spatial Information System">SIS</abbr>), -as the <code class="GeoAPI">geoapi-pending</code> module is never deployed on this central repository. -By contrast, certain <abbr>SIS</abbr> development branches may depend on <code class="GeoAPI">geoapi-pending</code>. +<span style="color: red">TODO</span> </p> + <p> -GeoAPI modules are: -</p> -<ul> -<li><p> -<b><code class="GeoAPI">geoapi</code></b> — includes interfaces covered by the -<a href="http://www.opengeospatial.org/standards/geoapi";>GeoAPI standard of the <abbr title="Open Geospatial Consortium">OGC</abbr></a>. -The final versions of Apache <abbr>SIS</abbr> depend on this module. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-pending</code></b> — contains a -<em>copy</em> of all interfaces in the <code class="GeoAPI">geoapi</code> module -(not a dependence) with additions that have not yet been approved as an <abbr>OGC</abbr> standard. -Some additions appear in interfaces normally defined by the <code class="GeoAPI">geoapi</code> module, hence the need to copy them. -Apache <abbr>SIS</abbr>’s development branches <code>jdk7</code> and <code>jdk8</code> depend on this module, -but this dependence becomes a dependence on the <code class="GeoAPI">geoapi</code> standard module when the branches are merged to the trunk. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-conformance</code></b> — includes a JUnit test suite that developers may use to test their implementations. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-examples</code></b> — includes examples of relatively simple implementations. -These examples are placed in the public domain in order to encourage users to copy and adapt them to their needs if -Apache <abbr>SIS</abbr> services are unsuitable. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-proj4</code></b> — contains a partial implementation of <code class="GeoAPI">org.opengis.referencing</code> -packages as adaptors based on the C/C++ Proj.4 library. -This module may be used as an alternative to the <code class="SIS">sis-referencing</code> module for certain functions. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-netcdf</code></b> — contains a partial implementation of <code class="GeoAPI">org.opengis.referencing</code> -and <code class="GeoAPI">org.opengis.coverage</code> packages as adaptors based on the <abbr>UCAR</abbr> <abbr>NetCDF</abbr> library. -The series of tests in this module was developed in such a way as to be reusable for other projects. -Apache <abbr>SIS</abbr> uses them to test its own <code class="SIS">sis-netcdf</code> module. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-openoffice</code></b> — contains an add-in for the OpenOffice.org office suite. -</p></li> -</ul> -</article> -</details> - - - -<h3 id="UML-annotation"><span class="section-number">1.2.1.</span> Explicit mapping given by <code class="GeoAPI">@UML</code> annotations</h3> -<p> -For each class, method and constant defined by an <abbr title="Open Geospatial Consortium">OGC</abbr> or <abbr>ISO</abbr> standard, -GeoAPI indicates its provenance using annotations defined in the <code class="GeoAPI">org.opengis.annotation</code> package. -In particular, the <code class="GeoAPI">@UML</code> annotations indicates the standard, -the name of the element in that standard, and also its obligation. -For example, in the following code snippet, the first <code class="GeoAPI">@UML</code> code indicates that the Java interface that follows -(<code class="GeoAPI">ProjectedCRS</code>) is defined using the <code class="OGC">SC_ProjectedCRS</code> type of <abbr>ISO</abbr> 19111 standard. -The second <code class="GeoAPI">@UML</code> annotation, this time applied to the <code class="GeoAPI">getCoordinateSystem()</code> method, -indicates that this method is defined using the <code class="OGC">coordinateSystem</code> association of <abbr>ISO</abbr> 19111 standard, -and that this association is mandatory — meaning, in Java, that the method is not allowed to return a <code>null</code> value. -</p> - -<pre><code><b>package</b> <code class="GeoAPI">org.opengis.referencing.crs</code>; - -<code class="comment">/** - * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface. - */</code> -@<code class="GeoAPI">UML</code>(specification=ISO_19111, identifier=<i>"<code class="OGC">SC_ProjectedCRS</code>"</i>) -<b>public</b> <b>interface</b> <code class="GeoAPI">ProjectedCRS</code> <b>extends</b> <code class="GeoAPI">GeneralDerivedCRS</code> { - <code class="comment">/** - * Returns the coordinate system, which must be Cartesian. - */</code> - @<code class="GeoAPI">UML</code>(obligation=MANDATORY, specification=ISO_19111, identifier=<i>"<code class="OGC">coordinateSystem</code>"</i>) - <code class="GeoAPI">CartesianCS</code> <code class="GeoAPI">getCoordinateSystem()</code>; -}</code></pre> - -<p> -Java reflection methods allow access to this information during the execution of an application. -This is useful for displaying UML identifiers for users familiar with <abbr>OGC</abbr> standards, -or for writing elements in an <abbr>XML</abbr> document. -Class <code class="SIS">org.apache.sis.util.iso.Types</code> provides static convenience methods -like <code class="SIS">getStandardName(Class)</code> for such operations. -For example the following code will display -“Standard name of type <code class="GeoAPI">org.opengis.referencing.crs.ProjectedCRS</code> is <code class="OGC">SC_ProjectedCRS</code>”: -</p> - -<pre><code>Class<?> type = <code class="GeoAPI">ProjectedCRS</code>.<b>class</b>; -System.out.println(<i>"Standard name of type "</i> + type.getName() + <i>" is "</i> + Types.getStandardName(type));</code></pre> - -<p> -The <code class="SIS">Types.forStandardName(String)</code> convenience method performs the reverse operation. -Applications who want to perform those operations without SIS convenience methods can follow indications -provided in a <a href="#UML-annotation-geoapi">separated chapter</a>. -</p> - - - -<h3 id="MappingToJDK"><span class="section-number">1.2.2.</span> Implicit mapping to standard <abbr>JDK</abbr></h3> -<p> -Some classes and methods have neither an <code class="GeoAPI">@UML</code> annotation, nor an entry in the <code class="GeoAPI">class-index.properties</code> file. -They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>. -In this last case, the mapping to <abbr>ISO</abbr> standards is implicit. -The following table describes this mapping for <abbr>ISO</abbr> 19103 types. -Java’s primitive types are preferred when applicable, -but where necessary their wrappers are used in order to authorize null values. -</p> -<table> -<caption>Mapping between <abbr>ISO</abbr> 19103 and <abbr>JDK</abbr> types</caption> -<tr> -<th><abbr>ISO</abbr> type</th> -<th><abbr>JDK</abbr> type</th> -<th>Remarks</th> -</tr> -<tr> -<td class="separator" colspan="2">Numbers</td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Integer</code></td> -<td><code>int</code></td> -<td class="leftBorder">Sometimes <code>java.lang.Integer</code> for optional attributes.</td> -</tr> -<tr> -<td><code class="OGC">Integer</code> (in some cases)</td> -<td><code>long</code></td> -<td class="leftBorder">Sometimes <code>java.lang.Long</code> for optional attributes.</td> -</tr> -<tr> -<td><code class="OGC">Real</code></td> -<td><code>double</code></td> -<td class="leftBorder">Sometimes <code>java.lang.Double</code> for optional attributes.</td> -</tr> -<tr> -<td><code class="OGC">Decimal</code></td> -<td><code>java.math.BigDecimal</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Number</code></td> -<td><code>java.lang.Number</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td class="separator" colspan="2">Texts</td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">FreeText</code></td> -<td>(no equivalent)</td> -<td class="leftBorder">See <code class="GeoAPI">org.opengis.util.InternationalString</code> below.</td> -</tr> -<tr> -<td><code class="OGC">CharacterString</code></td> -<td><code>java.lang.String</code></td> -<td class="leftBorder">Often <code class="GeoAPI">org.opengis.util.InternationalString</code> (see below).</td> -</tr> -<tr> -<td><code class="OGC">LocalisedCharacterString</code></td> -<td><code>java.lang.String</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Sequence<Character></code></td> -<td><code>java.lang.CharSequence</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Character</code></td> -<td><code>char</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td class="separator" colspan="2">Dates and hours</td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Date</code></td> -<td><code>java.util.Date</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Time</code></td> -<td><code>java.util.Date</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">DateTime</code></td> -<td><code>java.util.Date</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td class="separator" colspan="2">Collections</td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Collection</code></td> -<td><code>java.util.Collection</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Bag</code></td> -<td><code>java.util.Collection</code></td> -<td class="leftBorder">A <code class="OGC">Bag</code> is similar to a -<code class="OGC">Set</code> without being restricted by uniqueness.</td> -</tr> -<tr> -<td><code class="OGC">Set</code></td> -<td><code>java.util.Set</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Sequence</code></td> -<td><code>java.util.List</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Dictionary</code></td> -<td><code>java.util.Map</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">KeyValuePair</code></td> -<td><code>java.util.Map.Entry</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td class="separator" colspan="2">Enumerations</td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Enumeration</code></td> -<td><code>java.lang.Enum</code></td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">CodeList</code></td> -<td>(no equivalent)</td> -<td class="leftBorder">See <code class="GeoAPI">org.opengis.util.CodeList</code> below.</td> -</tr> -<tr> -<td class="separator" colspan="2">Various</td> -<td class="leftBorder"/> -</tr> -<tr> -<td><code class="OGC">Boolean</code></td> -<td><code>boolean</code></td> -<td class="leftBorder">Sometimes <code>java.lang.Boolean</code> for optional attributes.</td> -</tr> -<tr> -<td><code class="OGC">Any</code></td> -<td><code>java.lang.Object</code></td> -<td class="leftBorder"/> -</tr> -</table> - -<p> -The nearest equivalent for <code class="OGC">CharacterString</code> is the <code>String</code> class, -but GeoAPI often uses the <code class="GeoAPI">InternationalString</code> interface, allowing the client to choose the language. -For example, it is useful on a server that simultaneously provides pages in multiple languages. -By returning translations when objects are used rather than at the time of their creation, -we allow the <abbr title="Spatial Information System">SIS</abbr> library to provide the same instances of <code class="GeoAPI">Metadata</code> -or <code class="GeoAPI">Coverage</code> (for example) for the same data, regardless of the client’s language. -Translations may be made on the fly with the help of the application’s <code>ResourceBundle</code>, -or may be provided directly with the data (as in the case of <code class="GeoAPI">Metadata</code>). -</p> -<p> -An <code class="OGC">Enumeration</code> corresponds to an <code>Enum</code> in Java. -Both define all authorized values, without allowing the user to add any. -A <code class="OGC">CodeList</code> is similar to an enumeration, except that users may add their own items. -Standard <abbr>JDK</abbr> does not offer this possibility. -GeoAPI defines an abstract <code class="GeoAPI">CodeList</code> class that reproduces some of the functionality of <code>Enum</code> while being extensible. -Extensions are made available by the <code class="GeoAPI">valueOf(String)</code> static method, which, in contrast to <code>Enum</code>, -creates new instances if the name provided does not correspond to the name of an existing instance. -</p> - -<pre><code><code class="GeoAPI">MediumName</code> cdRom = <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">CD_ROM;</code> -<code class="GeoAPI">MediumName</code> usbKey = <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">USB_KEY</code>"</i>); <code class="comment">// There is no constraint on this value. -</code><b>assert</b> <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">CD_ROM</code>"</i>) == cdRom : <i>"valueOf must return existing constants."</i>; -<b>assert</b> <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">USB_KEY</code>"</i>) == usbKey : <i>"valueOf must cache the previously requested values."</i>;</code></pre> - - - -<h3 id="GeoAPI-implementation"><span class="section-number">1.2.3.</span> Implementations provided by Apache SIS</h3> -<p> -Apache SIS implements most GeoAPI interfaces by a class of the same name than the interface -but prefixed by “<code>Abstract</code>”, “<code>Default</code>” or “<code>General</code>”. -Apache SIS classes prefixed by “<code>Default</code>” can be instantiated directly by a -<code>new DefaultXXX(…)</code> statement or by a call to the <code>createXXX(…)</code> method in a factory. -</p> -<div class="example"><b>Example:</b> to represent a projected coordinate reference system (Mercator, Lambert, <i>etc</i>): -<ul> -<li><code class="GeoAPI">org.opengis.referencing.crs.ProjectedCRS</code> is the GeoAPI interface derived from ISO 19111 standard, and</li> -<li><code class="SIS">org.apache.sis.referencing.crs.DefaultProjectedCRS</code> is the implementation provided by Apache SIS.</li> -</ul> -An instance can be created by: -<ul> -<li><code>ProjectedCRS crs = new DefaultProjectedCRS(…)</code>, ou</li> -<li><code>ProjectedCRS crs = CRSFactory.createProjectedCRS(…)</code>.</li> -</ul> -Both approaches expect the same arguments (omitted in this example for brevity). -</div> -<p> -In the default Apache SIS configuration, using <code class="GeoAPI">CRSFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code> -is almost the same except that <code class="GeoAPI">Factory</code> may return existing instances instead than creating new instances, -and that exceptions thrown in case of invalid arguments are different types. -In more advanced configurations, using <code class="GeoAPI">Factory</code> reduces the -<a href="#ServiceLoader">direct dependencies toward Apache SIS</a> -and allows inversion of control. -</p><p> -The “<code>General</code>” prefix is sometime used instead than “<code>Default</code>” -to indicate that alternative implementations are available for some specific cases. -For example the <code>Envelope</code> interface is implemented by at least two Apache SIS classes: -<code class="SIS">GeneralEnvelope</code> and <code>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. -But many SIS 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 -– but not by <code class="GeoAPI">Factory</code> – despite being conceptually abstract. -However such instantiations should be done only in last resort, when it is not possible to determine the exact subtype. -</p> -</section> - - -<section> -<header> -<h2 id="AboutBook"><span class="section-number">1.3.</span> Conventions used in this guide</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 functions in order to designate -a set of possible values of inputs and outputs respectively. -But the functions to which they are applied by certain <abbr>ISO</abbr> standards are not the same as the functions to which they are applied by other libraries. -For example, <abbr>ISO</abbr> 19123 applies these terms to <code class="OGC">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. -But <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 of 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 title="Spatial Information System">SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr title="Open Geospatial Consortium">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> - - - -<h3 id="CodeColors"><span class="section-number">1.3.1.</span> Code colors</h3> -<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 order to facilitate an understanding of the relationships between Apache <abbr title="Spatial Information System">SIS</abbr> and the standards, these elements are also represented using the following colour codes: -</p> -<ul> -<li> -Elements defined in the <abbr title="Open Geospatial Consortium">OGC</abbr> standard -or the <abbr title="International Organization for Standardization">ISO</abbr> standard appear in blue. -Example: <code class="OGC">CD_Ellipsoid</code>. -</li> -<li> -Elements defined in GeoAPI appear in green. -Example: <code class="GeoAPI">Ellipsoid</code>. -</li> -<li> -Elements defined in Apache <abbr title="Spatial Information System">SIS</abbr> appear in brown. -Example: <code class="SIS">DefaultEllipsoid</code>. -</li> -<li> -Other elements, such as those in standard Java, are left in black. -Example: <code>String</code>. -</li> -</ul> -<p> -Text in gray boxes are for information purpose only and can be ignored. -</p> -</section> -</section> - - -<section> -<header> -<h1 id="DataAccess"><span class="section-number">2.</span> Geospatial data access</h1> -<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Standards">Previous chapter</a></div><div class="next-chapter"><a href="#Coverage">Next chapter</a> ➡</div></div></nav> -</header> -<nav>In this chapter:<ul class="toc"/></nav> -<p> -<span style="color: red">TODO</span> -</p> - -<p> -The <abbr title="International Organization for Standardization">ISO</abbr> 19115 standard defines hundreds of elements. -Some of them will be introduced progressively in next chapters. -But in order to give some idea about what is available, the following table lists a few metadata elements. -Most of the nodes accept an arbitrary amount of values. -For example the <code class="OGC">extent</code> node may contain many geographic areas. +The <abbr title="International Organization for Standardization">ISO</abbr> 19115 standard defines hundreds of elements. +Some of them will be introduced progressively in next chapters. +But in order to give some idea about what is available, the following table lists a few metadata elements. +Most of the nodes accept an arbitrary amount of values. +For example the <code class="OGC">extent</code> node may contain many geographic areas. </p> <table style="line-height:1"> @@ -1504,7 +1111,7 @@ named for instance “standards parallel <li>Positional accuracy is altered after coordinate transformations. The new accuracy is described by <code class="GeoAPI">CoordinateOperation.getCoordinateOperationAccuracy()</code>.</li> <li>Finding the most appropriate coordinate transformation parameters require the use of a geodetic dataset like <abbr>EPSG</abbr>. -Declaring those parameters within the <abbr title="Coordinate Reference System">CRS</abbr> (for example with a <code class="OGC">TOWGS84</code> element) is often not sufficient.</li> +Declaring those parameters within the <abbr>CRS</abbr> (for example with a <code class="OGC">TOWGS84</code> element) is often not sufficient.</li> </ul> <article> <header> @@ -1538,7 +1145,7 @@ which makes it a kind of moving target ( </ul> <div class="example"><p><b>Example:</b> the <abbr>EPSG</abbr> geodetic dataset defines about 50 transformations from <abbr>NAD27</abbr> to <abbr>NAD83</abbr>. -In an early binding approach, the same geographic <abbr title="Coordinate Reference System">CRS</abbr> (namely “<abbr>NAD27</abbr>”) in the <abbr>WKT</abbr> 1 +In an early binding approach, the same geographic <abbr>CRS</abbr> (namely “<abbr>NAD27</abbr>”) in the <abbr>WKT</abbr> 1 format would need to be defined with a <code>TOWGS84[-8, 160, 176]</code> element for coordinates in <abbr>USA</abbr> or with a <code>TOWGS84[-10, 158, 187]</code> element for coordinates in Canada. Different parameter values exist for other regions like Cuba, so it is not possible to represent such diversity @@ -1584,7 +1191,7 @@ Those types will be discussed in <a href <p> Spatial reference systems by coordinates provide necessary information for mapping numerical coordinate values to real-world locations. In Apache <abbr title="Spatial Information System">SIS</abbr>, most information is contained (directly or indirectly) in -classes with a name ending in <abbr title="Coordinate Reference System">CRS</abbr>, the abbreviation of <i>Coordinate Reference System</i>. +classes with a name ending in <abbr>CRS</abbr>, the abbreviation of <i>Coordinate Reference System</i>. Those objects contain: </p> <ul> @@ -1677,7 +1284,7 @@ into more irregular shapes, if the shape <h4 id="AxisOrder"><span class="section-number">5.1.3.1.</span> Axis order</h4> <p> -The axis order is specified by the authority (typically a national agency) defining the <cite>Coordinate Reference System</cite> (<abbr title="Coordinate Reference System">CRS</abbr>). +The axis order is specified by the authority (typically a national agency) defining the <cite>Coordinate Reference System</cite> (<abbr>CRS</abbr>). The order depends on the <abbr>CRS</abbr> type and the country defining the <abbr>CRS</abbr>. In the case of geographic <abbr>CRS</abbr>, the (<var>latitude</var>, <var>longitude</var>) axis order is widely used by geographers and pilots for centuries. However software developers tend to consistently use the (<var>x</var>, <var>y</var>) order for every kind of <abbr>CRS</abbr>. @@ -1686,13 +1293,13 @@ for some <code class="GeoAPI">ProjectedC </p><p> Recent <abbr title="Open Geospatial Consortium">OGC</abbr> standards mandate the use of axis order as defined by the authority. Oldest <abbr>OGC</abbr> standards used the (<var>x</var>, <var>y</var>) axis order instead, ignoring any authority specification. -Many softwares still use the old (<var>x</var>, <var>y</var>) axis order, +Many software products still use the old (<var>x</var>, <var>y</var>) axis order, maybe because such uniformization makes <abbr>CRS</abbr> implementation and usage <em>apparently</em> easier. Apache <abbr title="Spatial Information System">SIS</abbr> supports both conventions with the following approach: by default, <abbr>SIS</abbr> creates <abbr>CRS</abbr> with axis order <em>as defined by the authority</em>. Those <abbr>CRS</abbr> are created by calls to the <code>CRS.forCode(String)</code> method and the actual axis order can be verified after the <abbr>CRS</abbr> creation with <code>System.out.println(crs)</code>. -But if (<var>x</var>, <var>y</var>) axis order is wanted for compatibility with older <abbr>OGC</abbr> specifications or other softwares, +But if (<var>x</var>, <var>y</var>) axis order is wanted for compatibility with older <abbr>OGC</abbr> specifications or other software products, then <abbr>CRS</abbr> forced to <cite>longitude first</cite> axis order can be created by a call to the following method: </p> @@ -1753,7 +1360,7 @@ while countries elongated along the Nort </header> <p style="color: red">TODO</p> -<h3 id="CRSAuthorityFactory"><span class="section-number">5.2.1.</span> Looking <abbr title="Coordinate Reference System">CRS</abbr> defined by authorities</h3> +<h3 id="CRSAuthorityFactory"><span class="section-number">5.2.1.</span> Looking <abbr>CRS</abbr> defined by authorities</h3> <p style="color: red">TODO</p> <h3 id="CRSParsing"><span class="section-number">5.2.2.</span> Reading definitions in GML or WKT format</h3> @@ -1762,7 +1369,7 @@ while countries elongated along the Nort <h3 id="CRSFactory"><span class="section-number">5.2.3.</span> Constructing programmatically</h3> <p style="color: red">TODO</p> -<h3 id="CRS_UserCode"><span class="section-number">5.2.4.</span> Adding new <abbr title="Coordinate Reference System">CRS</abbr> definitions</h3> +<h3 id="CRS_UserCode"><span class="section-number">5.2.4.</span> Adding new <abbr>CRS</abbr> definitions</h3> <p style="color: red">TODO</p> </section> @@ -1772,7 +1379,7 @@ while countries elongated along the Nort <h2 id="CoordinateOperations"><span class="section-number">5.3.</span> Coordinate operations</h2> </header> <p> -Given a <em>source</em> coordinate reference system (<abbr title="Coordinate Reference System">CRS</abbr>) in which existing coordinate values are expressed, +Given a <em>source</em> coordinate reference system (<abbr>CRS</abbr>) in which existing coordinate values are expressed, and a <em>target</em> coordinate reference system in which coordinate values are desired, Apache <abbr title="Spatial Information System">SIS</abbr> can provide a <em>coordinate operation</em> performing the conversion or transformation work. The search for coordinate operations may use a third argument, optional but recommended, @@ -1836,7 +1443,7 @@ Consequently verifying the domain of val <h3 id="MathTransform"><span class="section-number">5.3.1.</span> Executing an operation on coordinate values</h3> <p> The <code class="GeoAPI">CoordinateOperation</code> object introduced in above section provides high-level informations -(source and target <abbr title="Coordinate Reference System">CRS</abbr>, domain of validity, positional accuracy, operation parameters, <i>etc</i>). +(source and target <abbr>CRS</abbr>, domain of validity, positional accuracy, operation parameters, <i>etc</i>). The actual mathematical work is performed by a separated object obtained by a call to <code class="GeoAPI">CoordinateOperation.getMathTransform()</code>. At the difference of <code class="GeoAPI">CoordinateOperation</code> instances, <code class="GeoAPI">MathTransform</code> instances do not carry any metadata. They are kind of black box which know nothing about the source and target <abbr>CRS</abbr> @@ -2136,7 +1743,7 @@ then back to geographic domain after the The result is a three-steps process illustrated in the “Conceptual chain of operations” column of the example below. However because that operation chain is very common, the <abbr>EPSG</abbr> geodetic dataset provides a shortcut named “Geocentric translation <em>in geographic domain</em>”. -Using this operation, the conversion steps between geographic and geocentric <abbr title="Coordinate Reference System">CRS</abbr> are implicit. +Using this operation, the conversion steps between geographic and geocentric <abbr>CRS</abbr> are implicit. Consequently the datum shifts as specified by <abbr>EPSG</abbr> appears as if it was a single operation, but this is not the real operation executed by Apache <abbr title="Spatial Information System">SIS</abbr>. </p> @@ -2714,7 +2321,7 @@ But when a <code class="OGC">nilReason</ <section> <header> <h1 id="Utilities"><span class="section-number">6.</span> Utility classes and methods</h1> -<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Referencing">Previous chapter</a></div><div class="next-chapter"><a href="#Annexes">Next chapter</a> ➡</div></div></nav> +<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Referencing">Previous chapter</a></div><div class="next-chapter"><a href="#GeoAPI-details">Next chapter</a> ➡</div></div></nav> </header> <nav>In this chapter:<ul class="toc"> <li><a href="#ComparisonModes">Comparison modes of objects</a></li> @@ -2898,230 +2505,639 @@ If the converter is neither order preser <section> <header> -<h2 id="Internationalization"><span class="section-number">6.3.</span> Internationalization</h2> +<h2 id="Internationalization"><span class="section-number">6.3.</span> Internationalization</h2> +</header> +<p> +In an architecture where a program executed on a server provides its data to multiple clients, +the server’s locale conventions are not necessarily the same as those of the clients. +Conventions may differ in language, but also in the way they write numeric values +(even between two countries that speak the same language) as well in time zone. +To produce messages that conform to the client’s conventions, <abbr title="Spatial Information System">SIS</abbr> uses +two approaches, distinguished by their level of granularity: at the level of the messages themselves, +or at the level of the objects that create the messages. +The approach used also determines whether it is possible to share the same instance of an object for all languages. +</p> + +<h3 id="LocalizedString"><span class="section-number">6.3.1.</span> Distinct character sequences for each locale</h3> +<p> +Some classes are only designed to function according to one locale convention at a time. +This is of course true for the standard implementations of <code>java.text.Format</code>, +as they are entirely dedicated to the work of internationalization. +But it is also the case for other less obvious classes like <code>javax.imageio.ImageReader</code> and <code>ImageWriter</code>. +When one of these classes is implemented by <abbr title="Spatial Information System">SIS</abbr>, +we identify it by implementing the <code class="SIS">org.apache.sis.util.Localized</code> interface. +The <code class="SIS">getLocale()</code> method of this interface can determine the locale conventions +by which the instance produces its message. +</p> +<p> +Another class that provides different methods for different locales is <code>java.lang.Throwable</code>. +The standard Java <abbr title="Application Programming Interface">API</abbr> defines two methods for getting the error message: +<code>getMessage()</code> and <code>getLocalizedMessage()</code>. +Usually those two methods return the same character sequences, +but some exceptions thrown by Apache <abbr>SIS</abbr> may use different locales. +The policy that <abbr>SIS</abbr> tries to apply on a <em>best-effort</em> basis is: +</p> +<ul> +<li><code>getMessage()</code> returns the message in the <abbr title="Java Virtual Machine">JVM</abbr> default locale. +In a client-server architecture, this is often the locale on the server side. +This is the recommended language for logging messages to be read by system administrators.</li> +<li><code>getLocalizedMessage()</code> returns the message in a locale that depends on the context +in which the exception has been thrown. This is often the locale used by a particular <code class="GeoAPI">Format</code> +or <code class="SIS">DataStore</code> instance, and can be presumed to be the locale on the client side. +This is the recommended language to show in the user application.</li> +</ul> + +<div class="example"><p><b>Example:</b> +If an error occurred while a Japanese client connected to an European server, the localized message may be sent +to the client in Japanese language as given by <code>getLocalizedMessage()</code> while the same error may be +logged on the server side in the French (for example) language as given by <code>getMessage()</code>. +This allows system administrator to analyze the issue without the need to understand client’s language. +</p></div> +<p> +The utility class <code class="SIS">org.apache.sis.util.Exceptions</code> provides convenience methods to get messages +according to the conventions of a given locale, when this information is available. +</p> + + + +<h3 id="InternationalString"><span class="section-number">6.3.2.</span> Single instance for all supported locales</h3> +<p> +The <abbr title="Application Programming Interface">API</abbr> conventions defined by <abbr title="Spatial Information System">SIS</abbr> or inherited by GeoAPI favour the use of the +<code class="GeoAPI">InternationalString</code> type when the value of a <code>String</code> type would likely be localized. +This approach allows us to defer the internationalization process to the time when a character sequence is requested, +rather than the time when the object that contains them is created. +This is particularly useful for immutable classes used for creating unique instances independently of locale conventions. +</p> +<div class="example"><p><b>Example:</b> +<abbr>SIS</abbr> includes only one instance of the <code class="GeoAPI">OperationMethod</code> +type representing the Mercator projection, regardless of the client’s language. +But its <code class="GeoAPI">getName()</code> method (indirectly) provides an instance of +<code class="GeoAPI">InternationalString</code>, so that <code>toString(Locale.ENGLISH)</code> returns <cite>Mercator projection</cite> +while <code>toString(Locale.FRENCH)</code> returns <cite>Projection de Mercator</cite>. +</p></div> +<p> +When defining spatial objects independently of locale conventions, we reduce the risk of computational overload. +For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the +same instance of <code class="GeoAPI">CoordinateOperation</code>, +even if the projection has a different name depending on the country. +Moreover, certain types of <code class="GeoAPI">CoordinateOperation</code> may require coordinate transformation matrices, +so sharing a single instance becomes even more preferable in order to reduce memory consumption. +</p> + + + +<h3 id="Locale.ROOT"><span class="section-number">6.3.3.</span> <code>Locale.ROOT</code> convention</h3> +<p> +All <abbr title="Spatial Information System">SIS</abbr> methods receiving or returning the value of a <code>Locale</code> type accept the <code>Locale.ROOT</code> value. +This value is interpreted as specifying not to localize the text. +The notion of a <cite>non-localized text</cite> is a little false, as it is always necessary to chose a formatting convention. +This convention however, though very close to English, is usually slightly different. +For example: +</p> +<ul> +<li> +Identifiers are written as they appear in <abbr title="Unified Modeling Language">UML</abbr> diagrams, +such as <cite>blurredImage</cite> instead of <cite>Blurred image</cite>. +</li> +<li> +Dates are written according to the <abbr title="International Organization for Standardization">ISO</abbr> 8601 format, +which does not correspond to English conventions. +</li> +<li> +Numbers are written using their <code>toString()</code> methods, rather than using a <code>java.text.NumberFormat</code>. +As a result, there are differences in the number of significant digits, +use of exponential notation and the absence of thousands separators. +</li> +</ul> + + + +<h3 id="UnicodePoint"><span class="section-number">6.3.4.</span> Treatment of characters</h3> +<p> +In Java, sequences of characters use UTF-16 encoding. +There is a direct correspondence between the values of the <code>char</code> type and the great majority of characters, +which facilitates the use of sequences so long as these characters are sufficient. +However, certain Unicode characters cannot be represented by a single <code>char</code>. +These <i>supplementary characters</i> include certain ideograms, +but also road and geographical symbols in the 1F680 to 1F700 range. +Support for these supplementary characters requires slightly more complex interactions than the classic case, +where we may assume a direct correspondence. +Thus, instead of the loop on the left below, international applications must generally use the loop on the right: +</p> + +<table class="hidden"> +<tr> +<th>Loop to Avoid</th> +<th>Recommended loop</th> +<th>Supplementary character examples</th> +</tr> +<tr> +<td> + +<pre style="margin-top: 6pt"><code><b>for</b> (<b>int</b> i=0; i<string.length(); i++) { + <b>char</b> c = string.charAt(i); + <b>if</b> (Character.isWhitespace(c)) { + <code class="comment">// A blank space was found. +</code> } +}</code></pre> + +</td><td> + +<pre style="margin-top: 6pt"><code><b>for</b> (<b>int</b> i=0; i<string.length();) { + <b>int</b> c = string.codePointAt(i); + <b>if</b> (Character.isWhitespace(c)) { + <code class="comment">// A blank space was found. +</code> } + i += Character.charCount(c); +}</code></pre> + +</td><td> +<center>(rendering depends on browser capabilities)</center> +<p style="font-size: 40px">🚉 🚥 🚧 🚫 +🚯 🚸 🚺 🚹 🛄 🚭</p> +</td> +</tr> +</table> + +<p> +<abbr title="Spatial Information System">SIS</abbr> supports supplementary characters by using the loop on the right where necessary, +but the loop on the left is occasionally used when it is known that the characters searched for are not supplementary characters, +even if some may be present in the sequence in which we are searching. +</p> + + + +<h4 id="Whitespaces"><span class="section-number">6.3.4.1.</span> Blank spaces interpretation</h4> +<p> +Standard Java provides two methods for determining whether a character is a blank space: +<code>Character.isWhitespace(…)</code> and <code>Character.isSpaceChar(…)</code>. +These two methods differ in their interpretations of non-breaking spaces, tabs and line breaks. +The first method conforms to the interpretation currently used in languages such as Java, C/C++ and <abbr>XML</abbr>, +which considers tabs and line breaks to be blank spaces, while non-breaking spaces are read as not blank. +The second method — which conforms strictly to the Unicode definition — makes the opposite interpretation. +</p> +<p> +<abbr title="Spatial Information System">SIS</abbr> uses each of these methods in different contexts. +<code>isWhitespace(…)</code> is used to <em>separate</em> the elements of a list (numbers, dates, words, etc.), +while <code>isSpaceChar(…)</code> is used to ignore blank spaces <em>inside</em> a single element. +</p> +<div class="example"><p><b>Example:</b> +Take a list of numbers represented according to French conventions. +Each number may contain <em>non-breaking spaces</em> as thousands separators, +while the different numbers in the list may be separated by ordinary spaces, tabs or line breaks. +When analyzing a number, we want to consider the non-breaking spaces as being part of the number, +whereas a tab or a line break most likely indicates a separation between this number and the next. +We would thus use <code>isSpaceChar(…)</code>. +Conversely, when separating the numbers in the list, we want to consider tabs and line breaks as separators, +but not non-breaking spaces. +We would thus use <code>isWhitespace(…)</code>. +The role of ordinary spaces, to which either case might apply, should be decided beforehand. +</p></div> +<p> +In practice, this distinction is reflected in the use of <code>isSpaceChar(…)</code> in the implementations of <code>java.text.Format</code>, +or the use of <code>isWhitespace(…)</code> in nearly all the rest of the <abbr>SIS</abbr> library. +</p> +</section> +</section> + + +<section> +<header> +<h1 id="GeoAPI-details"><span class="section-number">7.</span> GeoAPI relationship with standards</h1> +<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Utilities">Previous chapter</a></div><div class="next-chapter"><a href="#Tests">Next chapter</a> ➡</div></div></nav> +</header> + +<nav>In this chapter:<ul class="toc"> +<li><a href="#GeoAPI-modules">GeoAPI modules</a></li> +<li><a href="#SpecificationToInterfaces">From OGC specifications to Java interfaces</a><ul> +<li><a href="#UML-annotation">Explicit mapping given by @UML annotations</a></li> +<li><a href="#MappingToJDK">Implicit mapping to standard JDK</a></li></ul></li> +<li><a href="#ReduceDependency">Reduce direct dependency to Apache SIS</a><ul> +<li><a href="#UML-annotation-indep">Mapping given by @UML annotations</a></li> +<li><a href="#ServiceLoader">Fetching implementations of GeoAPI interfaces</a><ul> +<li><a href="#GeoAPI-simple">Defining custom implementations</a></li></ul></li></ul></li></ul></nav> +<p> +The GeoAPI project has been briefly presented <a href="#GeoAPI">in introduction</a> to this document. +This annex explains in more details how GeoAPI relates to international standards. +The goal is to allow developers to reduce their dependency toward GeoAPI or Apache SIS specificities. +</p> + + + + + + + +<section> +<header> +<h2 id="GeoAPI-modules"><span class="section-number">7.1.</span> GeoAPI modules</h2> +</header> +<p> +The GeoAPI project consists of a standardized part (<code class="GeoAPI">geoapi</code>) +and an experimental part (<code class="GeoAPI">geoapi-pending</code>). +As these two parts are mutually exclusive, users must take care not to mix them in the same project. +This separation is guaranteed for all projects that depend only on the Maven central repository +(including the final versions of Apache <abbr title="Spatial Information System">SIS</abbr>), +as the <code class="GeoAPI">geoapi-pending</code> module is never deployed on this central repository. +By contrast, certain <abbr>SIS</abbr> development branches may depend on <code class="GeoAPI">geoapi-pending</code>. +</p> +<p> +GeoAPI modules are: +</p> +<ul> +<li><p> +<b><code class="GeoAPI">geoapi</code></b> — includes interfaces covered by the +<a href="http://www.opengeospatial.org/standards/geoapi";>GeoAPI standard of the <abbr title="Open Geospatial Consortium">OGC</abbr></a>. +The final versions of Apache <abbr>SIS</abbr> depend on this module. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-pending</code></b> — contains a +<em>copy</em> of all interfaces in the <code class="GeoAPI">geoapi</code> module +(not a dependence) with additions that have not yet been approved as an <abbr>OGC</abbr> standard. +Some additions appear in interfaces normally defined by the <code class="GeoAPI">geoapi</code> module, hence the need to copy them. +Apache <abbr>SIS</abbr>’s development branches <code>jdk7</code> and <code>jdk8</code> depend on this module, +but this dependence becomes a dependence on the <code class="GeoAPI">geoapi</code> standard module when the branches are merged to the trunk. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-conformance</code></b> — includes a JUnit test suite that developers may use to test their implementations. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-examples</code></b> — includes examples of relatively simple implementations. +These examples are placed in the public domain in order to encourage users to copy and adapt them to their needs if +Apache <abbr>SIS</abbr> services are unsuitable. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-proj4</code></b> — contains a partial implementation of <code class="GeoAPI">org.opengis.referencing</code> +packages as adaptors based on the C/C++ Proj.4 library. +This module may be used as an alternative to the <code class="SIS">sis-referencing</code> module for certain functions. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-netcdf</code></b> — contains a partial implementation of <code class="GeoAPI">org.opengis.referencing</code> +and <code class="GeoAPI">org.opengis.coverage</code> packages as adaptors based on the <abbr title="University Corporation for Atmospheric Research">UCAR</abbr> <abbr title="Network Common Data Form">netCDF</abbr> library. +The series of tests in this module was developed in such a way as to be reusable for other projects. +Apache <abbr>SIS</abbr> uses them to test its own <code class="SIS">sis-netcdf</code> module. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-openoffice</code></b> — contains an add-in for the OpenOffice.org office suite. +Note: Apache <abbr>SIS</abbr> provides its own <i>add-in</i> in the <code class="SIS">sis-openoffice</code> module. +</p></li> +</ul> +</section> + + + +<section> +<header> +<h2 id="SpecificationToInterfaces"><span class="section-number">7.2.</span> From <abbr title="Open Geospatial Consortium">OGC</abbr> specifications to Java interfaces</h2> </header> <p> -In an architecture where a program executed on a server provides its data to multiple clients, -the server’s locale conventions are not necessarily the same as those of the clients. -Conventions may differ in language, but also in the way they write numeric values -(even between two countries that speak the same language) as well in time zone. -To produce messages that conform to the client’s conventions, <abbr title="Spatial Information System">SIS</abbr> uses -two approaches, distinguished by their level of granularity: at the level of the messages themselves, -or at the level of the objects that create the messages. -The approach used also determines whether it is possible to share the same instance of an object for all languages. -</p> - -<h3 id="LocalizedString"><span class="section-number">6.3.1.</span> Distinct character sequences for each locale</h3> -<p> -Some classes are only designed to function according to one locale convention at a time. -This is of course true for the standard implementations of <code>java.text.Format</code>, -as they are entirely dedicated to the work of internationalization. -But it is also the case for other less obvious classes like <code>javax.imageio.ImageReader</code> and <code>ImageWriter</code>. -When one of these classes is implemented by <abbr title="Spatial Information System">SIS</abbr>, -we identify it by implementing the <code class="SIS">org.apache.sis.util.Localized</code> interface. -The <code class="SIS">getLocale()</code> method of this interface can determine the locale conventions -by which the instance produces its message. +GeoAPI interfaces are sometime generated from other files provided by <abbr>OGC</abbr>, like <abbr title="XML Schema Definition">XSD</abbr> files. +But there is always a manual revision, and often modifications compared to automatically generated Java files. +It would have been possible to automatically generate Java interfaces from <abbr>OGC</abbr> standards using existing tools. +For example one of the most commonly-used approaches is to transform <a href="http://schemas.opengis.net/gml/3.3/";><abbr>XSD</abbr> schemas</a> +into Java interfaces using command line utility <code>xjc</code>. +As this utility is included in most Java distributions (it is one of the <a href="http://jaxb.java.net";><abbr title="Java Architecture for XML Binding">JAXB</abbr></a> tools), +this approach is favoured by many projects found on the Internet. +Other approaches use tools integrated into the Eclipse Development Environment, +which is based on <abbr title="Unified Modeling Language">UML</abbr> schemas rather than <abbr>XSD</abbr> ones. +A similar approach was attempted in the early days of the GeoAPI project, but was quickly abandoned. +We favor a manual approach for the following reasons: </p> +<ul> +<li> <p> -Another class that provides different methods for different locales is <code>java.lang.Throwable</code>. -The standard Java <abbr title="Application Programming Interface">API</abbr> defines two methods for getting the error message: -<code>getMessage()</code> and <code>getLocalizedMessage()</code>. -Usually those two methods return the same character sequences, -but some exceptions thrown by Apache <abbr>SIS</abbr> may use different locales. -The policy that <abbr>SIS</abbr> tries to apply on a <em>best-effort</em> basis is: +Some <abbr>XSD</abbr> schemas are much more verbose than the original <abbr>UML</abbr> schemas. +Converting from <abbr>XSD</abbr> schemas introduces — at least in the case of metadata — +almost double the number of interfaces actually defined by the standard, without adding any new features. +<abbr>XSD</abbr> schemas also define attributes specific to <abbr>XML</abbr> documents (<code class="OGC">id</code>, +<code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), that do not exist in the original <abbr>UML</abbr> diagrams, +and which we do not necessarily wish to expose in a Java <abbr title="Application Programming Interface">API</abbr>. +Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common. </p> -<ul> -<li><code>getMessage()</code> returns the message in the <abbr title="Java Virtual Machine">JVM</abbr> default locale. -In a client-server architecture, this is often the locale on the server side. -This is the recommended language for logging messages to be read by system administrators.</li> -<li><code>getLocalizedMessage()</code> returns the message in a locale that depends on the context -in which the exception has been thrown. This is often the locale used by a particular <code class="GeoAPI">Format</code> -or <code class="SIS">DataStore</code> instance, and can be presumed to be the locale on the client side. -This is the recommended language to show in the user application.</li> -</ul> - <div class="example"><p><b>Example:</b> -If an error occurred while a Japanese client connected to an European server, the localized message may be sent -to the client in Japanese language as given by <code>getLocalizedMessage()</code> while the same error may be -logged on the server side in the French (for example) language as given by <code>getMessage()</code>. -This allows system administrator to analyze the issue without the need to understand client’s language. +<abbr>XSD</abbr> metadata schemas insert a <code class="OGC"><gmd:CI_Citation></code> element +inside a <code class="OGC"><gmd:citation></code>, +a <code class="OGC"><gmd:CI_OnlineResource></code> element inside a <code class="OGC"><gmd:onlineResource></code>, +and so on for the hundreds of classes defined by <abbr title="International Organization for Standardization">ISO</abbr> 19115 standard. +This redundancy is certainly not necessary in a Java program. </p></div> +</li> +<li> <p> -The utility class <code class="SIS">org.apache.sis.util.Exceptions</code> provides convenience methods to get messages -according to the conventions of a given locale, when this information is available. -</p> - - - -<h3 id="InternationalString"><span class="section-number">6.3.2.</span> Single instance for all supported locales</h3> -<p> -The <abbr title="Application Programming Interface">API</abbr> conventions defined by <abbr title="Spatial Information System">SIS</abbr> or inherited by GeoAPI favour the use of the -<code class="GeoAPI">InternationalString</code> type when the value of a <code>String</code> type would likely be localized. -This approach allows us to defer the internationalization process to the time when a character sequence is requested, -rather than the time when the object that contains them is created. -This is particularly useful for immutable classes used for creating unique instances independently of locale conventions. +<abbr>OGC</abbr> standards use different naming conventions than Java. +In particular, the names of almost all <abbr>OGC</abbr> classes begin with a two-letter prefix, +such as <code class="OGC">MD_Identifier</code>. +This prefixes fulfill the same role as package names in Java. +GeoAPI adapts this practice by using interface names without prefixes and placing these interfaces in packages corresponding to the prefixes, +but with more descriptive names. +Occasionally we also change the names; for example, to avoid acronyms, or to conform to an established convention such as JavaBeans. </p> <div class="example"><p><b>Example:</b> -<abbr>SIS</abbr> includes only one instance of the <code class="GeoAPI">OperationMethod</code> -type representing the Mercator projection, regardless of the client’s language. -But its <code class="GeoAPI">getName()</code> method (indirectly) provides an instance of -<code class="GeoAPI">InternationalString</code>, so that <code>toString(Locale.ENGLISH)</code> returns <cite>Mercator projection</cite> -while <code>toString(Locale.FRENCH)</code> returns <cite>Projection de Mercator</cite>. +The <abbr>OGC</abbr> class <code class="OGC">MD_Identifier</code> becomes the +<code class="GeoAPI">Identifier</code> interface in the <code class="GeoAPI">org.opengis.metadata</code> package. +The <abbr>OGC</abbr> class <code class="OGC">SC_CRS</code> becomes the <code class="GeoAPI">CoordinateReferenceSystem</code> interface, +and the <code class="OGC">usesDatum</code> association becomes a <code class="GeoAPI">getDatum()</code> method, +rather than the “<code>getUsesDatum()</code>” that would result from an automatic conversion tool. +We do not allow programs to blindly apply rules that ignore the conventions of the community whose schemas we translate. </p></div> +</li> +<li> <p> -When defining spatial objects independently of locale conventions, we reduce the risk of computational overload. -For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the -same instance of <code class="GeoAPI">CoordinateOperation</code>, -even if the projection has a different name depending on the country. -Moreover, certain types of <code class="GeoAPI">CoordinateOperation</code> may require coordinate transformation matrices, -so sharing a single instance becomes even more preferable in order to reduce memory consumption. -</p> - - - -<h3 id="Locale.ROOT"><span class="section-number">6.3.3.</span> <code>Locale.ROOT</code> convention</h3> -<p> -All <abbr title="Spatial Information System">SIS</abbr> methods receiving or returning the value of a <code>Locale</code> type accept the <code>Locale.ROOT</code> value. -This value is interpreted as specifying not to localize the text. -The notion of a <cite>non-localized text</cite> is a little false, as it is always necessary to chose a formatting convention. -This convention however, though very close to English, is usually slightly different. -For example: +The standards may contain structures that do not have a direct equivalent in Java, +such as unions similar to what we would find in C/C++. +The strategy used to obtain an equivalent feature in Java depends on the context: +multiple inheritance of interfaces, modification of the hierarchy, or simply omitting the union. +These decisions are made case-by-case based on a needs analysis. </p> -<ul> -<li> -Identifiers are written as they appear in <abbr title="Unified Modeling Language">UML</abbr> diagrams, -such as <cite>blurredImage</cite> instead of <cite>Blurred image</cite>. +<div class="example"><p><b>Example:</b> +<abbr>ISO</abbr> 19111 standard defines different types of coordinate systems, such as spherical, cylindrical, polar or Cartesian. +It then defines several <em>subsets</em> of these types of coordinate systems systems. +These subsets, represented by unions, serve to specify that a class may only be associated with a particular type of coordinate system. +For example, a union of types may be associated with an image, named <code class="OGC">CS_ImageCS</code>, +which can only contain <code class="OGC">CS_CartesianCS</code> and <code class="OGC">CS_AffineCS</code>. +In this case, we get the desired effect in Java through a modification of the hierarchy of classes: +we define the <code class="GeoAPI">CartesianCS</code> interface as a specialization of <code class="GeoAPI">AffineCS</code>, +which is semantically correct. +But it is not possible to apply a similar strategy to other unions without violating the semantics. +</p></div> </li> <li> -Dates are written according to the <abbr title="International Organization for Standardization">ISO</abbr> 8601 format, -which does not correspond to English conventions. +<p> +Several specifications overlap. +GeoAPI performs the work of integration by replacing some duplicate structures with references to equivalent structures from the standards that best represent them. +</p> +<div class="example"><p><b>Example:</b> +<abbr>ISO</abbr> 19115:2003 standard, which defines metadata structures, +also attempts to describe a few structures representing coordinate reference systems (<abbr title="Coordinate Reference System">CRS</abbr>). +Yet these are also the focus of another standard: <abbr>ISO</abbr> 19111. +At the same time, <abbr>ISO</abbr> 19111:2007 states in section 3 that it reuses all of the elements of +<abbr>ISO</abbr> 19115:2003 except <code class="OGC">MD_CRS</code> and its components. +GeoAPI interfaces reduce the redundancy by applying the exclusion recommended by <abbr>ISO</abbr> 19111 to the entire project. +</p></div> </li> <li> -Numbers are written using their <code>toString()</code> methods, rather than using a <code>java.text.NumberFormat</code>. -As a result, there are differences in the number of significant digits, -use of exponential notation and the absence of thousands separators. +<p> +The complexity of some standards have increased for historical reasons rather than technical ones, related to the standardization process. +GeoAPI reduces the technical debt by designing interfaces with each element in its proper place, +regardless of the chronological order in which the standards were published. +</p> +<div class="example"><p><b>Example:</b> +<abbr>ISO</abbr> 19115-2 standard is an extension of <abbr>ISO</abbr> 19115-1 standard, adding image metadata structures. +These metadata were defined in a separate standard because they were not yet ready when the first part of the standard was published. +As it was not possible for administrative reasons to add attributes to already-published classes, +the new attributes were added in a sub-class bearing almost the same name. +Thus, <abbr>ISO</abbr> 19115-2 defines the class <code class="OGC">MI_Band</code>, +which extends the class <code class="OGC">MD_Band</code> from <abbr>ISO</abbr> 19115-1 by adding attributes that would have appeared +directly in the parent class if there were ready on time. +In GeoAPI, we have chosen to “repair” these anomalies by fusing these two classes into a single interface. +</p></div> </li> </ul> +<p> +Deviations from the standards are documented in each affected class and method. +Each mention of a deviation is also collected on a <a href="http://www.geoapi.org/3.0/javadoc/departures.html";>single page</a> in order to provide an overview. +Since these deviations blur the relationships between the standards and certain Java interfaces, +the correspondence between these languages is explained by <code class="GeoAPI">@UML</code> annotations and property files described in the following section. +</p> -<h3 id="UnicodePoint"><span class="section-number">6.3.4.</span> Treatment of characters</h3> +<h3 id="UML-annotation"><span class="section-number">7.2.1.</span> Explicit mapping given by <code class="GeoAPI">@UML</code> annotations</h3> <p> -In Java, sequences of characters use UTF-16 encoding. -There is a direct correspondence between the values of the <code>char</code> type and the great majority of characters, -which facilitates the use of sequences so long as these characters are sufficient. -However, certain Unicode characters cannot be represented by a single <code>char</code>. -These <i>supplementary characters</i> include certain ideograms, -but also road and geographical symbols in the 1F680 to 1F700 range. -Support for these supplementary characters requires slightly more complex interactions than the classic case, -where we may assume a direct correspondence. -Thus, instead of the loop on the left below, international applications must generally use the loop on the right: +For each class, method and constant defined by an <abbr title="Open Geospatial Consortium">OGC</abbr> or <abbr title="International Organization for Standardization">ISO</abbr> standard, +GeoAPI indicates its provenance using annotations defined in the <code class="GeoAPI">org.opengis.annotation</code> package. +In particular, the <code class="GeoAPI">@UML</code> annotations indicates the standard, +the name of the element in that standard, and also its obligation. +For example, in the following code snippet, the first <code class="GeoAPI">@UML</code> code indicates that the Java interface that follows +(<code class="GeoAPI">ProjectedCRS</code>) is defined using the <code class="OGC">SC_ProjectedCRS</code> type of <abbr>ISO</abbr> 19111 standard. +The second <code class="GeoAPI">@UML</code> annotation, this time applied to the <code class="GeoAPI">getCoordinateSystem()</code> method, +indicates that this method is defined using the <code class="OGC">coordinateSystem</code> association of <abbr>ISO</abbr> 19111 standard, +and that this association is mandatory — meaning, in Java, that the method is not allowed to return a <code>null</code> value. </p> -<table class="hidden"> -<tr> -<th>Loop to Avoid</th> -<th>Recommended loop</th> -<th>Supplementary character examples</th> -</tr> -<tr> -<td> - -<pre style="margin-top: 6pt"><code><b>for</b> (<b>int</b> i=0; i<string.length(); i++) { - <b>char</b> c = string.charAt(i); - <b>if</b> (Character.isWhitespace(c)) { - <code class="comment">// A blank space was found. -</code> } -}</code></pre> - -</td><td> +<pre><code><b>package</b> <code class="GeoAPI">org.opengis.referencing.crs</code>; -<pre style="margin-top: 6pt"><code><b>for</b> (<b>int</b> i=0; i<string.length();) { - <b>int</b> c = string.codePointAt(i); - <b>if</b> (Character.isWhitespace(c)) { - <code class="comment">// A blank space was found. -</code> } - i += Character.charCount(c); +<code class="comment">/** + * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface. + */</code> +@<code class="GeoAPI">UML</code>(specification=ISO_19111, identifier=<i>"<code class="OGC">SC_ProjectedCRS</code>"</i>) +<b>public</b> <b>interface</b> <code class="GeoAPI">ProjectedCRS</code> <b>extends</b> <code class="GeoAPI">GeneralDerivedCRS</code> { + <code class="comment">/** + * Returns the coordinate system, which must be Cartesian. + */</code> + @<code class="GeoAPI">UML</code>(obligation=MANDATORY, specification=ISO_19111, identifier=<i>"<code class="OGC">coordinateSystem</code>"</i>) + <code class="GeoAPI">CartesianCS</code> <code class="GeoAPI">getCoordinateSystem()</code>; }</code></pre> -</td><td> -<center>(rendering depends on browser capabilities)</center> -<p style="font-size: 40px">🚉 🚥 🚧 🚫 -🚯 🚸 🚺 🚹 🛄 🚭</p> -</td> -</tr> -</table> +<p> +Java reflection methods allow access to this information during the execution of an application. +This is useful for displaying UML identifiers for users familiar with <abbr>OGC</abbr> standards, +or for writing elements in an <abbr>XML</abbr> document. +Class <code class="SIS">org.apache.sis.util.iso.Types</code> provides static convenience methods +like <code class="SIS">getStandardName(Class)</code> for such operations. +For example the following code will display +“Standard name of type <code class="GeoAPI">org.opengis.referencing.crs.ProjectedCRS</code> is <code class="OGC">SC_ProjectedCRS</code>”: +</p> + +<pre><code>Class<?> type = <code class="GeoAPI">ProjectedCRS</code>.<b>class</b>; +System.out.println(<i>"Standard name of type "</i> + type.getName() + <i>" is "</i> + Types.getStandardName(type));</code></pre> <p> -<abbr title="Spatial Information System">SIS</abbr> supports supplementary characters by using the loop on the right where necessary, -but the loop on the left is occasionally used when it is known that the characters searched for are not supplementary characters, -even if some may be present in the sequence in which we are searching. +The <code class="SIS">Types.forStandardName(String)</code> convenience method performs the reverse operation. +Applications who want to perform those operations without SIS convenience methods can follow indications +provided in a <a href="#UML-annotation-geoapi">separated chapter</a>. </p> -<h4 id="Whitespaces"><span class="section-number">6.3.4.1.</span> Blank spaces interpretation</h4> +<h3 id="MappingToJDK"><span class="section-number">7.2.2.</span> Implicit mapping to standard <abbr>JDK</abbr></h3> <p> -Standard Java provides two methods for determining whether a character is a blank space: -<code>Character.isWhitespace(…)</code> and <code>Character.isSpaceChar(…)</code>. -These two methods differ in their interpretations of non-breaking spaces, tabs and line breaks. -The first method conforms to the interpretation currently used in languages such as Java, C/C++ and <abbr>XML</abbr>, -which considers tabs and line breaks to be blank spaces, while non-breaking spaces are read as not blank. -The second method — which conforms strictly to the Unicode definition — makes the opposite interpretation. +Some classes and methods have neither an <code class="GeoAPI">@UML</code> annotation, nor an entry in the <code class="GeoAPI">class-index.properties</code> file. +They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>. +In this last case, the mapping to <abbr title="International Organization for Standardization">ISO</abbr> standards is implicit. +The following table describes this mapping for <abbr>ISO</abbr> 19103 types. +Java’s primitive types are preferred when applicable, +but where necessary their wrappers are used in order to authorize null values. </p> +<table> +<caption>Mapping between <abbr>ISO</abbr> 19103 and <abbr>JDK</abbr> types</caption> +<tr> +<th><abbr>ISO</abbr> type</th> +<th><abbr>JDK</abbr> type</th> +<th>Remarks</th> +</tr> +<tr> +<td class="separator" colspan="2">Numbers</td> +<td class="leftBorder"/> +</tr> +<tr> +<td><code class="OGC">Integer</code></td> +<td><code>int</code></td> +<td class="leftBorder">Sometimes <code>java.lang.Integer</code> for optional attributes.</td> +</tr> +<tr> +<td><code class="OGC">Integer</code> (in some cases)</td> +<td><code>long</code></td> +<td class="leftBorder">Sometimes <code>java.lang.Long</code> for optional attributes.</td> +</tr> +<tr> +<td><code class="OGC">Real</code></td> +<td><code>double</code></td>
[... 370 lines stripped ...]
