Author: desruisseaux
Date: Sun Oct 5 05:49:32 2014
New Revision: 1629468
URL: http://svn.apache.org/r1629468
Log:
Edition: replaced some words by expressions commonly found in Java and SIS
domain:
E.g. data collection, coordinate reference system, core, package, etc.
Modified:
sis/site/trunk/content/book/en/developer-guide.html
sis/site/trunk/content/book/fr/developer-guide.html
Modified: sis/site/trunk/content/book/en/developer-guide.html
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/book/en/developer-guide.html?rev=1629468&r1=1629467&r2=1629468&view=diff
==============================================================================
--- sis/site/trunk/content/book/en/developer-guide.html [UTF-8] (original)
+++ sis/site/trunk/content/book/en/developer-guide.html [UTF-8] Sun Oct 5
05:49:32 2014
@@ -52,10 +52,10 @@
</ul></li>
<li><a href="#GeoAPI">GeoAPI</a><ul>
<li><a href="#SpecificationToInterfaces">Interface Specifications</a><ul>
- <li><a href="#UML-annotation">Correspondences Explained in
<code>@UML</code> Annotations</a></li>
- <li><a href="#MappingToJDK">Implicit Correspondences to Standard
<abbr>JDK</abbr></a></li>
+ <li><a href="#UML-annotation">Mapping Given by <code>@UML</code>
Annotations</a></li>
+ <li><a href="#MappingToJDK">Implicit Mapping to Standard
<abbr>JDK</abbr></a></li>
</ul></li>
- <li><a href="#ServiceLoader">Importing an Implementation of the
Interfaces</a><ul>
+ <li><a href="#ServiceLoader">Fetching an Implementation of the
Interfaces</a><ul>
<li><a href="#GeoAPI-simple">Providing the Correct
Implementation</a></li>
</ul></li>
<li><a href="#GeoAPI-modules">GeoAPI Modules</a><ul>
@@ -101,17 +101,17 @@
A geospatial information community is a collection of systems or individuals
capable of exchanging their geospatial data
through the use of common standards, allowing them to communicate with one
another.
As there are many ways to represent geospatial information, each community
tends to structure this information in light of its areas of interest.
- This diversity complicates the task of the users of (<abbr>SIS</abbr>)
- geographic information systems by confronting them with an apparently
chaotic variety of data formats and structures.
- The characteristics of these structures vary according to the phenomenon
observed and methods of measurement,
+ This diversity complicates the task of Spatial Information System
(<abbr>SIS</abbr>) users
+ by confronting them with an apparently chaotic variety of data formats and
structures.
+ The characteristics of these structures vary according to the observed
phenomenon and measurement methods,
as well as the habits of the organizations producing the data.
Such a variety represents an obstacle in studies that require heterogeneous
combinations of data,
especially when they originate in communities that are traditionally
distinct.
For example, a researcher studying cholera might be interested in
populations of shrimp as a propagation vector of the disease.
- But as doctors and oceanographers are not usually in the habit of sharing
their work,
+ But as doctors and oceanographers may not be used to share their work,
the participants of such a study may be limited by the effort required to
convert the data.
</p><p>
- We cannot impose a uniform format on all the collections of data, as the
diversity of formats is tied to factors such as the constraints imposed by the
measuring apparatus,
+ We cannot impose a uniform format on all data collections, as the diversity
of formats is tied to factors such as the constraints imposed by the measuring
apparatus,
and the statistical distribution of values.
A more flexible solution is to ensure the interoperability of data across a
common programming interface
(<abbr title="Application Programming Interface">API</abbr>).
@@ -120,7 +120,7 @@
But in order for this approach to be viable, the <abbr>API</abbr> must be
generally accepted by independent developers.
In other words, the <abbr>API</abbr> must come as near as possible to
industrial standards.
</p><p>
- For example, one task that would benefit from a successful standardization
is the accessing of relational databases.
+ For example, one task that benefit from a successful standardization is the
accessing of relational databases.
The industry has established a common language — the <abbr title="Structured
Query Language">SQL</abbr> standard — that the creators of Java
have embedded in standard <abbr title="Java DataBase
Connectivity">JDBC</abbr> programming interfaces.
Today, these interfaces are implemented by many software programs, both free
and commercial.
@@ -135,15 +135,15 @@
In general, complying with standards demands a greater effort than would be
required for an isolated development,
but rewards us with a double advantage: not only does it improve the
interoperability of our data with that of external projects,
it also points towards a robust way of elaborating the conceptual model
reflected in the <abbr title="Application Programming Interface">API</abbr>.
- In effect, the groups of experts who conceived of the standards anticipated
difficulties that sometimes escape the engineer at the beginning of a project,
- but which risk catching up with them before the end.
+ In effect, the groups of experts who conceived the standards anticipated
difficulties that sometimes escape the engineer at the beginning of a project,
+ but which risk to hit them before the end.
</p>
<h2 id="About">Conventions Used in This Guide</h2>
<p>
- The elements defined in an information language, such as classes and methods
in Java or elements in an <abbr>XML</abbr> document,
+ The elements defined in a computer language, such as classes and methods in
Java or elements in an <abbr>XML</abbr> document,
appear in monospaced font.
In order to facilitate an understanding of the relationships between Apache
<abbr>SIS</abbr> and the standards, these elements are also represented using
the following colour codes:
</p>
@@ -166,6 +166,9 @@
Example: <code>String</code>.
</li>
</ul>
+<p>
+ Text in gray boxes are for information purpose only and can be ignored.
+</p>
@@ -193,8 +196,8 @@
</p><p>
Besides these formal standardization organizations, there are organizations
that are not officially dedicated
to the creation of standards, but whose work has largely been adopted as
<i>de facto</i> standards.
- In particular, the <a href="http://www.epsg.org";>EPSG</a> database offers
numeric codes which allow the easy identification of coordinates among
- <a href="../sis-referencing/supported-codes.html">several thousand</a>.
+ In particular, the <a href="http://www.epsg.org";>EPSG</a> database offers
numeric codes which allow the easy identification of a
+ Coordinates Reference System (<abbr>CRS</abbr>) among <a
href="../sis-referencing/supported-codes.html">several thousand</a>.
This database is offered by petroleum companies that have an interest in
ensuring their explorations are conducted in the correct place,
even when using map produced by another party.
Other examples of <i>de facto</i> standards include <a
href="http://geotiff.osgeo.org";>GeoTIFF</a> for data distributed on a grid
(such as images),
@@ -238,11 +241,12 @@
even if those opposed are in a minority.
The decisions of the group are then integrated into the specifications by a
member who assumes the role of editor.
</p><p>
- As far as possible, the working group must structure the specifications as a
nucleus around which various extensions might be built.
+ As far as possible, the working group must structure the specifications as a
core around which various extensions might be built.
A series of tests must accompany the standard, allowing implementations to
be classified by the level of test passed.
There must be at least one <i>reference implementation</i> that passes all
the tests in order to demonstrate that the standard is usable.
</p><p>
- When the standard is judged ready, the <abbr title="Standard Working
Group">SWG</abbr> votes on a motion proposing its submission to a vote of the
higher authorities of the <abbr title="Open Geospatial Consortium">OGC</abbr>.
+ When the standard is considered ready, the <abbr title="Standard Working
Group">SWG</abbr> votes on a motion
+ proposing its submission to a vote by the higher authorities of the <abbr
title="Open Geospatial Consortium">OGC</abbr>.
This process takes several months.
There is a faster process for approving <i>de facto</i> standards, but it is
applied sparingly.
</p>
@@ -253,7 +257,7 @@
All proposals for standards are first examined by the <abbr title="Open
Geospatial Consortium">OGC</abbr> Architecture Board (<abbr>OAB</abbr>).
This board ensures that the standard conforms to the requirements of the
<abbr title="Open Geospatial Consortium">OGC</abbr> in form,
modularization, and in terms of integration with other standards.
- If the <abbr>OAB</abbr> approves it, the standard is next submitted to a
vote of the members of the Technical Committee (<abbr title="Technical
Committee">TC</abbr>).
+ If the <abbr>OAB</abbr> approves it, the standard is next submitted to a
vote by the members of the Technical Committee (<abbr title="Technical
Committee">TC</abbr>).
This committee consists of the principal members of the <abbr>OGC</abbr>,
and only they are capable of granting final approval.
If approved, the standard is made publicly available for comments during a
period of several months.
At the end of this period, the <abbr title="Standard Working
Group">SWG</abbr> must examine and respond to each comment.
@@ -262,7 +266,7 @@
</p><p>
Certain members of the <abbr title="Open Geospatial Consortium">OGC</abbr>
and the <abbr title="Technical Committee">TC</abbr> also act as liaisons with
the International Organization for Standardization (<abbr title="International
Organization for Standardization">ISO</abbr>).
Cooperation between the two organizations goes two ways: the
<abbr>OGC</abbr> adopts the <abbr>ISO</abbr> standards as a foundation on which
to develop new standards,
- and certain new <abbr>OGC</abbr> standards become <abbr>ISO</abbr> standards.
+ and certain <abbr>OGC</abbr> standards become <abbr>ISO</abbr> standards.
</p>
@@ -287,9 +291,9 @@
<abbr title="Open Geospatial Consortium">OGC</abbr> standards are specified
in several dozen documents.
Each document outlines a service — for example, the transformation of
coordinates.
The function of each service is described by a collection of object classes
and their interactions.
- These elements are illustrated by <abbr>UML</abbr> (Unified Modeling
Language) diagrams in specifications called “abstracts.”
+ These elements are illustrated by <abbr>UML</abbr> (Unified Modeling
Language) diagrams in specifications called “abstracts”.
</p><p>
- <a href="http://www.opengeospatial.org/standards/as";>Abstract
specifications</a> do not refer to any specific information language.
+ <a href="http://www.opengeospatial.org/standards/as";>Abstract
specifications</a> do not refer to any specific computer language.
Their concepts may be applied more or less directly to a programming
language, a database or an <abbr>XML</abbr> schema.
There is always an element of arbitrariness in the method of applying an
abstract specification,
given that adjustments are often necessary to take into account the
constraints or conventions of the target language. For example:
@@ -310,13 +314,13 @@
<p>
At the turn of the millennium, the abstract specifications were explicitly
concretized in <i>implementation specifications</i>.
The term “implementation” is used here in the sense of all types of
interfaces (Java or others) derived from <abbr title="Unified Modeling
Language">UML</abbr> diagrams, and not implementations in the Java sense.
- Such specifications exist for <abbr title="Structured Query
Language">SQL</abbr>, <abbr title="Common Object Request Broker
Architecture">CORBA</abbr>, <abbr title="Component Object Model">COM</abbr>,
and Java languages.
+ Such specifications existed for <abbr title="Structured Query
Language">SQL</abbr>, <abbr title="Common Object Request Broker
Architecture">CORBA</abbr>, <abbr title="Component Object Model">COM</abbr>,
and Java languages.
As these languages are capable of executing procedures, the specifications
of this period define not only data structures,
but also operations that apply to these structures.
</p><p>
- Thereafter, enthusiasm for “Web 2.0” increased interest <abbr>XML</abbr>
over other languages.
+ Thereafter, enthusiasm for “Web 2.0” increased interest for <abbr>XML</abbr>
over other languages.
Older implementation specifications were deprecated,
- and <abbr title="XML Schema Definition">XSD</abbr> schemas became the
principle concretization of abstract specifications.
+ and <abbr title="XML Schema Definition">XSD</abbr> schemas became the main
concretization of abstract specifications.
Even the way abstract specifications are designed has evolved: they are less
likely to define operations, and so what remains is closer to descriptions of
database schemas.
Some operations that were defined in older standards now appear, in another
form, in web service specifications.
Finally, the term “implementation specification” has been deprecated, to be
subsumed under the term “<abbr title="Open Geospatial Consortium">OGC</abbr>
standard.”
@@ -336,9 +340,9 @@
</ul>
<p>
The Apache <abbr title="Spatial Information System">SIS</abbr> project is
based on the most recent specifications, drawing from the archives of the <abbr
title="Open Geospatial Consortium">OGC</abbr> to complete certain abstract
standards or make them more usable.
- Some old definitions are preserved as “methods of convenience,” not always
bringing new functionality, but facilitating the practical use of a library.
+ Some old definitions are preserved as “convenience methods”, not always
bringing new functionality, but facilitating the practical use of a library.
</p><p>
- The following table lists the principal norms used by the project.
+ The following table lists the main norms used by the project.
Many norms are published both as <abbr title="International Organization for
Standardization">ISO</abbr> standards and as
<abbr title="Open Geospatial Consortium">OGC</abbr> standards, and their
corresponding names are listed next to one another in the first two columns.
Standards that are deprecated but still used appear <s>struck through</s>.
@@ -351,141 +355,163 @@
<th><abbr>OGC</abbr> Norm</th>
<th>Titre</th>
<th>GeoAPI package</th>
+ <th>Apache SIS package</th>
</tr>
<tr>
- <td class="separator" colspan="4">Abstract Specifications</td>
+ <td class="separator" colspan="5">Abstract Specifications</td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19103</td>
<td></td>
<td><i>Conceptual schema language</i></td>
<td><code>org.opengis.util</code></td>
+ <td><code>org.apache.sis.util.iso</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19115</td>
<td>Topic 11</td>
<td><i>Metadata</i></td>
<td><code>org.opengis.metadata</code></td>
+ <td><code>org.apache.sis.metadata.iso</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19111</td>
<td>Topic 2</td>
<td><i>Spatial referencing by coordinates</i></td>
<td><code>org.opengis.referencing</code></td>
+ <td><code>org.apache.sis.referencing</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19108</td>
<td></td>
<td><i>Temporal Schema</i></td>
<td><code>org.opengis.temporal</code></td>
+ <td></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19107</td>
<td>Topic 1</td>
<td><i>Feature geometry</i></td>
<td><code>org.opengis.geometry</code></td>
+ <td><code>org.apache.sis.geometry</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19101</td>
<td>Topic 5</td>
<td><i>Features</i></td>
<td><code>org.opengis.feature</code></td>
+ <td><code>org.apache.sis.feature</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19123</td>
<td>Topic 6</td>
<td><i>Schema for coverage geometry and functions</i></td>
<td><code>org.opengis.coverage</code></td>
+ <td><code>org.apache.sis.coverage</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19156</td>
<td>Topic 20</td>
<td><i>Observations and measurements</i></td>
<td><code>org.opengis.observation</code></td>
+ <td></td>
</tr>
<tr>
- <td class="separator" colspan="4">Implementation Specifications</td>
+ <td class="separator" colspan="5">Implementation Specifications</td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19139</td>
<td></td>
<td><i>Metadata <abbr>XML</abbr> schema implementation</i></td>
<td></td>
+ <td><code>org.apache.sis.xml</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 13249</td>
<td></td>
<td><i><abbr>SQL</abbr> spatial</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><s><abbr>OGC</abbr> 01-009</s></td>
<td><s><i>Coordinate Transformation Services</i></s></td>
<td><code>org.opengis.referencing</code></td>
+ <td><code>org.apache.sis.referencing</code></td>
</tr>
<tr>
<td></td>
<td><s><abbr>OGC</abbr> 01-004</s></td>
<td><s><i>Grid Coverage</i></s></td>
<td><code>org.opengis.coverage</code></td>
+ <td><code>org.apache.sis.coverage</code></td>
</tr>
<tr>
<td></td>
<td><abbr>SLD</abbr></td>
<td><i>Styled Layer Descriptor</i></td>
<td><code>org.opengis.style</code></td>
+ <td></td>
</tr>
<tr>
- <td class="separator" colspan="4">Web Services</td>
+ <td class="separator" colspan="5">Web Services</td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19128</td>
<td><abbr>WMS</abbr></td>
<td><i>Web Map Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>WMTS</abbr></td>
<td><i>Web Map Tile Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19142</td>
<td><abbr>WFS</abbr></td>
<td><i>Web Feature Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>WCS</abbr></td>
<td><i>Web Coverage Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>WPS</abbr></td>
<td><i>Web Processing Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td>Open<abbr>LS</abbr></td>
<td><i>Location Services</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>SWE</abbr></td>
<td><i>Sensor Web Enablement</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>SOS</abbr></td>
<td><i>Sensor Observation Service</i></td>
<td></td>
+ <td></td>
</tr>
</table>
@@ -516,8 +542,8 @@
<p>
The <a href="http://www.geoapi.org";>GeoAPI</a> project offers a set of Java
interfaces for geospatial applications.
In a series of <code class = "GeoAPI"> org.opengis.*</code> packages, GeoAPI
defines structures representing metadata,
- reference systems of coordinates and operations that perform cartographic
projections.
- In one part that is not yet standardized — called <i>pending</i> — GeoAPI
defines structures that represent geo-referenced images,
+ coordinate reference systems and operations that perform cartographic
projections.
+ In a part that is not yet standardized — called <i>pending</i> — GeoAPI
defines structures that represent geo-referenced images,
geometries, filters that can be applied to queries, and other features.
These interfaces closely follow the specifications of the <abbr title =
"Open Geospatial Consortium">OGC</abbr>,
while interpreting and adapting them to meet the needs of Java developers —
for example, conforming with naming conventions.
@@ -549,21 +575,23 @@
<p><b>History</b></p>
<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 title="Component Object
Model">COM</abbr>,
+ <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 title="Component Object Model">COM</abbr>,
<abbr title="Common Object Request Broker Architecture">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 title="Open Geospatial Consortium">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 pacet name <code
class="GeoAPI">org.opengis</code>, which would be adopted by GeoAPI.
+ 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
class="GeoAPI">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 title="Application Programming
Interface">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.
+ 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 title="Open Geospatial
Consortium">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.
@@ -579,7 +607,7 @@
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 title="Open Geospatial Consortium">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.
+ — 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>
@@ -651,7 +679,7 @@
It then defines several <em>subsets</em> of these types of coordinate
systems systems.
These subsets, represented by unions, serve to specify that a class may
only be associated with a particular type of coordinate system.
For example, a union of types may be associated with an image, named
<code class="OGC">CS_ImageCS</code>,
- which may only contain <code class="OGC">CS_CartesianCS</code> and <code
class="OGC">CS_AffineCS</code>.
+ which can only contain <code class="OGC">CS_CartesianCS</code> and <code
class="OGC">CS_AffineCS</code>.
In this case, we get the desired effect in Java through a modification
of the hierarchy of classes:
we define the <code class="GeoAPI">CartesianCS</code> interface as a
specialization of <code class="GeoAPI">AffineCS</code>,
which is semantically correct.
@@ -685,13 +713,13 @@
the new attributes were added in a sub-class bearing almost the same
name.
Thus, <abbr>ISO</abbr> Standard 19115-2 defines the class <code
class="OGC">MI_Band</code>,
which extends the class <code class="OGC">MD_Band</code> from
<abbr>ISO</abbr> Standard 19115-1 by adding attributes that would have appeared
- directly in the parent class if there had been time.
+ 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 class and method
affected.
+ Deviations from the standards are documented in each affected class and
method.
Each mention of a deviation is also collected on a <a
href="http://www.geoapi.org/3.0/javadoc/departures.html";>single page</a> in
order to provide an overview.
Since these deviations blur the relationships between the standards and
certain Java interfaces,
the correspondence between these languages is explained by <code
class="GeoAPI">@UML</code> annotations and property files described in the
following section.
@@ -699,7 +727,7 @@
-<h3 id="UML-annotation">Correspondences Explained in <code>@UML</code>
Annotations</h3>
+<h3 id="UML-annotation">Mapping Given by <code>@UML</code> Annotations</h3>
<p>
For each class, method and constant defined by an <abbr title="Open
Geospatial Consortium">OGC</abbr> or <abbr title="International Organization
for Standardization">ISO</abbr> standard,
GeoAPI indicates its provenance using annotations defined in the <code
class="GeoAPI">org.opengis.annotation</code> package.
@@ -739,16 +767,16 @@
<pre>Class<?> <var>type</var> = <code
class="GeoAPI">Citation</code>.class;
Method <var>method</var> = <var>type</var>.getMethod("<code
class="GeoAPI">getTitle</code>", (Class<?>[]) null);
<code class="GeoAPI">UML</code> <var>annot</var> =
<var>method</var>.getAnnotation(<code class="GeoAPI">UML</code>.class);
-String <var>ident</var> = <var>annot</var>.identifier();
-System.out.println("The standard name for the method " +
<var>method</var>.getName() + " is " + <var>ident</var>);</pre>
+String <var>id</var> = <var>annot</var>.identifier();
+System.out.println("The standard name for the " + <var>method</var>.getName()
+ " method is " + <var>id</var>);</pre>
<p>
- The class <code class="SIS">org.apache.sis.util.iso.Types</code> provides
the commodity method
- <code class="SIS">getStandardName(Class)</code> to perform this operation.
+ The class <code class="SIS">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 of a standard name
— is a bit more complicated.
+ 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 class="GeoAPI">org.opengis.annotation</code> package.
The following example reads the files just before searching for the name of
the interface corresponding to <code class="OGC">CI_Citation</code>.
Users are always encouraged to only read this file once and then save its
contents in their application's cache.
@@ -761,29 +789,29 @@ System.out.println("The standard name fo
String <var>isoName</var> = "<code class="OGC">CI_Citation</code>";
String <var>geoName</var> = getProperty(<var>isoName</var>);
Class<?> <var>type</var> = Class.forName(<var>geoName</var>);
-System.out.println("The GeoAPI interface <abbr>ISO</abbr> " +
<var>isoName</var> + " is " + <var>type</var>);</pre>
+System.out.println("The GeoAPI interface for <abbr>ISO</abbr> type " +
<var>isoName</var> + " is " + <var>type</var>);</pre>
<p>
- The class <code class="SIS">org.apache.sis.util.iso.Types</code> provides
the commodity method
- <code class="SIS">forStandardName(String)</code> to perform this operation.
+ The class <code class="SIS">org.apache.sis.util.iso.Types</code> provides the
+ <code class="SIS">forStandardName(String)</code> convenience method to
perform this operation.
</p>
-<h3 id="MappingToJDK">Implicit Correspondences to Standard
<abbr>JDK</abbr></h3>
+<h3 id="MappingToJDK">Implicit Mapping to Standard <abbr>JDK</abbr></h3>
<p>
- Come classes and methods have neither an <code class="GeoAPI">@UML</code>
annotation, nor an entry in the <code
class="GeoAPI">class-index.properties</code> file.
+ Some classes and methods have neither an <code class="GeoAPI">@UML</code>
annotation, nor an entry in the <code
class="GeoAPI">class-index.properties</code> file.
They are either extensions of GeoAPI, or else types defined in other
libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>.
- In this last case, the correspondence to <abbr title="International
Organization for Standardization">ISO</abbr> standards is implicit.
- The following table describes this correspondance for <abbr>ISO</abbr>
Standard 19103 types.
- Standard Java's original types are preferred when applicable,
- but where necessary their equivalents in the form of objects are used in
order to authorize null values.
+ In this last case, the mapping to <abbr title="International Organization
for Standardization">ISO</abbr> standards is implicit.
+ The following table describes this mapping for <abbr>ISO</abbr> 19103 types.
+ Java's primitive types are preferred when applicable,
+ but where necessary their wrappers are used in order to authorize null
values.
</p>
<table>
- <caption>Correspondences Between <abbr>ISO</abbr> 19103 et
<abbr>JDK</abbr></caption>
+ <caption>Mapping between <abbr>ISO</abbr> 19103 and <abbr>JDK</abbr>
types</caption>
<tr>
- <th>Type <abbr>ISO</abbr></th>
- <th>Type <abbr>JDK</abbr></th>
+ <th><abbr>ISO</abbr> type</th>
+ <th><abbr>JDK</abbr> type</th>
<th>Remarks</th>
</tr>
<tr>
@@ -909,7 +937,7 @@ System.out.println("The GeoAPI interface
</tr>
<tr>
<td><code class="OGC">CodeList</code></td>
- <td>(pas d’équivalent)</td>
+ <td>(no equivalent)</td>
<td class="leftBorder">See <code
class="GeoAPI">org.opengis.util.CodeList</code> below.</td>
</tr>
<tr>
@@ -943,21 +971,21 @@ System.out.println("The GeoAPI interface
Both define all authorized values, without allowing the user to add any.
A <code class="OGC">CodeList</code> is similar to an enumeration, except
that users may add their own items.
Standard <abbr title="Java Development Kit">JDK</abbr> does not offer this
possibility.
- GeoAPI defines an abstract <code class="GeoAPI">CodeList</code> class that
reproduces some of the functions of <code>Enum</code> while being extensible.
- Extensions are derived from <code class="GeoAPI">valueOf(String)</code>
static methods, which, in contrast to <code>Enum</code>,
+ GeoAPI defines an abstract <code class="GeoAPI">CodeList</code> class that
reproduces some of the functionality of <code>Enum</code> while being
extensible.
+ Extensions are made available by the <code
class="GeoAPI">valueOf(String)</code> static method, which, in contrast to
<code>Enum</code>,
creates new instances if the name provided does not correspond to the name
of an existing instance.
</p>
<pre><code class="GeoAPI">MediumName</code> <var>cdRom</var> = <code
class="GeoAPI">MediumName.CD_ROM;</code>
<code class="GeoAPI">MediumName</code> <var>usbKey</var> = <code
class="GeoAPI">MediumName.valueOf</code>("<code
class="GeoAPI">USB_KEY</code>"); <code class="comment">// There is no
constraint on this value.</code>
<b>assert</b> <code class="GeoAPI">MediumName.valueOf</code>("<code
class="GeoAPI">CD_ROM</code>") == <var>cdRom</var> : "valueOf must return
existing constants.";
-<b>assert</b> <code class="GeoAPI">MediumName.valueOf</code>("<code
class="GeoAPI">USB_KEY</code>") == <var>usbKey</var> : "valueOf must hide the
previously requested values.";</pre>
+<b>assert</b> <code class="GeoAPI">MediumName.valueOf</code>("<code
class="GeoAPI">USB_KEY</code>") == <var>usbKey</var> : "valueOf must cache the
previously requested values.";</pre>
-<h2 id="ServiceLoader">Importing an Implementation of the Interfaces</h2>
+<h2 id="ServiceLoader">Fetching an Implementation of the Interfaces</h2>
<p>
- GeoAPI defines factories (<code class="GeoAPI">Factory</code>) that can
create implementations of its interfaces.
+ GeoAPI defines factories (<code class="GeoAPI">Factory</code>) that can
create implementations of interfaces.
For example, <code class="GeoAPI">DatumFactory</code> provides methods that
can create instances which implement the interfaces of a
<code class="GeoAPI">org.opengis.referencing.datum</code> package.
A <code class="GeoAPI">Factory</code> must be implemented by a geospatial
library,
@@ -1808,7 +1836,8 @@ System.out.println("The GeoAPI interface
<abbr title="Spatial Information System">SIS</abbr> includes only one
instance of the <code class="GeoAPI">OperationMethod</code>
type representing the Mercator projection, regardless of the client's
language.
But its <code class="GeoAPI">getName()</code> method (indirectly) provides
an instance of
- <code class="GeoAPI">InternationalString</code>, so that
<code>toString(Locale.ENGLISH)</code> returns <cite>Mercator projection</cite>.
+ <code class="GeoAPI">InternationalString</code>, so that
<code>toString(Locale.ENGLISH)</code> returns <cite>Mercator projection</cite>
+ while <code>toString(Locale.FRENCH)</code> returns <cite>Projection de
Mercator</cite>.
</p></div>
<p>
When defining spatial objects independently of local conventions, we reduce
the risk of computational overload.
@@ -1832,7 +1861,7 @@ System.out.println("The GeoAPI interface
</p>
<ul>
<li>
- Identifiers are written so that they appear in <abbr title="Unified
Modeling Language">UML</abbr> diagrams,
+ Identifiers are written as they appear in <abbr title="Unified Modeling
Language">UML</abbr> diagrams,
such as <cite>blurredImage</cite> instead of <cite>Blurred image</cite>.
</li>
<li>
Modified: sis/site/trunk/content/book/fr/developer-guide.html
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/book/fr/developer-guide.html?rev=1629468&r1=1629467&r2=1629468&view=diff
==============================================================================
--- sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] (original)
+++ sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] Sun Oct 5
05:49:32 2014
@@ -170,6 +170,10 @@
Exemple: <code>String</code>.
</li>
</ul>
+<p>
+ Des compléments d’information apparaissent dans des boîtes grises.
+ Le lecteur peut ignorer ces boîtes grises sans que cela ne nuise à la
compréhension du texte.
+</p>
@@ -382,142 +386,164 @@
<th>Norme <abbr>ISO</abbr></th>
<th>Norme <abbr>OGC</abbr></th>
<th>Titre</th>
- <th>Paquet GeoAPI</th>
+ <th>Paquet de GeoAPI</th>
+ <th>Paquet de Apache SIS</th>
</tr>
<tr>
- <td class="separator" colspan="4">Spécifications abstraites</td>
+ <td class="separator" colspan="5">Spécifications abstraites</td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19103</td>
<td></td>
<td><i>Conceptual schema language</i></td>
<td><code>org.opengis.util</code></td>
+ <td><code>org.apache.sis.util.iso</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19115</td>
<td>Topic 11</td>
<td><i>Metadata</i></td>
<td><code>org.opengis.metadata</code></td>
+ <td><code>org.apache.sis.metadata.iso</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19111</td>
<td>Topic 2</td>
<td><i>Spatial referencing by coordinates</i></td>
<td><code>org.opengis.referencing</code></td>
+ <td><code>org.apache.sis.referencing</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19108</td>
<td></td>
<td><i>Temporal Schema</i></td>
<td><code>org.opengis.temporal</code></td>
+ <td></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19107</td>
<td>Topic 1</td>
<td><i>Feature geometry</i></td>
<td><code>org.opengis.geometry</code></td>
+ <td><code>org.apache.sis.geometry</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19101</td>
<td>Topic 5</td>
<td><i>Features</i></td>
<td><code>org.opengis.feature</code></td>
+ <td><code>org.apache.sis.feature</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19123</td>
<td>Topic 6</td>
<td><i>Schema for coverage geometry and functions</i></td>
<td><code>org.opengis.coverage</code></td>
+ <td><code>org.apache.sis.coverage</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19156</td>
<td>Topic 20</td>
<td><i>Observations and measurements</i></td>
<td><code>org.opengis.observation</code></td>
+ <td></td>
</tr>
<tr>
- <td class="separator" colspan="4">Spécifications d’implémentation</td>
+ <td class="separator" colspan="5">Spécifications d’implémentation</td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19139</td>
<td></td>
<td><i>Metadata <abbr>XML</abbr> schema implementation</i></td>
<td></td>
+ <td><code>org.apache.sis.xml</code></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 13249</td>
<td></td>
<td><i><abbr>SQL</abbr> spatial</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><s><abbr>OGC</abbr> 01-009</s></td>
<td><s><i>Coordinate Transformation Services</i></s></td>
<td><code>org.opengis.referencing</code></td>
+ <td><code>org.apache.sis.referencing</code></td>
</tr>
<tr>
<td></td>
<td><s><abbr>OGC</abbr> 01-004</s></td>
<td><s><i>Grid Coverage</i></s></td>
<td><code>org.opengis.coverage</code></td>
+ <td><code>org.apache.sis.coverage</code></td>
</tr>
<tr>
<td></td>
<td><abbr>SLD</abbr></td>
<td><i>Styled Layer Descriptor</i></td>
<td><code>org.opengis.style</code></td>
+ <td></td>
</tr>
<tr>
- <td class="separator" colspan="4">Services web</td>
+ <td class="separator" colspan="5">Services web</td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19128</td>
<td><abbr>WMS</abbr></td>
<td><i>Web Map Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>WMTS</abbr></td>
<td><i>Web Map Tile Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td><abbr>ISO</abbr> 19142</td>
<td><abbr>WFS</abbr></td>
<td><i>Web Feature Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>WCS</abbr></td>
<td><i>Web Coverage Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>WPS</abbr></td>
<td><i>Web Processing Service</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td>Open<abbr>LS</abbr></td>
<td><i>Location Services</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>SWE</abbr></td>
<td><i>Sensor Web Enablement</i></td>
<td></td>
+ <td></td>
</tr>
<tr>
<td></td>
<td><abbr>SOS</abbr></td>
<td><i>Sensor Observation Service</i></td>
<td></td>
+ <td></td>
</tr>
</table>
@@ -786,8 +812,8 @@
<pre>Class<?> <var>type</var> = <code
class="GeoAPI">Citation</code>.class;
Method <var>method</var> = <var>type</var>.getMethod("<code
class="GeoAPI">getTitle</code>", (Class<?>[]) null);
<code class="GeoAPI">UML</code> <var>annot</var> =
<var>method</var>.getAnnotation(<code class="GeoAPI">UML</code>.class);
-String <var>ident</var> = <var>annot</var>.identifier();
-System.out.println("Le nom standard de la méthode " +
<var>method</var>.getName() + " est " + <var>ident</var>);</pre>
+String <var>id</var> = <var>annot</var>.identifier();
+System.out.println("Le nom standard de la méthode " +
<var>method</var>.getName() + " est " + <var>id</var>);</pre>
<p>
La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit la
méthode de commodité
@@ -810,7 +836,7 @@ System.out.println("Le nom standard de l
String <var>isoName</var> = "<code class="OGC">CI_Citation</code>";
String <var>geoName</var> = getProperty(<var>isoName</var>);
Class<?> <var>type</var> = Class.forName(<var>geoName</var>);
-System.out.println("L’interface GeoAPI du type <abbr>ISO</abbr> " +
<var>isoName</var> + " est " + <var>type</var>);</pre>
+System.out.println("L’interface GeoAPI pour le type <abbr>ISO</abbr> " +
<var>isoName</var> + " est " + <var>type</var>);</pre>
<p>
La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit la
méthode de commodité
@@ -996,7 +1022,7 @@ System.out.println("L’interface GeoAPI
Le <abbr title="Java Development Kit">JDK</abbr> standard n’offrant pas
cette possibilité,
GeoAPI définit une classe abstraite <code class="GeoAPI">CodeList</code>
reproduisant certaines fonctionnalités de <code>Enum</code> tout en étant
extensible.
Les extensions s’obtiennent par les méthodes statiques <code
class="GeoAPI">valueOf(String)</code> qui,
- contrairement à celle de <code>Enum</code>, créera de nouvelles instances si
le nom donné ne correspond pas au nom d’une instance existante.
+ contrairement à celle de <code>Enum</code>, créeront de nouvelles instances
si le nom donné ne correspond pas au nom d’une instance existante.
</p>
<pre><code class="GeoAPI">MediumName</code> <var>cdRom</var> = <code
class="GeoAPI">MediumName.CD_ROM;</code>
@@ -1231,8 +1257,7 @@ System.out.println("L’interface GeoAPI
Par exemple la validation d’un objet <code
class="GeoAPI">GeographicCRS</code> impliquera
la validation de sa composante <code class="GeoAPI">GeodeticDatum</code>,
qui impliquera elle-même
la validation de sa composante <code class="GeoAPI">Ellipsoid</code>, et
ainsi de suite.
- Il est donc inutile de valider soi-même les composantes, à moins de vouloir
isoler le test d’un élément
- connu pour être souvent problématique.
+ Il est donc inutile de valider soi-même les composantes, à moins de vouloir
isoler le test d’un élément souvent problématique.
</p>
<p>
Par défaut, les validations sont aussi strictes que possible. Il est
possible toutefois d’assouplir certaines règles.
