sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1814367 [2/3] - in /sis/site/trunk/content/book: en/developer-guide.html fr/developer-guide.html
Date Sun, 05 Nov 2017 18:04:55 GMT

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">&lt;gmd:CI_Citation&gt;</code> element
-inside a <code class="OGC">&lt;gmd:citation&gt;</code>,
-a <code class="OGC">&lt;gmd:CI_OnlineResource&gt;</code> element inside a <code class="OGC">&lt;gmd:onlineResource&gt;</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&lt;?&gt; 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&lt;Character&gt;</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&lt;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&lt;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">&#128649; &#128677; &#128679; &#128683;
+&#128687; &#128696; &#128698; &#128697; &#128708; &#128685;</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">&lt;gmd:CI_Citation&gt;</code> element
+inside a <code class="OGC">&lt;gmd:citation&gt;</code>,
+a <code class="OGC">&lt;gmd:CI_OnlineResource&gt;</code> element inside a <code class="OGC">&lt;gmd:onlineResource&gt;</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&lt;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&lt;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">&#128649; &#128677; &#128679; &#128683;
-&#128687; &#128696; &#128698; &#128697; &#128708; &#128685;</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&lt;?&gt; 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 ...]


Mime
View raw message