You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2016/05/26 00:52:22 UTC
svn commit: r1745551 [1/7] - in /sis/site/trunk: book/en/ book/fr/
content/book/ content/book/en/ content/book/fr/
Author: desruisseaux
Date: Thu May 26 00:52:22 2016
New Revision: 1745551
URL: http://svn.apache.org/viewvc?rev=1745551&view=rev
Log:
Reorganize the chapter about GeoAPI by moving some content into "details" box,
and moving information about implementation-independence and test suites in separated chapters.
Added:
sis/site/trunk/book/en/implementation-independence.html
- copied, changed from r1743965, sis/site/trunk/book/en/geoapi.html
sis/site/trunk/book/en/test.html
- copied, changed from r1743965, sis/site/trunk/book/en/geoapi.html
sis/site/trunk/book/fr/implementation-independence.html
- copied, changed from r1743965, sis/site/trunk/book/fr/geoapi.html
sis/site/trunk/book/fr/test.html
- copied, changed from r1743965, sis/site/trunk/book/fr/geoapi.html
Modified:
sis/site/trunk/book/en/body.html
sis/site/trunk/book/en/geoapi.html
sis/site/trunk/book/en/introduction.html
sis/site/trunk/book/fr/body.html
sis/site/trunk/book/fr/geoapi.html
sis/site/trunk/book/fr/introduction.html
sis/site/trunk/content/book/book.css
sis/site/trunk/content/book/en/developer-guide.html
sis/site/trunk/content/book/fr/developer-guide.html
Modified: sis/site/trunk/book/en/body.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/body.html?rev=1745551&r1=1745550&r2=1745551&view=diff
==============================================================================
--- sis/site/trunk/book/en/body.html (original)
+++ sis/site/trunk/book/en/body.html Thu May 26 00:52:22 2016
@@ -48,6 +48,8 @@
<xi:include href="utility.html"/>
<xi:include href="geometry.html"/>
<xi:include href="coverage.html"/>
+ <xi:include href="implementation-independence.html"/>
+ <xi:include href="test.html"/>
</main>
</body>
</html>
Modified: sis/site/trunk/book/en/geoapi.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/geoapi.html?rev=1745551&r1=1745550&r2=1745551&view=diff
==============================================================================
--- sis/site/trunk/book/en/geoapi.html (original)
+++ sis/site/trunk/book/en/geoapi.html Thu May 26 00:52:22 2016
@@ -59,164 +59,244 @@
</p></li>
</ul>
- <article>
- <header>
- <h1>GeoAPI project history</h1>
- </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>
-
- <h2 id="SpecificationToInterfaces">Interface Specifications</h2>
- <p>
- Since <abbr>OGC</abbr> standards are defined by well-tested software engineering methods,
- it is possible to automatically generate Java interfaces using relatively common 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>
+ <details>
+ <summary>More about the GeoAPI project</summary>
+ <article>
+ <header>
+ <h1>GeoAPI project history</h1>
+ </header>
<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.
+ 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>
- <div class="example"><p><b>Example:</b>
- <abbr>XSD</abbr> metadata schemas insert a <code><gmd:CI_Citation></code> element
- inside a <code class="OGC"><gmd:citation></code>,
- a <code><gmd:CI_OnlineResource></code> element inside a <code class="OGC"><gmd:onlineResource></code>,
- and so on for the hundreds of classes defined by <abbr>ISO</abbr> 19115 standard.
- This redundancy is certainly not necessary in a Java program.
- </p></div>
- </li>
- <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>
+ </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>
+ <h1>From <abbr>OGC</abbr> specifications to Java interfaces</h1>
+ </header>
<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.
+ 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>
- <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>
+ <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><gmd:CI_Citation></code> element
+ inside a <code class="OGC"><gmd:citation></code>,
+ a <code><gmd:CI_OnlineResource></code> element inside a <code class="OGC"><gmd:onlineResource></code>,
+ and so on for the hundreds of classes defined by <abbr>ISO</abbr> 19115 standard.
+ This redundancy is certainly not necessary in a Java program.
+ </p></div>
+ </li>
+ <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>Exemple:</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">
+ <h1>GeoAPI Modules</h1>
<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.
+ 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>
- <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.
+ GeoAPI modules are:
</p>
- <div class="example"><p><b>Exemple:</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>
- <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>@UML</code> annotations and property files described in the following section.
- </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>jdk6</code>, <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.
+ <!--
+ Apache <abbr>SIS</abbr> offers its own add-in in the <code>sis-openoffice</code> module,
+ but uses the same function names as the GeoAPI module in order to maintain some compatibility.
+ -->
+ </p></li>
+ </ul>
+ </article>
+ </details>
- <h3 id="UML-annotation">Mapping Given by <code>@UML</code> Annotations</h3>
+ <h2 id="UML-annotation">Mapping Given by <code>@UML</code> Annotations</h2>
<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.
@@ -234,15 +314,12 @@
/**
* 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>")
+@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>")
+ @UML(obligation=MANDATORY, specification=ISO_19111, identifier="<code class="OGC">coordinateSystem</code>")
CartesianCS <code class="GeoAPI">getCoordinateSystem()</code>;
}</pre>
@@ -250,39 +327,19 @@ public interface ProjectedCRS extends Ge
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.
- The following example displays the standard name for the method <code class="GeoAPI">getTitle()</code> from the <code>Citation</code> interface:
+ 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>Class<?> type = Citation.class;
-Method method = type.getMethod("<code class="GeoAPI">getTitle</code>", (Class<?>[]) null);
-UML annot = method.getAnnotation(UML.class);
-String id = annot.identifier();
-System.out.println("The standard name for the " + method.getName() + " method is " + id);</pre>
+<pre>Class<?> type = ProjectedCRS.class;
+System.out.println("Standard name of type " + type.getName() + " is " + Types.getStandardName(type));</pre>
<p>
- The class <code>org.apache.sis.util.iso.Types</code> provides the
- <code class="SIS">getStandardName(Class)</code> convenience method to perform this operation.
- </p>
-
- <p>
- The reverse operation — getting the Java class and method from a standard name — is a bit more complicated.
- It requires reading the <code class="GeoAPI">class-index.properties</code> file provided in the <code>org.opengis.annotation</code> package.
- The following example reads the files just before searching for the name of the interface corresponding to <code>CI_Citation</code>.
- Users are always encouraged to only read this file once and then save its contents in their application's cache.
- </p>
-
-<pre>Properties isoToGeoAPI = new Properties();
-try (InputStream in = UML.class.getResourceAsStream("<code class="GeoAPI">class-index.properties</code>")) {
- isoToGeoAPI.load(in);
-}
-String isoName = "<code class="OGC">CI_Citation</code>";
-String geoName = getProperty(isoName);
-Class<?> type = Class.forName(geoName);
-System.out.println("The GeoAPI interface for <abbr>ISO</abbr> type " + isoName + " is " + type);</pre>
-
- <p>
- The class <code>org.apache.sis.util.iso.Types</code> provides the
- <code class="SIS">forStandardName(String)</code> convenience method to perform this operation.
+ 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>
@@ -472,353 +529,46 @@ assert MediumName.<code class="GeoAPI">v
- <h2 id="ServiceLoader">Fetching an Implementation of the Interfaces</h2>
- <p>
- GeoAPI defines factories (<code>Factory</code>) that can create implementations of interfaces.
- For example, <code>DatumFactory</code> provides methods that can create instances which implement interfaces of the
- <code>org.opengis.referencing.datum</code> package.
- A <code>Factory</code> must be implemented by a geospatial library,
- and declared as a <i>service</i> as defined by the <code>java.util.ServiceLoader</code> class.
- The <code>ServiceLoader</code> javadoc explains this procedure.
- In brief, the library must create a file in the <code>META-INF/services/</code> directory,
- with a name corresponding to the complete name of an interface in the factory
- (in the preceding example, <code>org.opengis.referencing.datum.DatumFactory</code>).
- On one line, this text file must include the complete name of the class that implements this interface.
- This class may be hidden from users, as they do not need to know of its existence.
- </p>
- <p>
- If the library has correctly declared its factories as services,
- users may import them by using <code>ServiceLoader</code>, as in the example below.
- This example only takes the first factory located; if there is more than one factory -
- for example when multiple libraries coexist — then the choice is left to the user.
- </p>
-
-<pre>import org.opengis.referencing.GeodeticDatum;
-import org.opengis.referencing.DatumFactory;
-import java.util.ServiceLoader;
-
-public class MyApplication {
- public void createMyDatum() {
- ServiceLoader loader = ServiceLoader.load(DatumFactory.class);
- DatumFactory factory = loader.iterator().next();
- GeodeticDatum myDatum = factory.<code class="GeoAPI">createGeodeticDatum</code>(…);
- }
-}</pre>
-
-
-
- <h3 id="GeoAPI-simple">Defining Custom Implementations</h3>
- <p>
- Implementing GeoAPI oneself in order to meet very specific needs is not difficult.
- A developer might concentrate on a handful of interfaces among the hundreds available,
- while keeping other interfaces as extension points to eventually implement as needed.
- </p>
+ <h2 id="GeoAPI-implementation">Interface implementations</h2>
<p>
- The conceptual model that the interfaces represent is complex. But this complexity may be reduced by combining certain interfaces.
- For example, many libraries, even well-known ones, do not distinguish between a <cite>Coordinate System</cite> (<abbr>CS</abbr>)
- and a <cite>Coordinate <u>Reference</u> System</cite> (<abbr>CRS</abbr>).
- A developer that also wishes not to make this distinction may implement these two interfaces with the same class.
- The resulting implementation may have a simpler class hierarchy than that of GeoAPI interfaces.
- The <code>geoapi-examples</code> module, discussed later, provides such combinations.
- The following table lists a few possible combinations:
- </p>
- <table>
- <tr>
- <th>Main Interface</th>
- <th>Auxiliary Interface</th>
- <th>Use</th>
- </tr>
- <tr>
- <td><code>CoordinateReferenceSystem</code></td>
- <td><code>CoordinateSystem</code></td>
- <td>Description of a spatial reference system (<abbr>CRS</abbr>).</td>
- </tr>
- <tr>
- <td><code>GeodeticDatum</code></td>
- <td><code>Ellipsoid</code></td>
- <td>Description of the geodetic datum.</td>
- </tr>
- <tr>
- <td><code>CoordinateOperation</code></td>
- <td><code>MathTransform</code></td>
- <td>Coordinate transformation operations.</td>
- </tr>
- <tr>
- <td><code>IdentifiedObject</code></td>
- <td><code>ReferenceIdentifier</code></td>
- <td>An objet (usually a <abbr>CRS</abbr>) that we can identify by a code.</td>
- </tr>
- <tr>
- <td><code>Citation</code></td>
- <td><code>InternationalString</code></td>
- <td>Bibliographic reference consisting of a simple title.</td>
- </tr>
- <tr>
- <td><code>GeographicBoundingBox</code></td>
- <td><code>Extent</code></td>
- <td>Spatial area in degrees of longitude and latitude.</td>
- </tr>
- <tr>
- <td><code>ParameterValue</code></td>
- <td><code>ParameterDescriptor</code></td>
- <td>Description of a parameter (name, type) associated with its value.</td>
- </tr>
- <tr>
- <td><code>ParameterValueGroup</code></td>
- <td><code>ParameterDescriptorGroup</code></td>
- <td>Description of a set of parameters associated with their values.</td>
- </tr>
- </table>
-
-
-
- <h2 id="GeoAPI-modules">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>jdk6</code>, <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.
- <!--
- Apache <abbr>SIS</abbr> offers its own add-in in the <code>sis-openoffice</code> module,
- but uses the same function names as the GeoAPI module in order to maintain some compatibility.
- -->
- </p></li>
- </ul>
-
- <h3 id="GeoAPI-core">The Interfaces' Definition Modules</h3>
- <p>
- <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>
-
-
-
- <h3 id="GeoAPI-conformance">The Conformance Tests Module</h3>
- <p>
- 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.
- For developers of a geospatial library, it offers the following advantages:
- </p>
- <ul>
- <li>Reduces the tedious task of writing tests by using existing tests.</li>
- <li>Increases confidence in the validity of tests,
- since <code>geoapi-conformance</code> has its own test suite and is applied to other implementations.</li>
- <li>Facilitates comparison with other implementations.</li>
- </ul>
-
-
-
- <h4 id="GeoAPI-validators">Instance Validations</h4>
- <p>
- GeoAPI can validate an instance of its interfaces by checking that certain constraints are observed.
- Many constraints can not be expressed in the method signature. Those constraints
- are usually described textually in the abstract specifications or in the javadoc.
- </p>
- <div class="example"><p><b>Example:</b>
- A coordinate conversion or transformation (<code>CC_CoordinateOperation</code>) may require a sequence of several steps.
- In such a sequence of operations (<code>CC_ConcatenatedOperation</code>), for each step (<code>CC_SingleOperation</code>)
- the number of output dimensions must equal the number of input dimensions in the next operation.
- Expressed in Java, this constraint stipulates that for the entire index 0 < <var>i</var> < <var>n</var> where <var>n</var>
- is the number of operations, we have <code>coordOperation[i].targetDimensions == coordOperation[i-1].sourceDimensions</code>.
- </p></div>
-
- <p>
- The easiest way to perform these verifications is to call the static methods <code class="GeoAPI">validate(…)</code>
- of the <code>org.opengis.test.Validators</code> class.
- As all of <code>Validators</code> methods bear the same name, it is enough to write “<code>validate(<var>value</var>)</code>”
- and then let the compiler choose the most appropriate method for the type of object given in argument.
- If the object type is not known at the time of compilation,
- the <code class="GeoAPI">dispatch(Object)</code> method can be invoked for redirecting the work to the most appropriate <code class="GeoAPI">validate(…)</code> method.
- </p>
- <p>
- All <code class="GeoAPI">validate(…)</code> functions follow a chain of dependencies,
- meaning that they will also validate each component of the object to be validated.
- For example, the validation of a <code>GeographicCRS</code> implies the validation of its component
- <code>GeodeticDatum</code>, which itself implies the validation of its component <code>Ellipsoid</code>, and so on.
- Thus it is unnecessary to validate the components explicitely, unless the developer wishes to isolate the test for a particular item known to cause problems.
- </p>
- <p>
- By default, validations are as strict as possible. It is always possible to relax certain rules.
- The most common is to tolerate the absence of attributes that would normally be mandatory.
- This rule and a few others may be modified globally for all tests executed by the currently running <abbr title="Java Virtual Machine">JVM</abbr>,
- as in the following example:
- </p>
-
-<pre>import org.opengis.metadata.Metadata;
-import org.opengis.test.Validators;
-import org.junit.Test;
-
-public class MyTest {
- /*
- * Tolerate the absence of mandatory attributes in metadata and citation packages.
- * This modification applies to all tests executed by the currently running <abbr>JVM</abbr>.
- * If there are multiple test classes, this initialization may be performed
- * in a parent class to all test classes.
- */
- static {
- Validators.<code class="GeoAPI">DEFAULT.metadata.requireMandatoryAttributes</code> = false;
- Validators.<code class="GeoAPI">DEFAULT.citation.requireMandatoryAttributes</code> = false;
- }
-
- @Test
- public void testMyMetadata() {
- Metadata myObject = …; // Create an object here.
- Validators.<code class="GeoAPI">validate</code>(myObject);
- }
-}</pre>
-
- <p>
- Rules may also be modified for a particular test suite without affecting the default configuration of the standard <abbr>JVM</abbr>.
- This approach requires the creation of a new instance of the validator that we wish to modify the configuration.
- </p>
-
-<pre>import org.opengis.metadata.Metadata;
-import org.opengis.test.ValidatorContainer;
-import org.junit.Test;
-
-public class MyTest {
- private final ValidatorContainer validators;
-
- public MyTest() {
- validators = new ValidatorContainer();
- validators.<code class="GeoAPI">metadata.requireMandatoryAttributes</code> = false;
- validators.<code class="GeoAPI">citation.requireMandatoryAttributes</code> = false;
- }
-
- @Test
- public void testMyMetadata() {
- Metadata myObject = …; // Create an object here.
- validators.<code class="GeoAPI">validate</code>(myObject);
- }
-}</pre>
-
-
-
- <h4 id="GeoAPI-tests">Executing Pre-defined Tests</h4>
- <p>
- JUnit tests are defined in the <code>org.opengis.test</code> sub-packages.
- All test classes bear a name ending in "<code>Test</code>".
- GeoAPI also provides an <code>org.opengis.test.TestSuite</code> class including all test classes defined in the
- <code>geoapi-conformance</code> module, but Apache <abbr>SIS</abbr> does not use it.
- Instead, Apache <abbr>SIS</abbr> inherits GeoAPI's <code class="GeoAPI">*Test</code> classes on a case-by-case basis,
- in the appropriate modules.
- The example below gives an example of a customized GeoAPI test:
- The <a href="http://www.geoapi.org/geoapi-conformance/apidocs/org/opengis/test/referencing/ParameterizedTransformTest.html">parent test javadoc</a>
- documents the tests performed in detail.
- In this example, only one test is modified and all the others are inherited as they are (it is not necessary to repeat them in the sub-class).
- However, this example adds a supplemental verification, annotated with <code>@After</code>, which will be executed after each test.
- </p>
-
-<pre>import org.junit.*;
-import org.junit.runner.RunWith;
-import org.junit.runners.JUnit4;
-import org.opengis.test.referencing.ParameterizedTransformTest;
-import static org.junit.Assert.*;
-
-@RunWith(JUnit4.class)
-public class MyTest extends ParameterizedTransformTest {
- /**
- * Specify our own coordinate transformation factory for the GeoAPI tests.
- * GeoAPI will test the objects created by this factory.
- */
- public MyTest() {
- super(new MyMathTransformFactory());
- }
-
- /**
- * Changes the behaviour of a test. This example relaxes the requirements of this test a little,
- * by accepting errors of up to 10 centimetres, rather than the default value of 1 cm.
- * This change only applies to this method, and does not affect the other inherited tests.
- */
- @Test
- @Override
- public void testLambertAzimuthalEqualArea() throws FactoryException, TransformException {
- <code class="GeoAPI">tolerance</code> = 0.1; // 10 cm tolerance.
- super.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>;
- }
-
- /**
- * Supplemental verification performed after each test, inherited or not.
- * In this example, we are verifying that the transformation tested
- * works correctly in two-dimensional spaces.
- */
- @After
- public void ensureAllTransformAreMath2D() {
- assertTrue(<code class="GeoAPI">transform</code> instanceof MathTransform2D);
- }
-}</pre>
-
-
-
- <h3 id="GeoAPI-examples">Example Modules</h3>
- <p>
- The <code>geoapi-examples</code> module provides examples of simple implementations.
- Many of these classes implement more than one interface at a time in order to provide a simpler conceptual model.
- The <a href="http://www.geoapi.org/geoapi-examples/apidocs/overview-summary.html">javadoc for this module</a>
- lists key packages and classes along with the combinations performed.
- This module illustrates not only how GeoAPI might be implemented,
- but also how the implementation might be tested using <code>geoapi-conformance</code>.
- </p>
- <p>
- Although its primary goal is to serve as a source of inspiration for implementors,
- <code>geoapi-examples</code> was also designed so as to be usable by applications with very simple needs.
- As all the examples are in the public domain, developers are invited to freely adapt copies of these classes as necessary.
- However, if changes are made outside the framework of the GeoAPI project,
- fair use demands that modified copies be placed in a package with a different name than <code>org.opengis</code>.
- </p>
- <p>
- For somewhat more involved needs, developers are invited to examine the
- <code>geoapi-proj4</code> and <code>geoapi-netcdf</code> modules.
- These two modules provide examples of adaptors that are allowed, via GeoAPI interfaces,
- to use some of the features of external libraries (Proj.4 and <abbr>NetCDF</abbr>).
- The advantage of using these interfaces is to provide a unified model to operate two very different <abbr>API</abbr>s,
- while retaining the ability to switch easily to another library if desired.
+ 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>
</body>
</html>