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>
