sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1814366 [2/4] - in /sis/site/trunk/book: en/ en/annex/ en/annexes/ en/annexes/design/ en/annexes/geoapi/ en/annexes/tests/ en/introduction/ fr/ fr/annex/ fr/annexes/ fr/annexes/design/ fr/annexes/geoapi/ fr/annexes/tests/ fr/introduction/
Date Sun, 05 Nov 2017 18:04:33 GMT
Copied: sis/site/trunk/book/en/annexes/geoapi/Modules.html (from r1814233, sis/site/trunk/book/en/introduction/GeoAPI.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/geoapi/Modules.html?p2=sis/site/trunk/book/en/annexes/geoapi/Modules.html&p1=sis/site/trunk/book/en/introduction/GeoAPI.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/introduction/GeoAPI.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/geoapi/Modules.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,554 +24,68 @@
   <head>
     <title>GeoAPI</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--
-      Content below this point is copied in "../../content/book/en/developer-guide.html"
+      Content below this point is copied in "(…)/content/book/en/developer-guide.html"
       by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
     -->
+
     <section>
       <header>
-        <h2 id="GeoAPI">From conceptual models to Java interfaces: GeoAPI</h2>
+        <h2 id="GeoAPI-modules">GeoAPI modules</h2>
       </header>
       <p>
-        The <a href="http://www.geoapi.org">GeoAPI</a> project offers a set of Java interfaces for geospatial applications.
-        In a series of <code>org.opengis.*</code> packages, GeoAPI defines structures representing metadata,
-        coordinate reference systems and operations that perform cartographic projections.
-        In a part that is not yet standardized — called <i>pending</i> — GeoAPI defines structures that represent geo-referenced images,
-        geometries, filters that can be applied to queries, and other features.
-        These interfaces closely follow the specifications of the <abbr>OGC</abbr>, while interpreting and adapting them
-        to meet the needs of Java developers — for example, conforming with naming conventions.
-        These interfaces benefit both client applications and libraries:
+        The GeoAPI project consists of a standardized part (<code>geoapi</code>)
+        and an experimental part (<code>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>SIS</abbr>),
+        as the <code>geoapi-pending</code> module is never deployed on this central repository.
+        By contrast, certain <abbr>SIS</abbr> development branches may depend on <code>geoapi-pending</code>.
+      </p>
+      <p>
+        GeoAPI modules are:
       </p>
       <ul>
         <li><p>
-          Developers of client applications benefit from the greater knowledge base available on the Internet
-          (due to the many publications related to <abbr>OGC</abbr> standards), as well as increased interoperability.
-          Interoperability is facilitated by a better separation between applications that <em>call</em> GeoAPI functions,
-          and libraries that <em>implement</em> GeoAPI.
-          The separation is similar to that offered by the <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/"><abbr>JDBC</abbr></a> (<i>Java Database Connectivity</i>) interfaces of standard Java.
-          Using the interfaces’ <abbr>API</abbr>, developers can ignore the underlying implementation.
-          For example, they can perform cartographic projections with the help of the <a href="http://www.geoapi.org/geoapi-proj4/index.html">Proj.4</a> library, or the Apache <abbr>SIS</abbr> library,
-          without having to change their programs when they change libraries.
+          <b><code>geoapi</code></b> — includes interfaces covered by the
+          <a href="http://www.opengeospatial.org/standards/geoapi">GeoAPI standard of the <abbr>OGC</abbr></a>.
+          The final versions of Apache <abbr>SIS</abbr> depend on this module.
+        </p></li>
+        <li><p>
+          <b><code>geoapi-pending</code></b> — contains a
+          <em>copy</em> of all interfaces in the <code>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>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>geoapi</code> standard module when the branches are merged to the trunk.
+        </p></li>
+        <li><p>
+          <b><code>geoapi-conformance</code></b> — includes a JUnit test suite that developers may use to test their implementations.
         </p></li>
         <li><p>
-          The developers of libraries inherit the expertise of the specifications’ authors, via the models that represent interfaces.
-          GeoAPI also provides a framework within which developers can prioritize the implementation of the features they most need,
-          while leaving the remaining features as extension points for future developments.
-          For example, clients can call a GeoAPI function even if it is not yet supported by the library,
-          and simply get a null value until a new version of the library returns a relevant value.
+          <b><code>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>geoapi-proj4</code></b> — contains a partial implementation of <code>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>sis-referencing</code> module for certain functions.
+        </p></li>
+        <li><p>
+          <b><code>geoapi-netcdf</code></b> — contains a partial implementation of <code>org.opengis.referencing</code>
+          and <code>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>sis-netcdf</code> module.
+        </p></li>
+        <li><p>
+          <b><code>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>sis-openoffice</code> module.
         </p></li>
       </ul>
-
-
-      <details>
-        <summary>More about the GeoAPI project</summary>
-        <article id="GeoAPI-history">
-          <header>
-            <h2>GeoAPI project history</h2>
-          </header>
-          <p>
-            In 2001, the Open GIS Consortium (the former name of the Open Geospatial Consortium) published
-            <a href="http://www.opengeospatial.org/standards/ct"><abbr>OGC</abbr> implementation specification 01-009:
-            <cite>Coordinate Transformation Services</cite></a>.
-            This specification, developed by the Computer Aided Development Corporation (Cadcorp),
-            was accompanied by <abbr>COM</abbr>, <abbr>CORBA</abbr>, and Java interfaces.
-            At this time, the wave of web services had not yet eclipsed classical programming interfaces.
-            The interfaces of the <abbr>OGC</abbr> did anticipate a networked world,
-            but invested rather — in the case of Java — in <abbr>RMI</abbr> (<i>Remote Method Invocation</i>) technology.
-            As the GeoAPI project did not yet exist, we retroactively designate these historical interfaces “<a href="http://www.geoapi.org/0.1/index.html">GeoAPI 0.1</a>”.
-            These interfaces already used the package name <code>org.opengis</code>, which would be adopted by GeoAPI.
-          </p><p>
-            In 2002, developers of free projects launched a
-            <a href="http://web.archive.org/web/20030509104308/http://digitalearth.org/story/2002/10/10/55046/206">call for the creation of a geospatial <abbr>API</abbr></a>.
-            The initial proposal attracted the interest of at least five free projects.
-            The project was created using <a href="http://sourceforge.net/projects/geoapi/">SourceForge</a>,
-            which has since hosted the source code in a <a href="http://www.geoapi.org/source-repository.html">Subversion repository</a>.
-            It was then that the project assumed the name “GeoAPI”, and used the interfaces of the <abbr>OGC</abbr> specification 01-009 as a starting point.
-          </p><p>
-            A few months later, the <abbr>OGC</abbr> launched the <a href="http://www.opengeospatial.org/standards/go"><abbr>GO</abbr>-1: <i>Geographic Objects</i></a> project,
-            which pursued goals similar to those of GeoAPI.
-            In the meantime, the <abbr>OGC</abbr> abandonned some of their specifications in favor of <abbr>ISO</abbr> standards.
-            GeoAPI and <abbr>GO-1</abbr> worked jointly to rework the GeoAPI interfaces and base them on the new <abbr>ISO</abbr> norms.
-            Their first interation, <a href="http://www.geoapi.org/1.0/index.html">GeoAPI 1.0</a>,
-            served as a starting point for the first draft of the <abbr>OGC</abbr> specification 03-064 by the <abbr>GO</abbr>-1 working group.
-            The final version of this specification became an <abbr>OGC</abbr> standard in 2005,
-            and <a href="http://www.geoapi.org/2.0/index.html">GeoAPI 2.0</a> was published at that time.
-          </p><p>
-            The <abbr>GO</abbr>-1 project was largely supported by a company called <i>Polexis</i>.
-            Its acquisition by <i>Sys Technology</i>, and the change in priorities under the new owners,
-            brought a halt to the <abbr>GO</abbr>-1 project, which in turn slowed development on GeoAPI.
-            In order to resume development, a new working group entitled “GeoAPI 3.0” was created at the <abbr>OGC</abbr>.
-            This group took a narrower focus compared to GeoAPI 2.0, concentrating on the most stable interfaces, and putting the others
-            — such as geometries — in a module entitled “<a href="http://www.geoapi.org/geoapi-pending/index.html">pending</a>”, for future consideration.
-            <a href="http://www.geoapi.org/3.0/index.html">GeoAPI 3.0</a> became an <a href="http://www.opengeospatial.org/standards/geoapi"><abbr>OGC</abbr> standard</a> in 2011.
-            This version was the first to be deployed in the <a href="http://search.maven.org/#search|ga|1|geoapi">Maven central repository</a>.
-          </p>
-        </article>
-      </details>
-
-      <p>GeoAPI interfaces are sometime generated from other files provided by <abbr>OGC</abbr>, like <abbr>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>@UML</code> annotations and property files described in the following section.
-      </p>
-
-      <details>
-        <summary>More about the reasons for manual definition of Java interfaces</summary>
-        <article id="SpecificationToInterfaces">
-          <header>
-            <h2>From <abbr>OGC</abbr> specifications to Java interfaces</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>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>UML</abbr> schemas rather than <abbr>XSD</abbr> ones.
-          </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:
-          </p>
-          <ul>
-            <li>
-              <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>API</abbr>.
-                Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common.
-              </p>
-              <div class="example"><p><b>Example:</b>
-                <abbr>XSD</abbr> metadata schemas insert a <code>&lt;gmd:CI_Citation&gt;</code> element
-                inside a <code class="OGC">&lt;gmd:citation&gt;</code>,
-                a <code>&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>
-            <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>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>MD_Identifier</code> becomes the
-                <code>Identifier</code> interface in the <code>org.opengis.metadata</code> package.
-                The <abbr>OGC</abbr> class <code>SC_CRS</code> becomes the <code>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>
-                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>CS_ImageCS</code>,
-                which can only contain <code>CS_CartesianCS</code> and <code>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>CartesianCS</code> interface as a specialization of <code>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>
-              <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>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>
-              <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>MI_Band</code>,
-                which extends the class <code>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>
-        </article>
-      </details>
-
-      <p id="GeoAPI-core">
-        GeoAPI is composed of many modules.
-        The <code>geoapi</code> and <code>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>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>
-
-      <details>
-        <summary>More about GeoAPI modules</summary>
-        <article id="GeoAPI-modules">
-          <h2>GeoAPI modules</h2>
-          <p>
-            The GeoAPI project consists of a standardized part (<code>geoapi</code>)
-            and an experimental part (<code>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>SIS</abbr>),
-            as the <code>geoapi-pending</code> module is never deployed on this central repository.
-            By contrast, certain <abbr>SIS</abbr> development branches may depend on <code>geoapi-pending</code>.
-          </p>
-          <p>
-            GeoAPI modules are:
-          </p>
-          <ul>
-            <li><p>
-              <b><code>geoapi</code></b> — includes interfaces covered by the
-              <a href="http://www.opengeospatial.org/standards/geoapi">GeoAPI standard of the <abbr>OGC</abbr></a>.
-              The final versions of Apache <abbr>SIS</abbr> depend on this module.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-pending</code></b> — contains a
-              <em>copy</em> of all interfaces in the <code>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>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>geoapi</code> standard module when the branches are merged to the trunk.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-conformance</code></b> — includes a JUnit test suite that developers may use to test their implementations.
-            </p></li>
-            <li><p>
-              <b><code>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>geoapi-proj4</code></b> — contains a partial implementation of <code>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>sis-referencing</code> module for certain functions.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-netcdf</code></b> — contains a partial implementation of <code>org.opengis.referencing</code>
-              and <code>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>sis-netcdf</code> module.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-openoffice</code></b> — contains an add-in for the OpenOffice.org office suite.
-            </p></li>
-          </ul>
-        </article>
-      </details>
-
-
-
-      <h3 id="UML-annotation">Explicit mapping given by <code>@UML</code> annotations</h3>
-      <p>
-        For each class, method and constant defined by an <abbr>OGC</abbr> or <abbr>ISO</abbr> standard,
-        GeoAPI indicates its provenance using annotations defined in the <code>org.opengis.annotation</code> package.
-        In particular, the <code>@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>@UML</code> code indicates that the Java interface that follows
-        (<code>ProjectedCRS</code>) is defined using the <code>SC_ProjectedCRS</code> type of <abbr>ISO</abbr> 19111 standard.
-        The second <code>@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>package <code class="GeoAPI">org.opengis.referencing.crs</code>;
-
-/**
- * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface.
- */
-@UML(specification=ISO_19111, identifier="<code class="OGC">SC_ProjectedCRS</code>")
-public interface ProjectedCRS extends GeneralDerivedCRS {
-    /**
-     * Returns the coordinate system, which must be Cartesian.
-     */
-    @UML(obligation=MANDATORY, specification=ISO_19111, identifier="<code class="OGC">coordinateSystem</code>")
-    CartesianCS <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>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>org.opengis.referencing.crs.ProjectedCRS</code> is <code>SC_ProjectedCRS</code>”:
-      </p>
-
-<pre><code>Class&lt;?&gt; type = ProjectedCRS.class;
-System.out.println("Standard name of type " + type.getName() + " is " + 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">Implicit mapping to standard <abbr>JDK</abbr></h3>
-      <p>
-        Some classes and methods have neither an <code>@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"></td>
-        </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"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Number</code></td>
-          <td><code>java.lang.Number</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Texts</td>
-          <td class="leftBorder"></td>
-        </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"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Sequence&lt;Character&gt;</code></td>
-          <td><code>java.lang.CharSequence</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Character</code></td>
-          <td><code>char</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Dates and hours</td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Date</code></td>
-          <td><code>java.util.Date</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Time</code></td>
-          <td><code>java.util.Date</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">DateTime</code></td>
-          <td><code>java.util.Date</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Collections</td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Collection</code></td>
-          <td><code>java.util.Collection</code></td>
-          <td class="leftBorder"></td>
-        </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"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Sequence</code></td>
-          <td><code>java.util.List</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Dictionary</code></td>
-          <td><code>java.util.Map</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">KeyValuePair</code></td>
-          <td><code>java.util.Map.Entry</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Enumerations</td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Enumeration</code></td>
-          <td><code>java.lang.Enum</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">CodeList</code></td>
-          <td>(no equivalent)</td>
-          <td class="leftBorder">See <code>org.opengis.util.CodeList</code> below.</td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Various</td>
-          <td class="leftBorder"></td>
-        </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"></td>
-        </tr>
-      </table>
-
-      <p>
-        The nearest equivalent for <code>CharacterString</code> is the <code>String</code> class,
-        but GeoAPI often uses the <code>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>SIS</abbr> library to provide the same instances of <code>Metadata</code>
-        or <code>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>Metadata</code>).
-      </p>
-      <p>
-        An <code>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>MediumName cdRom  = MediumName.<code class="GeoAPI">CD_ROM;</code>
-MediumName usbKey = MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>"); // There is no constraint on this value.
-assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">CD_ROM</code>")  == cdRom  : "valueOf must return existing constants.";
-assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>") == usbKey : "valueOf must cache the previously requested values.";</code></pre>
-
-
-
-      <h3 id="GeoAPI-implementation">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>org.opengis.referencing.crs.ProjectedCRS</code> is the GeoAPI interface derived from ISO 19111 standard, and</li>
-          <li><code>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>CRSFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code>
-        is almost the same except that <code>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>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>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>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>
   </body>
 </html>

Copied: sis/site/trunk/book/en/annexes/geoapi/ReduceDependency.html (from r1814233, sis/site/trunk/book/en/annex/ReduceDependency.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/geoapi/ReduceDependency.html?p2=sis/site/trunk/book/en/annexes/geoapi/ReduceDependency.html&p1=sis/site/trunk/book/en/annex/ReduceDependency.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/annex/ReduceDependency.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/geoapi/ReduceDependency.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,7 +24,7 @@
   <head>
     <title>ReduceDependency</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--

Copied: sis/site/trunk/book/en/annexes/geoapi/index.html (from r1814233, sis/site/trunk/book/en/annex/Annexes.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/geoapi/index.html?p2=sis/site/trunk/book/en/annexes/geoapi/index.html&p1=sis/site/trunk/book/en/annex/Annexes.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/annex/Annexes.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/geoapi/index.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,7 +24,7 @@
   <head>
     <title>Annexes</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--
@@ -33,12 +33,18 @@
     -->
     <section>
       <header>
-        <h1 id="Annexes">Annexes</h1>
+        <h1 id="GeoAPI-details">GeoAPI relationship with standards</h1>
       </header>
 
+      <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>
+
+      <xi:include href="Modules.html"/>
+      <xi:include href="DefinitionProcess.html"/>
       <xi:include href="ReduceDependency.html"/>
-      <xi:include href="Tests.html"/>
-      <xi:include href="DesignNotes.html"/>
     </section>
   </body>
 </html>

Copied: sis/site/trunk/book/en/annexes/tests/GeoApiConformance.html (from r1814233, sis/site/trunk/book/en/annex/Tests.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/tests/GeoApiConformance.html?p2=sis/site/trunk/book/en/annexes/tests/GeoApiConformance.html&p1=sis/site/trunk/book/en/annex/Tests.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/annex/Tests.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/tests/GeoApiConformance.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,7 +24,7 @@
   <head>
     <title>Tests</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--
@@ -33,17 +33,9 @@
     -->
     <section>
       <header>
-        <h2 id="Tests">Test suites</h2>
+        <h2 id="GeoAPI-conformance">GeoAPI conformance</h2>
       </header>
       <p>
-        In addition to its own tests, Apache SIS uses tests defined by GeoAPI.
-        One advantages is that those tests provide an external source for the definition of expected results
-        (for example the numerical values of coordinates obtained after a map projection).
-        Such external source reduce the risk that some tests are actually anti-regression tests
-        instead of correctness tests.
-        Those tests can also be used by projects other than Apache SIS.
-      </p>
-      <p id="GeoAPI-conformance">
         The <code>geoapi-conformance</code> module provides <i>validators</i>, a JUnit <i>test suite</i>, and <i>report generators</i>
         in the form of <abbr title="Hypertext Markup Language">HTML</abbr> pages.
         This module may be used with any GeoAPI implementation.

Copied: sis/site/trunk/book/en/annexes/tests/index.html (from r1814233, sis/site/trunk/book/en/annex/Annexes.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/annexes/tests/index.html?p2=sis/site/trunk/book/en/annexes/tests/index.html&p1=sis/site/trunk/book/en/annex/Annexes.html&r1=1814233&r2=1814366&rev=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/annex/Annexes.html [UTF-8] (original)
+++ sis/site/trunk/book/en/annexes/tests/index.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -24,7 +24,7 @@
   <head>
     <title>Annexes</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../../content/book/book.css"/>
   </head>
   <body>
     <!--
@@ -33,12 +33,18 @@
     -->
     <section>
       <header>
-        <h1 id="Annexes">Annexes</h1>
+        <h1 id="Tests">Test suites</h1>
       </header>
+      <p>
+        In addition to its own tests, Apache SIS uses tests defined by GeoAPI.
+        One advantages is that those tests provide an external source for the definition of expected results
+        (for example the numerical values of coordinates obtained after a map projection).
+        Such external source reduce the risk that some tests are actually anti-regression tests
+        instead of correctness tests.
+        Those tests can also be used by projects other than Apache SIS.
+      </p>
 
-      <xi:include href="ReduceDependency.html"/>
-      <xi:include href="Tests.html"/>
-      <xi:include href="DesignNotes.html"/>
+      <xi:include href="GeoApiConformance.html"/>
     </section>
   </body>
 </html>

Modified: sis/site/trunk/book/en/index.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/index.html?rev=1814366&r1=1814365&r2=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/index.html [UTF-8] (original)
+++ sis/site/trunk/book/en/index.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -45,12 +45,14 @@
     <main>
       <xi:include href="introduction/Standards.html"/>
       <xi:include href="overview/DataAccess.html"/>
-      <xi:include href="Coverage/coverage.html"/>
-      <xi:include href="Geometry/geometry.html"/>
+      <xi:include href="coverage/Coverage.html"/>
+      <xi:include href="geometry/Geometry.html"/>
       <xi:include href="referencing/Referencing.html"/>
       <xi:include href="storage/Formats.html"/>
       <xi:include href="utility/Utilities.html"/>
-      <xi:include href="annex/Annexes.html"/>
+      <xi:include href="annexes/geoapi/index.html"/>
+      <xi:include href="annexes/tests/index.html"/>
+      <xi:include href="annexes/design/index.html"/>
     </main>
   </body>
 </html>

Modified: sis/site/trunk/book/en/introduction/ConceptualModels.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/introduction/ConceptualModels.html?rev=1814366&r1=1814365&r2=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/introduction/ConceptualModels.html [UTF-8] (original)
+++ sis/site/trunk/book/en/introduction/ConceptualModels.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -301,12 +301,6 @@
           <td></td>
           <td><code>org.apache.sis.io.wkt</code></td>
         </tr><tr>
-          <td><abbr>ISO</abbr> 13249</td>
-          <td></td>
-          <td><i><abbr>SQL</abbr> spatial</i></td>
-          <td></td>
-          <td></td>
-        </tr><tr>
           <td></td>
           <td><s><abbr>OGC</abbr> 01-009</s></td>
           <td><s><i>Coordinate Transformation Services</i></s></td>
@@ -320,6 +314,24 @@
           <td><code>org.apache.sis.coverage</code></td>
         </tr><tr>
           <td></td>
+          <td><abbr>OGC</abbr> 10-092</td>
+          <td><i>NetCDF binary encoding: classic and 64-bit offset format</i></td>
+          <td></td>
+          <td><code>org.apache.sis.storage.netcdf</code></td>
+        </tr><tr>
+          <td></td>
+          <td><abbr>OGC</abbr> 14-084</td>
+          <td><i>Moving features Comma Separated Values (CSV) encoding</i></td>
+          <td></td>
+          <td><code>org.apache.sis.storage</code></td>
+        </tr><tr>
+          <td><abbr>ISO</abbr> 13249</td>
+          <td></td>
+          <td><i><abbr>SQL</abbr> spatial</i></td>
+          <td></td>
+          <td></td>
+        </tr><tr>
+          <td></td>
           <td><abbr>SLD</abbr></td>
           <td><i>Styled Layer Descriptor</i></td>
           <td><code>org.opengis.style</code></td>

Modified: sis/site/trunk/book/en/introduction/GeoAPI.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/introduction/GeoAPI.html?rev=1814366&r1=1814365&r2=1814366&view=diff
==============================================================================
--- sis/site/trunk/book/en/introduction/GeoAPI.html [UTF-8] (original)
+++ sis/site/trunk/book/en/introduction/GeoAPI.html [UTF-8] Sun Nov  5 18:04:32 2017
@@ -112,125 +112,6 @@
         </article>
       </details>
 
-      <p>GeoAPI interfaces are sometime generated from other files provided by <abbr>OGC</abbr>, like <abbr>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>@UML</code> annotations and property files described in the following section.
-      </p>
-
-      <details>
-        <summary>More about the reasons for manual definition of Java interfaces</summary>
-        <article id="SpecificationToInterfaces">
-          <header>
-            <h2>From <abbr>OGC</abbr> specifications to Java interfaces</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>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>UML</abbr> schemas rather than <abbr>XSD</abbr> ones.
-          </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:
-          </p>
-          <ul>
-            <li>
-              <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>API</abbr>.
-                Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common.
-              </p>
-              <div class="example"><p><b>Example:</b>
-                <abbr>XSD</abbr> metadata schemas insert a <code>&lt;gmd:CI_Citation&gt;</code> element
-                inside a <code class="OGC">&lt;gmd:citation&gt;</code>,
-                a <code>&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>
-            <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>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>MD_Identifier</code> becomes the
-                <code>Identifier</code> interface in the <code>org.opengis.metadata</code> package.
-                The <abbr>OGC</abbr> class <code>SC_CRS</code> becomes the <code>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>
-                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>CS_ImageCS</code>,
-                which can only contain <code>CS_CartesianCS</code> and <code>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>CartesianCS</code> interface as a specialization of <code>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>
-              <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>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>
-              <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>MI_Band</code>,
-                which extends the class <code>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>
-        </article>
-      </details>
-
       <p id="GeoAPI-core">
         GeoAPI is composed of many modules.
         The <code>geoapi</code> and <code>geoapi-pending</code> modules
@@ -238,297 +119,9 @@
         The conceptual model will be explained in detail in the chapters describing Apache <abbr>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 GeoAPI modules</summary>
-        <article id="GeoAPI-modules">
-          <h2>GeoAPI modules</h2>
-          <p>
-            The GeoAPI project consists of a standardized part (<code>geoapi</code>)
-            and an experimental part (<code>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>SIS</abbr>),
-            as the <code>geoapi-pending</code> module is never deployed on this central repository.
-            By contrast, certain <abbr>SIS</abbr> development branches may depend on <code>geoapi-pending</code>.
-          </p>
-          <p>
-            GeoAPI modules are:
-          </p>
-          <ul>
-            <li><p>
-              <b><code>geoapi</code></b> — includes interfaces covered by the
-              <a href="http://www.opengeospatial.org/standards/geoapi">GeoAPI standard of the <abbr>OGC</abbr></a>.
-              The final versions of Apache <abbr>SIS</abbr> depend on this module.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-pending</code></b> — contains a
-              <em>copy</em> of all interfaces in the <code>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>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>geoapi</code> standard module when the branches are merged to the trunk.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-conformance</code></b> — includes a JUnit test suite that developers may use to test their implementations.
-            </p></li>
-            <li><p>
-              <b><code>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>geoapi-proj4</code></b> — contains a partial implementation of <code>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>sis-referencing</code> module for certain functions.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-netcdf</code></b> — contains a partial implementation of <code>org.opengis.referencing</code>
-              and <code>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>sis-netcdf</code> module.
-            </p></li>
-            <li><p>
-              <b><code>geoapi-openoffice</code></b> — contains an add-in for the OpenOffice.org office suite.
-            </p></li>
-          </ul>
-        </article>
-      </details>
-
-
-
-      <h3 id="UML-annotation">Explicit mapping given by <code>@UML</code> annotations</h3>
-      <p>
-        For each class, method and constant defined by an <abbr>OGC</abbr> or <abbr>ISO</abbr> standard,
-        GeoAPI indicates its provenance using annotations defined in the <code>org.opengis.annotation</code> package.
-        In particular, the <code>@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>@UML</code> code indicates that the Java interface that follows
-        (<code>ProjectedCRS</code>) is defined using the <code>SC_ProjectedCRS</code> type of <abbr>ISO</abbr> 19111 standard.
-        The second <code>@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>package <code class="GeoAPI">org.opengis.referencing.crs</code>;
-
-/**
- * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface.
- */
-@UML(specification=ISO_19111, identifier="<code class="OGC">SC_ProjectedCRS</code>")
-public interface ProjectedCRS extends GeneralDerivedCRS {
-    /**
-     * Returns the coordinate system, which must be Cartesian.
-     */
-    @UML(obligation=MANDATORY, specification=ISO_19111, identifier="<code class="OGC">coordinateSystem</code>")
-    CartesianCS <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>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>org.opengis.referencing.crs.ProjectedCRS</code> is <code>SC_ProjectedCRS</code>”:
-      </p>
-
-<pre><code>Class&lt;?&gt; type = ProjectedCRS.class;
-System.out.println("Standard name of type " + type.getName() + " is " + 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">Implicit mapping to standard <abbr>JDK</abbr></h3>
-      <p>
-        Some classes and methods have neither an <code>@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"></td>
-        </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"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Number</code></td>
-          <td><code>java.lang.Number</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Texts</td>
-          <td class="leftBorder"></td>
-        </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"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Sequence&lt;Character&gt;</code></td>
-          <td><code>java.lang.CharSequence</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Character</code></td>
-          <td><code>char</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Dates and hours</td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Date</code></td>
-          <td><code>java.util.Date</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Time</code></td>
-          <td><code>java.util.Date</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">DateTime</code></td>
-          <td><code>java.util.Date</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Collections</td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Collection</code></td>
-          <td><code>java.util.Collection</code></td>
-          <td class="leftBorder"></td>
-        </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"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Sequence</code></td>
-          <td><code>java.util.List</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Dictionary</code></td>
-          <td><code>java.util.Map</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">KeyValuePair</code></td>
-          <td><code>java.util.Map.Entry</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Enumerations</td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">Enumeration</code></td>
-          <td><code>java.lang.Enum</code></td>
-          <td class="leftBorder"></td>
-        </tr>
-        <tr>
-          <td><code class="OGC">CodeList</code></td>
-          <td>(no equivalent)</td>
-          <td class="leftBorder">See <code>org.opengis.util.CodeList</code> below.</td>
-        </tr>
-        <tr>
-          <td class="separator" colspan="2">Various</td>
-          <td class="leftBorder"></td>
-        </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"></td>
-        </tr>
-      </table>
-
-      <p>
-        The nearest equivalent for <code>CharacterString</code> is the <code>String</code> class,
-        but GeoAPI often uses the <code>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>SIS</abbr> library to provide the same instances of <code>Metadata</code>
-        or <code>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>Metadata</code>).
-      </p>
-      <p>
-        An <code>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>MediumName cdRom  = MediumName.<code class="GeoAPI">CD_ROM;</code>
-MediumName usbKey = MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>"); // There is no constraint on this value.
-assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">CD_ROM</code>")  == cdRom  : "valueOf must return existing constants.";
-assert MediumName.<code class="GeoAPI">valueOf</code>("<code class="GeoAPI">USB_KEY</code>") == usbKey : "valueOf must cache the previously requested values.";</code></pre>
-
 
 
       <h3 id="GeoAPI-implementation">Implementations provided by Apache SIS</h3>



Mime
View raw message