You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2021/05/14 09:58:10 UTC
[sis-site] 21/39: Refactoring of developer guide source files.
This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/sis-site.git
commit 92a17552c77477ee99eab6689b28f5d8cec3f189
Author: Martin Desruisseaux <de...@apache.org>
AuthorDate: Mon Oct 5 19:01:58 2015 +0000
Refactoring of developer guide source files.
git-svn-id: https://svn.apache.org/repos/infra/websites/production/sis/content@967857 90ea9780-b833-de11-8433-001ec94261de
---
.../operation/projection/package-summary.html | 4 +-
.../transform/DefaultMathTransformFactory.html | 20 +-
book/book.css | 142 +-
book/en/developer-guide.html | 3450 +++++++++---------
book/fr/developer-guide.html | 3642 ++++++++++----------
content/reports.css => book/tables.css | 17 +
.../tables}/CoordinateOperationMethods.html | 2 +-
book/tables/CoordinateReferenceSystems.html | 22 +
command-line.html | 4 +-
index.html | 2 +-
release-notes/0.6.html | 2 +-
11 files changed, 3664 insertions(+), 3643 deletions(-)
diff --git a/apidocs/org/apache/sis/referencing/operation/projection/package-summary.html b/apidocs/org/apache/sis/referencing/operation/projection/package-summary.html
index c95b3cc..84056e9 100644
--- a/apidocs/org/apache/sis/referencing/operation/projection/package-summary.html
+++ b/apidocs/org/apache/sis/referencing/operation/projection/package-summary.html
@@ -180,7 +180,7 @@
More on this convention is explained below.</p>
<p>Users wanting to know more about the available projections and their parameters should look at the
- <a href="http://sis.apache.org/content/CoordinateOperationMethods.html">list of coordinate operation methods</a>.
+ <a href="http://sis.apache.org/book/tables/CoordinateOperationMethods.html">list of coordinate operation methods</a>.
Only users interested in the <em>implementation</em> of those projections should look at this package.</p>
@@ -301,7 +301,7 @@
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>0.6</dd>
<dt><span class="seeLabel">See Also:</span></dt>
-<dd><a href="http://www.remotesensing.org/geotiff/proj_list">Projections list on RemoteSensing.org</a>,
+<dd><a href="http://www.remotesensing.org/geotiff/proj_list">Projections list on RemoteSensing.org</a>,
<a href="http://mathworld.wolfram.com/MapProjection.html">Map projections on MathWorld</a></dd>
<p><font size="-1">Defined in the <code>sis-referencing</code> module</font></p>
diff --git a/apidocs/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html b/apidocs/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html
index 450c3c7..53f17d7 100644
--- a/apidocs/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html
+++ b/apidocs/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html
@@ -144,7 +144,7 @@ implements <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/op
<div class="section">Standard parameters</div>
<code>MathTransform</code> instances are created from <a href="../../../../../../org/apache/sis/parameter/DefaultParameterValueGroup.html" title="class in org.apache.sis.parameter">parameter values</a>. The parameters expected by each operation available in a default Apache SIS installation is
- <a href="http://sis.apache.org/content/CoordinateOperationMethods.html">listed here</a>.
+ <a href="http://sis.apache.org/book/tables/CoordinateOperationMethods.html">listed here</a>.
The set of parameters varies for each operation or projection, but the following can be considered typical:
<ul>
@@ -213,7 +213,7 @@ implements <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/op
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>0.6</dd>
<dt><span class="seeLabel">See Also:</span></dt>
-<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/MathTransformProvider.html" title="interface in org.apache.sis.referencing.operation.transform"><code>MathTransformProvider</code></a>,
+<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/MathTransformProvider.html" title="interface in org.apache.sis.referencing.operation.transform"><code>MathTransformProvider</code></a>,
<a href="../../../../../../org/apache/sis/referencing/operation/transform/AbstractMathTransform.html" title="class in org.apache.sis.referencing.operation.transform"><code>AbstractMathTransform</code></a></dd>
<p><font size="-1">Defined in the <code>sis-referencing</code> module</font></p>
@@ -480,8 +480,8 @@ implements <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/op
<dt><span class="returnLabel">Returns:</span></dt>
<dd>Methods available in this factory for coordinate operations of the given type.</dd>
<dt><span class="seeLabel">See Also:</span></dt>
-<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getDefaultParameters-java.lang.String-"><code>getDefaultParameters(String)</code></a>,
-<a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#createParameterizedTransform-org.opengis.parameter.ParameterValueGroup-"><code>createParameterizedTransform(ParameterValueGroup)</code></a>,
+<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getDefaultParameters-java.lang.String-"><code>getDefaultParameters(String)</code></a>,
+<a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#createParameterizedTransform-org.opengis.parameter.ParameterValueGroup-"><code>createParameterizedTransform(ParameterValueGroup)</code></a>,
<a href="../../../../../../org/apache/sis/referencing/operation/DefaultOperationMethod.html#getOperationType--"><code>DefaultOperationMethod.getOperationType()</code></a></dd>
</dl>
</li>
@@ -543,8 +543,8 @@ implements <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/op
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="http://www.geoapi.org/3.0/javadoc/org/opengis/util/NoSuchIdentifierException.html?is-external=true" title="class or interface in org.opengis.util">NoSuchIdentifierException</a></code> - if there is no method registered for the given name or identifier.</dd>
<dt><span class="seeLabel">See Also:</span></dt>
-<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getAvailableMethods-java.lang.Class-"><code>getAvailableMethods(Class)</code></a>,
-<a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#createParameterizedTransform-org.opengis.parameter.ParameterValueGroup-"><code>createParameterizedTransform(ParameterValueGroup)</code></a>,
+<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getAvailableMethods-java.lang.Class-"><code>getAvailableMethods(Class)</code></a>,
+<a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#createParameterizedTransform-org.opengis.parameter.ParameterValueGroup-"><code>createParameterizedTransform(ParameterValueGroup)</code></a>,
<a href="../../../../../../org/apache/sis/referencing/operation/transform/AbstractMathTransform.html#getParameterValues--"><code>AbstractMathTransform.getParameterValues()</code></a></dd>
</dl>
</li>
@@ -636,7 +636,7 @@ implements <a href="http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/op
<dd><code><a href="http://www.geoapi.org/3.0/javadoc/org/opengis/util/FactoryException.html?is-external=true" title="class or interface in org.opengis.util">FactoryException</a></code> - if the object creation failed. This exception is thrown
if some required parameter has not been supplied, or has illegal value.</dd>
<dt><span class="seeLabel">See Also:</span></dt>
-<dd><a href="../../../../../../org/apache/sis/referencing/cs/AxesConvention.html#NORMALIZED"><code>AxesConvention.NORMALIZED</code></a>,
+<dd><a href="../../../../../../org/apache/sis/referencing/cs/AxesConvention.html#NORMALIZED"><code>AxesConvention.NORMALIZED</code></a>,
<a href="../../../../../../org/apache/sis/referencing/operation/DefaultConversion.html#DefaultConversion-java.util.Map-org.opengis.referencing.operation.OperationMethod-org.opengis.referencing.operation.MathTransform-org.opengis.parameter.ParameterValueGroup-"><code>DefaultConversion.DefaultConversion(Map, OperationMethod, MathTransform, ParameterValueGroup)</code></a></dd>
</dl>
</li>
@@ -673,8 +673,8 @@ MathTransform mt = factory.<b>createParameterizedTransform</b>(group);</pre></bl
<dd><code><a href="http://www.geoapi.org/3.0/javadoc/org/opengis/util/FactoryException.html?is-external=true" title="class or interface in org.opengis.util">FactoryException</a></code> - if the object creation failed. This exception is thrown
if some required parameter has not been supplied, or has illegal value.</dd>
<dt><span class="seeLabel">See Also:</span></dt>
-<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getDefaultParameters-java.lang.String-"><code>getDefaultParameters(String)</code></a>,
-<a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getAvailableMethods-java.lang.Class-"><code>getAvailableMethods(Class)</code></a>,
+<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getDefaultParameters-java.lang.String-"><code>getDefaultParameters(String)</code></a>,
+<a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getAvailableMethods-java.lang.Class-"><code>getAvailableMethods(Class)</code></a>,
<a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#getLastMethodUsed--"><code>getLastMethodUsed()</code></a></dd>
</dl>
</li>
@@ -863,7 +863,7 @@ Target: firstAffectedOrdinate + subTransform.<b>getTargetDimensions</b>() + numT
for example following changes of the application classpath.</div>
<dl>
<dt><span class="seeLabel">See Also:</span></dt>
-<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#DefaultMathTransformFactory-java.lang.Iterable-"><code>DefaultMathTransformFactory(Iterable)</code></a>,
+<dd><a href="../../../../../../org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.html#DefaultMathTransformFactory-java.lang.Iterable-"><code>DefaultMathTransformFactory(Iterable)</code></a>,
<a href="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html?is-external=true#reload--" title="class or interface in java.util"><code>ServiceLoader.reload()</code></a></dd>
</dl>
</li>
diff --git a/book/book.css b/book/book.css
index ec67f1e..9d716ce 100644
--- a/book/book.css
+++ b/book/book.css
@@ -20,41 +20,75 @@
*/
ul.toc {
list-style-type: square;
+ margin-bottom: 30px;
}
ul.toc ul {
list-style-type: disc;
- padding-left: 21pt;
+ padding-left: 21px;
+}
+
+/*
+ * Links to previous and next chapters.
+ */
+div.chapter-links {
+ width: 100%;
+ background-color: #CCDFFF;
+ border-bottom-color: #0077B3;
+ border-bottom-style: solid;
+ border-bottom-width: 1px;
+ margin-top: 0px;
+ padding-top: 6px;
+ margin-bottom: 18px;
+ padding-bottom: 24px;
+ white-space: nowrap;
+}
+
+div.previous-chapter {
+ width: 50%;
+ float: left;
+}
+
+div.next-chapter {
+ width: 50%;
+ float: right;
+ text-align: right;
}
/*
* Chapters and sections titles (excluding the book titles).
*/
-h1 {
- margin-top: 120pt;
+section > header > h1 {
+ margin-top: 160px;
+ text-align: center;
background-color: #99AAFF;
border-top-color: #0000CC;
border-bottom-color: #0000CC;
border-top-style: solid;
border-bottom-style: solid;
- border-top-width: 2pt;
- border-bottom-width: 2pt;
- padding-bottom: 4pt;
- padding-top: 4pt;
+ border-top-width: 3px;
+ border-bottom-width: 3px;
+ padding-top: 6px;
+ padding-bottom: 0px;
+ margin-bottom: 0px;
}
-h2 {
- margin-top: 40pt;
+section > h2 {
+ margin-top: 60px;
border-bottom-style: solid;
- border-bottom-width: 2pt;
+ border-bottom-width: 2px;
+}
+
+section > h3 {
+ margin-top: 50px;
}
-h3 {
- margin-top: 24pt;
+section > h4 {
+ margin-top: 30px;
}
-h4 {
- margin-top: 15pt;
+span.section-number {
+ margin-right: 9px;
}
p {
@@ -62,55 +96,70 @@ p {
}
div.example {
- margin-left: 1.25cm;
- margin-right: 1.5cm;
+ margin-left: 21px;
+ margin-right: 24px;
font-size: smaller;
}
-aside {
- margin-left: 45pt;
- margin-right: 45pt;
- margin-top: 15pt;
- margin-bottom: 15pt;
- padding-left: 15pt;
- padding-right: 15pt;
+article, aside {
+ margin-left: 60px;
+ margin-right: 60px;
+ margin-top: 21px;
+ margin-bottom: 21px;
+ padding-left: 21px;
+ padding-right: 21px;
border-style: solid;
- border-width: 1pt;
+ border-width: 2px;
background-color: #EEEEEE;
border-color: #BBBBBB;
font-size: smaller;
}
+aside h1, article h1,
+aside h2, article h2,
+aside h3, article h3,
+aside h4, article h4,
+aside h5, article h5 {
+ font-size: medium;
+ margin-top: 12px;
+ margin-bottom: 12px;
+}
+
+aside h1, article h1 {
+ font-size: large;
+ margin-top: 15px;
+}
+
caption {
color: #0086E0;
font-weight: bold;
- padding-top: 9pt;
- padding-bottom: 3pt;
+ padding-top: 12px;
+ padding-bottom: 3px;
}
table {
margin-left: auto;
margin-right: auto;
border-style: solid;
- border-width: 2pt;
- border-spacing: 0pt;
+ border-width: 1px;
+ border-spacing: 0px;
}
table tr th {
background-color: #B9DCFF;
border-bottom-style: solid;
- border-bottom-width: 1pt;
- padding: 3pt;
+ border-bottom-width: 1px;
+ padding: 6px;
}
table tr td {
- padding-left: 9pt;
- padding-right: 9pt;
+ padding-left: 12px;
+ padding-right: 12px;
}
table tr td.leftBorder {
border-left-style: solid;
- border-left-width: 1pt;
+ border-left-width: 2px;
border-left-color: lightgray;
}
@@ -122,10 +171,10 @@ table tr td.separator {
border-bottom-color: LightGray;
border-top-style: solid;
border-bottom-style: solid;
- border-top-width: 1pt;
- border-bottom-width: 1pt;
- padding-top: 3pt;
- padding-bottom: 3pt;
+ border-top-width: 1px;
+ border-bottom-width: 1px;
+ padding-top: 6px;
+ padding-bottom: 6px;
}
table.hidden {
@@ -141,8 +190,8 @@ table.hidden tr th {
background: none;
color: #0086E0;
font-weight: bold;
- padding-top: 9pt;
- padding-bottom: 3pt;
+ padding-top: 12px;
+ padding-bottom: 6px;
padding-left: 0;
padding-right: 0;
}
@@ -152,15 +201,18 @@ table.hidden tr td {
}
pre {
- margin-left: 30pt;
- margin-right: 30pt;
- margin-top: 15pt;
- margin-bottom: 15pt;
- padding: 9pt;
- border: 1pt solid Gray;
+ margin-left: 30px;
+ margin-right: 30px;
+ margin-top: 21px;
+ margin-bottom: 21px;
+ padding: 12px;
+ border: 2px solid Gray;
background: #F8F8F8
}
+pre.xml {
+}
+
/*
* OGC/ISO, GeoAPI and SIS legends.
*/
diff --git a/book/en/developer-guide.html b/book/en/developer-guide.html
index 0f1025d..1007796 100644
--- a/book/en/developer-guide.html
+++ b/book/en/developer-guide.html
@@ -1,33 +1,21 @@
-<?xml version="1.0" encoding="UTF-8" ?>
+<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ Licensed to the Apache Software Foundation (ASF)
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ This is an automatically generated file. DO NOT EDIT.
+ See the files in the ../../../book/ directory instead.
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
- <head>
- <title>Introduction to Apache SIS</title>
- <link rel="stylesheet" type="text/css" href="../book.css"/>
- </head>
- <body>
- <!-- From this point, shift indentation 4 spaces to the left for saving space. -->
-
+<head>
+<title>Introduction to Apache SIS</title>
+<link rel="stylesheet" type="text/css" href="../book.css"/>
+</head>
+<body>
<p style="margin-top: 30pt"><span style="font-size: 30pt; font-weight: 900">Introduction to Apache SIS®</span></p>
<p style="margin-bottom: 20pt">(English | <a href="../fr/developer-guide.html">Français</a>)</p>
<p><i>Martin Desruisseaux</i><br/>
@@ -36,1428 +24,1400 @@
<hr/>
<p><b style="font-size: 20pt">Table of content</b></p>
-
+<nav>
<ul class="toc">
- <li><a href="#Foreword">Foreward</a><ul>
- <li><a href="#About">Conventions Used in This Guide</a></li>
- </ul></li>
- <li><a href="#Standards">Standards and Norms</a><ul>
- <li><a href="#OGC-process"><abbr>OGC</abbr> Standardization Process</a><ul>
- <li><a href="#OGC-SWG">Standard Working Group (<abbr>SWG</abbr>) Procedures</a></li>
- <li><a href="#OGC-OAB">The Architecture Board (<abbr>OAB</abbr>) and the Technical Committee (<abbr>TC</abbr>)</a></li>
- <li><a href="#OGC-RFC">Procedure for the Submission of Proposals for Modification</a></li>
- </ul></li>
- <li><a href="#SpecificationTypes">Different Types of Specifications</a></li>
- <li><a href="#DefinitionOfTerms">Definition of Terms</a></li>
- </ul></li>
- <li><a href="#GeoAPI">GeoAPI</a><ul>
- <li><a href="#SpecificationToInterfaces">Interface Specifications</a><ul>
- <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">Fetching an Implementation of the Interfaces</a><ul>
- <li><a href="#GeoAPI-simple">Defining Custom Implementations</a></li>
- </ul></li>
- <li><a href="#GeoAPI-modules">GeoAPI Modules</a><ul>
- <li><a href="#GeoAPI-core">The Interfaces' Definition Modules</a></li>
- <li><a href="#GeoAPI-conformance">The Conformance Tests Module</a><ul>
- <li><a href="#GeoAPI-validators">Instance Validations</a></li>
- <li><a href="#GeoAPI-tests">Executing Pre-defined Tests</a></li>
- </ul></li>
- <li><a href="#GeoAPI-examples">Example Modules</a></li>
- </ul></li>
- </ul></li>
- <li><a href="#XML-ISO">Representing Objects in <abbr>XML</abbr></a><ul>
- <li><a href="#XML-ISO-19115">Representing Metadata According to <abbr>ISO</abbr> 19115-3</a><ul>
- <li><a href="#gco-id">Identification of Already-Defined Instances</a></li>
- <li><a href="#nilReason">Representing Missing Values</a></li>
- </ul></li>
- </ul></li>
- <li><a href="#Utilities">Utility Classes and Methods</a><ul>
- <li><a href="#ComparisonMode">Comparison Modes of Objects</a></li>
- <li><a href="#Internationalization">Internationalization</a><ul>
- <li><a href="#LocalizedString">Distinct Character Sequences for Each Locale</a></li>
- <li><a href="#InternationalString">Single Instance in All Locale Conventions</a></li>
- <li><a href="#Locale.ROOT"><code>Locale.ROOT</code> Convention</a></li>
- <li><a href="#UnicodePoint">Treatment of Characters</a><ul>
- <li><a href="#Whitespaces">The Interpretation of Blank Spaces</a></li>
- </ul></li>
- </ul></li>
- </ul></li>
- <li><a href="#Geometry">Geometries</a><ul>
- <li><a href="#Geometry-root">Base Classes</a><ul>
- <li><a href="#DirectPosition">Direct Points and Positions</a></li>
- <li><a href="#Envelope">Envelopes</a><ul>
- <li><a href="#AntiMeridian">Envelopes that Cross the Antimeridian</a></li>
- </ul></li>
- </ul></li>
- </ul></li>
- <li><a href="#Coverage">Data Coverages</a></li>
+<li><a href="#Foreword">Foreward</a><ul>
+<li><a href="#Standards">Standards and Norms</a><ul>
+<li><a href="#SpecificationTypes">Different Types of Specifications</a></li></ul></li>
+<li><a href="#About">Conventions Used in This Guide</a><ul>
+<li><a href="#DefinitionOfTerms">Definition of Terms</a></li></ul></li></ul></li>
+<li><a href="#GeoAPI">GeoAPI</a><ul>
+<li><a href="#SpecificationToInterfaces">Interface Specifications</a><ul>
+<li><a href="#UML-annotation">Mapping Given by @UML Annotations</a></li>
+<li><a href="#MappingToJDK">Implicit Mapping to Standard JDK</a></li></ul></li>
+<li><a href="#ServiceLoader">Fetching an Implementation of the Interfaces</a><ul>
+<li><a href="#GeoAPI-simple">Defining Custom Implementations</a></li></ul></li>
+<li><a href="#GeoAPI-modules">GeoAPI Modules</a><ul>
+<li><a href="#GeoAPI-core">The Interfaces' Definition Modules</a></li>
+<li><a href="#GeoAPI-conformance">The Conformance Tests Module</a><ul>
+<li><a href="#GeoAPI-validators">Instance Validations</a></li>
+<li><a href="#GeoAPI-tests">Executing Pre-defined Tests</a></li></ul></li>
+<li><a href="#GeoAPI-examples">Example Modules</a></li></ul></li></ul></li>
+<li><a href="#XML-ISO">Representing Objects in XML</a><ul>
+<li><a href="#XML-ISO-19115">Representing Metadata According to ISO 19115-3</a><ul>
+<li><a href="#gco-id">Identification of Already-Defined Instances</a></li>
+<li><a href="#nilReason">Representing Missing Values</a></li></ul></li></ul></li>
+<li><a href="#Utilities">Utility Classes and Methods</a><ul>
+<li><a href="#ComparisonMode">Comparison Modes of Objects</a></li>
+<li><a href="#Internationalization">Internationalization</a><ul>
+<li><a href="#LocalizedString">Distinct Character Sequences for Each Locale</a></li>
+<li><a href="#InternationalString">Single instance for all supported locales</a></li>
+<li><a href="#Locale.ROOT">Locale.ROOT Convention</a></li>
+<li><a href="#UnicodePoint">Treatment of Characters</a><ul>
+<li><a href="#Whitespaces">The Interpretation of Blank Spaces</a></li></ul></li></ul></li></ul></li>
+<li><a href="#Geometry">Geometries</a><ul>
+<li><a href="#Geometry-root">Base Classes</a><ul>
+<li><a href="#DirectPosition">Direct Points and Positions</a></li>
+<li><a href="#Envelope">Envelopes</a><ul>
+<li><a href="#AntiMeridian">Envelopes that Cross the Antimeridian</a></li></ul></li></ul></li></ul></li>
+<li><a href="#Coverage">Data Coverages</a></li>
</ul>
-
-
-<h1 id="Foreword">Foreward</h1>
-<p>
- 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 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 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.
+</nav>
+
+<main>
+<section>
+<header>
+<h1 id="Foreword"><span class="section-number">1.</span> Foreward</h1>
+<nav><div class="chapter-links"><div class="next-chapter"><a href="#GeoAPI">Next chapter</a> ➡</div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#Standards">Standards and Norms</a><ul>
+<li><a href="#SpecificationTypes">Different Types of Specifications</a></li></ul></li>
+<li><a href="#About">Conventions Used in This Guide</a><ul>
+<li><a href="#DefinitionOfTerms">Definition of Terms</a></li></ul></li></ul></nav>
+<p>
+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 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 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 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>).
- This <abbr>API</abbr> is not necessarily defined in a programming language;
- the actual tendency is rather to define conventions that use existing web protocols, which we can translate into various programming languages.
- 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.
+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>).
+This <abbr>API</abbr> is not necessarily defined in a programming language;
+the actual tendency is rather to define conventions that use existing web protocols, which we can translate into various programming languages.
+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 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.
- Like databases, methods of accessing geographic information have been standardized.
- In this case, however, the efforts have been more recent, and their integration in software — especially in older programs — is incomplete and not always coherent.
- At the time of writing, no product to our knowledge has implemented all of the specifications in their entirety.
- However, there are many implementations that cover a fairly large spectrum.
- One of these is the Apache <abbr>SIS</abbr>® library that is described in this document.
+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.
+Like databases, methods of accessing geographic information have been standardized.
+In this case, however, the efforts have been more recent, and their integration in software — especially in older programs — is incomplete and not always coherent.
+At the time of writing, no product to our knowledge has implemented all of the specifications in their entirety.
+However, there are many implementations that cover a fairly large spectrum.
+One of these is the Apache <abbr>SIS</abbr>® library that is described in this document.
</p><p>
- Apache <abbr title="Spatial Information System">SIS</abbr> is characterized by a sustained effort to comply with standards,
- going so far as to participate in certain <abbr title="Open Geospatial Consortium">OGC</abbr> projects.
- 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 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 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>
-<ul>
- <li>
- Elements defined in the <abbr title="Open Geospatial Consortium">OGC</abbr> standard
- or the <abbr title="International Organization for Standardization">ISO</abbr> standard appear in blue.
- Example: <code class="OGC">CD_Ellipsoid</code>.
- </li>
- <li>
- Elements defined in GeoAPI appear in green.
- Example: <code class="GeoAPI">Ellipsoid</code>.
- </li>
- <li>
- Elements defined in Apache <abbr title="Spatial Information System">SIS</abbr> appear in brown.
- Example: <code class="SIS">DefaultEllipsoid</code>.
- </li>
- <li>
- Other elements, such as those in standard Java, are left in black.
- Example: <code>String</code>.
- </li>
-</ul>
-<p>
- Text in gray boxes are for information purpose only and can be ignored.
+Apache <abbr title="Spatial Information System">SIS</abbr> is characterized by a sustained effort to comply with standards.
+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>API</abbr>.
+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>
-<h1 id="Standards">Standards and Norms</h1>
+<h2 id="Standards"><span class="section-number">1.1.</span> Standards and Norms</h2>
<p>
- Most standards used by Apache <abbr title="Spatial Information System">SIS</abbr> have been devised by the <a href="http://www.opengeospatial.org">Open Geospatial Consortium</a> (<abbr>OGC</abbr>),
- sometimes in collaboration with the <a href="http://www.iso.org">International Organization for Standardization</a> (<abbr>ISO</abbr>).
- Some <abbr>ISO</abbr> standards themselves become European standards via the <a href="http://inspire.jrc.ec.europa.eu">INSPIRE Directive</a>.
- These standards offer two key features:
+Most standards used by Apache <abbr title="Spatial Information System">SIS</abbr> have been devised by the <a href="http://www.opengeospatial.org">Open Geospatial Consortium</a> (<abbr>OGC</abbr>),
+sometimes in collaboration with the <a href="http://www.iso.org">International Organization for Standardization</a> (<abbr>ISO</abbr>).
+Some <abbr>ISO</abbr> standards themselves become European standards via the <a href="http://inspire.jrc.ec.europa.eu">INSPIRE Directive</a>.
+These standards offer two key features:
</p>
<ul>
- <li>
- Allowing a community to make its information public in such a way that outside individuals or systems can discover it.
- </li>
- <li>
- Transferring information from one community to another while preserving its semantics,
- even if the two communities use very different internal representations.
- </li>
+<li>
+Allowing a community to make its information public in such a way that outside individuals or systems can discover it.
+</li>
+<li>
+Transferring information from one community to another while preserving its semantics,
+even if the two communities use very different internal representations.
+</li>
</ul>
<p>
- These standards are made available to the international community for free, as <a href="http://www.opengeospatial.org/standards/is">specifications (<abbr title="Portable Document Format">PDF</abbr> files)</a> or as <a href="http://schemas.opengis.net/gml/3.3/">schemas (<abbr title="XML Schema Definition">XSD</abbr> files)</a>.
- Standardization organizations do not create software; to obtain an implementation of these specifications,
- users must choose one of the compliant products available on the market, or develop their own solutions.
- Such voluntary compliance with these specifications allow independent communities to more easily exchange geographic information.
+These standards are made available to the international community for free,
+as <a href="http://www.opengeospatial.org/standards/is">specifications (<abbr title="Portable Document Format">PDF</abbr> files)</a> or
+as <a href="http://schemas.opengis.net/gml/3.3/">schemas (<abbr title="XML Schema Definition">XSD</abbr> files)</a>.
+Standardization organizations do not create software; to obtain an implementation of these specifications,
+users must choose one of the compliant products available on the market, or develop their own solutions.
+Such voluntary compliance with these specifications allow independent communities to more easily exchange geographic information.
</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 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),
- and <a href="http://en.wikipedia.org/wiki/Shapefile">Shapefile</a> for vector data (such as geometric shapes).
+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 a
+Coordinates Reference System (<abbr>CRS</abbr>) among <a href="../tables/CoordinateReferenceSystems.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),
+and <a href="http://en.wikipedia.org/wiki/Shapefile">Shapefile</a> for vector data (such as geometric shapes).
</p>
-<h2 id="OGC-process"><abbr>OGC</abbr> Standardization Process</h2>
+<article id="OGC-process">
+<header>
+<h1><abbr>OGC</abbr> Standardization Process</h1>
+</header>
<p>
- The work of the <abbr title="Open Geospatial Consortium">OGC</abbr> is done by email, teleconferences, and at <a href="http://www.opengeospatial.org/event?category=ogctcpc">in-person meetings</a>.
- The <abbr>OGC</abbr> organizes four meetings per year, each lasting five days, and hosted by member organizations that sponsor the event (companies, universities, research centres, <i>etc</i>).
- The host continent alternates between Europe and North America, with a growing presence in Asia since 2011.
- These meetings are usually attended by between 50 and 100 participants from among the hundreds of members of the <abbr>OGC</abbr>.
- Some participants are present at almost all the meetings, forming the pillars of the organization.
- The meetings of the <abbr title="Open Geospatial Consortium">OGC</abbr> offer opportunities for exchange among members from diverse backgrounds.
+The work of the <abbr title="Open Geospatial Consortium">OGC</abbr> is done by email, teleconferences, and at <a href="http://www.opengeospatial.org/event?category=ogctcpc">in-person meetings</a>.
+The <abbr>OGC</abbr> organizes four meetings per year, each lasting five days, and hosted by member organizations that sponsor the event (companies, universities, research centres, <i>etc</i>).
+The host continent alternates between Europe and North America, with a growing presence in Asia since 2011.
+These meetings are usually attended by between 50 and 100 participants from among the hundreds of members of the <abbr>OGC</abbr>.
+Some participants are present at almost all the meetings, forming the pillars of the organization.
+The meetings of the <abbr>OGC</abbr> offer opportunities for exchange among members from diverse backgrounds.
</p><p>
- The creation of a <abbr>OGC</abbr> standard begins with a gathering of organizations or individuals with a common interest in an issue.
- A working group is proposed as a <i>Discussion Working Group</i> (<abbr>DWG</abbr>) if the work is still in the exploratory stages,
- or as a <i>Standard Working Group</i> (<abbr>SWG</abbr>) if the work of standardization is ready to proceed.
- <abbr>DWG</abbr>s are open to all members of the <abbr>OGC</abbr>,
- while <abbr>SWG</abbr>s require that their participants enter into an agreement not to hinder the distribution of the standard through intellectual property claims.
+The creation of a <abbr>OGC</abbr> standard begins with a gathering of organizations or individuals with a common interest in an issue.
+A working group is proposed as a <i>Domain Working Group</i> (<abbr>DWG</abbr>) or as a <i>Standard Working Group</i> (<abbr>SWG</abbr>).
+<abbr>DWG</abbr>s are open to all members of the <abbr>OGC</abbr>,
+while <abbr>SWG</abbr>s require that their participants enter into an agreement not to hinder the distribution of the standard through intellectual property claims.
</p>
-
-
-<h3 id="OGC-SWG">Standard Working Group (<abbr>SWG</abbr>) Procedures</h3>
+<h2 id="OGC-SWG">Standard Working Group (<abbr>SWG</abbr>) Procedures</h2>
<p>
- In order to be accepted, a standardization project must be supported by a minimum number of members belonging to distinct organizations.
- These founding members draft a charter defining the objectives of the <abbr title="Standard Working Group">SWG</abbr>,
- which must be approved by the Technical Committee of the <abbr title="Open Geospatial Consortium">OGC</abbr>.
- Each founding member is endowed with the right to vote, with a limit of one voting member per organization.
- Each new member that wishes to join the <abbr>SWG</abbr> after its creation is granted the role of observer,
- and receives on request the right to vote after several months of observation.
+In order to be accepted, a standardization project must be supported by a minimum number of members belonging to distinct organizations.
+These founding members draft a charter defining the objectives of the <abbr>SWG</abbr>,
+which must be approved by the Technical Committee of the <abbr title="Open Geospatial Consortium">OGC</abbr>.
+Each founding member is endowed with the right to vote, with a limit of one voting member per organization.
+Each new member that wishes to join the <abbr>SWG</abbr> after its creation is granted the role of observer,
+and receives on request the right to vote after several months of observation.
</p><p>
- A <abbr title="Standard Working Group">SWG</abbr> may contain several dozen members,
- but the volunteers performing the bulk of the work are usually fewer.
- Their proposals are submitted to the entire membership of the group, who may accept them by unanimous consent.
- Any objections must be debated, and an alternative proposed.
- <abbr>SWG</abbr>s usually try to debate an issue until a consensus emerges rather than move ahead despite negative votes,
- 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.
+A <abbr>SWG</abbr> may contain several dozen members, but the volunteers performing the bulk of the work are usually fewer.
+Their proposals are submitted to the entire membership of the group, who may accept them by unanimous consent.
+Any objections must be debated, and an alternative proposed.
+<abbr>SWG</abbr>s usually try to debate an issue until a consensus emerges rather than move ahead despite negative votes,
+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 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.
+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 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.
+When the standard is considered ready, the <abbr>SWG</abbr> votes on a motion proposing its submission to a vote by the higher authorities of the <abbr>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>
-
-<h3 id="OGC-OAB">The Architecture Board (<abbr>OAB</abbr>) and the Technical Committee (<abbr>TC</abbr>)</h3>
+<h2 id="OGC-OAB">The Architecture Board (<abbr>OAB</abbr>) and the Technical Committee (<abbr>TC</abbr>)</h2>
<p>
- 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 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.
- The eventual modifications of the standard are submitted to the <abbr>OAB</abbr>, then the standard is published in its final form.
- This distribution is announced in a press release by the <abbr>OGC</abbr>.
+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>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 by the members of the Technical Committee (<abbr>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.
+The eventual modifications of the standard are submitted to the <abbr>OAB</abbr>, then the standard is published in its final form.
+This distribution is announced in a press release by the <abbr>OGC</abbr>.
</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 <abbr>OGC</abbr> standards become <abbr>ISO</abbr> standards.
+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>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 <abbr>OGC</abbr> standards become <abbr>ISO</abbr> standards.
</p>
-
-
-
-<h3 id="OGC-RFC">Procedure for the Submission of Proposals for Modification</h3>
+<h2 id="OGC-RFC">Procedure for the Submission of Proposals for Modification</h2>
<p>
- All users, whether or not they are members of the Open Geospatial Consortium, may propose modifications to <abbr title="Open Geospatial Consortium">OGC</abbr> standards.
- A list of current proposals for changes, along with a form for submitting new proposals, is <a href="http://www.opengeospatial.org/standards/cr">available online</a>.
- Each proposal is reviewed by the <abbr title="Standard Working Group">SWG</abbr>.
+All users, whether or not they are members of the Open Geospatial Consortium, may propose modifications to <abbr title="Open Geospatial Consortium">OGC</abbr> standards.
+A list of current proposals for changes, along with a form for submitting new proposals, is <a href="http://www.opengeospatial.org/standards/cr">available online</a>.
+Each proposal is reviewed by the <abbr title="Standard Working Group">SWG</abbr>.
</p><p>
- Some working groups use other parallel systems for submissions.
- In particular, the GeoAPI project continues to use a <a href="http://jira.codehaus.org/browse/GEO">JIRA task system</a>
- hosted outside of the structures of the <abbr title="Open Geospatial Consortium">OGC</abbr>.
- This set-up exists in part for historical reasons, and in part because developments on the GeoAPI project are done more at the level of source code rather than at the level of documents or class diagrams.
+Some working groups use other parallel systems for submissions, for example GitHub merge requests, hosted outside of the structures of the <abbr>OGC</abbr>.
</p>
+</article>
-
-<h2 id="SpecificationTypes">Different Types of Specifications</h2>
+<h3 id="SpecificationTypes"><span class="section-number">1.1.1.</span> Different Types of Specifications</h3>
<p>
- <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”.
+<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”.
</p><p>
- <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:
-</p>
-<ul>
- <li>
- Attempts to support an object-oriented paradigm result in a verbose approach in certain languages
- (notably the <abbr>XML</abbr> defined by <abbr>ISO</abbr> 19139) — for example, in order to support polymorphism.
- </li>
- <li>
- Certain data structures only exist in a few languages — for example, unions that exist in C/C++ but not in Java.
- </li>
- <li>
- Certain specifications (especially older ones) define operations which lend themselves easily to programming languages or services,
- but not to databases.
- </li>
-</ul>
-<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 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.
+<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.
+Certain data structures only exist in a few languages — for example, unions that exist in C/C++ but not in Java.
</p><p>
- 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 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.”
- But despite their depreciation, <a href="http://www.opengeospatial.org/standards/retired">old implementation specifications</a> remain useful to programs in Java, because:
+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 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 for <abbr>XML</abbr> over other languages.
+Older implementation specifications were deprecated,
+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>OGC</abbr> standard.”
+But despite their depreciation, <a href="http://www.opengeospatial.org/standards/retired">old implementation specifications</a> remain useful to programs in Java, because:
</p>
<ul>
- <li>
- Their simpler models, applied to the same concepts, are helpful in understanding new specifications.
- </li>
- <li>
- They sometimes define easy ways to perform common tasks, where the newer specifications limit themselves to general cases.
- </li>
- <li>
- As operations are more often omitted from the newer specifications,
- the old ones remain a useful supplement when defining <abbr title="Application Programming Interface">API</abbr>s.
- </li>
+<li>Their simpler models, applied to the same concepts, are helpful in understanding new specifications.</li>
+<li>They sometimes define easy ways to perform common tasks, where the newer specifications limit themselves to general cases.</li>
+<li>As operations are more often omitted from the newer specifications, the old ones remain a useful supplement when defining <abbr title="Application Programming Interface">API</abbr>s.</li>
</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 “convenience methods”, not always bringing new functionality, but facilitating the practical use of a library.
+The Apache <abbr title="Spatial Information System">SIS</abbr> project is based on the most recent specifications,
+drawing from the archives of the <abbr>OGC</abbr> to complete certain abstract standards or make them more usable.
+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 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>.
- Finally, GeoAPI packages will be introduced in upcoming chapters.
+The following table lists the main norms used by the project.
+Many norms are published both as <abbr>ISO</abbr> standards and as <abbr>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>.
+Finally, GeoAPI packages will be introduced in upcoming chapters.
</p>
<table>
- <caption>Main Standards Used in the Apache <abbr>SIS</abbr> project</caption>
- <tr>
- <th><abbr>ISO</abbr> Norm</th>
- <th><abbr>OGC</abbr> Norm</th>
- <th>Titre</th>
- <th>GeoAPI package</th>
- <th>Apache SIS package</th>
- </tr>
- <tr>
- <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="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="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>
+<caption>Main Standards Related to the Apache <abbr>SIS</abbr> project</caption>
+<tr>
+<th><abbr>ISO</abbr> Norm</th>
+<th><abbr>OGC</abbr> Norm</th>
+<th>Titre</th>
+<th>GeoAPI package</th>
+<th>Apache SIS package</th>
+</tr>
+<tr>
+<td class="separator" colspan="5">Abstract Specifications</td>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 19103</td>
+<td/>
+<td><i>Conceptual schema language</i></td>
+<td><code class="GeoAPI">org.opengis.util</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.metadata</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.referencing</code></td>
+<td><code class="SIS">org.apache.sis.referencing</code></td>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 19108</td>
+<td/>
+<td><i>Temporal Schema</i></td>
+<td><code class="GeoAPI">org.opengis.temporal</code></td>
+<td/>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 19107</td>
+<td>Topic 1</td>
+<td><i>Feature geometry</i></td>
+<td><code class="GeoAPI">org.opengis.geometry</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.feature</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.coverage</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.observation</code></td>
+<td/>
+</tr>
+<tr>
+<td class="separator" colspan="5">Implementation Specifications</td>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 19139</td>
+<td/>
+<td><i>Metadata <abbr>XML</abbr> schema implementation</i></td>
+<td/>
+<td><code class="SIS">org.apache.sis.xml</code></td>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 13249</td>
+<td/>
+<td><i><abbr>SQL</abbr> spatial</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td><s><abbr>OGC</abbr> 01-009</s></td>
+<td><s><i>Coordinate Transformation Services</i></s></td>
+<td><code class="GeoAPI">org.opengis.referencing</code></td>
+<td><code class="SIS">org.apache.sis.referencing</code></td>
+</tr>
+<tr>
+<td/>
+<td><s><abbr>OGC</abbr> 01-004</s></td>
+<td><s><i>Grid Coverage</i></s></td>
+<td><code class="GeoAPI">org.opengis.coverage</code></td>
+<td><code class="SIS">org.apache.sis.coverage</code></td>
+</tr>
+<tr>
+<td/>
+<td><abbr>SLD</abbr></td>
+<td><i>Styled Layer Descriptor</i></td>
+<td><code class="GeoAPI">org.opengis.style</code></td>
+<td/>
+</tr>
+<tr>
+<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/>
+</tr>
+<tr>
+<td/>
+<td><abbr>WMTS</abbr></td>
+<td><i>Web Map Tile Service</i></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/>
+</tr>
+<tr>
+<td/>
+<td><abbr>WCS</abbr></td>
+<td><i>Web Coverage Service</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td><abbr>WPS</abbr></td>
+<td><i>Web Processing Service</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td>Open<abbr>LS</abbr></td>
+<td><i>Location Services</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td><abbr>SWE</abbr></td>
+<td><i>Sensor Web Enablement</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td><abbr>SOS</abbr></td>
+<td><i>Sensor Observation Service</i></td>
+<td/>
+<td/>
+</tr>
</table>
-<h2 id="DefinitionOfTerms">Definition of Terms</h2>
+<h2 id="About"><span class="section-number">1.2.</span> Conventions Used in This Guide</h2>
<p>
- Standards sometimes favour the application of certain generic terms to particular contexts,
- which may differ from the context in which other communities use these terms.
- For example, the terms <i>domain</i> and <i>range</i> may apply to arbitrary functions in order to designate
- a set of possible values of inputs and outputs respectively.
- But the functions to which they are applied by certain <abbr title="International Organization for Standardization">ISO</abbr> standards are not the same as the functions to which they are applied by other libraries.
- For example, <abbr>ISO</abbr> 19123 applies these terms to <code class="OGC">CV_Coverage</code> objects,
- seen as functions in which the <i>domain</i> is the set of spatio-temporal coordinates encompassed by the data,
- and the <i>range</i> is the set of values encompassed.
- But <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>'s <abbr title="Network Common Data Form">NetCDF</abbr> library applies these terms instead to the function of converting pixel indices (its <i>domain</i>) to spatial-temporal coordinates (its <i>range</i>).
- Thus the <abbr>UCAR</abbr> library's <i>range</i> may be the <i>domain</i> of <abbr>ISO</abbr> 19123.
-</p><p>
- The Apache <abbr title="Spatial Information System">SIS</abbr> library prefers as much as possible to use terms in the sense of
- <abbr title="Open Geospatial Consortium">OGC</abbr> and <abbr title="International Organization for Standardization">ISO</abbr> norms.
- Particular care must be taken, however, with the interfaces between <abbr>SIS</abbr> and certain other external libraries,
- in order to reduce the risk of confusion.
+The elements defined in a computer language, such as classes and methods in Java or elements in an <abbr>XML</abbr> document,
+appear in monospaced font.
+In order to facilitate an understanding of the relationships between Apache <abbr title="Spatial Information System">SIS</abbr> and the standards, these elements are also represented using the following colour codes:
+</p>
+<ul>
+<li>
+Elements defined in the <abbr title="Open Geospatial Consortium">OGC</abbr> standard
+or the <abbr title="International Organization for Standardization">ISO</abbr> standard appear in blue.
+Example: <code class="OGC">CD_Ellipsoid</code>.
+</li>
+<li>
+Elements defined in GeoAPI appear in green.
+Example: <code class="GeoAPI">Ellipsoid</code>.
+</li>
+<li>
+Elements defined in Apache <abbr title="Spatial Information System">SIS</abbr> appear in brown.
+Example: <code class="SIS">DefaultEllipsoid</code>.
+</li>
+<li>
+Other elements, such as those in standard Java, are left in black.
+Example: <code>String</code>.
+</li>
+</ul>
+<p>
+Text in gray boxes are for information purpose only and can be ignored.
</p>
-<h1 id="GeoAPI">GeoAPI</h1>
+<h3 id="DefinitionOfTerms"><span class="section-number">1.2.1.</span> Definition of Terms</h3>
<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,
- 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.
- These interfaces benefit both client applications and libraries:
+Standards sometimes favour the application of certain generic terms to particular contexts,
+which may differ from the context in which other communities use these terms.
+For example, the terms <i>domain</i> and <i>range</i> may apply to arbitrary functions in order to designate
+a set of possible values of inputs and outputs respectively.
+But the functions to which they are applied by certain <abbr title="International Organization for Standardization">ISO</abbr> standards are not the same as the functions to which they are applied by other libraries.
+For example, <abbr>ISO</abbr> 19123 applies these terms to <code class="OGC">CV_Coverage</code> objects,
+seen as functions in which the <i>domain</i> is the set of spatio-temporal coordinates encompassed by the data,
+and the <i>range</i> is the set of values encompassed.
+But <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>'s <abbr title="Network Common Data Form">NetCDF</abbr> library
+applies these terms instead to the function of converting pixel indices (its <i>domain</i>) to spatial-temporal coordinates (its <i>range</i>).
+Thus the <abbr>UCAR</abbr> library's <i>range</i> may be the <i>domain</i> of <abbr>ISO</abbr> 19123.
+</p><p>
+The Apache <abbr title="Spatial Information System">SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr title="Open Geospatial Consortium">OGC</abbr> and <abbr>ISO</abbr> norms.
+Particular care must be taken, however, with the interfaces between <abbr>SIS</abbr> and certain other external libraries,
+in order to reduce the risk of confusion.
+</p>
+</section>
+<section>
+<header>
+<h1 id="GeoAPI"><span class="section-number">2.</span> GeoAPI</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Foreword">Previous chapter</a></div><div class="next-chapter"><a href="#XML-ISO">Next chapter</a> ➡</div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#SpecificationToInterfaces">Interface Specifications</a><ul>
+<li><a href="#UML-annotation">Mapping Given by @UML Annotations</a></li>
+<li><a href="#MappingToJDK">Implicit Mapping to Standard JDK</a></li></ul></li>
+<li><a href="#ServiceLoader">Fetching an Implementation of the Interfaces</a><ul>
+<li><a href="#GeoAPI-simple">Defining Custom Implementations</a></li></ul></li>
+<li><a href="#GeoAPI-modules">GeoAPI Modules</a><ul>
+<li><a href="#GeoAPI-core">The Interfaces' Definition Modules</a></li>
+<li><a href="#GeoAPI-conformance">The Conformance Tests Module</a><ul>
+<li><a href="#GeoAPI-validators">Instance Validations</a></li>
+<li><a href="#GeoAPI-tests">Executing Pre-defined Tests</a></li></ul></li>
+<li><a href="#GeoAPI-examples">Example Modules</a></li></ul></li></ul></nav>
+<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,
+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.
+These interfaces benefit both client applications and libraries:
</p>
<ul>
- <li><p>
- Developers of client applications benefit from the greater knowledge base available on the Internet
- (due to the many publications related to <abbr title="Open Geospatial Consortium">OGC</abbr> standards), as well as increased interoperability.
- Interoperability is facilitated by a better separation between applications that <em>call</em> GeoAPI functions,
- and libraries that <em>implement</em> GeoAPI.
- The separation is similar to that offered by the <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/"><abbr>JDBC</abbr></a> (<i>Java Database Connectivity</i>) interfaces of standard Java.
- Using the interfaces' <abbr title="Application Programming Interface">API</abbr>,
- developers can ignore the underlying implementation.
- For example, they can perform cartographic projections with the help of the <a href="http://www.geoapi.org/geoapi-proj4/index.html">Proj.4</a> library, or the Apache <abbr title="Spatial Information System">SIS</abbr> library,
- without having to change their programs when they change libraries.
- </p></li>
- <li><p>
- The developers of libraries inherit the expertise of the specifications' authors,
- via the models that represent interfaces.
- GeoAPI also provides a framework within which developers can prioritize the implementation of the features they most need,
- while leaving the remaining features as extension points for future developments.
- For example, clients can call a GeoAPI function even if it is not yet supported by the library,
- and simply get a null value until a new version of the library returns a relevant value.
- </p></li>
+<li><p>
+Developers of client applications benefit from the greater knowledge base available on the Internet
+(due to the many publications related to <abbr>OGC</abbr> standards), as well as increased interoperability.
+Interoperability is facilitated by a better separation between applications that <em>call</em> GeoAPI functions,
+and libraries that <em>implement</em> GeoAPI.
+The separation is similar to that offered by the <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/"><abbr title="Java DataBase Connectivity">JDBC</abbr></a> (<i>Java Database Connectivity</i>) interfaces of standard Java.
+Using the interfaces' <abbr title="Application Programming Interface">API</abbr>, developers can ignore the underlying implementation.
+For example, they can perform cartographic projections with the help of the <a href="http://www.geoapi.org/geoapi-proj4/index.html">Proj.4</a> library, or the Apache <abbr title="Spatial Information System">SIS</abbr> library,
+without having to change their programs when they change libraries.
+</p></li>
+<li><p>
+The developers of libraries inherit the expertise of the specifications' authors, via the models that represent interfaces.
+GeoAPI also provides a framework within which developers can prioritize the implementation of the features they most need,
+while leaving the remaining features as extension points for future developments.
+For example, clients can call a GeoAPI function even if it is not yet supported by the library,
+and simply get a null value until a new version of the library returns a relevant value.
+</p></li>
</ul>
-<aside>
- <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>,
- <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 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.
- </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.
- In the meantime, the <abbr>OGC</abbr> abandonned some of their specifications in favor of <abbr title="International Organization for Standardization">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 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.
- <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>
-</aside>
-
-
-<h2 id="SpecificationToInterfaces">Interface Specifications</h2>
-<p>
- Since <abbr title="Open Geospatial Consortium">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 title="Unified Modeling Language">UML</abbr> schemas rather than <abbr title="XML Schema Definition">XSD</abbr> ones.
+<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 title="Open Geospatial Consortium">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>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 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.
</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:
+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 title="International Organization for Standardization">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"><span class="section-number">2.1.</span> Interface Specifications</h2>
+<p>
+Since <abbr title="Open Geospatial Consortium">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 title="XML Schema Definition">XSD</abbr> schemas</a>
+into Java interfaces using command line utility <code>xjc</code>.
+As this utility is included in most Java distributions (it is one of the <a href="http://jaxb.java.net"><abbr>JAXB</abbr></a> tools),
+this approach is favoured by many projects found on the Internet.
+Other approaches use tools integrated into the Eclipse Development Environment,
+which is based on <abbr title="Unified Modeling Language">UML</abbr> schemas rather than <abbr>XSD</abbr> ones.
+</p><p>
+A similar approach was attempted in the early days of the GeoAPI project, but was quickly abandoned.
+We favor a manual approach for the following reasons:
</p>
<ul>
- <li>
- <p>
- Some <abbr title="XML Schema Definition">XSD</abbr> schemas are much more verbose than the original <abbr title="Unified Modeling Language">UML</abbr> schemas.
- Converting from <abbr>XSD</abbr> schemas introduces — at least in the case of metadata —
- almost double the number of interfaces actually defined by the standard, without adding any new features.
- <abbr>XSD</abbr> schemas also define attributes specific to <abbr>XML</abbr> documents (<code class="OGC">id</code>,
- <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), that do not exist in the original <abbr>UML</abbr> diagrams,
- and which we do not necessarily wish to expose in a Java <abbr title="Application Programming Interface">API</abbr>.
- Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common.
- </p>
- <div class="example"><p><b>Example:</b>
- <abbr title="XML Schema Definition">XSD</abbr> metadata schemas insert a <code class="OGC"><gmd:CI_Citation></code> element
- inside a <code class="OGC"><gmd:citation></code>,
- a <code class="OGC"><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 title="Open Geospatial Consortium">OGC</abbr> standards use different naming conventions than Java.
- In particular, the names of almost all <abbr>OGC</abbr> classes begin with a two-letter prefix,
- such as <code class="OGC">MD_Identifier</code>.
- This prefixes fulfill the same role as package names in Java.
- GeoAPI adapts this practice by using interface names without prefixes and placing these interfaces in packages corresponding to the prefixes,
- but with more descriptive names.
- Occasionally we also change the names; for example, to avoid acronyms, or to conform to an established convention such as JavaBeans.
- </p>
- <div class="example"><p><b>Example:</b>
- The <abbr title="Open Geospatial Consortium">OGC</abbr> class <code class="OGC">MD_Identifier</code> becomes the
- <code class="GeoAPI">Identifier</code> interface in the <code class="GeoAPI">org.opengis.metadata</code> package.
- The <abbr>OGC</abbr> class <code class="OGC">SC_CRS</code> becomes the <code class="GeoAPI">CoordinateReferenceSystem</code> interface,
- and the <code class="OGC">usesDatum</code> association becomes a <code class="GeoAPI">getDatum()</code> method,
- rather than the “<code>getUsesDatum()</code>” that would result from an automatic conversion tool.
- We do not allow programs to blindly apply rules that ignore the conventions of the community whose schemas we translate.
- </p></div>
- </li>
- <li>
- <p>
- The standards may contain structures that do not have a direct equivalent in Java,
- such as unions similar to what we would find in C/C++.
- The strategy used to obtain an equivalent feature in Java depends on the context:
- multiple inheritance of interfaces, modification of the hierarchy, or simply omitting the union.
- These decisions are made case-by-case based on a needs analysis.
- </p>
- <div class="example"><p><b>Example:</b>
- <abbr>ISO</abbr> 19111 standard defines different types of coordinate systems, such as spherical, cylindrical, polar or Cartesian.
- It then defines several <em>subsets</em> of these types of coordinate systems systems.
- These subsets, represented by unions, serve to specify that a class may only be associated with a particular type of coordinate system.
- For example, a union of types may be associated with an image, named <code class="OGC">CS_ImageCS</code>,
- which can only contain <code class="OGC">CS_CartesianCS</code> and <code class="OGC">CS_AffineCS</code>.
- In this case, we get the desired effect in Java through a modification of the hierarchy of classes:
- we define the <code class="GeoAPI">CartesianCS</code> interface as a specialization of <code class="GeoAPI">AffineCS</code>,
- which is semantically correct.
- But it is not possible to apply a similar strategy to other unions without violating the semantics.
- </p></div>
- </li>
- <li>
- <p>
- Several specifications overlap.
- GeoAPI performs the work of integration by replacing some duplicate structures with references to equivalent structures from the standards that best represent them.
- </p>
- <div class="example"><p><b>Example:</b>
- <abbr>ISO</abbr> 19115:2003 standard, which defines metadata structures,
- also attempts to describe a few structures representing coordinate reference systems (<abbr title="Coordinate Reference System">CRS</abbr>).
- Yet these are also the focus of another standard: <abbr>ISO</abbr> 19111.
- At the same time, <abbr>ISO</abbr> 19111:2007 states in section 3 that it reuses all of the elements of
- <abbr>ISO</abbr> 19115:2003 except <code class="OGC">MD_CRS</code> and its components.
- GeoAPI interfaces reduce the redundancy by applying the exclusion recommended by <abbr>ISO</abbr> 19111 to the entire project.
- </p></div>
- </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 class="OGC">MI_Band</code>,
- which extends the class <code class="OGC">MD_Band</code> from <abbr>ISO</abbr> 19115-1 by adding attributes that would have appeared
- directly in the parent class if there were ready on time.
- In GeoAPI, we have chosen to “repair” these anomalies by fusing these two classes into a single interface.
- </p></div>
- </li>
+<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 title="Application Programming Interface">API</abbr>.
+Converting from <abbr>UML</abbr> schemas avoids this problem, but tools capable of performing this operation are less common.
+</p>
+<div class="example"><p><b>Example:</b>
+<abbr>XSD</abbr> metadata schemas insert a <code class="OGC"><gmd:CI_Citation></code> element
+inside a <code class="OGC"><gmd:citation></code>,
+a <code class="OGC"><gmd:CI_OnlineResource></code> element inside a <code class="OGC"><gmd:onlineResource></code>,
+and so on for the hundreds of classes defined by <abbr title="International Organization for Standardization">ISO</abbr> 19115 standard.
+This redundancy is certainly not necessary in a Java program.
+</p></div>
+</li>
+<li>
+<p>
+<abbr>OGC</abbr> standards use different naming conventions than Java.
+In particular, the names of almost all <abbr>OGC</abbr> classes begin with a two-letter prefix,
+such as <code class="OGC">MD_Identifier</code>.
+This prefixes fulfill the same role as package names in Java.
+GeoAPI adapts this practice by using interface names without prefixes and placing these interfaces in packages corresponding to the prefixes,
+but with more descriptive names.
+Occasionally we also change the names; for example, to avoid acronyms, or to conform to an established convention such as JavaBeans.
+</p>
+<div class="example"><p><b>Example:</b>
+The <abbr>OGC</abbr> class <code class="OGC">MD_Identifier</code> becomes the
+<code class="GeoAPI">Identifier</code> interface in the <code class="GeoAPI">org.opengis.metadata</code> package.
+The <abbr>OGC</abbr> class <code class="OGC">SC_CRS</code> becomes the <code class="GeoAPI">CoordinateReferenceSystem</code> interface,
+and the <code class="OGC">usesDatum</code> association becomes a <code class="GeoAPI">getDatum()</code> method,
+rather than the “<code>getUsesDatum()</code>” that would result from an automatic conversion tool.
+We do not allow programs to blindly apply rules that ignore the conventions of the community whose schemas we translate.
+</p></div>
+</li>
+<li>
+<p>
+The standards may contain structures that do not have a direct equivalent in Java,
+such as unions similar to what we would find in C/C++.
+The strategy used to obtain an equivalent feature in Java depends on the context:
+multiple inheritance of interfaces, modification of the hierarchy, or simply omitting the union.
+These decisions are made case-by-case based on a needs analysis.
+</p>
+<div class="example"><p><b>Example:</b>
+<abbr>ISO</abbr> 19111 standard defines different types of coordinate systems, such as spherical, cylindrical, polar or Cartesian.
+It then defines several <em>subsets</em> of these types of coordinate systems systems.
+These subsets, represented by unions, serve to specify that a class may only be associated with a particular type of coordinate system.
+For example, a union of types may be associated with an image, named <code class="OGC">CS_ImageCS</code>,
+which can only contain <code class="OGC">CS_CartesianCS</code> and <code class="OGC">CS_AffineCS</code>.
+In this case, we get the desired effect in Java through a modification of the hierarchy of classes:
+we define the <code class="GeoAPI">CartesianCS</code> interface as a specialization of <code class="GeoAPI">AffineCS</code>,
+which is semantically correct.
+But it is not possible to apply a similar strategy to other unions without violating the semantics.
+</p></div>
+</li>
+<li>
+<p>
+Several specifications overlap.
+GeoAPI performs the work of integration by replacing some duplicate structures with references to equivalent structures from the standards that best represent them.
+</p>
+<div class="example"><p><b>Example:</b>
+<abbr>ISO</abbr> 19115:2003 standard, which defines metadata structures,
+also attempts to describe a few structures representing coordinate reference systems (<abbr title="Coordinate Reference System">CRS</abbr>).
+Yet these are also the focus of another standard: <abbr>ISO</abbr> 19111.
+At the same time, <abbr>ISO</abbr> 19111:2007 states in section 3 that it reuses all of the elements of
+<abbr>ISO</abbr> 19115:2003 except <code class="OGC">MD_CRS</code> and its components.
+GeoAPI interfaces reduce the redundancy by applying the exclusion recommended by <abbr>ISO</abbr> 19111 to the entire project.
+</p></div>
+</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 class="OGC">MI_Band</code>,
+which extends the class <code class="OGC">MD_Band</code> from <abbr>ISO</abbr> 19115-1 by adding attributes that would have appeared
+directly in the parent class if there were ready on time.
+In GeoAPI, we have chosen to “repair” these anomalies by fusing these two classes into a single interface.
+</p></div>
+</li>
</ul>
<p>
- Deviations from the standards are documented in each affected class and method.
- Each mention of a deviation is also collected on a <a href="http://www.geoapi.org/3.0/javadoc/departures.html">single page</a> in order to provide an overview.
- Since these deviations blur the relationships between the standards and certain Java interfaces,
- the correspondence between these languages is explained by <code class="GeoAPI">@UML</code> annotations and property files described in the following section.
+Deviations from the standards are documented in each affected class and method.
+Each mention of a deviation is also collected on a <a href="http://www.geoapi.org/3.0/javadoc/departures.html">single page</a> in order to provide an overview.
+Since these deviations blur the relationships between the standards and certain Java interfaces,
+the correspondence between these languages is explained by <code class="GeoAPI">@UML</code> annotations and property files described in the following section.
</p>
-<h3 id="UML-annotation">Mapping Given by <code>@UML</code> Annotations</h3>
+<h3 id="UML-annotation"><span class="section-number">2.1.1.</span> Mapping Given by <code class="GeoAPI">@UML</code> Annotations</h3>
<p>
- For each class, method and constant defined by an <abbr title="Open Geospatial Consortium">OGC</abbr> or <abbr title="International Organization for Standardization">ISO</abbr> standard,
- GeoAPI indicates its provenance using annotations defined in the <code class="GeoAPI">org.opengis.annotation</code> package.
- In particular, the <code class="GeoAPI">@UML</code> annotations indicates the standard,
- the name of the element in that standard, and also its obligation.
- For example, in the following code snippet, the first <code class="GeoAPI">@UML</code> code indicates that the Java interface that follows
- (<code class="GeoAPI">ProjectedCRS</code>) is defined using the <code class="OGC">SC_ProjectedCRS</code> type of <abbr>ISO</abbr> 19111 standard.
- The second <code class="GeoAPI">@UML</code> annotation, this time applied to the <code class="GeoAPI">getCoordinateSystem()</code> method,
- indicates that this method is defined using the <code class="OGC">coordinateSystem</code> association of <abbr>ISO</abbr> 19111 standard,
- and that this association is mandatory — meaning, in Java, that the method is not allowed to return a <code>null</code> value.
+For each class, method and constant defined by an <abbr title="Open Geospatial Consortium">OGC</abbr> or <abbr title="International Organization for Standardization">ISO</abbr> standard,
+GeoAPI indicates its provenance using annotations defined in the <code class="GeoAPI">org.opengis.annotation</code> package.
+In particular, the <code class="GeoAPI">@UML</code> annotations indicates the standard,
+the name of the element in that standard, and also its obligation.
+For example, in the following code snippet, the first <code class="GeoAPI">@UML</code> code indicates that the Java interface that follows
+(<code class="GeoAPI">ProjectedCRS</code>) is defined using the <code class="OGC">SC_ProjectedCRS</code> type of <abbr>ISO</abbr> 19111 standard.
+The second <code class="GeoAPI">@UML</code> annotation, this time applied to the <code class="GeoAPI">getCoordinateSystem()</code> method,
+indicates that this method is defined using the <code class="OGC">coordinateSystem</code> association of <abbr>ISO</abbr> 19111 standard,
+and that this association is mandatory — meaning, in Java, that the method is not allowed to return a <code>null</code> value.
</p>
<pre><b>package</b> <code class="GeoAPI">org.opengis.referencing.crs</code>;
-<code class="comment">
-/**
+
+<code class="comment">/**
* A 2D coordinate reference system used to approximate the shape of the earth on a planar surface.
*/</code>
-<code class="GeoAPI">@UML</code>(<var>specification</var> = ISO_19111,
- <var>identifier</var> = "<code class="OGC">SC_ProjectedCRS</code>")
-<b>public interface</b> <code class="GeoAPI">ProjectedCRS</code> <b>extends</b> <code class="GeoAPI">GeneralDerivedCRS</code> {<code class="comment">
- /**
+@<code class="GeoAPI">UML</code>(specification = ISO_19111,
+ identifier = <i>"<code class="OGC">SC_ProjectedCRS</code>"</i>)
+<b>public</b> <b>interface</b> <code class="GeoAPI">ProjectedCRS</code> <b>extends</b> <code class="GeoAPI">GeneralDerivedCRS</code> {
+ <code class="comment">/**
* Returns the coordinate system, which must be Cartesian.
*/</code>
- <code class="GeoAPI">@UML</code>(<var>obligation</var> = MANDATORY,
- <var>specification</var> = ISO_19111,
- <var>identifier</var> = "<code class="OGC">coordinateSystem</code>")
- <code class="GeoAPI">CartesianCS getCoordinateSystem()</code>;
+ @<code class="GeoAPI">UML</code>(obligation = MANDATORY,
+ specification = ISO_19111,
+ identifier = <i>"<code class="OGC">coordinateSystem</code>"</i>)
+ <code class="GeoAPI">CartesianCS</code> <code class="GeoAPI">getCoordinateSystem()</code>;
}</pre>
<p>
- Java reflection methods allow access to this information during the execution of an application.
- This is useful for displaying UML identifiers for users familiar with <abbr title="Open Geospatial Consortium">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 class="GeoAPI">Citation</code> interface:
+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 class="GeoAPI">Citation</code> interface:
</p>
-<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>id</var> = <var>annot</var>.identifier();
-System.out.println("The standard name for the " + <var>method</var>.getName() + " method is " + <var>id</var>);</pre>
+<pre>Class<?> type = <code class="GeoAPI">Citation</code>.<b>class</b>;
+Method method = type.getMethod(<i>"<code class="GeoAPI">getTitle</code>"</i>, (Class<?>[]) <b>null</b>);
+<code class="GeoAPI">UML</code> annot = method.getAnnotation(<code class="GeoAPI">UML</code>.<b>class</b>);
+String id = annot.identifier();
+System.out.println(<i>"The standard name for the "</i> + method.getName() + <i>" method is "</i> + id);</pre>
<p>
- 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.
+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 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.
+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.
</p>
-<pre>Properties <var>isoToGeoAPI</var> = <b>new</b> Properties();
-<b>try</b> (InputStream in = <code class="GeoAPI">UML</code>.class.getResourceAsStream("<code class="GeoAPI">class-index.properties</code>")) {
- <var>isoToGeoAPI</var>.load(in);
+<pre>Properties isoToGeoAPI = <b>new</b> Properties();
+<b>try</b> (InputStream in = <code class="GeoAPI">UML</code>.<b>class</b>.getResourceAsStream(<i>"<code class="GeoAPI">class-index.properties</code>"</i>)) {
+ isoToGeoAPI.load(in);
}
-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 for <abbr>ISO</abbr> type " + <var>isoName</var> + " is " + <var>type</var>);</pre>
+String isoName = <i>"<code class="OGC">CI_Citation</code>"</i>;
+String geoName = getProperty(isoName);
+Class<?> type = Class.forName(geoName);
+System.out.println(<i>"The GeoAPI interface for <abbr>ISO</abbr> type "</i> + isoName + <i>" is "</i> + type);</pre>
<p>
- 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.
+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 Mapping to Standard <abbr>JDK</abbr></h3>
+<h3 id="MappingToJDK"><span class="section-number">2.1.2.</span> Implicit Mapping to Standard <abbr>JDK</abbr></h3>
<p>
- Some classes and methods have neither an <code class="GeoAPI">@UML</code> annotation, nor an entry in the <code class="GeoAPI">class-index.properties</code> file.
- They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>.
- In this last case, the mapping to <abbr 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.
+Some classes and methods have neither an <code class="GeoAPI">@UML</code> annotation, nor an entry in the <code class="GeoAPI">class-index.properties</code> file.
+They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>.
+In this last case, the mapping to <abbr title="International Organization for Standardization">ISO</abbr> standards is implicit.
+The following table describes this mapping for <abbr>ISO</abbr> 19103 types.
+Java's primitive types are preferred when applicable,
+but where necessary their wrappers are used in order to authorize null values.
</p>
<table>
- <caption>Mapping between <abbr>ISO</abbr> 19103 and <abbr>JDK</abbr> types</caption>
- <tr>
- <th><abbr>ISO</abbr> type</th>
- <th><abbr>JDK</abbr> type</th>
- <th>Remarks</th>
- </tr>
- <tr>
- <td class="separator" colspan="2">Numbers</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Integer</code></td>
- <td><code>int</code></td>
- <td class="leftBorder">Sometimes <code>java.lang.Integer</code> for optional attributes.</td>
- </tr>
- <tr>
- <td><code class="OGC">Integer</code> (in some cases)</td>
- <td><code>long</code></td>
- <td class="leftBorder">Sometimes <code>java.lang.Long</code> for optional attributes.</td>
- </tr>
- <tr>
- <td><code class="OGC">Real</code></td>
- <td><code>double</code></td>
- <td class="leftBorder">Sometimes <code>java.lang.Double</code> for optional attributes.</td>
- </tr>
- <tr>
- <td><code class="OGC">Decimal</code></td>
- <td><code>java.math.BigDecimal</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Number</code></td>
- <td><code>java.lang.Number</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Texts</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">FreeText</code></td>
- <td>(no equivalent)</td>
- <td class="leftBorder">See <code class="GeoAPI">org.opengis.util.InternationalString</code> below.</td>
- </tr>
- <tr>
- <td><code class="OGC">CharacterString</code></td>
- <td><code>java.lang.String</code></td>
- <td class="leftBorder">Often <code class="GeoAPI">org.opengis.util.InternationalString</code> (see below).</td>
- </tr>
- <tr>
- <td><code class="OGC">LocalisedCharacterString</code></td>
- <td><code>java.lang.String</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Sequence<Character></code></td>
- <td><code>java.lang.CharSequence</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Character</code></td>
- <td><code>char</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Dates and hours</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Date</code></td>
- <td><code>java.util.Date</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Time</code></td>
- <td><code>java.util.Date</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">DateTime</code></td>
- <td><code>java.util.Date</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Collections</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Collection</code></td>
- <td><code>java.util.Collection</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Bag</code></td>
- <td><code>java.util.Collection</code></td>
- <td class="leftBorder">A <code class="OGC">Bag</code> is similar to a
- <code class="OGC">Set</code> without being restricted by uniqueness.</td>
- </tr>
- <tr>
- <td><code class="OGC">Set</code></td>
- <td><code>java.util.Set</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Sequence</code></td>
- <td><code>java.util.List</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Dictionary</code></td>
- <td><code>java.util.Map</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">KeyValuePair</code></td>
- <td><code>java.util.Map.Entry</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Enumerations</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Enumeration</code></td>
- <td><code>java.lang.Enum</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">CodeList</code></td>
- <td>(no equivalent)</td>
- <td class="leftBorder">See <code class="GeoAPI">org.opengis.util.CodeList</code> below.</td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Various</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Boolean</code></td>
- <td><code>boolean</code></td>
- <td class="leftBorder">Sometimes <code>java.lang.Boolean</code> for optional attributes.</td>
- </tr>
- <tr>
- <td><code class="OGC">Any</code></td>
- <td><code>java.lang.Object</code></td>
- <td class="leftBorder"></td>
- </tr>
+<caption>Mapping between <abbr>ISO</abbr> 19103 and <abbr>JDK</abbr> types</caption>
+<tr>
+<th><abbr>ISO</abbr> type</th>
+<th><abbr>JDK</abbr> type</th>
+<th>Remarks</th>
+</tr>
+<tr>
+<td class="separator" colspan="2">Numbers</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Integer</code></td>
+<td><code>int</code></td>
+<td class="leftBorder">Sometimes <code>java.lang.Integer</code> for optional attributes.</td>
+</tr>
+<tr>
+<td><code class="OGC">Integer</code> (in some cases)</td>
+<td><code>long</code></td>
+<td class="leftBorder">Sometimes <code>java.lang.Long</code> for optional attributes.</td>
+</tr>
+<tr>
+<td><code class="OGC">Real</code></td>
+<td><code>double</code></td>
+<td class="leftBorder">Sometimes <code>java.lang.Double</code> for optional attributes.</td>
+</tr>
+<tr>
+<td><code class="OGC">Decimal</code></td>
+<td><code>java.math.BigDecimal</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Number</code></td>
+<td><code>java.lang.Number</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td class="separator" colspan="2">Texts</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">FreeText</code></td>
+<td>(no equivalent)</td>
+<td class="leftBorder">See <code class="GeoAPI">org.opengis.util.InternationalString</code> below.</td>
+</tr>
+<tr>
+<td><code class="OGC">CharacterString</code></td>
+<td><code>java.lang.String</code></td>
+<td class="leftBorder">Often <code class="GeoAPI">org.opengis.util.InternationalString</code> (see below).</td>
+</tr>
+<tr>
+<td><code class="OGC">LocalisedCharacterString</code></td>
+<td><code>java.lang.String</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Sequence<Character></code></td>
+<td><code>java.lang.CharSequence</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Character</code></td>
+<td><code>char</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td class="separator" colspan="2">Dates and hours</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Date</code></td>
+<td><code>java.util.Date</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Time</code></td>
+<td><code>java.util.Date</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">DateTime</code></td>
+<td><code>java.util.Date</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td class="separator" colspan="2">Collections</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Collection</code></td>
+<td><code>java.util.Collection</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Bag</code></td>
+<td><code>java.util.Collection</code></td>
+<td class="leftBorder">A <code class="OGC">Bag</code> is similar to a
+<code class="OGC">Set</code> without being restricted by uniqueness.</td>
+</tr>
+<tr>
+<td><code class="OGC">Set</code></td>
+<td><code>java.util.Set</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Sequence</code></td>
+<td><code>java.util.List</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Dictionary</code></td>
+<td><code>java.util.Map</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">KeyValuePair</code></td>
+<td><code>java.util.Map.Entry</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td class="separator" colspan="2">Enumerations</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Enumeration</code></td>
+<td><code>java.lang.Enum</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">CodeList</code></td>
+<td>(no equivalent)</td>
+<td class="leftBorder">See <code class="GeoAPI">org.opengis.util.CodeList</code> below.</td>
+</tr>
+<tr>
+<td class="separator" colspan="2">Various</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Boolean</code></td>
+<td><code>boolean</code></td>
+<td class="leftBorder">Sometimes <code>java.lang.Boolean</code> for optional attributes.</td>
+</tr>
+<tr>
+<td><code class="OGC">Any</code></td>
+<td><code>java.lang.Object</code></td>
+<td class="leftBorder"/>
+</tr>
</table>
<p>
- The nearest equivalent for <code class="OGC">CharacterString</code> is the <code>String</code> class,
- but GeoAPI often uses the <code class="GeoAPI">InternationalString</code> interface, allowing the client to choose the language.
- For example, it is useful on a server that simultaneously provides pages in multiple languages.
- By returning translations when objects are used rather than at the time of their creation,
- we allow the <abbr title="Spatial Information System">SIS</abbr> library to provide the same instances of <code class="GeoAPI">Metadata</code>
- or <code class="GeoAPI">Coverage</code> (for example) for the same data, regardless of the client's language.
- Translations may be made on the fly with the help of the application's <code>ResourceBundle</code>,
- or may be provided directly with the data (as in the case of <code class="GeoAPI">Metadata</code>).
+The nearest equivalent for <code class="OGC">CharacterString</code> is the <code>String</code> class,
+but GeoAPI often uses the <code class="GeoAPI">InternationalString</code> interface, allowing the client to choose the language.
+For example, it is useful on a server that simultaneously provides pages in multiple languages.
+By returning translations when objects are used rather than at the time of their creation,
+we allow the <abbr title="Spatial Information System">SIS</abbr> library to provide the same instances of <code class="GeoAPI">Metadata</code>
+or <code class="GeoAPI">Coverage</code> (for example) for the same data, regardless of the client's language.
+Translations may be made on the fly with the help of the application's <code>ResourceBundle</code>,
+or may be provided directly with the data (as in the case of <code class="GeoAPI">Metadata</code>).
</p>
<p>
- An <code class="OGC">Enumeration</code> corresponds to an <code>Enum</code> in Java.
- Both define all authorized values, without allowing the user to add any.
- A <code class="OGC">CodeList</code> is similar to an enumeration, except that users may add their own items.
- Standard <abbr 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 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.
+An <code class="OGC">Enumeration</code> corresponds to an <code>Enum</code> in Java.
+Both define all authorized values, without allowing the user to add any.
+A <code class="OGC">CodeList</code> is similar to an enumeration, except that users may add their own items.
+Standard <abbr>JDK</abbr> does not offer this possibility.
+GeoAPI defines an abstract <code class="GeoAPI">CodeList</code> class that reproduces some of the functionality of <code>Enum</code> while being extensible.
+Extensions are made available by the <code class="GeoAPI">valueOf(String)</code> static method, which, in contrast to <code>Enum</code>,
+creates new instances if the name provided does not correspond to the name of an existing instance.
</p>
-<pre><code 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 cache the previously requested values.";</pre>
+<pre><code class="GeoAPI">MediumName</code> cdRom = <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">CD_ROM;</code>
+<code class="GeoAPI">MediumName</code> usbKey = <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">USB_KEY</code>"</i>); <code class="comment">// There is no constraint on this value.
+</code><b>assert</b> <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">CD_ROM</code>"</i>) == cdRom : <i>"valueOf must return existing constants."</i>;
+<b>assert</b> <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">USB_KEY</code>"</i>) == usbKey : <i>"valueOf must cache the previously requested values."</i>;</pre>
-<h2 id="ServiceLoader">Fetching an Implementation of the Interfaces</h2>
+<h2 id="ServiceLoader"><span class="section-number">2.2.</span> Fetching an Implementation of the Interfaces</h2>
<p>
- 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 interfaces of the
- <code class="GeoAPI">org.opengis.referencing.datum</code> package.
- A <code class="GeoAPI">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 class="GeoAPI">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.
+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 interfaces of the
+<code class="GeoAPI">org.opengis.referencing.datum</code> package.
+A <code class="GeoAPI">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 class="GeoAPI">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.
+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><b>import</b> <code class="GeoAPI">org.opengis.referencing.GeodeticDatum</code>;
-<b>import</b> <code class="GeoAPI">org.opengis.referencing.DatumFactory</code>;
+<pre><b>import</b> org.opengis.referencing.<code class="GeoAPI">GeodeticDatum</code>;
+<b>import</b> org.opengis.referencing.<code class="GeoAPI">DatumFactory</code>;
<b>import</b> java.util.ServiceLoader;
-<b>public class</b> MyApplication {
- <b>public void</b> createMyDatum() {
- ServiceLoader <var>loader</var> = ServiceLoader.load(<code class="GeoAPI">DatumFactory</code>.class);
- <code class="GeoAPI">DatumFactory</code> <var>factory</var> = <var>loader</var>.iterator().next();
- <code class="GeoAPI">GeodeticDatum</code> <var>myDatum</var> = <var>factory</var>.<code class="GeoAPI">createGeodeticDatum</code>(…);
+<b>public</b> <b>class</b> MyApplication {
+ <b>public</b> <b>void</b> createMyDatum() {
+ ServiceLoader loader = ServiceLoader.load(<code class="GeoAPI">DatumFactory</code>.<b>class</b>);
+ <code class="GeoAPI">DatumFactory</code> factory = loader.iterator().next();
+ <code class="GeoAPI">GeodeticDatum</code> myDatum = factory.<code class="GeoAPI">createGeodeticDatum</code>(…);
}
}</pre>
-<h3 id="GeoAPI-simple">Defining Custom Implementations</h3>
+<h3 id="GeoAPI-simple"><span class="section-number">2.2.1.</span> 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.
+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>
<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 class="GeoAPI">geoapi-examples</code> module, discussed later, provides such combinations.
- The following table lists a few possible combinations:
+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 title="Coordinate Reference System">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 class="GeoAPI">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 class="GeoAPI">CoordinateReferenceSystem</code></td>
- <td><code class="GeoAPI">CoordinateSystem</code></td>
- <td>Description of a spatial reference system (<abbr title="Coordinate Reference System">CRS</abbr>).</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">GeodeticDatum</code></td>
- <td><code class="GeoAPI">Ellipsoid</code></td>
- <td>Description of the geodetic datum.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">CoordinateOperation</code></td>
- <td><code class="GeoAPI">MathTransform</code></td>
- <td>Coordinate transformation operations.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">IdentifiedObject</code></td>
- <td><code class="GeoAPI">ReferenceIdentifier</code></td>
- <td>An objet (usually a <abbr>CRS</abbr>) that we can identify by a code.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">Citation</code></td>
- <td><code class="GeoAPI">InternationalString</code></td>
- <td>Bibliographic reference consisting of a simple title.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">GeographicBoundingBox</code></td>
- <td><code class="GeoAPI">Extent</code></td>
- <td>Spatial area in degrees of longitude and latitude.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">ParameterValue</code></td>
- <td><code class="GeoAPI">ParameterDescriptor</code></td>
- <td>Description of a parameter (name, type) associated with its value.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">ParameterValueGroup</code></td>
- <td><code class="GeoAPI">ParameterDescriptorGroup</code></td>
- <td>Description of a set of parameters associated with their values.</td>
- </tr>
+<tr>
+<th>Main Interface</th>
+<th>Auxiliary Interface</th>
+<th>Use</th>
+</tr>
+<tr>
+<td><code class="GeoAPI">CoordinateReferenceSystem</code></td>
+<td><code class="GeoAPI">CoordinateSystem</code></td>
+<td>Description of a spatial reference system (<abbr>CRS</abbr>).</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">GeodeticDatum</code></td>
+<td><code class="GeoAPI">Ellipsoid</code></td>
+<td>Description of the geodetic datum.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">CoordinateOperation</code></td>
+<td><code class="GeoAPI">MathTransform</code></td>
+<td>Coordinate transformation operations.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">IdentifiedObject</code></td>
+<td><code class="GeoAPI">ReferenceIdentifier</code></td>
+<td>An objet (usually a <abbr>CRS</abbr>) that we can identify by a code.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">Citation</code></td>
+<td><code class="GeoAPI">InternationalString</code></td>
+<td>Bibliographic reference consisting of a simple title.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">GeographicBoundingBox</code></td>
+<td><code class="GeoAPI">Extent</code></td>
+<td>Spatial area in degrees of longitude and latitude.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">ParameterValue</code></td>
+<td><code class="GeoAPI">ParameterDescriptor</code></td>
+<td>Description of a parameter (name, type) associated with its value.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">ParameterValueGroup</code></td>
+<td><code class="GeoAPI">ParameterDescriptorGroup</code></td>
+<td>Description of a set of parameters associated with their values.</td>
+</tr>
</table>
-<h2 id="GeoAPI-modules">GeoAPI Modules</h2>
+<h2 id="GeoAPI-modules"><span class="section-number">2.3.</span> GeoAPI Modules</h2>
<p>
- The GeoAPI project consists of a standardized part (<code class="GeoAPI">geoapi</code>)
- and an experimental part (<code class="GeoAPI">geoapi-pending</code>).
- As these two parts are mutually exclusive, users must take care not to mix them in the same project.
- This separation is guaranteed for all projects that depend only on the Maven central repository
- (including the final versions of Apache <abbr title="Spatial Information System">SIS</abbr>),
- as the <code class="GeoAPI">geoapi-pending</code> module is never deployed on this central repository.
- By contrast, certain <abbr>SIS</abbr> development branches may depend on <code class="GeoAPI">geoapi-pending</code>.
+The GeoAPI project consists of a standardized part (<code class="GeoAPI">geoapi</code>)
+and an experimental part (<code class="GeoAPI">geoapi-pending</code>).
+As these two parts are mutually exclusive, users must take care not to mix them in the same project.
+This separation is guaranteed for all projects that depend only on the Maven central repository
+(including the final versions of Apache <abbr title="Spatial Information System">SIS</abbr>),
+as the <code class="GeoAPI">geoapi-pending</code> module is never deployed on this central repository.
+By contrast, certain <abbr>SIS</abbr> development branches may depend on <code class="GeoAPI">geoapi-pending</code>.
</p>
<p>
- GeoAPI modules are:
+GeoAPI modules are:
</p>
<ul>
- <li><p>
- <b><code class="GeoAPI">geoapi</code></b> — includes interfaces covered by the
- <a href="http://www.opengeospatial.org/standards/geoapi">GeoAPI standard of the <abbr title="Open Geospatial Consortium">OGC</abbr></a>.
- The final versions of Apache <abbr title="Spatial Information System">SIS</abbr> depend on this module.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-pending</code></b> — contains a
- <em>copy</em> of all interfaces in the <code class="GeoAPI">geoapi</code> module
- (not a dependence) with additions that have not yet been approved as an <abbr>OGC</abbr> standard.
- Some additions appear in interfaces normally defined by the <code class="GeoAPI">geoapi</code> module, hence the need to copy them.
- Apache <abbr>SIS</abbr>'s development branches <code>jdk6</code>, <code>jdk7</code> and <code>jdk8</code> depend on this module,
- but this dependence becomes a dependence on the <code class="GeoAPI">geoapi</code> standard module when the branches are merged to the trunk.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-conformance</code></b> — includes a JUnit test suite that developers may use to test their implementations.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-examples</code></b> — includes examples of relatively simple implementations.
- These examples are placed in the public domain in order to encourage users to copy and adapt them to their needs if
- Apache <abbr>SIS</abbr> services are unsuitable.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-proj4</code></b> — contains a partial implementation of <code class="GeoAPI">org.opengis.referencing</code>
- packages as adaptors based on the C/C++ Proj.4 library.
- This module may be used as an alternative to the <code class="SIS">sis-referencing</code> module for certain functions.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-netcdf</code></b> — contains a partial implementation of <code class="GeoAPI">org.opengis.referencing</code>
- and <code class="GeoAPI">org.opengis.coverage</code> packages as adaptors based on the
- <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>
- <abbr title="Network Common Data Form">NetCDF</abbr> library.
- The series of tests in this module was developed in such a way as to be reusable for other projects.
- Apache <abbr>SIS</abbr> uses them to test its own <code class="SIS">sis-netcdf</code> module.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-openoffice</code></b> — contains an add-in for the OpenOffice.org office suite.
- <!--
- Apache <abbr>SIS</abbr> offers its own add-in in the <code class="SIS">sis-openoffice</code> module,
- but uses the same function names as the GeoAPI module in order to maintain some compatibility.
- -->
- </p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi</code></b> — includes interfaces covered by the
+<a href="http://www.opengeospatial.org/standards/geoapi">GeoAPI standard of the <abbr title="Open Geospatial Consortium">OGC</abbr></a>.
+The final versions of Apache <abbr>SIS</abbr> depend on this module.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-pending</code></b> — contains a
+<em>copy</em> of all interfaces in the <code class="GeoAPI">geoapi</code> module
+(not a dependence) with additions that have not yet been approved as an <abbr>OGC</abbr> standard.
+Some additions appear in interfaces normally defined by the <code class="GeoAPI">geoapi</code> module, hence the need to copy them.
+Apache <abbr>SIS</abbr>'s development branches <code>jdk6</code>, <code>jdk7</code> and <code>jdk8</code> depend on this module,
+but this dependence becomes a dependence on the <code class="GeoAPI">geoapi</code> standard module when the branches are merged to the trunk.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-conformance</code></b> — includes a JUnit test suite that developers may use to test their implementations.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-examples</code></b> — includes examples of relatively simple implementations.
+These examples are placed in the public domain in order to encourage users to copy and adapt them to their needs if
+Apache <abbr>SIS</abbr> services are unsuitable.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-proj4</code></b> — contains a partial implementation of <code class="GeoAPI">org.opengis.referencing</code>
+packages as adaptors based on the C/C++ Proj.4 library.
+This module may be used as an alternative to the <code class="SIS">sis-referencing</code> module for certain functions.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-netcdf</code></b> — contains a partial implementation of <code class="GeoAPI">org.opengis.referencing</code>
+and <code class="GeoAPI">org.opengis.coverage</code> packages as adaptors based on the <abbr title="University Corporation for Atmospheric Research">UCAR</abbr> <abbr title="Network Common Data Form">NetCDF</abbr> library.
+The series of tests in this module was developed in such a way as to be reusable for other projects.
+Apache <abbr>SIS</abbr> uses them to test its own <code class="SIS">sis-netcdf</code> module.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-openoffice</code></b> — contains an add-in for the OpenOffice.org office suite.
+<!--
+ 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>
+<h3 id="GeoAPI-core"><span class="section-number">2.3.1.</span> The Interfaces' Definition Modules</h3>
<p>
- <code class="GeoAPI">geoapi</code> and <code class="GeoAPI">geoapi-pending</code> modules provide interfaces derived from
- <abbr title="Unified Modeling Language">UML</abbr> schemas of international standards.
- The conceptual model will be explained in detail in the chapters describing Apache <abbr>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>.
+<code class="GeoAPI">geoapi</code> and <code class="GeoAPI">geoapi-pending</code> modules
+provide interfaces derived from <abbr title="Unified Modeling Language">UML</abbr> schemas of international standards.
+The conceptual model will be explained in detail in the chapters describing Apache <abbr title="Spatial Information System">SIS</abbr> implementation.
+However, we can get an overview of its content by consulting the page listing the mapping between
+<a href="http://www.geoapi.org/3.0/javadoc/content.html">GeoAPI methods and the standards where they come from</a>.
</p>
-<h3 id="GeoAPI-conformance">The Conformance Tests Module</h3>
+<h3 id="GeoAPI-conformance"><span class="section-number">2.3.2.</span> The Conformance Tests Module</h3>
<p>
- The <code class="GeoAPI">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:
+The <code class="GeoAPI">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 class="GeoAPI">geoapi-conformance</code> has its own test suite and is applied to other implementations.</li>
- <li>Facilitates comparison with other implementations.</li>
+<li>Reduces the tedious task of writing tests by using existing tests.</li>
+<li>Increases confidence in the validity of tests,
+since <code class="GeoAPI">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>
+<h4 id="GeoAPI-validators"><span class="section-number">2.3.2.1.</span> 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.
+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 class="OGC">CC_CoordinateOperation</code>) may require a sequence of several steps.
- In such a sequence of operations (<code class="OGC">CC_ConcatenatedOperation</code>), for each step (<code class="OGC">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>.
+A coordinate conversion or transformation (<code class="OGC">CC_CoordinateOperation</code>) may require a sequence of several steps.
+In such a sequence of operations (<code class="OGC">CC_ConcatenatedOperation</code>), for each step (<code class="OGC">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 class="GeoAPI">org.opengis.test.Validators</code> class.
- As all of <code class="GeoAPI">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.
+The easiest way to perform these verifications is to call the static methods <code class="GeoAPI">validate(…)</code>
+of the <code class="GeoAPI">org.opengis.test.Validators</code> class.
+As all of <code class="GeoAPI">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 class="GeoAPI">GeographicCRS</code> implies the validation of its component
- <code class="GeoAPI">GeodeticDatum</code>, which itself implies the validation of its component <code class="GeoAPI">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.
+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 class="GeoAPI">GeographicCRS</code> implies the validation of its component
+<code class="GeoAPI">GeodeticDatum</code>, which itself implies the validation of its component <code class="GeoAPI">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:
+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><b>import</b> <code class="GeoAPI">org.opengis.metadata.Metadata</code>;
-<b>import</b> <code class="GeoAPI">org.opengis.test.Validators</code>;
+<pre><b>import</b> org.opengis.metadata.<code class="GeoAPI">Metadata</code>;
+<b>import</b> org.opengis.test.<code class="GeoAPI">Validators</code>;
<b>import</b> org.junit.Test;
-<b>public class</b> MyTest {<code class="comment">
- /*
+<b>public</b> <b>class</b> MyTest {
+ <code class="comment">/*
* 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.
*/</code>
<b>static</b> {
- <code class="GeoAPI">Validators.DEFAULT.metadata.requireMandatoryAttributes</code> = <b>false</b>;
- <code class="GeoAPI">Validators.DEFAULT.citation.requireMandatoryAttributes</code> = <b>false</b>;
+ <code class="GeoAPI">Validators</code>.<code class="GeoAPI">DEFAULT.metadata.requireMandatoryAttributes</code> = <b>false</b>;
+ <code class="GeoAPI">Validators</code>.<code class="GeoAPI">DEFAULT.citation.requireMandatoryAttributes</code> = <b>false</b>;
}
@Test
- <b>public void</b> testMyMetadata() {
- <code class="GeoAPI">Metadata</code> <var>myObject</var> = …; <code class="comment">// Create an object here.</code>
- <code class="GeoAPI">Validators.validate</code>(<var>myObject</var>);
+ <b>public</b> <b>void</b> testMyMetadata() {
+ <code class="GeoAPI">Metadata</code> myObject = …; <code class="comment">// Create an object here.
+</code> <code class="GeoAPI">Validators</code>.<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 title="Java Virtual Machine">JVM</abbr>.
- This approach requires the creation of a new instance of the validator that we wish to modify the configuration.
+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><b>import</b> <code class="GeoAPI">org.opengis.metadata.Metadata</code>;
-<b>import</b> <code class="GeoAPI">org.opengis.test.ValidatorContainer</code>;
+<pre><b>import</b> org.opengis.metadata.<code class="GeoAPI">Metadata</code>;
+<b>import</b> org.opengis.test.<code class="GeoAPI">ValidatorContainer</code>;
<b>import</b> org.junit.Test;
-<b>public class</b> MyTest {
- <b>private final</b> <code class="GeoAPI">ValidatorContainer</code> <var>validators</var>;
+<b>public</b> <b>class</b> MyTest {
+ <b>private</b> <b>final</b> <code class="GeoAPI">ValidatorContainer</code> validators;
<b>public</b> MyTest() {
- <var>validators</var> = <b>new</b> <code class="GeoAPI">ValidatorContainer()</code>;
- <var>validators</var>.<code class="GeoAPI">metadata.requireMandatoryAttributes</code> = <b>false</b>;
- <var>validators</var>.<code class="GeoAPI">citation.requireMandatoryAttributes</code> = <b>false</b>;
+ validators = <b>new</b> <code class="GeoAPI">ValidatorContainer</code>();
+ validators.<code class="GeoAPI">metadata.requireMandatoryAttributes</code> = <b>false</b>;
+ validators.<code class="GeoAPI">citation.requireMandatoryAttributes</code> = <b>false</b>;
}
@Test
- <b>public void</b> testMyMetadata() {
- <code class="GeoAPI">Metadata</code> <var>myObject</var> = …; <code class="comment">// Create an object here.</code>
- <var>validators</var>.<code class="GeoAPI">validate</code>(<var>myObject</var>);
+ <b>public</b> <b>void</b> testMyMetadata() {
+ <code class="GeoAPI">Metadata</code> myObject = …; <code class="comment">// Create an object here.
+</code> validators.<code class="GeoAPI">validate</code>(myObject);
}
}</pre>
-<h4 id="GeoAPI-tests">Executing Pre-defined Tests</h4>
+<h4 id="GeoAPI-tests"><span class="section-number">2.3.2.2.</span> Executing Pre-defined Tests</h4>
<p>
- JUnit tests are defined in the <code class="GeoAPI">org.opengis.test</code> sub-packages.
- All test classes bear a name ending in "<code>Test</code>".
- GeoAPI also provides an <code class="GeoAPI">org.opengis.test.TestSuite</code> class including all test classes defined in the
- <code class="GeoAPI">geoapi-conformance</code> module, but Apache <abbr title="Spatial Information System">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.
+JUnit tests are defined in the <code class="GeoAPI">org.opengis.test</code> sub-packages.
+All test classes bear a name ending in "<code>Test</code>".
+GeoAPI also provides an <code class="GeoAPI">org.opengis.test.TestSuite</code> class including all test classes defined in the
+<code class="GeoAPI">geoapi-conformance</code> module, but Apache <abbr title="Spatial Information System">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><b>import</b> org.junit.*;
<b>import</b> org.junit.runner.RunWith;
<b>import</b> org.junit.runners.JUnit4;
-<b>import</b> <code class="GeoAPI">org.opengis.test.referencing.ParameterizedTransformTest</code>;
-<b>import static</b> org.junit.Assert.*;
+<b>import</b> org.opengis.test.referencing.<code class="GeoAPI">ParameterizedTransformTest</code>;
+<b>import</b> <b>static</b> org.junit.Assert.*;
-@RunWith(JUnit4.class)
-<b>public class</b> MyTest <b>extends</b> <code class="GeoAPI">ParameterizedTransformTest</code> {<code class="comment">
- /**
+@RunWith(JUnit4.<b>class</b>)
+<b>public</b> <b>class</b> MyTest <b>extends</b> <code class="GeoAPI">ParameterizedTransformTest</code> {
+ <code class="comment">/**
* Specify our own coordinate transformation factory for the GeoAPI tests.
* GeoAPI will test the objects created by this factory.
*/</code>
<b>public</b> MyTest() {
<b>super</b>(<b>new</b> MyMathTransformFactory());
}
-<code class="comment">
- /**
+
+ <code class="comment">/**
* 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.
*/</code>
@Test
@Override
- <b>public void</b> testLambertAzimuthalEqualArea() <b>throws</b> <code class="GeoAPI">FactoryException</code>, <code class="GeoAPI">TransformException</code> {
- <code class="GeoAPI"><var>tolerance</var></code> = 0.1; // 10 cm tolerance.
- <b>super</b>.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>;
+ <b>public</b> <b>void</b> testLambertAzimuthalEqualArea() <b>throws</b> <code class="GeoAPI">FactoryException</code>, <code class="GeoAPI">TransformException</code> {
+ <code class="GeoAPI">tolerance</code> = 0.1; <code class="comment">// 10 cm tolerance.
+</code> <b>super</b>.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>;
}
-<code class="comment">
- /**
+
+ <code class="comment">/**
* 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.
*/</code>
@After
- <b>public void</b> ensureAllTransformAreMath2D() {
- assertTrue(<code class="GeoAPI"><var>transform</var></code> <b>instanceof</b> <code class="GeoAPI">MathTransform2D</code>);
+ <b>public</b> <b>void</b> ensureAllTransformAreMath2D() {
+ assertTrue(<code class="GeoAPI">transform</code> <b>instanceof</b> <code class="GeoAPI">MathTransform2D</code>);
}
}</pre>
-<h3 id="GeoAPI-examples">Example Modules</h3>
+<h3 id="GeoAPI-examples"><span class="section-number">2.3.3.</span> Example Modules</h3>
<p>
- The <code class="GeoAPI">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 class="GeoAPI">geoapi-conformance</code>.
+The <code class="GeoAPI">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 class="GeoAPI">geoapi-conformance</code>.
</p>
<p>
- Although its primary goal is to serve as a source of inspiration for implementors,
- <code class="GeoAPI">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 class="GeoAPI">org.opengis</code>.
+Although its primary goal is to serve as a source of inspiration for implementors,
+<code class="GeoAPI">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 class="GeoAPI">org.opengis</code>.
</p>
<p>
- For somewhat more involved needs, developers are invited to examine the
- <code class="GeoAPI">geoapi-proj4</code> and <code class="GeoAPI">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 title="Network Common Data Form">NetCDF</abbr>).
- The advantage of using these interfaces is to provide a unified model to operate two very different
- <abbr title="Application Programming Interface">API</abbr>s,
- while retaining the ability to switch easily to another library if desired.
+For somewhat more involved needs, developers are invited to examine the
+<code class="GeoAPI">geoapi-proj4</code> and <code class="GeoAPI">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 title="Network Common Data Form">NetCDF</abbr>).
+The advantage of using these interfaces is to provide a unified model to operate two very different <abbr title="Application Programming Interface">API</abbr>s,
+while retaining the ability to switch easily to another library if desired.
</p>
-
-
-
-<h1 id="XML-ISO">Representing Objects in <abbr>XML</abbr></h1>
+</section>
+<section>
+<header>
+<h1 id="XML-ISO"><span class="section-number">3.</span> Representing Objects in <abbr>XML</abbr></h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#GeoAPI">Previous chapter</a></div><div class="next-chapter"><a href="#Utilities">Next chapter</a> ➡</div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#XML-ISO-19115">Representing Metadata According to ISO 19115-3</a><ul>
+<li><a href="#gco-id">Identification of Already-Defined Instances</a></li>
+<li><a href="#nilReason">Representing Missing Values</a></li></ul></li></ul></nav>
<p>
- Objects defined by
- <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr title="International Organization for Standardization">ISO</abbr>
- standards must be able to communicate with remote machines via the Internet,
- using different software written in different languages.
- Some of the better known formats include <abbr>WKT</abbr> (<i>Well Known Text</i>) and
- <abbr>WKB</abbr> (<i>Well Known Binary</i>).
- But the most exhaustive and often referred format is <abbr>XML</abbr>,
- to the point where the representation of <abbr>ISO</abbr> objects in this format is itself sometimes
- the entire focus of an international standard.
- Thus are metadata classes described in <abbr>ISO</abbr> 19115-1 standard (an abstract specification),
- while the representation of these classes in <abbr>XML</abbr> is described in <abbr>ISO</abbr> 19115-3 and 19139 standards.
+Objects defined by <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr title="International Organization for Standardization">ISO</abbr> standards must be able to communicate with remote machines via the Internet,
+using different software written in different languages.
+Some of the better known formats include <abbr>WKT</abbr> (<i>Well Known Text</i>) and <abbr>WKB</abbr> (<i>Well Known Binary</i>).
+But the most exhaustive and often referred format is <abbr>XML</abbr>,
+to the point where the representation of <abbr>ISO</abbr> objects in this format is itself sometimes
+the entire focus of an international standard.
+Thus are metadata classes described in <abbr>ISO</abbr> 19115-1 standard (an abstract specification),
+while the representation of these classes in <abbr>XML</abbr> is described in <abbr>ISO</abbr> 19115-3 and 19139 standards.
</p>
<p>
- Different <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr title="International Organization for Standardization">ISO</abbr>
- standards do not always use the same strategy to express objects in <abbr>XML</abbr>.
- <abbr>ISO</abbr> 19115-3 standard in particular uses a more verbose approach than other standards,
- and will be the subject of its <a href="#XML-ISO-19115">own section</a>.
- But most <abbr>XML</abbr> formats define supplementary types and attributes that are not part of
- the original abstract specifications.
- These supplementary attributes are usually specific to <abbr>XML</abbr> and may not appear in the
- <abbr title="Application Programming Interface">API</abbr> of Apache <abbr title="Spatial Information System">SIS</abbr>.
- However, some of these attributes, such as <code class="OGC">id</code>, <code class="OGC">uuid</code> and
- <code>xlink:href</code>, remain accessible in the form of key-value pairs.
+Different <abbr>OGC</abbr>/<abbr>ISO</abbr> standards do not always use the same strategy to express objects in <abbr>XML</abbr>.
+<abbr>ISO</abbr> 19115-3 standard in particular uses a more verbose approach than other standards,
+and will be the subject of its <a href="#XML-ISO-19115">own section</a>.
+But most <abbr>XML</abbr> formats define supplementary types and attributes that are not part of the original abstract specifications.
+These supplementary attributes are usually specific to <abbr>XML</abbr> and may not appear in the <abbr title="Application Programming Interface">API</abbr> of Apache <abbr title="Spatial Information System">SIS</abbr>.
+However, some of these attributes, such as <code class="OGC">id</code>, <code class="OGC">uuid</code> and
+<code>xlink:href</code>, remain accessible in the form of key-value pairs.
</p>
<p>
- <abbr>XML</abbr> documents may use any prefixes,
- but the following prefixes are commonly used.
- They therefore appear by default in documents produced by Apache <abbr>SIS</abbr>.
- These prefixes are defined in the <code class="SIS">org.apache.sis.xml.Namespaces</code> class.
+<abbr>XML</abbr> documents may use any prefixes,
+but the following prefixes are commonly used.
+They therefore appear by default in documents produced by Apache <abbr>SIS</abbr>.
+These prefixes are defined in the <code class="SIS">org.apache.sis.xml.Namespaces</code> class.
</p>
<table>
- <caption>Common <abbr>XML</abbr> namespace prefixes</caption>
- <tr>
- <th>Prefix</th>
- <th>Namespace</th>
- </tr>
- <tr>
- <td><code class="OGC">gco</code></td>
- <td><code>http://www.isotc211.org/2005/gco</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gfc</code></td>
- <td><code>http://www.isotc211.org/2005/gfc</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gmd</code></td>
- <td><code>http://www.isotc211.org/2005/gmd</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gmi</code></td>
- <td><code>http://www.isotc211.org/2005/gmi</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gmx</code></td>
- <td><code>http://www.isotc211.org/2005/gmx</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gml</code></td>
- <td><code>http://www.opengis.net/gml/3.2</code></td>
- </tr>
- <tr>
- <td><code>xlink</code></td>
- <td><code>http://www.w3.org/1999/xlink</code></td>
- </tr>
+<caption>Common <abbr>XML</abbr> namespace prefixes</caption>
+<tr>
+<th>Prefix</th>
+<th>Namespace</th>
+</tr>
+<tr>
+<td><code class="OGC">gco</code></td>
+<td><code>http://www.isotc211.org/2005/gco</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gfc</code></td>
+<td><code>http://www.isotc211.org/2005/gfc</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmd</code></td>
+<td><code>http://www.isotc211.org/2005/gmd</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmi</code></td>
+<td><code>http://www.isotc211.org/2005/gmi</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmx</code></td>
+<td><code>http://www.isotc211.org/2005/gmx</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gml</code></td>
+<td><code>http://www.opengis.net/gml/3.2</code></td>
+</tr>
+<tr>
+<td><code>xlink</code></td>
+<td><code>http://www.w3.org/1999/xlink</code></td>
+</tr>
</table>
<aside>
- <p><b>Tools for Reading and Writing <abbr>XML</abbr> Documents</b></p>
- <p>
- Apache <abbr title="Spatial Information System">SIS</abbr> uses different libraries to read and write
- different types of objects.
- The library used depends on the complexity of the object and on performance constraints.
- For example, <abbr title="Java Architecture for XML Binding">JAXB</abbr> annotations have the advantage of being close to code,
- which makes it easier to maintain mapping between Java and <abbr>XML</abbr>.
- On the other hand, <abbr title="Simple API for XML">SAX</abbr> is more efficient.
- In general, Apache <abbr>SIS</abbr> uses:
- </p>
- <ul>
- <li>
- <abbr title="Java Architecture for XML Binding">JAXB</abbr> for objects that do not occur very often in <abbr>XML</abbr> documents,
- but with complex structures and deep hierarchies.
- The metadata set in <abbr>ISO</abbr> 19115-3 standard is a typical example
- </li>
- <li>
- <abbr title="Simple API for XML">SAX</abbr> for objects that are relatively simple,
- but which may exist in very large numbers.
- The set of points in a geometry is a typical example.
- </li>
- <li>
- <abbr title="Document Object Model">DOM</abbr> as an alternative to
- <abbr title="Java Architecture for XML Binding">JAXB</abbr> when the <abbr>XML</abbr> elements do not correspond
- exactly to Java attributes.
- <i>Features</i> are an example, as their structure is dynamic.
- </li>
- </ul>
+<h2>Tools for Reading and Writing <abbr>XML</abbr> Documents</h2>
+<p>
+Apache <abbr title="Spatial Information System">SIS</abbr> uses different libraries to read and write different types of objects.
+The library used depends on the complexity of the object and on performance constraints.
+For example, <abbr title="Java Architecture for XML Binding">JAXB</abbr> annotations have the advantage of being close to code,
+which makes it easier to maintain mapping between Java and <abbr>XML</abbr>.
+On the other hand, <abbr title="Simple API for XML">SAX</abbr> is more efficient.
+In general, Apache <abbr>SIS</abbr> uses:
+</p>
+<ul>
+<li>
+<abbr>JAXB</abbr> for objects that do not occur very often in <abbr>XML</abbr> documents, but with complex structures and deep hierarchies.
+The metadata set in <abbr title="International Organization for Standardization">ISO</abbr> 19115-3 standard is a typical example
+</li>
+<li>
+<abbr>SAX</abbr> for objects that are relatively simple, but which may exist in very large numbers.
+The set of points in a geometry is a typical example.
+</li>
+<li>
+<abbr title="Document Object Model">DOM</abbr> as an alternative to <abbr>JAXB</abbr>
+when the <abbr>XML</abbr> elements do not correspond exactly to Java attributes.
+<i>Features</i> are an example, as their structure is dynamic.
+</li>
+</ul>
</aside>
-<h2 id="XML-ISO-19115">Representing Metadata According to <abbr>ISO</abbr> 19115-3</h2>
+<h2 id="XML-ISO-19115"><span class="section-number">3.1.</span> Representing Metadata According to <abbr title="International Organization for Standardization">ISO</abbr> 19115-3</h2>
<p>
- For each metadata class, there is an <abbr>XML</abbr> type with the same name than in the abstract specification
- (for example, <code class="OGC">gmd:MD_Metadata</code> and <code class="OGC">gmd:CI_Citation</code>).
- All of these types may be used as the root of an <abbr>XML</abbr> document.
- It is therefore possible to write a document representing a complete <code class="OGC">MD_Metadata</code> object,
- or to write a document representing only a <code class="OGC">CI_Citation</code> object.
+For each metadata class, there is an <abbr>XML</abbr> type with the same name than in the abstract specification
+(for example, <code class="OGC">gmd:MD_Metadata</code> and <code class="OGC">gmd:CI_Citation</code>).
+All of these types may be used as the root of an <abbr>XML</abbr> document.
+It is therefore possible to write a document representing a complete <code class="OGC">MD_Metadata</code> object,
+or to write a document representing only a <code class="OGC">CI_Citation</code> object.
</p>
<p>
- <abbr>ISO</abbr> 19115-3 standard arranges the content of these objects in an unusual way:
- for each property whose value type is itself another class of <abbr>ISO</abbr> 19115,
- the value is wrapped in an element that represents its type, rather than being written directly.
- For example, in an object of the <code class="OGC">CI_Citation</code> type,
- the value of the <code class="OGC">citedResponsibleParty</code> property is incorporated into a
- <code class="OGC">CI_Responsibility</code> element.
- This practice doubles the depth of the hierarchy, and introduces duplication at all levels for each value,
- as in the following example:
+<abbr>ISO</abbr> 19115-3 standard arranges the content of these objects in an unusual way:
+for each property whose value type is itself another class of <abbr>ISO</abbr> 19115,
+the value is wrapped in an element that represents its type, rather than being written directly.
+For example, in an object of the <code class="OGC">CI_Citation</code> type,
+the value of the <code class="OGC">citedResponsibleParty</code> property is incorporated
+into a <code class="OGC">CI_Responsibility</code> element.
+This practice doubles the depth of the hierarchy, and introduces duplication at all levels for each value,
+as in the following example:
</p>
-<pre><b><MD_Metadata></b>
+
+<pre class="xml"><b><MD_Metadata></b>
<identificationInfo>
<b><MD_DataIdentification></b>
<citation>
@@ -1488,715 +1448,721 @@ System.out.println("The GeoAPI interface for <abbr>ISO</abbr> type " + <var>isoN
<b></MD_Metadata></b></pre>
<p>
- The preceding example, like all documents that conform to <abbr>ISO</abbr> 19115-3,
- consists of a systematic alternation of two types of <abbr>XML</abbr> elements:
+The preceding example, like all documents that conform to <abbr>ISO</abbr> 19115-3,
+consists of a systematic alternation of two types of <abbr>XML</abbr> elements:
</p>
<ol>
- <li><p>
- It begins with the name of the property, which always begins with a lower-case letter (ignoring prefixes).
- In Java <abbr title="Application Programming Interface">API</abbr>s, each property corresponds to a method in its enclosing class.
- In the example above, <code class="OGC">gmd:identificationInfo</code> (a property of <code class="OGC">MD_Metadata</code> class)
- corresponds to the <code class="GeoAPI">Metadata.getIdentificationInfo()</code> method.
- </p></li>
- <li><p>
- The value type is included under each property, unless it has been replaced with a reference
- (the following <a href="#gco-id">sub-section</a> will elaborate on this subject).
- The value type is an <abbr>XML</abbr> element whose name always begins with an upper-case letter,
- ignoring prefixes.
- In the example above we had <code class="OGC">MD_DataIdentification</code>,
- which corresponds to the <code class="GeoAPI">DataIdentification</code> Java interface.
- It is this <abbr>XML</abbr> element that contains the child properties.
- </p></li>
+<li><p>
+It begins with the name of the property, which always begins with a lower-case letter (ignoring prefixes).
+In Java <abbr title="Application Programming Interface">API</abbr>s, each property corresponds to a method in its enclosing class.
+In the example above, <code class="OGC">gmd:identificationInfo</code> (a property of <code class="OGC">MD_Metadata</code> class)
+corresponds to the <code class="GeoAPI">Metadata.getIdentificationInfo()</code> method.
+</p></li>
+<li><p>
+The value type is included under each property, unless it has been replaced with a reference
+(the following <a href="#gco-id">sub-section</a> will elaborate on this subject).
+The value type is an <abbr>XML</abbr> element whose name always begins with an upper-case letter,
+ignoring prefixes.
+In the example above we had <code class="OGC">MD_DataIdentification</code>,
+which corresponds to the <code class="GeoAPI">DataIdentification</code> Java interface.
+It is this <abbr>XML</abbr> element that contains the child properties.
+</p></li>
</ol>
<p>
- In order to reduce the complexity of the libraries, GeoAPI and Apache <abbr title="Spatial Information System">SIS</abbr>
- only expose publicly a single unified view of these two types of elements.
- The public <abbr title="Application Programming Interface">API</abbr> basically corresponds to the second group.
- However, when writing an <abbr>XML</abbr> document, elements of the first group must be temporarily recreated.
- The corresponding classes are defined in internal <abbr title="Spatial Information System">SIS</abbr> packages.
- These classes may be ignored, unless the developer wishes to implement his or her own classes whose instances
- must be written in <abbr title="Java Architecture for XML Binding">JAXB</abbr>.
+In order to reduce the complexity of the libraries, GeoAPI and Apache <abbr title="Spatial Information System">SIS</abbr>
+only expose publicly a single unified view of these two types of elements.
+The public <abbr>API</abbr> basically corresponds to the second group.
+However, when writing an <abbr>XML</abbr> document, elements of the first group must be temporarily recreated.
+The corresponding classes are defined in internal <abbr>SIS</abbr> packages.
+These classes may be ignored, unless the developer wishes to implement his or her own classes whose instances must be written in <abbr title="Java Architecture for XML Binding">JAXB</abbr>.
</p>
<aside>
- <p><b>Implementation Strategy in Apache <abbr>SIS</abbr></b></p>
- <p>
- <code class="SIS">org.apache.sis.internal.jaxb.*</code> packages (non-public) define
- <abbr title="Java Architecture for XML Binding">JAXB</abbr> adaptors for all types of <abbr>ISO</abbr> objects.
- These adaptors are required anyway to allow <abbr>JAXB</abbr> to get
- <abbr title="Spatial Information System">SIS</abbr> classes while implementing GeoAPI interfaces.
- Conveniently, <abbr>SIS</abbr> made both <abbr>JAXB</abbr> adaptors and objects wrapping the “real” object
- to be read or written.
- This double usage avoids having to double the number of classes (already quite high) present in the internal packages.
- </p>
- <p><b>Naming Conventions in <abbr>XSD</abbr> Schemas</b></p>
- <p>
- For each element of the first group listed above, the <abbr title="XML Schema Definition">XSD</abbr> schemas of the
- <abbr title="Open Geospatial Consortium">OGC</abbr> define a type whose name ends with “<code class="OGC">_PropertyType</code>”.
- For the second group, each element has a type whose name ends with “<code class="OGC">_Type</code>”.
- The “<code class="OGC">_PropertyType</code>” elements may have a group of attributes
- (such as <code class="OGC">gmd:idref</code>, <code class="OGC">gco:uuidref</code> and <code>xlink:href</code>)
- which the <abbr>XSD</abbr> schemas collectively name <code class="OGC">gco:ObjectIdentification</code>.
- These attributes do not have dedicated Java methods, but are accessible indirectly via the
- <code class="SIS">IdentifiedObject</code> interface described in the following subsection.
- </p>
+<h3>Implementation Strategy in Apache <abbr title="Spatial Information System">SIS</abbr></h3>
+<p>
+<code class="SIS">org.apache.sis.internal.jaxb.*</code> packages (non-public) define <abbr title="Java Architecture for XML Binding">JAXB</abbr> adaptors for all types of <abbr title="International Organization for Standardization">ISO</abbr> objects.
+These adaptors are required anyway to allow <abbr>JAXB</abbr> to get <abbr>SIS</abbr> classes while implementing GeoAPI interfaces.
+Conveniently, <abbr>SIS</abbr> made both <abbr>JAXB</abbr> adaptors and objects wrapping the “real” object to be read or written.
+This double usage avoids having to double the number of classes (already quite high) present in the internal packages.
+</p>
+<h4>Naming Conventions in <abbr title="XML Schema Definition">XSD</abbr> Schemas</h4>
+<p>
+For each element of the first group listed above, the <abbr>XSD</abbr> schemas of the <abbr title="Open Geospatial Consortium">OGC</abbr>
+define a type whose name ends with “<code class="OGC">_PropertyType</code>”.
+For the second group, each element has a type whose name ends with “<code class="OGC">_Type</code>”.
+The “<code class="OGC">_PropertyType</code>” elements may have a group of attributes
+(such as <code class="OGC">gmd:idref</code>, <code class="OGC">gco:uuidref</code> and <code>xlink:href</code>)
+which the <abbr>XSD</abbr> schemas collectively name <code class="OGC">gco:ObjectIdentification</code>.
+These attributes do not have dedicated Java methods, but are accessible indirectly via the
+<code class="SIS">IdentifiedObject</code> interface described in the following subsection.
+</p>
</aside>
-<h3 id="gco-id">Identification of Already-Defined Instances</h3>
+<h3 id="gco-id"><span class="section-number">3.1.1.</span> Identification of Already-Defined Instances</h3>
<p>
- The parent element may contain an <code class="OGC">id</code>, <code class="OGC">uuid</code> or
- <code>xlink:href</code> attribute.
- If one of these attributes is present, the parent attribute may be completely omitted;
- it will be replaced at the time of reading by the element referenced by the attribute.
- In the following example, the part on the left defines an element associated with the identifier “<code>my_id</code>,”
- while the part on the right references this element:
+The parent element may contain an <code class="OGC">id</code>, <code class="OGC">uuid</code> or
+<code>xlink:href</code> attribute.
+If one of these attributes is present, the parent attribute may be completely omitted;
+it will be replaced at the time of reading by the element referenced by the attribute.
+In the following example, the part on the left defines an element associated with the identifier “<code>my_id</code>,”
+while the part on the right references this element:
</p>
<table class="hidden">
- <tr>
- <th>Defining an Identifier</th>
- <th>Using a Defined Identifier</th>
- </tr>
- <tr>
- <td>
- <pre style="margin-top: 6pt"><MD_MetaData>
+<tr>
+<th>Defining an Identifier</th>
+<th>Using a Defined Identifier</th>
+</tr>
+<tr>
+<td>
+<pre class="xml" style="margin-top: 6pt"><MD_MetaData>
<identificationInfo>
- <MD_DataIdentification id="<b>my_id</b>">
+ <MD_DataIdentification id=<i>"<b>my_id</b>"</i>>
<code class="comment"><!-- insert child properties here --></code>
</MD_DataIdentification>
</identificationInfo>
</MD_MetaData></pre>
- </td>
- <td>
- <pre style="margin-top: 6pt"><MD_MetaData>
- <identificationInfo idref="<b>my_id</b>"/>
+</td>
+<td>
+<pre class="xml" style="margin-top: 6pt"><MD_MetaData>
+ <identificationInfo idref=<i>"<b>my_id</b>"</i>/>
</MD_MetaData></pre>
- </td>
- </tr>
+</td>
+</tr>
</table>
<p>
- The decision of which attribute to use depends on the scope of the referenced item:
+The decision of which attribute to use depends on the scope of the referenced item:
</p>
<ul>
- <li>
- <code class="OGC">id</code> is only valid in the same <abbr>XML</abbr> document that defines the object it references.
- </li>
- <li>
- <code class="OGC">uuid</code> may be valid outside the <abbr>XML</abbr> document,
- but someone must maintain a database providing the objects for each given UUID.
- </li>
- <li>
- <code>xlink:href</code> may reference another <abbr>XML</abbr> document accessible on the Internet.
- </li>
+<li>
+<code class="OGC">id</code> is only valid in the same <abbr>XML</abbr> document that defines the object it references.
+</li>
+<li>
+<code class="OGC">uuid</code> may be valid outside the <abbr>XML</abbr> document,
+but someone must maintain a database providing the objects for each given UUID.
+</li>
+<li>
+<code>xlink:href</code> may reference another <abbr>XML</abbr> document accessible on the Internet.
+</li>
</ul>
<p>
- In the <abbr title="Spatial Information System">SIS</abbr> library,
- all objects that can be identified in an <abbr>XML</abbr> document implements the
- <code class="SIS">org.apache.sis.xml.IdentifiedObject</code> interface.
- Each instance of this interface provides a view of its identifiers in the form of a <code>Map<Citation,String></code>,
- in which the <code class="GeoAPI">Citation</code> key indicates the type of identifier and the value is the identifier itself.
- Some constants representing different types of identifiers are listed in <code class="SIS">IdentifierSpace</code>,
- including <code class="SIS">ID</code>, <code class="SIS">UUID</code> and <code class="SIS">HREF</code>.
- Each of these keys may be associated with a different type of value (usually <code>String</code>,
- <code>UUID</code> or <code>URI</code>) depending on the key.
- For example, the following code defines a value for the <code class="OGC">uuid</code> attribute:
+In the <abbr title="Spatial Information System">SIS</abbr> library, all objects that can be identified in an <abbr>XML</abbr> document
+implements the <code class="SIS">org.apache.sis.xml.IdentifiedObject</code> interface.
+Each instance of this interface provides a view of its identifiers in the form of a <code>Map<Citation,String></code>,
+in which the <code class="GeoAPI">Citation</code> key indicates the type of identifier and the value is the identifier itself.
+Some constants representing different types of identifiers are listed in <code class="SIS">IdentifierSpace</code>,
+including <code class="SIS">ID</code>, <code class="SIS">UUID</code> and <code class="SIS">HREF</code>.
+Each of these keys may be associated with a different type of value (usually <code>String</code>,
+<code>UUID</code> or <code>URI</code>) depending on the key.
+For example, the following code defines a value for the <code class="OGC">uuid</code> attribute:
</p>
-<pre><b>import</b> <code class="SIS">org.apache.sis.metadata.iso.DefaultMetadata</code>;
-<b>import</b> <code class="SIS">org.apache.sis.xml.IdentifierSpace</code>;
+<pre><b>import</b> org.apache.sis.metadata.iso.<code class="SIS">DefaultMetadata</code>;
+<b>import</b> org.apache.sis.xml.<code class="SIS">IdentifierSpace</code>;
<b>import</b> java.util.UUID;
-<b>public class</b> MyClass {
- <b>public void</b> myMethod() {
- UUID <var>identifier</var> = UUID.randomUUID();
- <code class="SIS">DefaultMetadata</code> <var>metadata</var> = <b>new</b> <code class="SIS">DefaultMetadata</code>();
- <var>metadata</var>.<code class="SIS">getIdentifierMap().putSpecialized</code>(<code class="SIS">IdentifierSpace.UUID</code>, <var>identifier</var>);
+<b>public</b> <b>class</b> MyClass {
+ <b>public</b> <b>void</b> myMethod() {
+ UUID identifier = UUID.randomUUID();
+ <code class="SIS"><code class="SIS">DefaultMetadata</code></code> metadata = <b>new</b> <code class="SIS"><code class="SIS">DefaultMetadata</code></code>();
+ metadata.<code class="SIS">getIdentifierMap().putSpecialized</code>(<code class="SIS">IdentifierSpace</code>.UUID, identifier);
}
}</pre>
<p>
- Although this mechanism has been defined in order to better support the representation of <abbr>XML</abbr> attributes
- of the <code class="OGC">gco:ObjectIdentification</code> group,
- it also conveniently allows other types of identifiers to be manipulated.
- For example, the <code class="GeoAPI">ISBN</code> and <code class="GeoAPI">ISSN</code> attributes of
- <code class="GeoAPI">Citation</code> may be manipulated in this way.
- The methods of the <code class="SIS">IdentifiedObject</code> interface therefore provides a specific location
- where all types of identifiers (not only <abbr>XML</abbr>) associated with an object may be manipulated.
+Although this mechanism has been defined in order to better support the representation of <abbr>XML</abbr> attributes
+of the <code class="OGC">gco:ObjectIdentification</code> group,
+it also conveniently allows other types of identifiers to be manipulated.
+For example, the <code class="GeoAPI">ISBN</code> and <code class="GeoAPI">ISSN</code> attributes of
+<code class="GeoAPI">Citation</code> may be manipulated in this way.
+The methods of the <code class="SIS">IdentifiedObject</code> interface therefore provides a specific location
+where all types of identifiers (not only <abbr>XML</abbr>) associated with an object may be manipulated.
</p>
-<h3 id="nilReason">Representing Missing Values</h3>
+<h3 id="nilReason"><span class="section-number">3.1.2.</span> Representing Missing Values</h3>
<p>
- When a property is not defined, the corresponding GeoAPI method usually returns <code>null</code>.
- However, things become complicated when the missing property is a value considered mandatory by <abbr>ISO</abbr> 19115 standard.
- <abbr>ISO</abbr> 19115-3 allows for the omission of mandatory properties so long as the reason for the missing value is indicated.
- The reason may be that the property is not applicable (<code class="OGC">inapplicable</code>),
- that the value probably exists but is not known (<code class="OGC">unknown</code>),
- that the value cannot exist (<code class="OGC">missing</code>),
- or that the value cannot be revealed (<code class="OGC">withheld</code>), <i>etc.</i>
- The transmission of this information requires the use of a non-nul object, even when the value is missing.
- <abbr title="Spatial Information System">SIS</abbr> will then return an object that,
- besides implementing the desired GeoAPI interface, also implements the
- <code class="SIS">org.apache.sis.xml.NilObject</code> interface.
- This interface flags the instances where all methods return an empty collection, an empty table, <code>null</code>,
- <code>NaN</code>, <code>0</code> or <code>false</code>, in this preference order, as permitted by the return types of the methods.
- Each instance that implements <code class="SIS">NilObject</code> provides a <code class="SIS">getNilReason()</code> method
- indicating why the object is nil.
+When a property is not defined, the corresponding GeoAPI method usually returns <code>null</code>.
+However, things become complicated when the missing property is a value considered mandatory by <abbr title="International Organization for Standardization">ISO</abbr> 19115 standard.
+<abbr>ISO</abbr> 19115-3 allows for the omission of mandatory properties so long as the reason for the missing value is indicated.
+The reason may be that the property is not applicable (<code class="OGC">inapplicable</code>),
+that the value probably exists but is not known (<code class="OGC">unknown</code>),
+that the value cannot exist (<code class="OGC">missing</code>),
+or that the value cannot be revealed (<code class="OGC">withheld</code>), <i>etc.</i>
+The transmission of this information requires the use of a non-nul object, even when the value is missing.
+<abbr title="Spatial Information System">SIS</abbr> will then return an object that, besides implementing the desired GeoAPI interface,
+also implements the <code class="SIS">org.apache.sis.xml.NilObject</code> interface.
+This interface flags the instances where all methods return an empty collection, an empty table, <code>null</code>,
+<code>NaN</code>, <code>0</code> or <code>false</code>, in this preference order, as permitted by the return types of the methods.
+Each instance that implements <code class="SIS">NilObject</code> provides a <code class="SIS">getNilReason()</code> method
+indicating why the object is nil.
</p>
<p>
- In the following example, the left side shows a <code class="OGC">CI_Citation</code> element containing a
- <code class="OGC">CI_Series</code> element, while on the right side the series is unknown.
- If the <code class="OGC">CI_Series</code> element had been completely omitted,
- then the <code class="GeoAPI">Citation.getSeries()</code> method would return <code>null</code> in Java.
- But when a <code class="OGC">nilReason</code> is present, the <abbr title="Spatial Information System">SIS</abbr>
- implementation of <code class="SIS">getSeries()</code> returns instead an object that implements both the
- <code class="GeoAPI">Series</code> and <code class="SIS">NilReason</code> interfaces, and in which the
- <code class="SIS">getNilReason()</code> method returns the constant <code class="SIS">UNKNOWN</code>.
+In the following example, the left side shows a <code class="OGC">CI_Citation</code> element containing a
+<code class="OGC">CI_Series</code> element, while on the right side the series is unknown.
+If the <code class="OGC">CI_Series</code> element had been completely omitted,
+then the <code class="GeoAPI">Citation.getSeries()</code> method would return <code>null</code> in Java.
+But when a <code class="OGC">nilReason</code> is present, the <abbr>SIS</abbr> implementation of
+<code class="SIS">getSeries()</code> returns instead an object that implements both the
+<code class="GeoAPI">Series</code> and <code class="SIS">NilReason</code> interfaces, and in which the
+<code class="SIS">getNilReason()</code> method returns the constant <code class="SIS">UNKNOWN</code>.
</p>
<table class="hidden">
- <tr>
- <th>Information Included</th>
- <th>Missing Information</th>
- </tr>
- <tr>
- <td>
- <pre style="margin-top: 6pt"><CI_Citation>
+<tr>
+<th>Information Included</th>
+<th>Missing Information</th>
+</tr>
+<tr>
+<td>
+<pre class="xml" style="margin-top: 6pt"><CI_Citation>
<series>
<CI_Series>
<code class="comment"><!-- insert child properties here --></code>
</CI_Series>
</series>
</CI_Citation></pre>
- </td>
- <td>
- <pre style="margin-top: 6pt"><CI_Citation>
- <series nilReason="unknown"/>
+</td>
+<td>
+<pre class="xml" style="margin-top: 6pt"><CI_Citation>
+ <series nilReason=<i>"unknown"</i>/>
</CI_Citation></pre>
- </td>
- </tr>
+</td>
+</tr>
</table>
-
-
-
-<h1 id="Utilities">Utility Classes and Methods</h1>
-<p>
- This chapter describes aspects of Apache <abbr title="Spatial Information System">SIS</abbr> that apply to the entire library.
- Most of these utilities are not specific to spatial information systems.
-</p>
-
-<h2 id="ComparisonMode">Comparison Modes of Objects</h2>
-<p>
- There are various opinions on how to implement Java standard's <code>Object.equals(Object)</code> method.
- According to some, it should be possible to compare different implementations of the same interface or base class.
- But to follow this policy, each interface or base class's javadoc must define the algorithms that all implementations
- shall use for their <code>equals(Object)</code> and <code>hashCode()</code> methods.
- This approach is common in <code>java.util.Collection</code> and its child interfaces.
- Transferring this approach to certain GeoAPI interfaces, however, would be a difficult task,
- and would probably not be followed in many implementations.
- Moreover, it comes at the expense of being able to take into account supplementary attributes in the child interfaces,
- unless this possibility has been specified in the parent interface.
- This constraint arises from the following points of the <code>equals(Object)</code> and <code>hashCode()</code> method contracts:
+</section>
+<section>
+<header>
+<h1 id="Utilities"><span class="section-number">4.</span> Utility Classes and Methods</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#XML-ISO">Previous chapter</a></div><div class="next-chapter"><a href="#Geometry">Next chapter</a> ➡</div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#ComparisonMode">Comparison Modes of Objects</a></li>
+<li><a href="#Internationalization">Internationalization</a><ul>
+<li><a href="#LocalizedString">Distinct Character Sequences for Each Locale</a></li>
+<li><a href="#InternationalString">Single instance for all supported locales</a></li>
+<li><a href="#Locale.ROOT">Locale.ROOT Convention</a></li>
+<li><a href="#UnicodePoint">Treatment of Characters</a><ul>
+<li><a href="#Whitespaces">The Interpretation of Blank Spaces</a></li></ul></li></ul></li></ul></nav>
+<p>
+This chapter describes aspects of Apache <abbr title="Spatial Information System">SIS</abbr> that apply to the entire library.
+Most of these utilities are not specific to spatial information systems.
+</p>
+
+<h2 id="ComparisonMode"><span class="section-number">4.1.</span> Comparison Modes of Objects</h2>
+<p>
+There are various opinions on how to implement Java standard's <code>Object.equals(Object)</code> method.
+According to some, it should be possible to compare different implementations of the same interface or base class.
+But to follow this policy, each interface or base class's javadoc must define the algorithms that all implementations
+shall use for their <code>equals(Object)</code> and <code>hashCode()</code> methods.
+This approach is common in <code>java.util.Collection</code> and its child interfaces.
+Transferring this approach to certain GeoAPI interfaces, however, would be a difficult task,
+and would probably not be followed in many implementations.
+Moreover, it comes at the expense of being able to take into account supplementary attributes in the child interfaces,
+unless this possibility has been specified in the parent interface.
+This constraint arises from the following points of the <code>equals(Object)</code> and <code>hashCode()</code> method contracts:
</p>
<ul>
- <li><code>A.equals(B)</code> implies <code>B.equals(A)</code> (symmetry);</li>
- <li><code>A.equals(B)</code> and <code>B.equals(C)</code> implies <code>A.equals(C)</code> (transitivity);</li>
- <li><code>A.equals(B)</code> implies <code>A.hashCode() == B.hashCode()</code>.</li>
+<li><code>A.equals(B)</code> implies <code>B.equals(A)</code> (symmetry);</li>
+<li><code>A.equals(B)</code> and <code>B.equals(C)</code> implies <code>A.equals(C)</code> (transitivity);</li>
+<li><code>A.equals(B)</code> implies <code>A.hashCode() == B.hashCode()</code>.</li>
</ul>
<p>
- For example, these three constraints are violated if <var>A</var> (and eventually <var>C</var>) can contain attributes
- which <var>B</var> ignores.
- To bypass this problem, an alternative approach is to require that the objects compared by the
- <code>Object.equals(Object)</code> method be of the same class; in other words, <code>A.getClass() == B.getClass()</code>.
- This approach is sometimes regarded as contrary to the principles of object oriented programming.
- In practice, for relatively complex applications, the important accorded to these principles depends on the context
- in which the objects are compared:
- if the objects are added to a <code>HashSet</code> or used as keys in a <code>HashMap</code>,
- we would need a stricter adherence to the <code>equals(Object)</code> and <code>hashCode()</code> contract.
- But if the developer is comparing the objects his- or herself, for example to check that the relevant information has been changed,
- then the constraints of symmetry, transitivity or coherence with the hash values may be of little interest.
- More permissive comparisons may be desirable, sometimes going so far as to tolerate minor discrepancies in numerical values.
-</p>
-<p>
- In order to allow developers a certain amount of flexibility, many classes in the <abbr title="Spatial Information System">SIS</abbr>
- library implement the <code class="SIS">org.apache.sis.util.LenientComparable</code> interface,
- which defines a <code class="SIS">equals(Object, ComparisonMode)</code> method.
- The principle modes of comparison are:
+For example, these three constraints are violated if <var>A</var> (and eventually <var>C</var>) can contain attributes
+which <var>B</var> ignores.
+To bypass this problem, an alternative approach is to require that the objects compared by the
+<code>Object.equals(Object)</code> method be of the same class; in other words, <code>A.getClass() == B.getClass()</code>.
+This approach is sometimes regarded as contrary to the principles of object oriented programming.
+In practice, for relatively complex applications, the important accorded to these principles depends on the context
+in which the objects are compared:
+if the objects are added to a <code>HashSet</code> or used as keys in a <code>HashMap</code>,
+we would need a stricter adherence to the <code>equals(Object)</code> and <code>hashCode()</code> contract.
+But if the developer is comparing the objects his- or herself, for example to check that the relevant information has been changed,
+then the constraints of symmetry, transitivity or coherence with the hash values may be of little interest.
+More permissive comparisons may be desirable, sometimes going so far as to tolerate minor discrepancies in numerical values.
+</p>
+<p>
+In order to allow developers a certain amount of flexibility, many classes in the <abbr title="Spatial Information System">SIS</abbr>
+library implement the <code class="SIS">org.apache.sis.util.LenientComparable</code> interface,
+which defines a <code class="SIS">equals(Object, ComparisonMode)</code> method.
+The principle modes of comparison are:
</p>
<ul>
- <li><p>
- <b><code class="SIS">STRICT</code></b> — The objects compared must share the same class and have exactly equal attributes,
- including any possible public attributes specific to the implementation.
- </p></li>
- <li><p>
- <b><code class="SIS">BY_CONTRACT</code></b> — The objects compared must implement the same GeoAPI (or other standard)
- interface, but need not be of the same implementation class.
- Only the attributes defined in the interface are compared;
- all other attributes specific to the implementation — even if they are public — are ignored.
- </p></li>
- <li><p>
- <b><code class="SIS">IGNORE_METADATA</code></b> — Like <code class="SIS">BY_CONTRACT</code>,
- but only compares attributes that influence the operations (numeric calculations or otherwise) performed by the object.
- For example, in a geodesic datum, the longitude (in relation to Greenwich) of the original meridian
- would be taken into account, while the name of the meridian would be ignored.
- </p></li>
- <li><p>
- <b><code class="SIS">APPROXIMATIVE</code></b> — Like <code class="SIS">IGNORE_METADATA</code>,
- but tolerates minor discrepancies in numerical values.
- </p></li>
+<li><p>
+<b><code class="SIS">STRICT</code></b> — The objects compared must share the same class and have exactly equal attributes,
+including any possible public attributes specific to the implementation.
+</p></li>
+<li><p>
+<b><code class="SIS">BY_CONTRACT</code></b> — The objects compared must implement the same GeoAPI (or other standard)
+interface, but need not be of the same implementation class.
+Only the attributes defined in the interface are compared;
+all other attributes specific to the implementation — even if they are public — are ignored.
+</p></li>
+<li><p>
+<b><code class="SIS">IGNORE_METADATA</code></b> — Like <code class="SIS">BY_CONTRACT</code>,
+but only compares attributes that influence the operations (numeric calculations or otherwise) performed by the object.
+For example, in a geodesic datum, the longitude (in relation to Greenwich) of the original meridian
+would be taken into account, while the name of the meridian would be ignored.
+</p></li>
+<li><p>
+<b><code class="SIS">APPROXIMATIVE</code></b> — Like <code class="SIS">IGNORE_METADATA</code>,
+but tolerates minor discrepancies in numerical values.
+</p></li>
</ul>
<p>
- The default mode, used in all <code>equals(Object)</code> methods in <abbr title="Spatial Information System">SIS</abbr>,
- is <code class="SIS">STRICT</code>. This mode is chosen for a safe operation — particularly with <code>HashMap</code> —
- without the need to rigorously define <code>equals(Object)</code> and <code>hashCode()</code> operations in every interface.
- With this mode, the order of objects (<code>A.equals(B)</code> or <code>B.equals(A)</code>) is unimportant.
- It is, however, the only mode that offers this guarantee.
- In the expression <code>A.equals(B)</code>, the <code class="SIS">BY_CONTRACT</code> mode
- (and so by extension all other modes that depend on it) only compares the properties known to <code>A</code>,
- regardless of whether <code>B</code> knows more.
+The default mode, used in all <code>equals(Object)</code> methods in <abbr>SIS</abbr>,
+is <code class="SIS">STRICT</code>. This mode is chosen for a safe operation — particularly with <code>HashMap</code> —
+without the need to rigorously define <code>equals(Object)</code> and <code>hashCode()</code> operations in every interface.
+With this mode, the order of objects (<code>A.equals(B)</code> or <code>B.equals(A)</code>) is unimportant.
+It is, however, the only mode that offers this guarantee.
+In the expression <code>A.equals(B)</code>, the <code class="SIS">BY_CONTRACT</code> mode
+(and so by extension all other modes that depend on it) only compares the properties known to <code>A</code>,
+regardless of whether <code>B</code> knows more.
</p>
-<h2 id="Internationalization">Internationalization</h2>
+<h2 id="Internationalization"><span class="section-number">4.2.</span> Internationalization</h2>
<p>
- In an architecture where a program executed on a server provides its data to multiple clients,
- the server's locale conventions are not necessarily the same as those of the clients.
- Conventions may differ in language, but also in the way they write numeric values
- (even between two countries that speak the same language) as well in time zone.
- To produce messages that conform to the client's conventions, <abbr title="Spatial Information System">SIS</abbr> uses
- two approaches, distinguished by their level of granularity: at the level of the messages themselves,
- or at the level of the objects that create the messages.
- The approach used also determines whether it is possible to share the same instance of an object for all languages.
+In an architecture where a program executed on a server provides its data to multiple clients,
+the server's locale conventions are not necessarily the same as those of the clients.
+Conventions may differ in language, but also in the way they write numeric values
+(even between two countries that speak the same language) as well in time zone.
+To produce messages that conform to the client's conventions, <abbr title="Spatial Information System">SIS</abbr> uses
+two approaches, distinguished by their level of granularity: at the level of the messages themselves,
+or at the level of the objects that create the messages.
+The approach used also determines whether it is possible to share the same instance of an object for all languages.
</p>
-<h3 id="LocalizedString">Distinct Character Sequences for Each Locale</h3>
+<h3 id="LocalizedString"><span class="section-number">4.2.1.</span> Distinct Character Sequences for Each Locale</h3>
<p>
- Some classes are only designed to function according to one locale convention at a time.
- This is of course true for the standard implementations of <code>java.text.Format</code>,
- as they are entirely dedicated to the work of internationalization.
- But it is also the case for other less obvious classes like <code>javax.imageio.ImageReader</code>/<code>ImageWriter</code>
- and for <code>Exception</code> subclasses.
- When one of these classes is implemented by <abbr title="Spatial Information System">SIS</abbr>,
- we identify it by implementing the <code class="SIS">org.apache.sis.util.Localized</code> interface.
- The <code class="SIS">getLocale()</code> method of this interface can determine the locale conventions
- by which the instance produces its message.
+Some classes are only designed to function according to one locale convention at a time.
+This is of course true for the standard implementations of <code>java.text.Format</code>,
+as they are entirely dedicated to the work of internationalization.
+But it is also the case for other less obvious classes like <code>javax.imageio.ImageReader</code>/<code>ImageWriter</code>
+and for <code>Exception</code> subclasses.
+When one of these classes is implemented by <abbr title="Spatial Information System">SIS</abbr>,
+we identify it by implementing the <code class="SIS">org.apache.sis.util.Localized</code> interface.
+The <code class="SIS">getLocale()</code> method of this interface can determine the locale conventions
+by which the instance produces its message.
</p>
<p>
- Some sub-classes of <code>Exception</code> defined by <abbr title="Spatial Information System">SIS</abbr>
- also implement the <code class="SIS">Localized</code> interface.
- For these exceptions, the error message may be produced according to two locale conventions,
- for either the administrator or the client respectively:
- <code>getMessage()</code> returns the exception message according to the system default conventions,
- while <code>getLocalizedMessage()</code> returns the exception message according to the locale conventions specified
- by <code class="SIS">getLocale()</code>.
- This <code>Locale</code> will be determined by the <code class="SIS">Localized</code> object that threw the exception.
+Some sub-classes of <code>Exception</code> defined by <abbr>SIS</abbr> also implement the <code class="SIS">Localized</code> interface.
+For these exceptions, the error message may be produced according to two locale conventions,
+for either the administrator or the client respectively:
+<code>getMessage()</code> returns the exception message according to the system default conventions,
+while <code>getLocalizedMessage()</code> returns the exception message according to the locale conventions specified
+by <code class="SIS">getLocale()</code>.
+This <code>Locale</code> will be determined by the <code class="SIS">Localized</code> object that threw the exception.
</p>
<div class="example"><p><b>Example:</b>
- Given an environment in which the default language is English and an <code class="SIS">AngleFormat</code> object is created to
- read angles according to French conventions.
- If a <code>ParseException</code> is thrown when using this formatter, <code>getMessage()</code> returns the error message in English,
- while <code>getLocalizedMessage()</code> returns the error message in French.
+Given an environment in which the default language is English and an <code class="SIS">AngleFormat</code> object is created to
+read angles according to French conventions.
+If a <code>ParseException</code> is thrown when using this formatter, <code>getMessage()</code> returns the error message in English,
+while <code>getLocalizedMessage()</code> returns the error message in French.
</p></div>
<p>
- The exceptions defined by <abbr title="Spatial Information System">SIS</abbr> do not implement all of the <code class="SIS">Localized</code> interface.
- Only those most likely to be shown to the user are localized in this way.
- <code>ParseException</code> are good candidates because they often occur due to an incorrect entry by the client.
- By contrast, <code>NullPointerException</code> are generally caused by a programming error;
- they may be localized in the system default language, but that is usually all.
+The exceptions defined by <abbr>SIS</abbr> do not implement all of the <code class="SIS">Localized</code> interface.
+Only those most likely to be shown to the user are localized in this way.
+<code>ParseException</code> are good candidates because they often occur due to an incorrect entry by the client.
+By contrast, <code>NullPointerException</code> are generally caused by a programming error;
+they may be localized in the system default language, but that is usually all.
</p>
<p>
- The utility class <code class="SIS">org.apache.sis.util.Exceptions</code> provides convenience methods to get messages
- according to the conventions of a given locale, when this information is available.
+The utility class <code class="SIS">org.apache.sis.util.Exceptions</code> provides convenience methods to get messages
+according to the conventions of a given locale, when this information is available.
</p>
-<h3 id="InternationalString">Single instance for all supported locales</h3>
+<h3 id="InternationalString"><span class="section-number">4.2.2.</span> Single instance for all supported locales</h3>
<p>
- The <abbr title="Application Programming Interface">API</abbr> conventions defined by <abbr title="Spatial Information System">SIS</abbr>
- or inherited by GeoAPI favour the use of the <code class="GeoAPI">InternationalString</code> type when the value of a
- <code>String</code> type would likely be localized.
- This approach allows us to defer the internationalization process to the time when a character sequence is requested,
- rather than the time when the object that contains them is created.
- This is particularly useful for immutable classes used for creating unique instances independently of locale conventions.
+The <abbr title="Application Programming Interface">API</abbr> conventions defined by <abbr title="Spatial Information System">SIS</abbr> or inherited by GeoAPI favour the use of the
+<code class="GeoAPI">InternationalString</code> type when the value of a <code>String</code> type would likely be localized.
+This approach allows us to defer the internationalization process to the time when a character sequence is requested,
+rather than the time when the object that contains them is created.
+This is particularly useful for immutable classes used for creating unique instances independently of locale conventions.
</p>
<div class="example"><p><b>Example:</b>
- <abbr 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>
- while <code>toString(Locale.FRENCH)</code> returns <cite>Projection de Mercator</cite>.
+<abbr>SIS</abbr> includes only one instance of the <code class="GeoAPI">OperationMethod</code>
+type representing the Mercator projection, regardless of the client's language.
+But its <code class="GeoAPI">getName()</code> method (indirectly) provides an instance of
+<code class="GeoAPI">InternationalString</code>, so that <code>toString(Locale.ENGLISH)</code> returns <cite>Mercator projection</cite>
+while <code>toString(Locale.FRENCH)</code> returns <cite>Projection de Mercator</cite>.
</p></div>
<p>
- When defining spatial objects independently of locale conventions, we reduce the risk of computational overload.
- For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the
- same instance of <code class="GeoAPI">CoordinateOperation</code>,
- even if the projection has a different name depending on the country.
- Moreover, certain types of <code class="GeoAPI">CoordinateOperation</code> may require coordinate transformation matrices,
- so sharing a single instance becomes even more preferable in order to reduce memory consumption.
+When defining spatial objects independently of locale conventions, we reduce the risk of computational overload.
+For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the
+same instance of <code class="GeoAPI">CoordinateOperation</code>,
+even if the projection has a different name depending on the country.
+Moreover, certain types of <code class="GeoAPI">CoordinateOperation</code> may require coordinate transformation matrices,
+so sharing a single instance becomes even more preferable in order to reduce memory consumption.
</p>
-<h3 id="Locale.ROOT"><code>Locale.ROOT</code> Convention</h3>
+<h3 id="Locale.ROOT"><span class="section-number">4.2.3.</span> <code>Locale.ROOT</code> Convention</h3>
<p>
- All <abbr title="Spatial Information System">SIS</abbr> methods receiving or returning the value of a
- <code>Locale</code> type accept the <code>Locale.ROOT</code> value.
- This value is interpreted as specifying not to localize the text.
- The notion of a <cite>non-localized text</cite> is a little false, as it is always necessary to chose a formatting convention.
- This convention however, though very close to English, is usually slightly different.
- For example:
+All <abbr title="Spatial Information System">SIS</abbr> methods receiving or returning the value of a <code>Locale</code> type accept the <code>Locale.ROOT</code> value.
+This value is interpreted as specifying not to localize the text.
+The notion of a <cite>non-localized text</cite> is a little false, as it is always necessary to chose a formatting convention.
+This convention however, though very close to English, is usually slightly different.
+For example:
</p>
<ul>
- <li>
- Identifiers are written as they appear in <abbr title="Unified Modeling Language">UML</abbr> diagrams,
- such as <cite>blurredImage</cite> instead of <cite>Blurred image</cite>.
- </li>
- <li>
- Dates are written according to the <abbr>ISO</abbr> 8601 format,
- which does not correspond to English conventions.
- </li>
- <li>
- Numbers are written using their <code>toString()</code> methods, rather than using a <code>java.text.NumberFormat</code>.
- As a result, there are differences in the number of significant digits,
- use of exponential notation and the absence of thousands separators.
- </li>
+<li>
+Identifiers are written as they appear in <abbr title="Unified Modeling Language">UML</abbr> diagrams,
+such as <cite>blurredImage</cite> instead of <cite>Blurred image</cite>.
+</li>
+<li>
+Dates are written according to the <abbr title="International Organization for Standardization">ISO</abbr> 8601 format,
+which does not correspond to English conventions.
+</li>
+<li>
+Numbers are written using their <code>toString()</code> methods, rather than using a <code>java.text.NumberFormat</code>.
+As a result, there are differences in the number of significant digits,
+use of exponential notation and the absence of thousands separators.
+</li>
</ul>
-<h3 id="UnicodePoint">Treatment of Characters</h3>
+<h3 id="UnicodePoint"><span class="section-number">4.2.4.</span> Treatment of Characters</h3>
<p>
- In Java, sequences of characters use UTF-16 encoding.
- There is a direct correspondence between the values of the <code>char</code> type and the great majority of characters,
- which facilitates the use of sequences so long as these characters are sufficient.
- However, certain Unicode characters cannot be represented by a single <code>char</code>.
- These <i>supplementary characters</i> include certain ideograms,
- but also road and geographical symbols in the 1F680 to 1F700 range.
- Support for these supplementary characters requires slightly more complex interactions than the classic case,
- where we may assume a direct correspondence.
- Thus, instead of the loop on the left below, international applications must generally use the loop on the right:
+In Java, sequences of characters use UTF-16 encoding.
+There is a direct correspondence between the values of the <code>char</code> type and the great majority of characters,
+which facilitates the use of sequences so long as these characters are sufficient.
+However, certain Unicode characters cannot be represented by a single <code>char</code>.
+These <i>supplementary characters</i> include certain ideograms,
+but also road and geographical symbols in the 1F680 to 1F700 range.
+Support for these supplementary characters requires slightly more complex interactions than the classic case,
+where we may assume a direct correspondence.
+Thus, instead of the loop on the left below, international applications must generally use the loop on the right:
</p>
<table class="hidden">
- <tr>
- <th>Loop to Avoid</th>
- <th>Recommended loop</th>
- </tr>
- <tr>
- <td>
- <pre style="margin-top: 6pt"><b>for</b> (<b>int</b> <var>i</var>=0; <var>i</var><<var>string</var>.length(); <var>i</var>++) {
- <b>char</b> <var>c</var> = <var>string</var>.charAt(<var>i</var>);
- <b>if</b> (Character.isWhitespace(<var>c</var>)) {
- <code class="comment">// A blank space was found.</code>
- }
+<tr>
+<th>Loop to Avoid</th>
+<th>Recommended loop</th>
+</tr>
+<tr>
+<td>
+<pre style="margin-top: 6pt"><b>for</b> (<b>int</b> i=0; i<string.length(); i++) {
+ <b>char</b> c = string.charAt(i);
+ <b>if</b> (Character.isWhitespace(c)) {
+ <code class="comment">// A blank space was found.
+</code> }
}</pre>
- </td>
- <td>
- <pre style="margin-top: 6pt"><b>for</b> (<b>int</b> <var>i</var>=0; <var>i</var><<var>string</var>.length();) {
- <b>int</b> <var>c</var> = <var>string</var>.codePointAt(<var>i</var>);
- <b>if</b> (Character.isWhitespace(<var>c</var>)) {
- <code class="comment">// A blank space was found.</code>
- }
- <var>i</var> += Character.charCount(<var>c</var>);
+</td>
+<td>
+<pre style="margin-top: 6pt"><b>for</b> (<b>int</b> i=0; i<string.length();) {
+ <b>int</b> c = string.codePointAt(i);
+ <b>if</b> (Character.isWhitespace(c)) {
+ <code class="comment">// A blank space was found.
+</code> }
+ i += Character.charCount(c);
}</pre>
- </td>
- </tr>
+</td>
+</tr>
</table>
<p>
- <abbr title="Spatial Information System">SIS</abbr> supports supplementary characters by using the loop on the right where necessary,
- but the loop on the left is occasionally used when it is known that the characters searched for are not supplementary characters,
- even if some may be present in the sequence in which we are searching.
+<abbr title="Spatial Information System">SIS</abbr> supports supplementary characters by using the loop on the right where necessary,
+but the loop on the left is occasionally used when it is known that the characters searched for are not supplementary characters,
+even if some may be present in the sequence in which we are searching.
</p>
-<h4 id="Whitespaces">The Interpretation of Blank Spaces</h4>
+<h4 id="Whitespaces"><span class="section-number">4.2.4.1.</span> The Interpretation of Blank Spaces</h4>
<p>
- Standard Java provides two methods for determining whether a character is a blank space:
- <code>Character.isWhitespace(…)</code> and <code>Character.isSpaceChar(…)</code>.
- These two methods differ in their interpretations of non-breaking spaces, tabs and line breaks.
- The first method conforms to the interpretation currently used in languages such as Java, C/C++ and <abbr>XML</abbr>,
- which considers tabs and line breaks to be blank spaces, while non-breaking spaces are read as not blank.
- The second method — which conforms strictly to the Unicode definition — makes the opposite interpretation.
+Standard Java provides two methods for determining whether a character is a blank space:
+<code>Character.isWhitespace(…)</code> and <code>Character.isSpaceChar(…)</code>.
+These two methods differ in their interpretations of non-breaking spaces, tabs and line breaks.
+The first method conforms to the interpretation currently used in languages such as Java, C/C++ and <abbr>XML</abbr>,
+which considers tabs and line breaks to be blank spaces, while non-breaking spaces are read as not blank.
+The second method — which conforms strictly to the Unicode definition — makes the opposite interpretation.
</p>
<p>
- <abbr title="Spatial Information System">SIS</abbr> uses each of these methods in different contexts.
- <code>isWhitespace(…)</code> is used to <em>separate</em> the elements of a list (numbers, dates, words, etc.),
- while <code>isSpaceChar(…)</code> is used to ignore blank spaces <em>inside</em> a single element.
+<abbr title="Spatial Information System">SIS</abbr> uses each of these methods in different contexts.
+<code>isWhitespace(…)</code> is used to <em>separate</em> the elements of a list (numbers, dates, words, etc.),
+while <code>isSpaceChar(…)</code> is used to ignore blank spaces <em>inside</em> a single element.
</p>
<div class="example"><p><b>Example:</b>
- Take a list of numbers represented according to French conventions.
- Each number may contain <em>non-breaking spaces</em> as thousands separators,
- while the different numbers in the list may be separated by ordinary spaces, tabs or line breaks.
- When analyzing a number, we want to consider the non-breaking spaces as being part of the number,
- whereas a tab or a line break most likely indicates a separation between this number and the next.
- We would thus use <code>isSpaceChar(…)</code>.
- Conversely, when separating the numbers in the list, we want to consider tabs and line breaks as separators,
- but not non-breaking spaces.
- We would thus use <code>isWhitespace(…)</code>.
- The role of ordinary spaces, to which either case might apply, should be decided beforehand.
+Take a list of numbers represented according to French conventions.
+Each number may contain <em>non-breaking spaces</em> as thousands separators,
+while the different numbers in the list may be separated by ordinary spaces, tabs or line breaks.
+When analyzing a number, we want to consider the non-breaking spaces as being part of the number,
+whereas a tab or a line break most likely indicates a separation between this number and the next.
+We would thus use <code>isSpaceChar(…)</code>.
+Conversely, when separating the numbers in the list, we want to consider tabs and line breaks as separators,
+but not non-breaking spaces.
+We would thus use <code>isWhitespace(…)</code>.
+The role of ordinary spaces, to which either case might apply, should be decided beforehand.
</p></div>
<p>
- In practice, this distinction is reflected in the use of <code>isSpaceChar(…)</code> in the implementations of <code>java.text.Format</code>,
- or the use of <code>isWhitespace(…)</code> in nearly all the rest of the <abbr title="Spatial Information System">SIS</abbr> library.
+In practice, this distinction is reflected in the use of <code>isSpaceChar(…)</code> in the implementations of <code>java.text.Format</code>,
+or the use of <code>isWhitespace(…)</code> in nearly all the rest of the <abbr>SIS</abbr> library.
</p>
-
-
-
-<h1 id="Geometry">Geometries</h1>
+</section>
+<section>
+<header>
+<h1 id="Geometry"><span class="section-number">5.</span> Geometries</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Utilities">Previous chapter</a></div><div class="next-chapter"><a href="#Coverage">Next chapter</a> ➡</div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#Geometry-root">Base Classes</a><ul>
+<li><a href="#DirectPosition">Direct Points and Positions</a></li>
+<li><a href="#Envelope">Envelopes</a><ul>
+<li><a href="#AntiMeridian">Envelopes that Cross the Antimeridian</a></li></ul></li></ul></li></ul></nav>
<p>
- This chapter introduces a few aspects of <abbr>ISO</abbr> 19107 standard (<i>Spatial schema</i>) and the
- Apache <abbr title="Spatial Information System">SIS</abbr> classes that implement them.
+This chapter introduces a few aspects of <abbr title="International Organization for Standardization">ISO</abbr> 19107 standard (<i>Spatial schema</i>)
+and the Apache <abbr title="Spatial Information System">SIS</abbr> classes that implement them.
</p>
-<h2 id="Geometry-root">Base Classes</h2>
+<h2 id="Geometry-root"><span class="section-number">5.1.</span> Base Classes</h2>
<p>
- Each geometric object is considered an infinite set of points.
- As a set, their most fundamental operations are of the same nature as the standard operations of Java collections.
- We may therefore see a geometry as a kind of <code>java.util.Set</code> in which the elements are points,
- except that the number of elements contained in the set is infinite (with the exception of geometries representing a simple point).
- To better represent this concept, the <abbr title="International Organization for Standardization">ISO</abbr> standard
- and GeoAPI define a <code class="OGC">TransfiniteSet</code> interface which we could see as a <code>Set</code> of infinite size.
- Although a parent relationship exists conceptually between these interfaces,
- GeoAPI does not define <code class="GeoAPI">TransfiniteSet</code> as a sub-interface of <code>java.util.Set</code>,
- as the definition of certain methods such as <code>size()</code> and <code>iterator()</code> would be problematic.
- However, we find very similar methods such as <code class="GeoAPI">contains(…)</code> and <code class="GeoAPI">intersects(…)</code>.
+Each geometric object is considered an infinite set of points.
+As a set, their most fundamental operations are of the same nature as the standard operations of Java collections.
+We may therefore see a geometry as a kind of <code>java.util.Set</code> in which the elements are points,
+except that the number of elements contained in the set is infinite (with the exception of geometries representing a simple point).
+To better represent this concept, the <abbr title="International Organization for Standardization">ISO</abbr> standard and GeoAPI define a <code class="OGC">TransfiniteSet</code> interface
+which we could see as a <code>Set</code> of infinite size.
+Although a parent relationship exists conceptually between these interfaces,
+GeoAPI does not define <code class="GeoAPI">TransfiniteSet</code> as a sub-interface of <code>java.util.Set</code>,
+as the definition of certain methods such as <code>size()</code> and <code>iterator()</code> would be problematic.
+However, we find very similar methods such as <code class="GeoAPI">contains(…)</code> and <code class="GeoAPI">intersects(…)</code>.
</p>
<p>
- All geometries are specializations of <code class="GeoAPI">TransfiniteSet</code>.
- The parent class of those geometries is called <code class="OGC">GM_Object</code> in <abbr>ISO</abbr> 19107 standard.
- GeoAPI interfaces use the <code class="GeoAPI">Geometry</code> name instead, as the omission of the <code class="OGC">GM_</code>
- prefix (as prescribed in GeoAPI convention) would leave a name too similar to Java's <code>Object</code> class.
+All geometries are specializations of <code class="GeoAPI">TransfiniteSet</code>.
+The parent class of those geometries is called <code class="OGC">GM_Object</code> in <abbr>ISO</abbr> 19107 standard.
+GeoAPI interfaces use the <code class="GeoAPI">Geometry</code> name instead, as the omission of the <code class="OGC">GM_</code>
+prefix (as prescribed in GeoAPI convention) would leave a name too similar to Java's <code>Object</code> class.
</p>
-<h3 id="DirectPosition">Direct Points and Positions</h3>
+<h3 id="DirectPosition"><span class="section-number">5.1.1.</span> Direct Points and Positions</h3>
<p>
- <abbr>ISO</abbr> 19107 defines two types of structures to represent a point:
- <code class="OGC">GM_Point</code> and <code class="OGC">DirectPosition</code>.
- The first type is a true geometry and may therefore be relatively cumbersome, depending on the implementation.
- The second type is not formally considered to be a geometry;
- it extends neither <code class="OGC">GM_Object</code> nor <code class="OGC">TransfiniteSet</code>.
- It barely defines any operations besides the storing of a sequence of numbers representing a coordinate.
- It may therefore be a more lightweight object.
+<abbr title="International Organization for Standardization">ISO</abbr> 19107 defines two types of structures to represent a point:
+<code class="OGC">GM_Point</code> and <code class="OGC">DirectPosition</code>.
+The first type is a true geometry and may therefore be relatively cumbersome, depending on the implementation.
+The second type is not formally considered to be a geometry;
+it extends neither <code class="OGC">GM_Object</code> nor <code class="OGC">TransfiniteSet</code>.
+It barely defines any operations besides the storing of a sequence of numbers representing a coordinate.
+It may therefore be a more lightweight object.
</p>
<p>
- In order to allow the <abbr title="Application Programming Interface">API</abbr> to work equally with these two types of positions,
- <abbr>ISO</abbr> 19107 defines <code class="OGC">Position</code> as a <cite>union</cite> of
- <code class="OGC">DirectPosition</code> and <code class="OGC">GM_Point</code>.
- It is a union in the sense of C/C++. For the Java language, GeoAPI obtains the same effect by defining
- <code class="GeoAPI">Position</code> as the parent interface of <code class="GeoAPI">DirectPosition</code> and <code class="GeoAPI">Point</code>.
- In practice, the great majority of Apache <abbr title="Spatial Information System">SIS</abbr>'s
- <abbr title="Application Programming Interface">API</abbr> works on <code class="GeoAPI">DirectPosition</code>s,
- or occasionally on <code class="GeoAPI">Position</code>s when it seems useful to also allow geometric points.
+In order to allow the <abbr title="Application Programming Interface">API</abbr> to work equally with these two types of positions,
+<abbr>ISO</abbr> 19107 defines <code class="OGC">Position</code> as a <cite>union</cite> of
+<code class="OGC">DirectPosition</code> and <code class="OGC">GM_Point</code>.
+It is a union in the sense of C/C++. For the Java language, GeoAPI obtains the same effect by defining
+<code class="GeoAPI">Position</code> as the parent interface of <code class="GeoAPI">DirectPosition</code> and <code class="GeoAPI">Point</code>.
+In practice, the great majority of Apache <abbr title="Spatial Information System">SIS</abbr>'s <abbr>API</abbr> works on <code class="GeoAPI">DirectPosition</code>s,
+or occasionally on <code class="GeoAPI">Position</code>s when it seems useful to also allow geometric points.
</p>
-<h3 id="Envelope">Envelopes</h3>
+<h3 id="Envelope"><span class="section-number">5.1.2.</span> Envelopes</h3>
<p>
- Envelopes store minimal and maximal coordinate values of a geometry.
- Envelopes are <em>not</em> geometries themselves; they are not infinite sets of points (<code class="OGC">TransfiniteSet</code>).
- There is no guarantee that all the positions contained within the limits of an envelope are geographically valid.
- Envelopes must be seen as information about extreme values that might take the coordinates of a geometry as if
- each dimension were independent of the others, nothing more.
- Nevertheless, we speak of envelopes as rectangles, cubes or hyper-cubes (depending on the number of dimensions)
- in order to facilitate discussion, while bearing in mind their non-geometric nature.
+Envelopes store minimal and maximal coordinate values of a geometry.
+Envelopes are <em>not</em> geometries themselves; they are not infinite sets of points (<code class="OGC">TransfiniteSet</code>).
+There is no guarantee that all the positions contained within the limits of an envelope are geographically valid.
+Envelopes must be seen as information about extreme values that might take the coordinates of a geometry as if
+each dimension were independent of the others, nothing more.
+Nevertheless, we speak of envelopes as rectangles, cubes or hyper-cubes (depending on the number of dimensions)
+in order to facilitate discussion, while bearing in mind their non-geometric nature.
</p>
<div class="example"><p><b>Example:</b>
- We could test whether a position is within the limits of an envelope.
- A positive result does not guarantee that the position is within the geometry delimited by the envelope,
- but a negative result guarantees that it is outside the envelope.
- We can perform intersection tests in the same way.
- On the other hand, it makes little sense to apply a rotation to an envelope,
- as the result may be very different from that which we would obtain be performing a rotation on the original geometry,
- and then recalculating its envelope.
+We could test whether a position is within the limits of an envelope.
+A positive result does not guarantee that the position is within the geometry delimited by the envelope,
+but a negative result guarantees that it is outside the envelope.
+We can perform intersection tests in the same way.
+On the other hand, it makes little sense to apply a rotation to an envelope,
+as the result may be very different from that which we would obtain be performing a rotation on the original geometry,
+and then recalculating its envelope.
</p></div>
<p>
- An envelope might be represented by two positions corresponding to two opposite corners of a rectangle,
- cube or hyper-cube.
- For the first corner, we often take the one whose ordinates all have the maximal value (<code class="OGC">upperCorner</code>).
- When displayed using a conventional system of coordinates (with <var>y</var> axis values running upwards),
- these two positions appear respectively in the lower left corner and the upper right corner of a rectangle.
- Care must be taken with different coordinate systems, however, which may vary the positions of these corners on the screen.
- The expressions <i>lower corner</i> and <i>upper corner</i> should thus be understood in the mathematical rather than the visual sense.
+An envelope might be represented by two positions corresponding to two opposite corners of a rectangle,
+cube or hyper-cube.
+For the first corner, we often take the one whose ordinates all have the maximal value (<code class="OGC">upperCorner</code>).
+When displayed using a conventional system of coordinates (with <var>y</var> axis values running upwards),
+these two positions appear respectively in the lower left corner and the upper right corner of a rectangle.
+Care must be taken with different coordinate systems, however, which may vary the positions of these corners on the screen.
+The expressions <i>lower corner</i> and <i>upper corner</i> should thus be understood in the mathematical rather than the visual sense.
</p>
-<h4 id="AntiMeridian">Envelopes that Cross the Antimeridian</h4>
+<h4 id="AntiMeridian"><span class="section-number">5.1.2.1.</span> Envelopes that Cross the Antimeridian</h4>
<p>
- Minimums and maximums are the values most often assigned to <code class="OGC">lowerCorner</code>
- and <code class="OGC">upperCorner</code>.
- But the situation becomes complicated when an envelope crosses the antimeridian (-180° or 180° longitude).
- For example, an envelope 10° in size may begin at 175° longitude and end at -175°.
- In this case, the longitude value assigned to <code class="OGC">lowerCorner</code> is greater than that assigned to <code class="OGC">upperCorner</code>.
- Apache <abbr title="Spatial Information System">SIS</abbr> therefore uses a slightly different definition of these two corners:
+Minimums and maximums are the values most often assigned to <code class="OGC">lowerCorner</code>
+and <code class="OGC">upperCorner</code>.
+But the situation becomes complicated when an envelope crosses the antimeridian (-180° or 180° longitude).
+For example, an envelope 10° in size may begin at 175° longitude and end at -175°.
+In this case, the longitude value assigned to <code class="OGC">lowerCorner</code> is greater than that assigned to <code class="OGC">upperCorner</code>.
+Apache <abbr title="Spatial Information System">SIS</abbr> therefore uses a slightly different definition of these two corners:
</p>
<ul>
- <li><b><code class="SIS">lowerCorner</code>:</b>
- the starting point, if we move along the inside of the envelope in the direction of ascending values.
- </li>
- <li><b><code class="SIS">upperCorner</code>:</b>
- the end-point, if we move along the inside of the envelope in the direction of ascending values.
- </li>
+<li><b><code class="SIS">lowerCorner</code>:</b>
+the starting point, if we move along the inside of the envelope in the direction of ascending values.
+</li>
+<li><b><code class="SIS">upperCorner</code>:</b>
+the end-point, if we move along the inside of the envelope in the direction of ascending values.
+</li>
</ul>
<p>
- If the envelope does not cross the antimeridian, these two definitions are equivalent to the selection of minimal and
- maximal values respectively. This is the case in the green rectangle in the figure below.
- When the envelope crosses the antimeridian, the <code class="SIS">lowerCorner</code> and the
- <code class="SIS">upperCorner</code> appear again at the bottom and top of the rectangle
- (assuming a standard system of coordinates), so their names remain appropriate from a visual standpoint.
- However, the left and right positions are switched.
- This case is illustrated by the red rectangle in the figure below.
+If the envelope does not cross the antimeridian, these two definitions are equivalent to the selection of minimal and
+maximal values respectively. This is the case in the green rectangle in the figure below.
+When the envelope crosses the antimeridian, the <code class="SIS">lowerCorner</code> and the
+<code class="SIS">upperCorner</code> appear again at the bottom and top of the rectangle
+(assuming a standard system of coordinates), so their names remain appropriate from a visual standpoint.
+However, the left and right positions are switched.
+This case is illustrated by the red rectangle in the figure below.
</p>
<center>
- <img src="../../apidocs/org/apache/sis/geometry/doc-files/AntiMeridian.png"
- alt="Exemples d’enveloppes avec et sans croisement de l’antiméridien."/>
+<img alt="Envelope example with and without anti-meridian spanning." src="../../apidocs/org/apache/sis/geometry/doc-files/AntiMeridian.png"/>
</center>
<p>
- The notions of inclusion and intersection, however, interpreted slightly differently in these two cases.
- In the usual case where we do not cross the antimeridian, the green rectangle covers a region of inclusion.
- The regions excluded from this rectangle continue on to infinity in all directions.
- In other words, the region of inclusion is not repeated every 360°.
- But in the case of the red rectangle, the information provided by the envelope actually covers a region of exclusion
- between the two edges of the rectangle. The region of inclusion extends to infinity to the left and right.
- We could stipulate that all longitudes below -180° or above 180° are considered excluded,
- but this would be an arbitrary decision that would not be an exact counterpart to the usual case (green rectangle).
- A developer may wish to use these values, for example, in a mosaic where the map of the world is repeated several times
- horizontally and each repetition is considered distinct.
- If developers wish to perform operations as though the regions of inclusion or exclusion were repeated every 360°,
- they themselves will have to bring the longitudinal values between -180° and 180° in advance.
- All the <code class="SIS">add(…)</code>, <code class="SIS">contains(…)</code>,
- <code class="SIS">intersect(…)</code>, etc. functions of all the envelopes defined in the
- <code class="SIS">org.apache.sis.geometry</code> package perform their calculations according to this convention.
+The notions of inclusion and intersection, however, interpreted slightly differently in these two cases.
+In the usual case where we do not cross the antimeridian, the green rectangle covers a region of inclusion.
+The regions excluded from this rectangle continue on to infinity in all directions.
+In other words, the region of inclusion is not repeated every 360°.
+But in the case of the red rectangle, the information provided by the envelope actually covers a region of exclusion
+between the two edges of the rectangle. The region of inclusion extends to infinity to the left and right.
+We could stipulate that all longitudes below -180° or above 180° are considered excluded,
+but this would be an arbitrary decision that would not be an exact counterpart to the usual case (green rectangle).
+A developer may wish to use these values, for example, in a mosaic where the map of the world is repeated several times
+horizontally and each repetition is considered distinct.
+If developers wish to perform operations as though the regions of inclusion or exclusion were repeated every 360°,
+they themselves will have to bring the longitudinal values between -180° and 180° in advance.
+All the <code class="SIS">add(…)</code>, <code class="SIS">contains(…)</code>,
+<code class="SIS">intersect(…)</code>, etc. functions of all the envelopes defined in the
+<code class="SIS">org.apache.sis.geometry</code> package perform their calculations according to this convention.
</p>
<aside>
- <p><b>Generalizing to Other Types of Axes</b></p>
- <p>
- This section specifically relates to longitude, as it is the most usual example of a cyclic axis.
- However, in Apache <abbr title="Spatial Information System">SIS</abbr> envelopes,
- there is no explicit mention of longitude, or of its 360° cycle.
- The characteristics of the range of values of each axis (its extremum, units, type of cycle, etc.)
- are attributes of <code class="GeoAPI">CoordinateSystemAxis</code> objects,
- indirectly associated with envelopes via the coordinate reference system.
- Apache <abbr>SIS</abbr> inspects these attributes to determine the way in which it must perform these operations.
- Thus, any axis associated with the code <code class="GeoAPI">RangeMeaning.WRAPAROUND</code> benefit from
- the same treatment as does longitude.
- For example, this could be a time axis for climatological data (one “year” represents the average temperature in all the
- months of January, followed by the average of all the months of February, etc.)
- This generalization also applies to longitude axes defined by a range of 0° to 360° rather than -180° to 180°.
- </p>
+<h5>Generalizing to Other Types of Axes</h5>
+<p>
+This section specifically relates to longitude, as it is the most usual example of a cyclic axis.
+However, in Apache <abbr title="Spatial Information System">SIS</abbr> envelopes, there is no explicit mention of longitude, or of its 360° cycle.
+The characteristics of the range of values of each axis (its extremum, units, type of cycle, etc.)
+are attributes of <code class="GeoAPI">CoordinateSystemAxis</code> objects,
+indirectly associated with envelopes via the coordinate reference system.
+Apache <abbr>SIS</abbr> inspects these attributes to determine the way in which it must perform these operations.
+Thus, any axis associated with the code <code class="GeoAPI">RangeMeaning.WRAPAROUND</code> benefit from
+the same treatment as does longitude.
+For example, this could be a time axis for climatological data (one “year” represents the average temperature in all the
+months of January, followed by the average of all the months of February, etc.)
+This generalization also applies to longitude axes defined by a range of 0° to 360° rather than -180° to 180°.
+</p>
</aside>
<p>
- In order for functions such as <code class="SIS">add(…)</code> to work correctly,
- all objects involved must use the same coordinate reference system, including the same range of values.
- Thus an envelope that expresses longitudes in the range [-180 … +180]° is not compatible with an envelope that expresses
- longitudes in the range [0 … 360]°.
- The conversions, if necessary, are up to the user
- (the <code class="SIS">Envelopes</code> class provides convenience methods to do this).
- Moreover, the envelope's coordinates must be included within the system of coordinates,
- unless the developer explicitly decides to consider (for example) 300° longitude as a position distinct from -60°.
- The <code class="SIS">GeneralEnvelope</code> class provides a <code class="SIS">normalize()</code> method to bring
- coordinates within the desired limits, sometimes at the coast of <cite><i>lower</i></cite> values being higher than
- <cite><i>upper</i></cite> values.
+In order for functions such as <code class="SIS">add(…)</code> to work correctly,
+all objects involved must use the same coordinate reference system, including the same range of values.
+Thus an envelope that expresses longitudes in the range [-180 … +180]° is not compatible with an envelope that expresses
+longitudes in the range [0 … 360]°.
+The conversions, if necessary, are up to the user
+(the <code class="SIS">Envelopes</code> class provides convenience methods to do this).
+Moreover, the envelope's coordinates must be included within the system of coordinates,
+unless the developer explicitly decides to consider (for example) 300° longitude as a position distinct from -60°.
+The <code class="SIS">GeneralEnvelope</code> class provides a <code class="SIS">normalize()</code> method to bring
+coordinates within the desired limits, sometimes at the coast of <cite><i>lower</i></cite> values being higher than
+<cite><i>upper</i></cite> values.
</p>
<aside>
- <p><b>The Special Case of the Range [+0 … -0]</b></p>
- <p>
- Java (or more generally, IEEE Standard 754) defines two values distinct from zero:
- a positive zero and a negative zero. These two values are considered equal when we compare them with the <code>==</code>
- operator in Java.
- But in <abbr title="Spatial Information System">SIS</abbr> envelopes,
- they may actually return opposite results for axes using <code class="GeoAPI">RangeMeaning.WRAPAROUND</code>.
- An envelope whose range is [0 … 0], [-0 … -0] or [-0 … +0] would normally be considered an empty envelope,
- but the [+0 … -0] range would in fact be considered to include the entire set of values all around the world.
- This behaviour conforms to the definition of <code class="SIS">lowerCorner</code> and <code class="SIS">upperCorner</code>,
- which considers +0 as the starting point, and -0 as the end-point after cycling through all possible values.
- Such behaviour only occurs for the pair of values +0 and -0, and only in that order.
- For all other real values, if the condition <code>lower</code> <code>==</code> <code>upper</code> is true,
- then it is guaranteed that the envelope is empty.
- </p>
+<h5>The Special Case of the Range [+0 … -0]</h5>
+<p>
+Java (or more generally, IEEE Standard 754) defines two values distinct from zero:
+a positive zero and a negative zero. These two values are considered equal when we compare them with the <code>==</code> operator in Java.
+But in <abbr title="Spatial Information System">SIS</abbr> envelopes, they may actually return opposite results for axes using <code class="GeoAPI">RangeMeaning.WRAPAROUND</code>.
+An envelope whose range is [0 … 0], [-0 … -0] or [-0 … +0] would normally be considered an empty envelope,
+but the [+0 … -0] range would in fact be considered to include the entire set of values all around the world.
+This behaviour conforms to the definition of <code class="SIS">lowerCorner</code> and <code class="SIS">upperCorner</code>,
+which considers +0 as the starting point, and -0 as the end-point after cycling through all possible values.
+Such behaviour only occurs for the pair of values +0 and -0, and only in that order.
+For all other real values, if the condition <code>lower</code> <code>==</code> <code>upper</code> is true,
+then it is guaranteed that the envelope is empty.
+</p>
</aside>
-
-
-
-<h1 id="Coverage">Data Coverages</h1>
-<p>
- Images, or <i>rasters</i>, are a particular case of a data structure called a <i>coverage</i>.
- We could think of this as a “coverage of data.”
- The title of the <abbr>ISO</abbr> 19123 standard that describes them, “Coverage Geometry and Functions”,
- nicely summarizes the two essential elements of coverages:
+</section>
+<section>
+<header>
+<h1 id="Coverage"><span class="section-number">6.</span> Data Coverages</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Geometry">Previous chapter</a></div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc"/></nav>
+<p>
+Images, or <i>rasters</i>, are a particular case of a data structure called a <i>coverage</i>.
+We could think of this as a “coverage of data.”
+The title of the <abbr title="International Organization for Standardization">ISO</abbr> 19123 standard that describes them, “Coverage Geometry and Functions”,
+nicely summarizes the two essential elements of coverages:
</p>
<ul>
- <li>
- <p>
- A coverage is a function which returns an attribute value from an entered coordinate.
- The set of values that may be entered is called the domain, while the set of values that may be returned is called the range.
- The domain is often the spatio-temporal area covered by the data,
- but nothing in <abbr title="Spatial Information System">SIS</abbr> prevents coverages from extending to other dimensions.
- For example, thermodynamic studies often use an area where the dimensions are temperature and pressure.
- </p>
- <div class="example"><p><b>Example:</b>
- The pixel values of an image may contain measures for terrain elevation.
- If the function <var>h</var> = <var>f</var>(φ,λ) allows us to obtain (eventually, with the help of interpolations)
- the elevation <var>h</var> according the the geographic coordinate (φ,λ),
- then the geographic envelope of the image defined by the domain — the function <var>f</var> — is the <i>coverage</i>,
- and the set of values <var>h</var> that this function can return is the <i>range</i>.
- </p></div>
- </li>
- <li>
- <p>
- Different types of coverages may be characterized by the geometry of their cells.
- In particular, a coverage is not necessarily composed of quadrilateral cells.
- However, given that quadrilateral cells are by far the most frequent (since this is the usual geometry of image pixels),
- we often use the term “grid coverage” to specify coverages composed of such cells.
- In <abbr title="Spatial Information System">SIS</abbr>, the geometry of coverages is described by the <code class="SIS">GridGeometry</code> class.
- </p>
- </li>
+<li>
+<p>
+A coverage is a function which returns an attribute value from an entered coordinate.
+The set of values that may be entered is called the domain, while the set of values that may be returned is called the range.
+The domain is often the spatio-temporal area covered by the data,
+but nothing in <abbr title="Spatial Information System">SIS</abbr> prevents coverages from extending to other dimensions.
+For example, thermodynamic studies often use an area where the dimensions are temperature and pressure.
+</p>
+<div class="example"><p><b>Example:</b>
+The pixel values of an image may contain measures for terrain elevation.
+If the function <var>h</var> = <var>f</var>(φ,λ) allows us to obtain (eventually, with the help of interpolations)
+the elevation <var>h</var> according the the geographic coordinate (φ,λ),
+then the geographic envelope of the image defined by the domain — the function <var>f</var> — is the <i>coverage</i>,
+and the set of values <var>h</var> that this function can return is the <i>range</i>.
+</p></div>
+</li>
+<li>
+<p>
+Different types of coverages may be characterized by the geometry of their cells.
+In particular, a coverage is not necessarily composed of quadrilateral cells.
+However, given that quadrilateral cells are by far the most frequent (since this is the usual geometry of image pixels),
+we often use the term “grid coverage” to specify coverages composed of such cells.
+In <abbr>SIS</abbr>, the geometry of coverages is described by the <code class="SIS">GridGeometry</code> class.
+</p>
+</li>
</ul>
<p>
- The characteristics of the spatial domain are defined by <abbr>ISO</abbr> 19123 standard,
- while the characteristics of range are not included in the standard.
- The standard simply mentions that ranges may be finite or infinite,
- and are not necessarily numerical.
- For example, the values returned by a coverage may come from an enumeration (“this is a forest,” “this is a lake,” etc.).
- However, the standard defines two important types of coverage which have an impact on the types of authorized ranges:
- <i>discrete</i> coverages and <i>continuous</i> coverages.
- Stated simply, continuous coverages are functions that can use interpolation methods.
- Thus, since interpolations are only possible with numeric values, the ranges of non-numeric values may only be used with coverages of the
- <code class="OGC">CV_DiscreteCoverage</code> type.
+The characteristics of the spatial domain are defined by <abbr>ISO</abbr> 19123 standard,
+while the characteristics of range are not included in the standard.
+The standard simply mentions that ranges may be finite or infinite,
+and are not necessarily numerical.
+For example, the values returned by a coverage may come from an enumeration (“this is a forest,” “this is a lake,” etc.).
+However, the standard defines two important types of coverage which have an impact on the types of authorized ranges:
+<i>discrete</i> coverages and <i>continuous</i> coverages.
+Stated simply, continuous coverages are functions that can use interpolation methods.
+Thus, since interpolations are only possible with numeric values, the ranges of non-numeric values may only be used with coverages of the
+<code class="OGC">CV_DiscreteCoverage</code> type.
</p>
<aside>
- <p><b>SIS's <code class="SIS">Range</code> Class and its Relationship to the Standards</b></p>
- <p>
- The distinction between the ranges of all types of values and the ranges of numeric values is represented in
- <abbr title="Spatial Information System">SIS</abbr> by the <code class="SIS">Range</code> and <code class="SIS">NumberRange</code>
- classes respectively.
- The <code class="SIS">NumberRange</code> is used more often, and is also the one that most closely approaches the
- <a href="http://en.wikipedia.org/wiki/Interval_%28mathematics%29">the common mathematical concept of an interval</a>.
- This textual representation approaches the specifications of <abbr>ISO</abbr> 31-11 standard,
- except that the comma is replaced by the character “…” as the separator of minimal and maximal values.
- For example, “[0 … 256)” represents the range of values from 0 inclusive to 256 exclusive.
- </p>
- <p>
- <code class="SIS">Range</code> objects are only indirectly associated with coverages.
- In <abbr title="Spatial Information System">SIS</abbr>, the values that can return coverages are described by objects of the
- <code class="SIS">SampleDimension</code> type. It is these that contain instances of <code class="SIS">Range</code>,
- as well as other information such as <i>transfer function</i> (described later).
- </p>
+<h2>SIS's <code class="SIS">Range</code> Class and its Relationship to the Standards</h2>
+<p>
+The distinction between the ranges of all types of values and the ranges of numeric values is represented in
+<abbr title="Spatial Information System">SIS</abbr> by the <code class="SIS">Range</code> and <code class="SIS">NumberRange</code>
+classes respectively.
+The <code class="SIS">NumberRange</code> is used more often, and is also the one that most closely approaches the
+<a href="http://en.wikipedia.org/wiki/Interval_%28mathematics%29">the common mathematical concept of an interval</a>.
+This textual representation approaches the specifications of <abbr title="International Organization for Standardization">ISO</abbr> 31-11 standard,
+except that the comma is replaced by the character “…” as the separator of minimal and maximal values.
+For example, “[0 … 256)” represents the range of values from 0 inclusive to 256 exclusive.
+</p>
+<p>
+<code class="SIS">Range</code> objects are only indirectly associated with coverages.
+In <abbr>SIS</abbr>, the values that can return coverages are described by objects of the
+<code class="SIS">SampleDimension</code> type. It is these that contain instances of <code class="SIS">Range</code>,
+as well as other information such as <i>transfer function</i> (described later).
+</p>
</aside>
-
- <!-- End of shifted indentation. -->
- </body>
-</html>
+</section>
+</main>
+</body>
+</html>
\ No newline at end of file
diff --git a/book/fr/developer-guide.html b/book/fr/developer-guide.html
index bb6eb74..051f699 100644
--- a/book/fr/developer-guide.html
+++ b/book/fr/developer-guide.html
@@ -1,33 +1,21 @@
-<?xml version="1.0" encoding="UTF-8" ?>
+<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<!--
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ Licensed to the Apache Software Foundation (ASF)
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ This is an automatically generated file. DO NOT EDIT.
+ See the files in the ../../../book/ directory instead.
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="fr">
- <head>
- <title>Introduction à Apache SIS</title>
- <link rel="stylesheet" type="text/css" href="../book.css"/>
- </head>
- <body>
- <!-- From this point, shift indentation 4 spaces to the left for saving space. -->
-
+<head>
+<title>Introduction à Apache SIS</title>
+<link rel="stylesheet" type="text/css" href="../book.css"/>
+</head>
+<body>
<p style="margin-top: 30pt"><span style="font-size: 30pt; font-weight: 900">Introduction à Apache SIS®</span></p>
<p style="margin-bottom: 20pt">(<a href="../en/developer-guide.html">English</a> | Français)</p>
<p><i>Martin Desruisseaux</i><br/>
@@ -36,1491 +24,1462 @@
<hr/>
<p><b style="font-size: 20pt">Table des matières</b></p>
-
+<nav>
<ul class="toc">
- <li><a href="#Foreword">Préface</a><ul>
- <li><a href="#About">Conventions utilisées dans ce guide</a></li>
- </ul></li>
- <li><a href="#Standards">Standards et normes</a><ul>
- <li><a href="#OGC-process">Processus de standardisation à l’<abbr>OGC</abbr></a><ul>
- <li><a href="#OGC-SWG">Fonctionnement des groupes de travail (<abbr>SWG</abbr>)</a></li>
- <li><a href="#OGC-OAB">Le conseil d’architecture (<abbr>OAB</abbr>) et le comité technique (<abbr>TC</abbr>)</a></li>
- <li><a href="#OGC-RFC">Procédure de soumission de propositions de modifications</a></li>
- </ul></li>
- <li><a href="#SpecificationTypes">Les différents types de spécifications</a></li>
- <li><a href="#DefinitionOfTerms">Définitions des termes</a></li>
- </ul></li>
- <li><a href="#GeoAPI">GeoAPI</a><ul>
- <li><a href="#SpecificationToInterfaces">Des spécifications aux interfaces</a><ul>
- <li><a href="#UML-annotation">Correspondances explicitées par l’annotation <code>@UML</code></a></li>
- <li><a href="#MappingToJDK">Correspondances implicites avec le <abbr>JDK</abbr> standard</a></li>
- </ul></li>
- <li><a href="#ServiceLoader">Obtenir une implémentation des interfaces</a><ul>
- <li><a href="#GeoAPI-simple">Fournir sa propre implémentation</a></li>
- </ul></li>
- <li><a href="#GeoAPI-modules">Les modules de GeoAPI</a><ul>
- <li><a href="#GeoAPI-core">Les modules de définition des interfaces</a></li>
- <li><a href="#GeoAPI-conformance">Le module de tests de conformité</a><ul>
- <li><a href="#GeoAPI-validators">Validations des instances</a></li>
- <li><a href="#GeoAPI-tests">Exécution des tests pré-définis</a></li>
- </ul></li>
- <li><a href="#GeoAPI-examples">Les modules d’exemples</a></li>
- </ul></li>
- </ul></li>
- <li><a href="#XML-ISO">Représentation des objets en <abbr>XML</abbr></a><ul>
- <li><a href="#XML-ISO-19115">Représentation des méta-données selon <abbr>ISO</abbr> 19115-3</a><ul>
- <li><a href="#gco-id">Identification d’instances déjà définies</a></li>
- <li><a href="#nilReason">Représentation de valeurs manquantes</a></li>
- </ul></li>
- </ul></li>
- <li><a href="#Utilities">Classes et méthodes utilitaires</a><ul>
- <li><a href="#ComparisonMode">Modes de comparaisons des objets</a></li>
- <li><a href="#Internationalization">Internationalisation</a><ul>
- <li><a href="#LocalizedString">Chaînes de caractères distinctes pour chaque conventions locales</a></li>
- <li><a href="#InternationalString">Instance unique pour toutes les conventions locales</a></li>
- <li><a href="#Locale.ROOT">Convention <code>Locale.ROOT</code></a></li>
- <li><a href="#UnicodePoint">Traitement des caractères</a><ul>
- <li><a href="#Whitespaces">Interprétation des espaces blancs</a></li>
- </ul></li>
- </ul></li>
- </ul></li>
- <li><a href="#Geometry">Géométries</a><ul>
- <li><a href="#Geometry-root">Classes de base</a><ul>
- <li><a href="#DirectPosition">Points et positions directes</a></li>
- <li><a href="#Envelope">Enveloppes</a><ul>
- <li><a href="#AntiMeridian">Enveloppes traversant l’antiméridien</a></li>
- </ul></li>
- </ul></li>
- </ul></li>
- <li><a href="#Coverage">Couvertures de données (<i>Coverages</i>)</a></li>
+<li><a href="#Foreword">Préface</a><ul>
+<li><a href="#Standards">Standards et normes</a><ul>
+<li><a href="#SpecificationTypes">Les différents types de spécifications</a></li></ul></li>
+<li><a href="#About">Conventions utilisées dans ce guide</a><ul>
+<li><a href="#DefinitionOfTerms">Définitions des termes</a></li></ul></li></ul></li>
+<li><a href="#GeoAPI">GeoAPI</a><ul>
+<li><a href="#SpecificationToInterfaces">Des spécifications aux interfaces</a><ul>
+<li><a href="#UML-annotation">Correspondances explicitées par l’annotation @UML</a></li>
+<li><a href="#MappingToJDK">Correspondances implicites avec le JDK standard</a></li></ul></li>
+<li><a href="#ServiceLoader">Obtenir une implémentation des interfaces</a><ul>
+<li><a href="#GeoAPI-simple">Fournir sa propre implémentation</a></li></ul></li>
+<li><a href="#GeoAPI-modules">Les modules de GeoAPI</a><ul>
+<li><a href="#GeoAPI-core">Les modules de définition des interfaces</a></li>
+<li><a href="#GeoAPI-conformance">Le module de tests de conformité</a><ul>
+<li><a href="#GeoAPI-validators">Validations des instances</a></li>
+<li><a href="#GeoAPI-tests">Exécution des tests pré-définis</a></li></ul></li>
+<li><a href="#GeoAPI-examples">Les modules d’exemples</a></li></ul></li></ul></li>
+<li><a href="#XML-ISO">Représentation des objets en XML</a><ul>
+<li><a href="#XML-ISO-19115">Représentation des méta-données selon ISO 19115-3</a><ul>
+<li><a href="#gco-id">Identification d’instances déjà définies</a></li>
+<li><a href="#nilReason">Représentation de valeurs manquantes</a></li></ul></li></ul></li>
+<li><a href="#Utilities">Classes et méthodes utilitaires</a><ul>
+<li><a href="#ComparisonMode">Modes de comparaisons des objets</a></li>
+<li><a href="#Internationalization">Internationalisation</a><ul>
+<li><a href="#LocalizedString">Chaînes de caractères distinctes pour chaque conventions locales</a></li>
+<li><a href="#InternationalString">Instance unique pour toutes les conventions locales</a></li>
+<li><a href="#Locale.ROOT">Convention Locale.ROOT</a></li>
+<li><a href="#UnicodePoint">Traitement des caractères</a><ul>
+<li><a href="#Whitespaces">Interprétation des espaces blancs</a></li></ul></li></ul></li></ul></li>
+<li><a href="#Geometry">Géométries</a><ul>
+<li><a href="#Geometry-root">Classes de base</a><ul>
+<li><a href="#DirectPosition">Points et positions directes</a></li>
+<li><a href="#Envelope">Enveloppes</a><ul>
+<li><a href="#AntiMeridian">Enveloppes traversant l’antiméridien</a></li></ul></li></ul></li></ul></li>
+<li><a href="#Coverage">Couvertures de données (Coverages)</a></li>
</ul>
-
-
-<h1 id="Foreword">Préface</h1>
-<p>
- Une communauté d’informations géospatiales est un ensemble de systèmes ou d’individus capables d’échanger
- leurs données géospatiales grâce à des définitions et des standards communs ainsi qu’une reconnaissance réciproque.
- Comme il existe une multitude de façons de représenter des informations géospatiales,
- chaque communauté est amenée à les structurer en fonction de ses centres d’intérêts.
- Cette diversité complique la tâche des utilisateurs de systèmes d’information géographiques (<abbr>SIG</abbr>)
- en les plaçant devant une variété apparemment chaotique de formats et de structures de données.
- Les caractéristiques de ces structures varient en fonction des phénomènes observés et des méthodes de mesure,
- ainsi que des habitudes des organisations produisant les données.
- Une telle variété agit comme un frein aux études qui requièrent des combinaisons de données hétérogènes,
- surtout lorsqu’elles proviennent de communautés traditionnellement distinctes.
- Par exemple, un chercheur étudiant le choléra peut s’intéresser aux populations de crevettes comme vecteur de propagation de la maladie.
- Mais les médecins et les océanographes n’ayant pas forcement l’habitude de partager leurs travaux,
- les participants à une telle étude peuvent être limités par les efforts qu’ils sont disposés à fournir pour convertir les données.
+</nav>
+
+<main>
+<section>
+<header>
+<h1 id="Foreword"><span class="section-number">1.</span> Préface</h1>
+<nav><div class="chapter-links"><div class="next-chapter"><a href="#GeoAPI">Chapitre précédent</a> ➡</div></div></nav>
+</header>
+<nav>Dans ce chapitre:<ul class="toc">
+<li><a href="#Standards">Standards et normes</a><ul>
+<li><a href="#SpecificationTypes">Les différents types de spécifications</a></li></ul></li>
+<li><a href="#About">Conventions utilisées dans ce guide</a><ul>
+<li><a href="#DefinitionOfTerms">Définitions des termes</a></li></ul></li></ul></nav>
+<p>
+Une communauté d’informations géospatiales est un ensemble de systèmes ou d’individus capables d’échanger
+leurs données géospatiales grâce à des définitions et des standards communs ainsi qu’une reconnaissance réciproque.
+Comme il existe une multitude de façons de représenter des informations géospatiales,
+chaque communauté est amenée à les structurer en fonction de ses centres d’intérêts.
+Cette diversité complique la tâche des utilisateurs de systèmes d’information géographiques (<abbr>SIG</abbr>)
+en les plaçant devant une variété apparemment chaotique de formats et de structures de données.
+Les caractéristiques de ces structures varient en fonction des phénomènes observés et des méthodes de mesure,
+ainsi que des habitudes des organisations produisant les données.
+Une telle variété agit comme un frein aux études qui requièrent des combinaisons de données hétérogènes,
+surtout lorsqu’elles proviennent de communautés traditionnellement distinctes.
+Par exemple, un chercheur étudiant le choléra peut s’intéresser aux populations de crevettes comme vecteur de propagation de la maladie.
+Mais les médecins et les océanographes n’ayant pas forcement l’habitude de partager leurs travaux,
+les participants à une telle étude peuvent être limités par les efforts qu’ils sont disposés à fournir pour convertir les données.
</p><p>
- Nous ne pouvons pas imposer un format uniforme à l’ensemble des données, car la diversité des formats tient
- à des facteurs tels que les contraintes des appareils de mesure et la distribution statistique des valeurs.
- Une solution plus flexible consiste à assurer l’interopérabilité des données à travers une interface de programmation
- (<abbr title="Application Programming Interface">API</abbr>) commune.
- Cette <abbr>API</abbr> n’est pas forcement définie dans un langage de programmation;
- la tendance actuelle est plutôt de définir des conventions utilisant les protocoles web existants,
- que l’on peut transposer dans des langages de programmation.
- Mais pour que cette démarche puisse être pérennisée, l’<abbr>API</abbr> doit être largement accepté par des développeurs indépendants.
- Autrement dit, l’<abbr>API</abbr> doit s’approcher autant que possible des standards industriels.
+Nous ne pouvons pas imposer un format uniforme à l’ensemble des données, car la diversité des formats tient
+à des facteurs tels que les contraintes des appareils de mesure et la distribution statistique des valeurs.
+Une solution plus flexible consiste à assurer l’interopérabilité des données à travers une interface de programmation
+(<abbr title="Application Programming Interface">API</abbr>) commune.
+Cette <abbr>API</abbr> n’est pas forcement définie dans un langage de programmation;
+la tendance actuelle est plutôt de définir des conventions utilisant les protocoles web existants,
+que l’on peut transposer dans des langages de programmation.
+Mais pour que cette démarche puisse être pérennisée, l’<abbr>API</abbr> doit être largement accepté par des développeurs indépendants.
+Autrement dit, l’<abbr>API</abbr> doit s’approcher autant que possible des standards industriels.
</p><p>
- Les accès aux bases de données relationnelles sont un exemple de tâche ayant bénéficié d’une standardisation relativement bien réussie.
- L’industrie a établie un langage commun — le standard <abbr title="Structured Query Language">SQL</abbr> — que les concepteurs du Java
- ont enrobé dans des interfaces de programmation formant le standard <abbr title="Java DataBase Connectivity">JDBC</abbr>.
- Ces interfaces sont aujourd’hui implementées par de nombreux logiciels libres et commerciaux.
- Comme pour les bases de données, des méthodes d’accès aux informations géographiques ont été standardisées.
- Mais les efforts en ce sens sont plus récents et leurs intégrations dans les logiciels, surtout les plus anciens,
- sont incomplètes et pas toujours cohérentes.
- Au moment d’écrire ces lignes, aucun produit de notre connaissance n’implémente la totalité des spécifications.
- Mais on trouve de nombreuses implémentations couvrant un spectre plus ou moins large.
- La bibliothèque Apache <abbr>SIS</abbr>® décrite dans ce document en est une.
+Les accès aux bases de données relationnelles sont un exemple de tâche ayant bénéficié d’une standardisation relativement bien réussie.
+L’industrie a établie un langage commun — le standard <abbr title="Structured Query Language">SQL</abbr> — que les concepteurs du Java
+ont enrobé dans des interfaces de programmation formant le standard <abbr title="Java DataBase Connectivity">JDBC</abbr>.
+Ces interfaces sont aujourd’hui implementées par de nombreux logiciels libres et commerciaux.
+Comme pour les bases de données, des méthodes d’accès aux informations géographiques ont été standardisées.
+Mais les efforts en ce sens sont plus récents et leurs intégrations dans les logiciels, surtout les plus anciens,
+sont incomplètes et pas toujours cohérentes.
+Au moment d’écrire ces lignes, aucun produit de notre connaissance n’implémente la totalité des spécifications.
+Mais on trouve de nombreuses implémentations couvrant un spectre plus ou moins large.
+La bibliothèque Apache <abbr>SIS</abbr>® décrite dans ce document en est une.
</p><p>
- Apache <abbr title="Spatial Information System">SIS</abbr> se caractérise par un effort soutenu de respect des standards,
- allant jusqu’à une participation à certains travaux de l’<abbr title="Open Geospatial Consortium">OGC</abbr>.
- De manière générale, le respect des standards exige un effort plus grand que ce qu’aurait requis un développement isolé,
- mais se rentabilise par un double avantage: en plus d’accroître l’interopérabilité des données avec celles des projets externes,
- il nous indique aussi une voie robuste à suivre pour l’élaboration du modèle conceptuel qui sera reflété par l’<abbr title="Application Programming Interface">API</abbr>.
- En effet, les groupes d’experts qui conçoivent les standards anticipent des difficultés qui échappent parfois à l’ingénieur en début de projet,
- mais qui risquent de le rattraper avant la fin.
-</p>
-
-
-
-<h2 id="About">Conventions utilisées dans ce guide</h2>
-<p>
- Les éléments définis dans un langage informatique, tels que les classes ou méthodes en Java
- ainsi que les éléments dans un fichier <abbr>XML</abbr>, apparaissent avec une police de caractères mono-espacée.
- Afin de faciliter la compréhension des liens qui existent entre Apache <abbr>SIS</abbr> et les standards,
- ces éléments sont en outre représentés en utilisant les codes de couleurs suivants:
-</p>
-<ul>
- <li>
- Les éléments définis dans un standard de l’<abbr title="Open Geospatial Consortium">OGC</abbr>
- ou de l’<abbr title="International Organization for Standardization">ISO</abbr> apparaissent en bleu.
- Exemple: <code class="OGC">CD_Ellipsoid</code>.
- </li>
- <li>
- Les éléments définis dans GeoAPI apparaissent en vert.
- Exemple: <code class="GeoAPI">Ellipsoid</code>.
- </li>
- <li>
- Les éléments définis dans Apache <abbr title="Spatial Information System">SIS</abbr> apparaissent en brun.
- Exemple: <code class="SIS">DefaultEllipsoid</code>.
- </li>
- <li>
- Les autres éléments, notamment ceux du Java standard, sont laissés en noir.
- 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.
+Apache <abbr title="Spatial Information System">SIS</abbr> se caractérise par un effort soutenu de respect des standards.
+De manière générale, le respect des standards exige un effort plus grand que ce qu’aurait requis un développement isolé,
+mais se rentabilise par un double avantage: en plus d’accroître l’interopérabilité des données avec celles des projets externes,
+il nous indique aussi une voie robuste à suivre pour l’élaboration du modèle conceptuel qui sera reflété par l’<abbr>API</abbr>.
+En effet, les groupes d’experts qui conçoivent les standards anticipent des difficultés qui échappent parfois à l’ingénieur en début de projet,
+mais qui risquent de le rattraper avant la fin.
</p>
-<h1 id="Standards">Standards et normes</h1>
+<h2 id="Standards"><span class="section-number">1.1.</span> Standards et normes</h2>
<p>
- La majorité des standards utilisés par Apache <abbr title="Spatial Information System">SIS</abbr> ont été élaborés
- par le <a href="http://www.opengeospatial.org">consortium <i>Open Geospatial</i></a> (<abbr>OGC</abbr>),
- parfois en collaboration avec l’<a href="http://www.iso.org">organisation internationale de normalisation</a> (<abbr>ISO</abbr>).
- Certains standards de l’<abbr>ISO</abbr> deviennent eux-mêmes des standards Européens via la
- <a href="http://inspire.jrc.ec.europa.eu">directive INSPIRE</a>, ou des standards français via l’<abbr>AFNOR</abbr>.
- Ces standards offrent deux technologies clés:
+La majorité des standards utilisés par Apache <abbr title="Spatial Information System">SIS</abbr> ont été élaborés
+par le <a href="http://www.opengeospatial.org">consortium <i>Open Geospatial</i></a> (<abbr>OGC</abbr>),
+parfois en collaboration avec l’<a href="http://www.iso.org">organisation internationale de normalisation</a> (<abbr>ISO</abbr>).
+Certains standards de l’<abbr>ISO</abbr> deviennent eux-mêmes des standards Européens via la
+<a href="http://inspire.jrc.ec.europa.eu">directive INSPIRE</a>, ou des standards français via l’<abbr>AFNOR</abbr>.
+Ces standards offrent deux technologies clés:
</p>
<ul>
- <li>
- Permettre à une communauté d’annoncer leurs informations,
- de manière à ce que des individus ou des systèmes en dehors de cette communauté puissent les découvrir.
- </li>
- <li>
- Transférer des informations d’une communauté vers une autre en préservant leurs sémantiques,
- même si les deux communautés utilisent des représentations internes très différentes.
- </li>
+<li>
+Permettre à une communauté d’annoncer leurs informations,
+de manière à ce que des individus ou des systèmes en dehors de cette communauté puissent les découvrir.
+</li>
+<li>
+Transférer des informations d’une communauté vers une autre en préservant leurs sémantiques,
+même si les deux communautés utilisent des représentations internes très différentes.
+</li>
</ul>
<p>
- Ces standards sont fournis gratuitement à la communauté internationale sous la forme de
- <a href="http://www.opengeospatial.org/standards/is">spécifications (fichiers <abbr title="Portable Document Format">PDF</abbr>)</a> ou de
- <a href="http://schemas.opengis.net/gml/3.3/">schémas (fichiers <abbr title="XML Schema Definition">XSD</abbr>)</a>.
- Les organismes de normalisation ne fabriquent pas de logiciel; pour obtenir une implémentation de ces spécifications,
- les utilisateurs doivent choisir un des produits conformes disponibles sur le marché ou développer leur propres solutions.
- C’est le respect volontaire de ces spécifications qui permet à des communautés à priori indépendantes d’échanger
- plus facilement des informations géographiques.
+Ces standards sont fournis gratuitement à la communauté internationale sous la forme de
+<a href="http://www.opengeospatial.org/standards/is">spécifications (fichiers <abbr title="Portable Document Format">PDF</abbr>)</a> ou de
+<a href="http://schemas.opengis.net/gml/3.3/">schémas (fichiers <abbr title="XML Schema Definition">XSD</abbr>)</a>.
+Les organismes de normalisation ne fabriquent pas de logiciel; pour obtenir une implémentation de ces spécifications,
+les utilisateurs doivent choisir un des produits conformes disponibles sur le marché ou développer leur propres solutions.
+C’est le respect volontaire de ces spécifications qui permet à des communautés à priori indépendantes d’échanger
+plus facilement des informations géographiques.
</p><p>
- Outre ces organisations formelles de normalisation, il existe aussi des organisations qui ne sont pas officiellement
- dédiées à l’élaboration de normes mais dont les travaux ont été largement adoptés comme standards de fait.
- En particulier, la base de données <a href="http://www.epsg.org">EPSG</a> fournit des codes numériques permettant d’identifier
- facilement un système de référence des coordonnées parmi <a href="../sis-referencing/supported-codes.html">plusieurs milliers</a>.
- Cette base de données est offerte par des compagnies pétrolières qui ont vu leur intérêt à ce que leurs prospections se fassent
- bien à l’endroit voulu, sachant qu’elles ne contrôlent pas toujours la production des cartes sur lesquelles elles se positionnent.
- D’autres exemples de standards de fait sont les formats
- <a href="http://geotiff.osgeo.org">GeoTIFF</a> pour les données réparties sur une grille (les images), et
- <a href="http://fr.wikipedia.org/wiki/Shapefile">Shapefile</a> pour les données vectorielles (les géométries).
-</p>
-
-
-
-<h2 id="OGC-process">Processus de standardisation à l’<abbr>OGC</abbr></h2>
-<p>
- Les travaux de l’<abbr title="Open Geospatial Consortium">OGC</abbr> se font par courriers électroniques,
- par conférences téléphoniques et par <a href="http://www.opengeospatial.org/event?category=ogctcpc">réunions réelles</a>.
- L’<abbr>OGC</abbr> organise quatre réunions par années, chacune d’une durée de cinq jours,
- hébergées par des organisations membres sponsorisant l’événement (compagnies, universités, centres de recherches, <i>etc.</i>).
- Le continent hôte alterne entre l’Europe et l’Amérique du Nord, avec une présence croissante en Asie depuis 2011.
- Ces réunions reçoivent habituellement entre 50 et 100 participants parmi les centaines de membres de l’<abbr>OGC</abbr>.
- Certains participants sont présents à quasiment toutes les réunions et constituent des piliers de l’organisation.
+Outre ces organisations formelles de normalisation, il existe aussi des organisations qui ne sont pas officiellement
+dédiées à l’élaboration de normes mais dont les travaux ont été largement adoptés comme standards de fait.
+En particulier, la base de données <a href="http://www.epsg.org">EPSG</a> fournit des codes numériques permettant d’identifier
+facilement un système de référence des coordonnées parmi <a href="../tables/CoordinateReferenceSystems.html">plusieurs milliers</a>.
+Cette base de données est offerte par des compagnies pétrolières qui ont vu leur intérêt à ce que leurs prospections se fassent
+bien à l’endroit voulu, sachant qu’elles ne contrôlent pas toujours la production des cartes sur lesquelles elles se positionnent.
+D’autres exemples de standards de fait sont les formats
+<a href="http://geotiff.osgeo.org">GeoTIFF</a> pour les données réparties sur une grille (les images), et
+<a href="http://fr.wikipedia.org/wiki/Shapefile">Shapefile</a> pour les données vectorielles (les géométries).
+</p>
+
+
+
+<article id="OGC-process">
+<header>
+<h1>Processus de standardisation à l’<abbr>OGC</abbr></h1>
+</header>
+<p>
+Les travaux de l’<abbr title="Open Geospatial Consortium">OGC</abbr> se font par courriers électroniques,
+par conférences téléphoniques et par <a href="http://www.opengeospatial.org/event?category=ogctcpc">réunions réelles</a>.
+L’<abbr>OGC</abbr> organise quatre réunions par années, chacune d’une durée de cinq jours,
+hébergées par des organisations membres sponsorisant l’événement (compagnies, universités, centres de recherches, <i>etc.</i>).
+Le continent hôte alterne entre l’Europe et l’Amérique du Nord, avec une présence croissante en Asie depuis 2011.
+Ces réunions reçoivent habituellement entre 50 et 100 participants parmi les centaines de membres de l’<abbr>OGC</abbr>.
+Certains participants sont présents à quasiment toutes les réunions et constituent des piliers de l’organisation.
</p><p>
- Les réunions de l’<abbr title="Open Geospatial Consortium">OGC</abbr> offrent des opportunités d’échanges avec des membres d’horizons diverses.
- La création d’un standard <abbr>OGC</abbr> commence par le regroupement d’organisations ou d’individus constatant un intérêt commun pour une problématique.
- Un groupe de travail est proposé sous l’appellation de <i>Discussion Working Group</i> (<abbr>DWG</abbr>) si le travail est au stade exploratoire,
- ou <i>Standard Working Group</i> (<abbr>SWG</abbr>) si le travail de normalisation peut commencer.
- Les <abbr>DWG</abbr> sont ouverts à tout membre de l’<abbr>OGC</abbr>,
- tandis que les <abbr>SWG</abbr> nécessitent de la part des participants un engagement à ne pas entraver
- la diffusion du standard par des réclamations de propriétés intellectuelles.
-</p>
-
-
-
-<h3 id="OGC-SWG">Fonctionnement des groupes de travail (<abbr>SWG</abbr>)</h3>
-<p>
- Pour être accepté, un projet de standardisation doit être supporté par un nombre minimal de membres appartement à des organisations distinctes.
- Ces membres fondateurs rédigent une charte définissant les objectifs du <abbr title="Standard Working Group">SWG</abbr>,
- qui doit être approuvée par le comité technique de l’<abbr title="Open Geospatial Consortium">OGC</abbr>.
- Chaque membre fondateur est doté d’un droit de vote, dans les limites d’un membre votant par organisation.
- Tout nouveau membre qui souhaite joindre le <abbr>SWG</abbr> après sa création se verra attribué un rôle d’observateur,
- avec attribution sur demande d’un droit de vote après quelques mois d’observation.
+Les réunions de l’<abbr>OGC</abbr> offrent des opportunités d’échanges avec des membres d’horizons diverses.
+La création d’un standard <abbr>OGC</abbr> commence par le regroupement d’organisations ou d’individus constatant un intérêt commun pour une problématique.
+Un groupe de travail est proposé sous l’appellation de <i>Domain Working Group</i> (<abbr>DWG</abbr>) ou <i>Standard Working Group</i> (<abbr>SWG</abbr>).
+Les <abbr>DWG</abbr> sont ouverts à tout membre de l’<abbr>OGC</abbr>,
+tandis que les <abbr>SWG</abbr> nécessitent de la part des participants un engagement à ne pas entraver
+la diffusion du standard par des réclamations de propriétés intellectuelles.
+</p>
+
+<h2 id="OGC-SWG">Fonctionnement des groupes de travail (<abbr>SWG</abbr>)</h2>
+<p>
+Pour être accepté, un projet de standardisation doit être supporté par un nombre minimal de membres appartement à des organisations distinctes.
+Ces membres fondateurs rédigent une charte définissant les objectifs du <abbr>SWG</abbr>,
+qui doit être approuvée par le comité technique de l’<abbr title="Open Geospatial Consortium">OGC</abbr>.
+Chaque membre fondateur est doté d’un droit de vote, dans les limites d’un membre votant par organisation.
+Tout nouveau membre qui souhaite joindre le <abbr>SWG</abbr> après sa création se verra attribué un rôle d’observateur,
+avec attribution sur demande d’un droit de vote après quelques mois d’observation.
</p><p>
- Un <abbr title="Standard Working Group">SWG</abbr> peut contenir plusieurs dizaines de membres,
- mais les volontaires effectuant l’essentiel du travail sont habituellement moins nombreux.
- Leurs propositions sont soumises à l’ensemble des membres du groupe, qui peuvent les accepter par consentement unanime.
- Les objections, s’il y en a, doivent être argumentées et une alternative proposée.
- Les <abbr>SWG</abbr> essaient généralement de débattre d’un problème jusqu’à ce qu’un consensus se forme
- plutôt que d’avancer malgré des votes négatifs, même s’ils sont minoritaires.
- Les décisions du groupes sont alors intégrées dans la spécification par un membre assumant le rôle d’éditeur.
+Un <abbr>SWG</abbr> peut contenir plusieurs dizaines de membres,
+mais les volontaires effectuant l’essentiel du travail sont habituellement moins nombreux.
+Leurs propositions sont soumises à l’ensemble des membres du groupe, qui peuvent les accepter par consentement unanime.
+Les objections, s’il y en a, doivent être argumentées et une alternative proposée.
+Les <abbr>SWG</abbr> essaient généralement de débattre d’un problème jusqu’à ce qu’un consensus se forme
+plutôt que d’avancer malgré des votes négatifs, même s’ils sont minoritaires.
+Les décisions du groupes sont alors intégrées dans la spécification par un membre assumant le rôle d’éditeur.
</p><p>
- Le groupe de travail doit autant que possible structurer la spécification sous forme d’un noyau autour duquel gravite diverses extensions.
- Une suite de tests doit accompagner le standard, et permettre de classer les implémentations en fonction du niveau des tests passés.
- Au moins une <i>implémentation de référence</i> passant les tests doit exister pour démontrer que le standard est utilisable.
+Le groupe de travail doit autant que possible structurer la spécification sous forme d’un noyau autour duquel gravite diverses extensions.
+Une suite de tests doit accompagner le standard, et permettre de classer les implémentations en fonction du niveau des tests passés.
+Au moins une <i>implémentation de référence</i> passant les tests doit exister pour démontrer que le standard est utilisable.
</p><p>
- Lorsque le standard est jugé prêt, le <abbr title="Standard Working Group">SWG</abbr> vote une motion
- proposant de le soumettre au vote des instances supérieures de l’<abbr title="Open Geospatial Consortium">OGC</abbr>.
- Cette procédure nécessite plusieurs mois.
- Il existe une procédure plus rapide pour entériner des standards de fait, mais elle n’est appliquée qu’avec parcimonie.
-</p>
-
-
-
-<h3 id="OGC-OAB">Le conseil d’architecture (<abbr>OAB</abbr>) et le comité technique (<abbr>TC</abbr>)</h3>
-<p>
- Toute proposition de standard est d’abord examinée par le conseil d’architecture
- (<i><abbr title="Open Geospatial Consortium">OGC</abbr> Architecture Board</i> — <abbr>OAB</abbr>).
- Ce conseil vérifie que le standard répond aux exigences de l’<abbr title="Open Geospatial Consortium">OGC</abbr> sur la forme,
- sur la modularisation, et en termes d’intégration avec les autres standards.
- Si l’<abbr>OAB</abbr> donne son aval, le standard est alors soumis au vote des membres du comité technique (<abbr title="Technical Committe">TC</abbr>).
- Ce comité regroupe les principaux membres de l’<abbr>OGC</abbr> qui sont seuls habilités à donner le vote final.
- En cas d’approbation, le standard est diffusé publiquement pour commentaires pendant une période de quelques mois.
- Au terme de cette période, le <abbr title="Standard Working Group">SWG</abbr> doit examiner et répondre à chacun des commentaires.
- Les éventuelles modifications au standard sous soumises à l’<abbr>OAB</abbr>, puis le standard est définitivement publié.
- Cette diffusion est alors annoncée par un communiqué de presse de l’<abbr>OGC</abbr>.
+Lorsque le standard est jugé prêt, le <abbr>SWG</abbr> vote une motion
+proposant de le soumettre au vote des instances supérieures de l’<abbr>OGC</abbr>.
+Cette procédure nécessite plusieurs mois.
+Il existe une procédure plus rapide pour entériner des standards de fait, mais elle n’est appliquée qu’avec parcimonie.
+</p>
+
+<h2 id="OGC-OAB">Le conseil d’architecture (<abbr>OAB</abbr>) et le comité technique (<abbr>TC</abbr>)</h2>
+<p>
+Toute proposition de standard est d’abord examinée par le conseil d’architecture (<i><abbr title="Open Geospatial Consortium">OGC</abbr> Architecture Board</i> — <abbr>OAB</abbr>).
+Ce conseil vérifie que le standard répond aux exigences de l’<abbr>OGC</abbr> sur la forme,
+sur la modularisation, et en termes d’intégration avec les autres standards.
+Si l’<abbr>OAB</abbr> donne son aval, le standard est alors soumis au vote des membres du comité technique (<abbr>TC</abbr>).
+Ce comité regroupe les principaux membres de l’<abbr>OGC</abbr> qui sont seuls habilités à donner le vote final.
+En cas d’approbation, le standard est diffusé publiquement pour commentaires pendant une période de quelques mois.
+Au terme de cette période, le <abbr title="Standard Working Group">SWG</abbr> doit examiner et répondre à chacun des commentaires.
+Les éventuelles modifications au standard sous soumises à l’<abbr>OAB</abbr>, puis le standard est définitivement publié.
+Cette diffusion est alors annoncée par un communiqué de presse de l’<abbr>OGC</abbr>.
</p><p>
- Certains membres de l’<abbr title="Open Geospatial Consortium">OGC</abbr> et du <abbr title="Technical Committe">TC</abbr>
- assurent aussi la liaison avec l’organisation internationale de normalisation (<abbr title="International Organization for Standardization">ISO</abbr>).
- La coopération entre les deux organismes va dans les deux sens: l’<abbr>OGC</abbr> adopte les standards <abbr>ISO</abbr> comme base sur
- laquelle développer de nouveaux standards, et certains de ces nouveaux standards <abbr>OGC</abbr> deviennent des standards <abbr>ISO</abbr>.
+Certains membres de l’<abbr title="Open Geospatial Consortium">OGC</abbr> et du <abbr title="Technical Committe">TC</abbr>
+assurent aussi la liaison avec l’organisation internationale de normalisation (<abbr title="International Organization for Standardization">ISO</abbr>).
+La coopération entre les deux organismes va dans les deux sens: l’<abbr>OGC</abbr> adopte les standards <abbr>ISO</abbr> comme base sur
+laquelle développer de nouveaux standards, et certains de ces nouveaux standards <abbr>OGC</abbr> deviennent des standards <abbr>ISO</abbr>.
</p>
-
-
-<h3 id="OGC-RFC">Procédure de soumission de propositions de modifications</h3>
+<h2 id="OGC-RFC">Procédure de soumission de propositions de modifications</h2>
<p>
- Tout utilisateur, qu’il soit membre ou non du consortium <i>Open Geospatial</i>, peut proposer des modifications
- à des standards <abbr title="Open Geospatial Consortium">OGC</abbr>.
- Une liste des propositions actuelles de changements, ainsi qu’un formulaire permettant d’en soumettre de nouvelles,
- sont <a href="http://www.opengeospatial.org/standards/cr">disponibles en ligne</a>.
- Chaque proposition est revue par le <abbr title="Standard Working Group">SWG</abbr>.
+Tout utilisateur, qu’il soit membre ou non du consortium <i>Open Geospatial</i>, peut proposer des modifications à des standards <abbr title="Open Geospatial Consortium">OGC</abbr>.
+Une liste des propositions actuelles de changements, ainsi qu’un formulaire permettant d’en soumettre de nouvelles,
+sont <a href="http://www.opengeospatial.org/standards/cr">disponibles en ligne</a>.
+Chaque proposition est revue par le <abbr title="Standard Working Group">SWG</abbr>.
</p><p>
- Certains groupes de travail utilisent d’autres systèmes de soumission en parallèle.
- En particulier, le projet GeoAPI continue à utiliser un <a href="http://jira.codehaus.org/browse/GEO">système de tâches JIRA</a>
- hébergé en dehors des structures de l’<abbr title="Open Geospatial Consortium">OGC</abbr>.
- Cet état des choses existe en partie pour des raisons historiques, et en partie parce que les
- développements du projet GeoAPI se font davantage au niveau d’un code source plutôt qu’au
- niveau de documents ou de diagrammes de classes.
+Certains groupes de travail utilisent d’autres systèmes de soumission en parallèle, par exemple GitHub,
+hébergés en dehors des structures de l’<abbr>OGC</abbr>.
</p>
+</article>
-<h2 id="SpecificationTypes">Les différents types de spécifications</h2>
+<h3 id="SpecificationTypes"><span class="section-number">1.1.1.</span> Les différents types de spécifications</h3>
<p>
- Les standards <abbr title="Open Geospatial Consortium">OGC</abbr> sont spécifiés dans plusieurs dizaines de documents.
- Chaque document élabore un service, par exemple les transformations de coordonnées.
- Le fonctionnement de chaque service est décrit par un ensemble de classes d’objets et leurs interactions.
- Ces éléments sont illustrés par des diagrammes <abbr>UML</abbr> (<i>Unified Modeling Language</i>)
- dans des spécifications dites « abstraites ».
+Les standards <abbr title="Open Geospatial Consortium">OGC</abbr> sont spécifiés dans plusieurs dizaines de documents.
+Chaque document élabore un service, par exemple les transformations de coordonnées.
+Le fonctionnement de chaque service est décrit par un ensemble de classes d’objets et leurs interactions.
+Ces éléments sont illustrés par des diagrammes <abbr>UML</abbr> (<i>Unified Modeling Language</i>)
+dans des spécifications dites « abstraites ».
</p><p>
- Les <a href="http://www.opengeospatial.org/standards/as">spécifications abstraites</a> ne font référence à aucun langage informatique concret.
- Leurs concepts peuvent se concrétiser dans un langage de programmation, une base de données ou un schéma <abbr>XML</abbr> de manière plus ou moins directe.
- Il existe toutefois une part d’arbitraire dans la façon de concrétiser une spécification abstraite, étant donné que des ajustements sont souvent nécessaires
- pour tenir compte des contraintes ou des conventions du langage ciblé. Par exemple:
-</p>
-<ul>
- <li>
- L’approche orientée objets se concrétise par des solutions verbeuses dans certains langages
- (notamment le <abbr>XML</abbr> défini par <abbr>ISO</abbr> 19139), par exemple pour le support du polymorphisme.
- </li>
- <li>
- Certaines structures de données n’existent que dans quelques langages,
- par exemple les unions qui existent en C/C++ mais pas en Java.
- </li>
- <li>
- Certaines spécifications (surtout les plus anciennes) définissent des opérations,
- qui se prêtent bien aux langages de programmation ou à des services mais pas à des bases de données.
- </li>
-</ul>
-<p>
- Au tournant du millénaire, les spécifications abstraites étaient explicitement concrétisées dans des <i>spécifications d’implémentations</i>.
- Le terme « implémentation » était ici à prendre au sens de tout type d’interfaces (Java ou autres) dérivées des diagrammes
- <abbr title="Unified Modeling Language">UML</abbr> — et non pas d’implémentations au sens du Java.
- Des telles spécifications existaient pour les langages <abbr title="Structured Query Language">SQL</abbr>,
- <abbr title="Common Object Request Broker Architecture">CORBA</abbr>, <abbr title="Component Object Model">COM</abbr> et Java.
- Ces langages étant capables d’exécuter des procédures, les spécifications de cette époque définissaient
- non seulement des structures de données, mais aussi des opérations s’appliquant sur ces structures.
+Les <a href="http://www.opengeospatial.org/standards/as">spécifications abstraites</a> ne font référence à aucun langage informatique concret.
+Leurs concepts peuvent se concrétiser dans un langage de programmation, une base de données ou un schéma <abbr>XML</abbr> de manière plus ou moins directe.
+Il existe toutefois une part d’arbitraire dans la façon de concrétiser une spécification abstraite, étant donné que des ajustements sont souvent nécessaires
+pour tenir compte des contraintes ou des conventions du langage ciblé.
+Certaines structures de données n’existent que dans quelques langages, par exemple les unions qui existent en C/C++ mais pas en Java.
+</p><p>
+Au tournant du millénaire, les spécifications abstraites étaient explicitement concrétisées dans des <i>spécifications d’implémentations</i>.
+Le terme « implémentation » était ici à prendre au sens de tout type d’interfaces (Java ou autres) dérivées des diagrammes
+<abbr title="Unified Modeling Language">UML</abbr> — et non pas d’implémentations au sens du Java.
+Des telles spécifications existaient pour les langages <abbr title="Structured Query Language">SQL</abbr>,
+<abbr title="Common Object Request Broker Architecture">CORBA</abbr>, <abbr title="Component Object Model">COM</abbr> et Java.
+Ces langages étant capables d’exécuter des procédures, les spécifications de cette époque définissaient
+non seulement des structures de données, mais aussi des opérations s’appliquant sur ces structures.
</p><p>
- Par la suite, l’engouement pour le « web 2.0 » a fait grimper l’intérêt pour le <abbr>XML</abbr> au détriment des autres langages.
- Les anciennes spécifications d’implémentations ont été dépréciées, et les schémas <abbr title="XML Schema Definition">XSD</abbr>
- sont devenus la principale concrétisation des spécifications abstraites.
- Même la façon de concevoir les spécifications abstraites a évoluée: les opérations y sont plus rarement définies,
- par conséquence ce qui reste ressemble davantage à des descriptions de schémas de base de données.
- Certaines opérations qui étaient définies dans les anciennes normes apparaissent maintenant, sous une autre forme, dans les spécifications des services web.
- Enfin le terme « spécification d’implémentation » a été abandonné, pour être englobé dans « standard <abbr title="Open Geospatial Consortium">OGC</abbr> ».
- Mais malgré leur dépréciation, les <a href="http://www.opengeospatial.org/standards/retired">anciennes spécifications d’implémentations</a>
- restent utiles aux programmes en langage Java car:
+Par la suite, l’engouement pour le « web 2.0 » a fait grimper l’intérêt pour le <abbr>XML</abbr> au détriment des autres langages.
+Les anciennes spécifications d’implémentations ont été dépréciées, et les schémas <abbr title="XML Schema Definition">XSD</abbr>
+sont devenus la principale concrétisation des spécifications abstraites.
+Même la façon de concevoir les spécifications abstraites a évoluée: les opérations y sont plus rarement définies,
+par conséquence ce qui reste ressemble davantage à des descriptions de schémas de base de données.
+Certaines opérations qui étaient définies dans les anciennes normes apparaissent maintenant, sous une autre forme, dans les spécifications des services web.
+Enfin le terme « spécification d’implémentation » a été abandonné, pour être englobé dans « standard <abbr title="Open Geospatial Consortium">OGC</abbr> ».
+Mais malgré leur dépréciation, les <a href="http://www.opengeospatial.org/standards/retired">anciennes spécifications d’implémentations</a>
+restent utiles aux programmes en langage Java car:
</p>
<ul>
- <li>
- Leurs modèles plus simples, appliqués aux mêmes concepts, aident à comprendre les nouvelles spécifications.
- </li>
- <li>
- Ils définissent parfois des façons simples d’effectuer des tâches courantes
- là où les nouvelles spécifications se limitent au cas général.
- </li>
- <li>
- Les opérations étant plus souvent omises dans les nouvelles spécifications,
- les anciennes spécifications restent un complément utile pour définir des
- <abbr title="Application Programming Interface">API</abbr>.
- </li>
+<li>
+Leurs modèles plus simples, appliqués aux mêmes concepts, aident à comprendre les nouvelles spécifications.
+</li>
+<li>
+Ils définissent parfois des façons simples d’effectuer des tâches courantes
+là où les nouvelles spécifications se limitent au cas général.
+</li>
+<li>
+Les opérations étant plus souvent omises dans les nouvelles spécifications,
+les anciennes spécifications restent un complément utile pour définir des <abbr title="Application Programming Interface">API</abbr>.
+</li>
</ul>
<p>
- Le projet Apache <abbr title="Spatial Information System">SIS</abbr> se base sur les spécifications les plus récentes,
- tout en puisant dans les archives de l’<abbr title="Open Geospatial Consortium">OGC</abbr>
- pour compléter certains standards abstraits ou les rendre un peu plus facile d’utilisation.
- Certaines anciennes définitions sont conservées comme « méthodes de commodités »,
- n’apportant pas toujours de nouvelles fonctionnalités mais facilitant l’usage pratique d’une bibliothèque.
+Le projet Apache <abbr title="Spatial Information System">SIS</abbr> se base sur les spécifications les plus récentes,
+tout en puisant dans les archives de l’<abbr title="Open Geospatial Consortium">OGC</abbr>
+pour compléter certains standards abstraits ou les rendre un peu plus facile d’utilisation.
+Certaines anciennes définitions sont conservées comme « méthodes de commodités »,
+n’apportant pas toujours de nouvelles fonctionnalités mais facilitant l’usage pratique d’une bibliothèque.
</p><p>
- Le tableau suivant liste les principales normes utilisées par le projet.
- Plusieurs normes sont publiées à la fois comme standard <abbr title="International Organization for Standardization">ISO</abbr>
- et comme standard <abbr title="Open Geospatial Consortium">OGC</abbr>, d’où la disposition côte-à-côte des deux premières colonnes.
- Les normes dépréciées mais malgré tout utilisées apparaissent <s>barrées</s>.
- Enfin, les paquets GeoAPI seront introduits dans le chapitre suivant.
+Le tableau suivant liste les principales normes utilisées par le projet.
+Plusieurs normes sont publiées à la fois comme standard <abbr title="International Organization for Standardization">ISO</abbr> et comme standard <abbr>OGC</abbr>,
+d’où la disposition côte-à-côte des deux premières colonnes.
+Les normes dépréciées mais malgré tout utilisées apparaissent <s>barrées</s>.
+Enfin, les paquets GeoAPI seront introduits dans le chapitre suivant.
</p>
<table>
- <caption>Principaux standards utilisés par le projet Apache <abbr>SIS</abbr></caption>
- <tr>
- <th>Norme <abbr>ISO</abbr></th>
- <th>Norme <abbr>OGC</abbr></th>
- <th>Titre</th>
- <th>Paquet de GeoAPI</th>
- <th>Paquet de Apache SIS</th>
- </tr>
- <tr>
- <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="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="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>
+<caption>Principaux standards en relation avec le projet Apache <abbr>SIS</abbr></caption>
+<tr>
+<th>Norme <abbr>ISO</abbr></th>
+<th>Norme <abbr>OGC</abbr></th>
+<th>Titre</th>
+<th>Paquet de GeoAPI</th>
+<th>Paquet de Apache SIS</th>
+</tr>
+<tr>
+<td class="separator" colspan="5">Spécifications abstraites</td>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 19103</td>
+<td/>
+<td><i>Conceptual schema language</i></td>
+<td><code class="GeoAPI">org.opengis.util</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.metadata</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.referencing</code></td>
+<td><code class="SIS">org.apache.sis.referencing</code></td>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 19108</td>
+<td/>
+<td><i>Temporal Schema</i></td>
+<td><code class="GeoAPI">org.opengis.temporal</code></td>
+<td/>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 19107</td>
+<td>Topic 1</td>
+<td><i>Feature geometry</i></td>
+<td><code class="GeoAPI">org.opengis.geometry</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.feature</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.coverage</code></td>
+<td><code class="SIS">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 class="GeoAPI">org.opengis.observation</code></td>
+<td/>
+</tr>
+<tr>
+<td class="separator" colspan="5">Spécifications d’implémentation</td>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 19139</td>
+<td/>
+<td><i>Metadata <abbr>XML</abbr> schema implementation</i></td>
+<td/>
+<td><code class="SIS">org.apache.sis.xml</code></td>
+</tr>
+<tr>
+<td><abbr>ISO</abbr> 13249</td>
+<td/>
+<td><i><abbr>SQL</abbr> spatial</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td><s><abbr>OGC</abbr> 01-009</s></td>
+<td><s><i>Coordinate Transformation Services</i></s></td>
+<td><code class="GeoAPI">org.opengis.referencing</code></td>
+<td><code class="SIS">org.apache.sis.referencing</code></td>
+</tr>
+<tr>
+<td/>
+<td><s><abbr>OGC</abbr> 01-004</s></td>
+<td><s><i>Grid Coverage</i></s></td>
+<td><code class="GeoAPI">org.opengis.coverage</code></td>
+<td><code class="SIS">org.apache.sis.coverage</code></td>
+</tr>
+<tr>
+<td/>
+<td><abbr>SLD</abbr></td>
+<td><i>Styled Layer Descriptor</i></td>
+<td><code class="GeoAPI">org.opengis.style</code></td>
+<td/>
+</tr>
+<tr>
+<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/>
+</tr>
+<tr>
+<td/>
+<td><abbr>WMTS</abbr></td>
+<td><i>Web Map Tile Service</i></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/>
+</tr>
+<tr>
+<td/>
+<td><abbr>WCS</abbr></td>
+<td><i>Web Coverage Service</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td><abbr>WPS</abbr></td>
+<td><i>Web Processing Service</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td>Open<abbr>LS</abbr></td>
+<td><i>Location Services</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td><abbr>SWE</abbr></td>
+<td><i>Sensor Web Enablement</i></td>
+<td/>
+<td/>
+</tr>
+<tr>
+<td/>
+<td><abbr>SOS</abbr></td>
+<td><i>Sensor Observation Service</i></td>
+<td/>
+<td/>
+</tr>
</table>
-<h2 id="DefinitionOfTerms">Définitions des termes</h2>
+<h2 id="About"><span class="section-number">1.2.</span> Conventions utilisées dans ce guide</h2>
<p>
- Les standards privilégient parfois l’application de certains termes génériques à des contextes particuliers,
- qui peuvent différer du contexte dans lequel d’autres communautés emploient ces termes.
- Par exemple les termes <i>domain</i> et <i>range</i> peuvent s’appliquer à des fonctions arbitraires
- pour désigner l’ensemble des valeurs possibles en entrés et en sorties respectivement.
- Mais les fonctions auxquelles certains standards <abbr title="International Organization for Standardization">ISO</abbr>
- les appliquent ne sont pas les mêmes que les fonctions auxquelles d’autres bibliothèques les appliquent.
- Par exemple <abbr>ISO</abbr> 19123 applique ces termes aux objets <code class="OGC">CV_Coverage</code>,
- vus comme des fonctions dont le domaine est l’ensemble des coordonnées spatio-temporelles de la couverture de données
- et le <i>range</i> l’ensemble des valeurs de la couverture.
- Mais la bibliothèque <abbr title="Network Common Data Form">NetCDF</abbr> de l’<abbr title="University Corporation for Atmospheric Research">UCAR</abbr>
- applique plutôt ces termes à la fonction convertissant les indices de pixels (son domaine) vers les coordonnées spatio-temporelles (son <i>range</i>).
- Ainsi, un <i>range</i> de la bibliothèque de l’<abbr>UCAR</abbr> peut être le domaine de <abbr>ISO</abbr> 19123.
-</p><p>
- La bibliothèque Apache <abbr title="Spatial Information System">SIS</abbr> privilégie autant que possible l’utilisation des termes dans le sens
- des normes <abbr title="Open Geospatial Consortium">OGC</abbr> et <abbr title="International Organization for Standardization">ISO</abbr>.
- Mais un soin particulier doit être apporté aux interfaces entre <abbr>SIS</abbr> et certaines bibliothèques externes, afin de réduire les risques de confusions.
+Les éléments définis dans un langage informatique, tels que les classes ou méthodes en Java
+ainsi que les éléments dans un fichier <abbr>XML</abbr>, apparaissent avec une police de caractères mono-espacée.
+Afin de faciliter la compréhension des liens qui existent entre Apache <abbr title="Spatial Information System">SIS</abbr> et les standards,
+ces éléments sont en outre représentés en utilisant les codes de couleurs suivants:
+</p>
+<ul>
+<li>
+Les éléments définis dans un standard de l’<abbr title="Open Geospatial Consortium">OGC</abbr>
+ou de l’<abbr title="International Organization for Standardization">ISO</abbr> apparaissent en bleu.
+Exemple: <code class="OGC">CD_Ellipsoid</code>.
+</li>
+<li>
+Les éléments définis dans GeoAPI apparaissent en vert.
+Exemple: <code class="GeoAPI">Ellipsoid</code>.
+</li>
+<li>
+Les éléments définis dans Apache <abbr title="Spatial Information System">SIS</abbr> apparaissent en brun.
+Exemple: <code class="SIS">DefaultEllipsoid</code>.
+</li>
+<li>
+Les autres éléments, notamment ceux du Java standard, sont laissés en noir.
+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>
-<h1 id="GeoAPI">GeoAPI</h1>
+<h3 id="DefinitionOfTerms"><span class="section-number">1.2.1.</span> Définitions des termes</h3>
<p>
- Le projet <a href="http://www.geoapi.org">GeoAPI</a> offre un ensemble d’interfaces Java pour les applications géo-spatiales.
- Dans une séries de paquets <code class="GeoAPI">org.opengis.*</code>, GeoAPI définit des structures représentant des méta-données,
- des systèmes de référence des coordonnées, ainsi que des opérations effectuant des projections cartographiques.
- Dans une partie qui n’est pas encore standardisée — dénommée <i>pending</i> — GeoAPI définit des structures
- représentant des images géo-référencées, des géométries, des filtres pouvant s’appliquer à des requêtes, et d’autres fonctionnalités.
- Ces interfaces suivent de très près les spécifications de l’<abbr title="Open Geospatial Consortium">OGC</abbr>,
- tout en les interprétant et en les adaptant de manière à répondre aux attentes des développeurs Java — par exemple
- en se conformant aux conventions de nommage.
- Ces interfaces bénéficient à la fois aux applications clientes et aux bibliothèques:
+Les standards privilégient parfois l’application de certains termes génériques à des contextes particuliers,
+qui peuvent différer du contexte dans lequel d’autres communautés emploient ces termes.
+Par exemple les termes <i>domain</i> et <i>range</i> peuvent s’appliquer à des fonctions arbitraires
+pour désigner l’ensemble des valeurs possibles en entrés et en sorties respectivement.
+Mais les fonctions auxquelles certains standards <abbr title="International Organization for Standardization">ISO</abbr>
+les appliquent ne sont pas les mêmes que les fonctions auxquelles d’autres bibliothèques les appliquent.
+Par exemple <abbr>ISO</abbr> 19123 applique ces termes aux objets <code class="OGC">CV_Coverage</code>,
+vus comme des fonctions dont le domaine est l’ensemble des coordonnées spatio-temporelles de la couverture de données
+et le <i>range</i> l’ensemble des valeurs de la couverture.
+Mais la bibliothèque <abbr title="Network Common Data Form">NetCDF</abbr> de l’<abbr title="University Corporation for Atmospheric Research">UCAR</abbr>
+applique plutôt ces termes à la fonction convertissant les indices de pixels (son domaine) vers les coordonnées spatio-temporelles (son <i>range</i>).
+Ainsi, un <i>range</i> de la bibliothèque de l’<abbr>UCAR</abbr> peut être le domaine de <abbr>ISO</abbr> 19123.
+</p><p>
+La bibliothèque Apache <abbr title="Spatial Information System">SIS</abbr> privilégie autant que possible l’utilisation des termes dans le sens des normes <abbr title="Open Geospatial Consortium">OGC</abbr> et <abbr>ISO</abbr>.
+Mais un soin particulier doit être apporté aux interfaces entre <abbr>SIS</abbr> et certaines bibliothèques externes, afin de réduire les risques de confusions.
+</p>
+</section>
+<section>
+<header>
+<h1 id="GeoAPI"><span class="section-number">2.</span> GeoAPI</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Foreword">Chapitre suivant</a></div><div class="next-chapter"><a href="#XML-ISO">Chapitre précédent</a> ➡</div></div></nav>
+</header>
+<nav>Dans ce chapitre:<ul class="toc">
+<li><a href="#SpecificationToInterfaces">Des spécifications aux interfaces</a><ul>
+<li><a href="#UML-annotation">Correspondances explicitées par l’annotation @UML</a></li>
+<li><a href="#MappingToJDK">Correspondances implicites avec le JDK standard</a></li></ul></li>
+<li><a href="#ServiceLoader">Obtenir une implémentation des interfaces</a><ul>
+<li><a href="#GeoAPI-simple">Fournir sa propre implémentation</a></li></ul></li>
+<li><a href="#GeoAPI-modules">Les modules de GeoAPI</a><ul>
+<li><a href="#GeoAPI-core">Les modules de définition des interfaces</a></li>
+<li><a href="#GeoAPI-conformance">Le module de tests de conformité</a><ul>
+<li><a href="#GeoAPI-validators">Validations des instances</a></li>
+<li><a href="#GeoAPI-tests">Exécution des tests pré-définis</a></li></ul></li>
+<li><a href="#GeoAPI-examples">Les modules d’exemples</a></li></ul></li></ul></nav>
+<p>
+Le projet <a href="http://www.geoapi.org">GeoAPI</a> offre un ensemble d’interfaces Java pour les applications géo-spatiales.
+Dans une séries de paquets <code class="GeoAPI">org.opengis.*</code>, GeoAPI définit des structures représentant des méta-données,
+des systèmes de référence des coordonnées, ainsi que des opérations effectuant des projections cartographiques.
+Dans une partie qui n’est pas encore standardisée — dénommée <i>pending</i> — GeoAPI définit des structures
+représentant des images géo-référencées, des géométries, des filtres pouvant s’appliquer à des requêtes, et d’autres fonctionnalités.
+Ces interfaces suivent de très près les spécifications de l’<abbr title="Open Geospatial Consortium">OGC</abbr>, tout en les interprétant et en les adaptant
+de manière à répondre aux attentes des développeurs Java — par exemple en se conformant aux conventions de nommage.
+Ces interfaces bénéficient à la fois aux applications clientes et aux bibliothèques:
</p>
<ul>
- <li><p>
- Les développeurs des applications clientes bénéficient d’une plus grande base de connaissances disponible sur internet
- (due aux nombreuses publications en lien avec les standards de l’<abbr title="Open Geospatial Consortium">OGC</abbr>), ainsi que d’une interopérabilité accrue.
- L’interopérabilité est facilitée par une meilleure séparation entre les applications qui <em>appellent</em> les fonctions de GeoAPI,
- et les bibliothèques qui <em>implémentent</em> GeoAPI. Il s’agit d’une séparation similaire à celle qu’offrent les interfaces
- <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/"><abbr>JDBC</abbr></a> (<i>Java Database Connectivity</i>) du Java standard.
- En utilisant l’<abbr title="Application Programming Interface">API</abbr> des interfaces,
- les développeurs peuvent faire abstraction de l’implémentation sous-jacente.
- Par exemple ils peuvent effectuer des projections cartographiques à l’aide des bibliothèques
- <a href="http://www.geoapi.org/geoapi-proj4/index.html">Proj.4</a> ou Apache <abbr title="Spatial Information System">SIS</abbr>,
- sans changer leurs programmes lorsqu’ils changent de bibliothèque.
- </p></li>
- <li><p>
- Les développeurs des bibliothèques héritent de l’expertise des auteurs des spécifications, via les modèles que représentent les interfaces.
- GeoAPI fournit aussi un cadre dans lequel les développeurs peuvent implémenter en priorité les fonctionnalité qui leurs sont le plus nécessaires,
- tout en ayant des points où raccrocher les développements futurs.
- Par exemple les clients peuvent appeler une fonction de GeoAPI même si elle n’est pas encore supportée par la bibliothèque,
- quitte à obtenir une valeur nulle en attendant qu’une nouvelle version de la bibliothèque retourne une valeur intéressante.
- </p></li>
+<li><p>
+Les développeurs des applications clientes bénéficient d’une plus grande base de connaissances disponible sur internet
+(due aux nombreuses publications en lien avec les standards de l’<abbr>OGC</abbr>), ainsi que d’une interopérabilité accrue.
+L’interopérabilité est facilitée par une meilleure séparation entre les applications qui <em>appellent</em> les fonctions de GeoAPI,
+et les bibliothèques qui <em>implémentent</em> GeoAPI. Il s’agit d’une séparation similaire à celle qu’offrent les interfaces
+<a href="http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/"><abbr title="Java DataBase Connectivity">JDBC</abbr></a> (<i>Java Database Connectivity</i>) du Java standard.
+En utilisant l’<abbr title="Application Programming Interface">API</abbr> des interfaces, les développeurs peuvent faire abstraction de l’implémentation sous-jacente.
+Par exemple ils peuvent effectuer des projections cartographiques à l’aide des bibliothèques
+<a href="http://www.geoapi.org/geoapi-proj4/index.html">Proj.4</a> ou Apache <abbr title="Spatial Information System">SIS</abbr>,
+sans changer leurs programmes lorsqu’ils changent de bibliothèque.
+</p></li>
+<li><p>
+Les développeurs des bibliothèques héritent de l’expertise des auteurs des spécifications, via les modèles que représentent les interfaces.
+GeoAPI fournit aussi un cadre dans lequel les développeurs peuvent implémenter en priorité les fonctionnalité qui leurs sont le plus nécessaires,
+tout en ayant des points où raccrocher les développements futurs.
+Par exemple les clients peuvent appeler une fonction de GeoAPI même si elle n’est pas encore supportée par la bibliothèque,
+quitte à obtenir une valeur nulle en attendant qu’une nouvelle version de la bibliothèque retourne une valeur intéressante.
+</p></li>
</ul>
-<aside>
- <p><b>Historique</b></p>
- <p>
- En 2001, le consortium <i>Open GIS</i> (l’ancien nom du consortium <i>Open Geospatial</i>) publia la spécification d’implémentation
- <a href="http://www.opengeospatial.org/standards/ct"><abbr>OGC</abbr> 01-009: <cite>Coordinate Transformation Services</cite></a>.
- Cette spécification, élaborée par <i>Computer Aided Development Corporation</i> (Cadcorp), était accompagnée d’interfaces
- <abbr title="Component Object Model">COM</abbr>, <abbr title="Common Object Request Broker Architecture">CORBA</abbr> et Java.
- À cette époque, la vague des services web n’avait pas encore éclipsé les interfaces de programmation classiques.
- Les interfaces de l’<abbr title="Open Geospatial Consortium">OGC</abbr> anticipaient tout de même un monde connecté en réseau,
- mais misaient plutôt — dans le cas du Java — sur la technologie <abbr>RMI</abbr> (<i>Remote Method Invocation</i>).
- Bien que le projet GeoAPI n’existait pas encore, nous désignons rétrospectivement ces interfaces historiques sous le nom de
- « <a href="http://www.geoapi.org/0.1/index.html">GeoAPI 0.1</a> ».
- Ces interfaces utilisaient déjà le nom de paquet <code class="GeoAPI">org.opengis</code>, qui sera adopté par GeoAPI.
- </p><p>
- En 2002, des développeurs de projets libres ont lancé un <a href="http://web.archive.org/web/20030509104308/http://digitalearth.org/story/2002/10/10/55046/206">appel
- à la création d’un <abbr title="Application Programming Interface">API</abbr> géo-spatial</a>.
- La proposition initiale suscita l’intérêt d’au moins cinq projets libres.
- Le projet fut créé sur <a href="http://sourceforge.net/projects/geoapi/">SourceForge</a>,
- qui héberge depuis lors le code source dans un <a href="http://www.geoapi.org/source-repository.html">dépôt Subversion</a>.
- Le projet pris le nom de « GeoAPI » à ce moment là, et utilisa les interfaces de la spécification <abbr>OGC</abbr> 01-009 comme point de départ.
- </p><p>
- Quelques mois plus tard, l’<abbr title="Open Geospatial Consortium">OGC</abbr> lança le projet
- <a href="http://www.opengeospatial.org/standards/go"><abbr>GO-1</abbr>: <i>Geographic Objects</i></a>,
- qui poursuivait des buts similaires à ceux de GeoAPI.
- Entre-temps, l’<abbr>OGC</abbr> avait abandonné certaines de leur spécifications en faveur des normes <abbr title="International Organization for Standardization">ISO</abbr>.
- GeoAPI et <abbr>GO-1</abbr> ont joint leurs efforts pour une refonte des interfaces de GeoAPI en les basant sur ces nouvelles normes <abbr>ISO</abbr>.
- La première mouture, <a href="http://www.geoapi.org/1.0/index.html">GeoAPI 1.0</a>, a servit de point de départ
- aux premières ébauches de la spécification <abbr>OGC</abbr> 03-064 du groupe de travail <abbr>GO</abbr>-1.
- La version finale de cette spécification est devenue un standard <abbr>OGC</abbr> en 2005, et
- <a href="http://www.geoapi.org/2.0/index.html">GeoAPI 2.0</a> a été publiée à cette occasion.
- </p><p>
- Le projet <abbr>GO</abbr>-1 était porté essentiellement par une compagnie nommée <i>Polexis</i>.
- Son rachat par <i>Sys Technology</i> et le changement de priorité des nouveaux propriétaires
- ont causé l’arrêt des travaux de <abbr>GO</abbr>-1, et par ricochet un ralentissement des développements de GeoAPI.
- Afin de reprendre les développements, un nouveau groupe de travail « GeoAPI 3.0 » a été créé à l’<abbr title="Open Geospatial Consortium">OGC</abbr>.
- Ce groupe a réduit les ambitions par rapport à GeoAPI 2.0 en se concentrant sur les interfaces les plus stables,
- et en plaçant les autres — notamment les géométries — dans un module nommé « <a href="http://www.geoapi.org/geoapi-pending/index.html">pending</a> »,
- pour considérations futures. <a href="http://www.geoapi.org/3.0/index.html">GeoAPI 3.0</a> est devenu un
- <a href="http://www.opengeospatial.org/standards/geoapi">standard <abbr>OGC</abbr></a> en 2011.
- Cette version a été la première à être déployée dans le <a href="http://search.maven.org/#search|ga|1|geoapi">dépôt central de Maven</a>.
- </p>
-</aside>
-
-
-<h2 id="SpecificationToInterfaces">Des spécifications aux interfaces</h2>
-<p>
- Les standards de l’<abbr title="Open Geospatial Consortium">OGC</abbr> étant définis par des moyens bien éprouvés en génie logiciel,
- il est possible de générer automatiquement des interfaces Java à l’aide d’outils relativement répandus.
- Une des approches les plus utilisées est de transformer les <a href="http://schemas.opengis.net/gml/3.3/">schémas <abbr>XSD</abbr></a>
- en interfaces Java à l’aide de l’utilitaire en ligne de commande <code>xjc</code>.
- Cet utilitaire étant fournit avec la plupart des distributions du Java (il fait partie des outils de <a href="http://jaxb.java.net"><abbr>JAXB</abbr></a>),
- cette approche est choisie par plusieurs projets que l’on trouve sur internet.
- D’autres approches utilisent des outils intégrés à l’environnement de développement Eclipse,
- ou prennent comme point de départ les schémas <abbr title="Unified Modeling Language">UML</abbr>
- plutôt que <abbr title="XML Schema Definition">XSD</abbr>.
+<article>
+<header>
+<h1>Historique du projet GeoAPI</h1>
+</header>
+<p>
+En 2001, le consortium <i>Open GIS</i> (l’ancien nom du consortium <i>Open Geospatial</i>) publia la spécification d’implémentation
+<a href="http://www.opengeospatial.org/standards/ct"><abbr title="Open Geospatial Consortium">OGC</abbr> 01-009: <cite>Coordinate Transformation Services</cite></a>.
+Cette spécification, élaborée par <i>Computer Aided Development Corporation</i> (Cadcorp),
+était accompagnée d’interfaces <abbr title="Component Object Model">COM</abbr>, <abbr title="Common Object Request Broker Architecture">CORBA</abbr> et Java.
+À cette époque, la vague des services web n’avait pas encore éclipsé les interfaces de programmation classiques.
+Les interfaces de l’<abbr>OGC</abbr> anticipaient tout de même un monde connecté en réseau,
+mais misaient plutôt — dans le cas du Java — sur la technologie <abbr>RMI</abbr> (<i>Remote Method Invocation</i>).
+Bien que le projet GeoAPI n’existait pas encore, nous désignons rétrospectivement ces interfaces historiques sous le nom de
+« <a href="http://www.geoapi.org/0.1/index.html">GeoAPI 0.1</a> ».
+Ces interfaces utilisaient déjà le nom de paquet <code class="GeoAPI">org.opengis</code>, qui sera adopté par GeoAPI.
+</p><p>
+En 2002, des développeurs de projets libres ont lancé un
+<a href="http://web.archive.org/web/20030509104308/http://digitalearth.org/story/2002/10/10/55046/206">appel à la création d’un <abbr title="Application Programming Interface">API</abbr> géo-spatial</a>.
+La proposition initiale suscita l’intérêt d’au moins cinq projets libres.
+Le projet fut créé sur <a href="http://sourceforge.net/projects/geoapi/">SourceForge</a>,
+qui héberge depuis lors le code source dans un <a href="http://www.geoapi.org/source-repository.html">dépôt Subversion</a>.
+Le projet pris le nom de « GeoAPI » à ce moment là, et utilisa les interfaces de la spécification <abbr>OGC</abbr> 01-009 comme point de départ.
+</p><p>
+Quelques mois plus tard, l’<abbr>OGC</abbr> lança le projet
+<a href="http://www.opengeospatial.org/standards/go"><abbr>GO-1</abbr>: <i>Geographic Objects</i></a>,
+qui poursuivait des buts similaires à ceux de GeoAPI.
+Entre-temps, l’<abbr>OGC</abbr> avait abandonné certaines de leur spécifications en faveur des normes <abbr title="International Organization for Standardization">ISO</abbr>.
+GeoAPI et <abbr>GO-1</abbr> ont joint leurs efforts pour une refonte des interfaces de GeoAPI en les basant sur ces nouvelles normes <abbr>ISO</abbr>.
+La première mouture, <a href="http://www.geoapi.org/1.0/index.html">GeoAPI 1.0</a>, a servit de point de départ
+aux premières ébauches de la spécification <abbr>OGC</abbr> 03-064 du groupe de travail <abbr>GO</abbr>-1.
+La version finale de cette spécification est devenue un standard <abbr>OGC</abbr> en 2005, et
+<a href="http://www.geoapi.org/2.0/index.html">GeoAPI 2.0</a> a été publiée à cette occasion.
+</p><p>
+Le projet <abbr>GO</abbr>-1 était porté essentiellement par une compagnie nommée <i>Polexis</i>.
+Son rachat par <i>Sys Technology</i> et le changement de priorité des nouveaux propriétaires
+ont causé l’arrêt des travaux de <abbr>GO</abbr>-1, et par ricochet un ralentissement des développements de GeoAPI.
+Afin de reprendre les développements, un nouveau groupe de travail « GeoAPI 3.0 » a été créé à l’<abbr>OGC</abbr>.
+Ce groupe a réduit les ambitions par rapport à GeoAPI 2.0 en se concentrant sur les interfaces les plus stables,
+et en plaçant les autres — notamment les géométries — dans un module nommé « <a href="http://www.geoapi.org/geoapi-pending/index.html">pending</a> »,
+pour considérations futures. <a href="http://www.geoapi.org/3.0/index.html">GeoAPI 3.0</a> est devenu un
+<a href="http://www.opengeospatial.org/standards/geoapi">standard <abbr>OGC</abbr></a> en 2011.
+Cette version a été la première à être déployée dans le <a href="http://search.maven.org/#search|ga|1|geoapi">dépôt central de Maven</a>.
+</p>
+</article>
+
+
+<h2 id="SpecificationToInterfaces"><span class="section-number">2.1.</span> Des spécifications aux interfaces</h2>
+<p>
+Les standards de l’<abbr title="Open Geospatial Consortium">OGC</abbr> étant définis par des moyens bien éprouvés en génie logiciel,
+il est possible de générer automatiquement des interfaces Java à l’aide d’outils relativement répandus.
+Une des approches les plus utilisées est de transformer les <a href="http://schemas.opengis.net/gml/3.3/">schémas <abbr title="XML Schema Definition">XSD</abbr></a>
+en interfaces Java à l’aide de l’utilitaire en ligne de commande <code>xjc</code>.
+Cet utilitaire étant fournit avec la plupart des distributions du Java (il fait partie des outils de <a href="http://jaxb.java.net"><abbr>JAXB</abbr></a>),
+cette approche est choisie par plusieurs projets que l’on trouve sur internet.
+D’autres approches utilisent des outils intégrés à l’environnement de développement Eclipse,
+ou prennent comme point de départ les schémas <abbr title="Unified Modeling Language">UML</abbr> plutôt que <abbr>XSD</abbr>.
</p><p>
- Une approche similaire avait été tentée dans les débuts du projet GeoAPI, mais a été rapidement abandonnée.
- Nous avons privilégié une approche manuelle pour les raisons suivantes:
+Une approche similaire avait été tentée dans les débuts du projet GeoAPI, mais a été rapidement abandonnée.
+Nous avons privilégié une approche manuelle pour les raisons suivantes:
</p>
<ul>
- <li>
- <p>
- Certains schémas <abbr title="XML Schema Definition">XSD</abbr> sont beaucoup plus verbeux
- que les schémas <abbr title="Unified Modeling Language">UML</abbr> d’origines.
- Une conversion à partir des schémas <abbr>XSD</abbr> introduit, au moins dans le cas des méta-données,
- près du double du nombre d’interfaces réellement définies par le standard, sans que cela n’apporte de nouvelles fonctionnalités.
- Les schémas <abbr>XSD</abbr> définissent aussi des attributs propres aux documents <abbr>XML</abbr>
- (<code class="OGC">id</code>, <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>),
- qui n’existent pas dans les diagrammes <abbr>UML</abbr> originaux et que l’on ne souhaite pas forcément exposer
- dans un <abbr title="Application Programming Interface">API</abbr> Java.
- Une conversion à partir des schémas <abbr>UML</abbr> évite ce problème,
- mais les outils capable d’effectuer cette opération sont plus rares.
- </p>
- <div class="example"><p><b>Exemple:</b>
- Les schémas <abbr title="XML Schema Definition">XSD</abbr> des méta-données insèrent
- un élément <code class="OGC"><gmd:CI_Citation></code> à l’intérieur de <code class="OGC"><gmd:citation></code>,
- un élément <code class="OGC"><gmd:CI_OnlineResource></code> à l’intérieur de <code class="OGC"><gmd:onlineResource></code>,
- et ainsi de suite pour la centaine de classes définies dans le standard <abbr>ISO</abbr> 19115.
- Cette redondance n’est absolument pas nécessaire à un programme Java.
- </p></div>
- </li>
- <li>
- <p>
- Les standards de l’<abbr title="Open Geospatial Consortium">OGC</abbr> utilisent des conventions de nommage qui sont différentes de celles du Java.
- En particulier les noms de presque toutes les classes de l’<abbr>OGC</abbr> commencent par un préfixe de deux lettres,
- comme dans <code class="OGC">MD_Identifier</code>. Ces préfixes jouent le même rôle que les noms de paquets en Java.
- GeoAPI adapte cette pratique en utilisant des noms d’interfaces sans préfixes,
- et en plaçant ces interfaces dans des paquets correspondants aux préfixes mais avec des noms plus descriptifs.
- Occasionnellement nous changeons aussi les noms, par exemple pour éviter des acronymes
- ou pour se conformer à une convention établie telle que <i>Java beans</i>.
- </p>
- <div class="example"><p><b>Exemple:</b>
- la classe <code class="OGC">MD_Identifier</code> de l’<abbr title="Open Geospatial Consortium">OGC</abbr> devient
- l’interface <code class="GeoAPI">Identifier</code> dans le paquet <code class="GeoAPI">org.opengis.metadata</code>.
- La classe <code class="OGC">SC_CRS</code> de l’<abbr>OGC</abbr> devient l’interface <code class="GeoAPI">CoordinateReferenceSystem</code>,
- et l’association <code class="OGC">usesDatum</code> devient une méthode <code class="GeoAPI">getDatum()</code> — et non pas
- « <code>getUsesDatum()</code> » comme aurait fait un outil de conversion automatique.
- Nous ne laissons pas des programmes appliquer aveuglement des règles qui ignorent les conventions de la communauté dont on traduit les schémas.
- </p></div>
- </li>
- <li>
- <p>
- Les standards contiennent parfois des structures qui n’ont pas d’équivalent direct en Java,
- notamment les unions telles qu’on peut trouver en C/C++.
- La stratégie employée pour obtenir une fonctionnalité équivalente en Java dépend du contexte:
- multi-héritage des interfaces, modification de la hiérarchie ou simplement omettre l’union.
- Les décisions se font au cas-par-cas en fonction de l’analyse des besoins.
- </p>
- <div class="example"><p><b>Exemple:</b>
- Le standard <abbr>ISO</abbr> 19111 définit différents types de systèmes de coordonnées, tels que sphérique, cylindrique, polaire ou cartésien.
- Puis, il définit différents <em>sous-ensembles</em> de ces types de systèmes de coordonnées.
- Ces sous-ensembles, représentés par des unions, servent à spécifier qu’une classe peut être associée à seulement tel ou tel type de système de coordonnées.
- Par exemple l’union des types pouvant être associés à une image, nommée <code class="OGC">CS_ImageCS</code>,
- ne contient que <code class="OGC">CS_CartesianCS</code> et <code class="OGC">CS_AffineCS</code>.
- Dans ce cas particulier, nous obtenons en Java l’effet souhaité par une modification de la hiérarchie des classes:
- nous définissons l’interface <code class="GeoAPI">CartesianCS</code> comme une spécialisation de <code class="GeoAPI">AffineCS</code>, ce qui est sémantiquement correct.
- Mais il n’est pas possible d’appliquer une stratégie similaire pour les autres unions sans violer la sémantique.
- </p></div>
- </li>
- <li>
- <p>
- Plusieurs spécifications se chevauchent. GeoAPI effectue un travail d’intégration en remplaçant certaines
- structures qui font doublons par des références vers les structures équivalentes du standard qui les définies le mieux.
- </p>
- <div class="example"><p><b>Exemple:</b>
- Le standard <abbr>ISO</abbr> 19115, qui définit des structures de méta-données, s’aventure aussi à décrire quelques
- structures représentant les systèmes de références des coordonnées (<abbr title="Coordinate Reference System">CRS</abbr>).
- Or ces derniers sont le sujet à part entière d’un autre standard: <abbr>ISO</abbr> 19111.
- D’ailleurs le standard <abbr>ISO</abbr> 19111:2007 stipule, dans sa section 3, qu’il réutilise tous les éléments
- de <abbr>ISO</abbr> 19115 à l’exclusion de <code class="OGC">MD_CRS</code> et de ses composantes.
- Les interfaces de GeoAPI réduisent la redondance en appliquant à l’ensemble du projet l’exclusion recommandée par <abbr>ISO</abbr> 19111.
- </p></div>
- </li>
- <li>
- <p>
- Certains standards ont vu leur complexité s’accroître pour des raisons historiques plutôt que techniques,
- liées au processus de standardisation. GeoAPI réduit la dette technique en concevant les interfaces comme
- si chaque élément avait pu être intégré à sa place, sans les contraintes liées à l’ordre chronologique
- dans lequel les standards ont été publiés.
- </p>
- <div class="example"><p><b>Exemple:</b>
- Le standard <abbr>ISO</abbr> 19115-2 est une extension du standard <abbr>ISO</abbr> 19115-1 ajoutant des structures de méta-données d’images.
- Ces méta-données ont été définies dans un standard séparé parce qu’elles n’ont pas été prêtes à temps pour la publication de la première partie du standard.
- Comme il n’était pas possible, pour des raisons administratives, d’ajouter des attributs dans les classes déjà publiées,
- les nouveaux attributs ont été ajoutées dans une sous-classe portant quasiment le même nom.
- Ainsi, le standard <abbr>ISO</abbr> 19115-2 définit une classe <code class="OGC">MI_Band</code> qui étend la
- classe <code class="OGC">MD_Band</code> du standard <abbr>ISO</abbr> 19115-1 en y ajoutant les attributs qui
- auraient dû apparaître directement dans la classe parente s’ils avaient été prêts à temps.
- Dans GeoAPI, nous avons choisis de « réparer » ces anomalies en fusionnant ces deux classes en une seule interface.
- </p></div>
- </li>
+<li>
+<p>
+Certains schémas <abbr>XSD</abbr> sont beaucoup plus verbeux que les schémas <abbr>UML</abbr> d’origines.
+Une conversion à partir des schémas <abbr>XSD</abbr> introduit, au moins dans le cas des méta-données,
+près du double du nombre d’interfaces réellement définies par le standard, sans que cela n’apporte de nouvelles fonctionnalités.
+Les schémas <abbr>XSD</abbr> définissent aussi des attributs propres aux documents <abbr>XML</abbr>
+(<code class="OGC">id</code>, <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>),
+qui n’existent pas dans les diagrammes <abbr>UML</abbr> originaux et que l’on ne souhaite pas forcément exposer dans un <abbr title="Application Programming Interface">API</abbr> Java.
+Une conversion à partir des schémas <abbr>UML</abbr> évite ce problème, mais les outils capable d’effectuer cette opération sont plus rares.
+</p>
+<div class="example"><p><b>Exemple:</b>
+Les schémas <abbr>XSD</abbr> des méta-données insèrent
+un élément <code class="OGC"><gmd:CI_Citation></code> à l’intérieur de <code class="OGC"><gmd:citation></code>,
+un élément <code class="OGC"><gmd:CI_OnlineResource></code> à l’intérieur de <code class="OGC"><gmd:onlineResource></code>,
+et ainsi de suite pour la centaine de classes définies dans le standard <abbr title="International Organization for Standardization">ISO</abbr> 19115.
+Cette redondance n’est absolument pas nécessaire à un programme Java.
+</p></div>
+</li>
+<li>
+<p>
+Les standards de l’<abbr>OGC</abbr> utilisent des conventions de nommage qui sont différentes de celles du Java.
+En particulier les noms de presque toutes les classes de l’<abbr>OGC</abbr> commencent par un préfixe de deux lettres,
+comme dans <code class="OGC">MD_Identifier</code>. Ces préfixes jouent le même rôle que les noms de paquets en Java.
+GeoAPI adapte cette pratique en utilisant des noms d’interfaces sans préfixes,
+et en plaçant ces interfaces dans des paquets correspondants aux préfixes mais avec des noms plus descriptifs.
+Occasionnellement nous changeons aussi les noms, par exemple pour éviter des acronymes
+ou pour se conformer à une convention établie telle que <i>Java beans</i>.
+</p>
+<div class="example"><p><b>Exemple:</b>
+la classe <code class="OGC">MD_Identifier</code> de l’<abbr>OGC</abbr> devient
+l’interface <code class="GeoAPI">Identifier</code> dans le paquet <code class="GeoAPI">org.opengis.metadata</code>.
+La classe <code class="OGC">SC_CRS</code> de l’<abbr>OGC</abbr> devient l’interface <code class="GeoAPI">CoordinateReferenceSystem</code>,
+et l’association <code class="OGC">usesDatum</code> devient une méthode <code class="GeoAPI">getDatum()</code> — et non pas
+« <code>getUsesDatum()</code> » comme aurait fait un outil de conversion automatique.
+Nous ne laissons pas des programmes appliquer aveuglement des règles qui ignorent les conventions de la communauté dont on traduit les schémas.
+</p></div>
+</li>
+<li>
+<p>
+Les standards contiennent parfois des structures qui n’ont pas d’équivalent direct en Java,
+notamment les unions telles qu’on peut trouver en C/C++.
+La stratégie employée pour obtenir une fonctionnalité équivalente en Java dépend du contexte:
+multi-héritage des interfaces, modification de la hiérarchie ou simplement omettre l’union.
+Les décisions se font au cas-par-cas en fonction de l’analyse des besoins.
+</p>
+<div class="example"><p><b>Exemple:</b>
+Le standard <abbr>ISO</abbr> 19111 définit différents types de systèmes de coordonnées, tels que sphérique, cylindrique, polaire ou cartésien.
+Puis, il définit différents <em>sous-ensembles</em> de ces types de systèmes de coordonnées.
+Ces sous-ensembles, représentés par des unions, servent à spécifier qu’une classe peut être associée à seulement tel ou tel type de système de coordonnées.
+Par exemple l’union des types pouvant être associés à une image, nommée <code class="OGC">CS_ImageCS</code>,
+ne contient que <code class="OGC">CS_CartesianCS</code> et <code class="OGC">CS_AffineCS</code>.
+Dans ce cas particulier, nous obtenons en Java l’effet souhaité par une modification de la hiérarchie des classes:
+nous définissons l’interface <code class="GeoAPI">CartesianCS</code> comme une spécialisation de <code class="GeoAPI">AffineCS</code>, ce qui est sémantiquement correct.
+Mais il n’est pas possible d’appliquer une stratégie similaire pour les autres unions sans violer la sémantique.
+</p></div>
+</li>
+<li>
+<p>
+Plusieurs spécifications se chevauchent. GeoAPI effectue un travail d’intégration en remplaçant certaines
+structures qui font doublons par des références vers les structures équivalentes du standard qui les définies le mieux.
+</p>
+<div class="example"><p><b>Exemple:</b>
+Le standard <abbr>ISO</abbr> 19115, qui définit des structures de méta-données, s’aventure aussi à décrire quelques
+structures représentant les systèmes de références des coordonnées (<abbr title="Coordinate Reference System">CRS</abbr>).
+Or ces derniers sont le sujet à part entière d’un autre standard: <abbr>ISO</abbr> 19111.
+D’ailleurs le standard <abbr>ISO</abbr> 19111:2007 stipule, dans sa section 3, qu’il réutilise tous les éléments
+de <abbr>ISO</abbr> 19115 à l’exclusion de <code class="OGC">MD_CRS</code> et de ses composantes.
+Les interfaces de GeoAPI réduisent la redondance en appliquant à l’ensemble du projet l’exclusion recommandée par <abbr>ISO</abbr> 19111.
+</p></div>
+</li>
+<li>
+<p>
+Certains standards ont vu leur complexité s’accroître pour des raisons historiques plutôt que techniques,
+liées au processus de standardisation. GeoAPI réduit la dette technique en concevant les interfaces comme
+si chaque élément avait pu être intégré à sa place, sans les contraintes liées à l’ordre chronologique
+dans lequel les standards ont été publiés.
+</p>
+<div class="example"><p><b>Exemple:</b>
+Le standard <abbr>ISO</abbr> 19115-2 est une extension du standard <abbr>ISO</abbr> 19115-1 ajoutant des structures de méta-données d’images.
+Ces méta-données ont été définies dans un standard séparé parce qu’elles n’ont pas été prêtes à temps pour la publication de la première partie du standard.
+Comme il n’était pas possible, pour des raisons administratives, d’ajouter des attributs dans les classes déjà publiées,
+les nouveaux attributs ont été ajoutées dans une sous-classe portant quasiment le même nom.
+Ainsi, le standard <abbr>ISO</abbr> 19115-2 définit une classe <code class="OGC">MI_Band</code> qui étend la
+classe <code class="OGC">MD_Band</code> du standard <abbr>ISO</abbr> 19115-1 en y ajoutant les attributs qui
+auraient dû apparaître directement dans la classe parente s’ils avaient été prêts à temps.
+Dans GeoAPI, nous avons choisis de « réparer » ces anomalies en fusionnant ces deux classes en une seule interface.
+</p></div>
+</li>
</ul>
<p>
- Les écarts par rapport aux normes sont documentés dans chaque classe et chaque méthode concernées.
- Chaque mention d’un écart est aussi recopiée dans <a href="http://www.geoapi.org/3.0/javadoc/departures.html">une page unique</a>,
- pour donner une vue d’ensemble.
- Étant donné que ces écarts brouillent les liens qui existent entre les standards et certaines interfaces Java,
- la correspondance entre ces langages est explicitée par des annotations <code class="GeoAPI">@UML</code>
- et des fichiers de propriétés, décrits dans la section suivante.
+Les écarts par rapport aux normes sont documentés dans chaque classe et chaque méthode concernées.
+Chaque mention d’un écart est aussi recopiée dans <a href="http://www.geoapi.org/3.0/javadoc/departures.html">une page unique</a>,
+pour donner une vue d’ensemble.
+Étant donné que ces écarts brouillent les liens qui existent entre les standards et certaines interfaces Java,
+la correspondance entre ces langages est explicitée par des annotations <code class="GeoAPI">@UML</code>
+et des fichiers de propriétés, décrits dans la section suivante.
</p>
-<h3 id="UML-annotation">Correspondances explicitées par l’annotation <code>@UML</code></h3>
+<h3 id="UML-annotation"><span class="section-number">2.1.1.</span> Correspondances explicitées par l’annotation <code class="GeoAPI">@UML</code></h3>
<p>
- Pour chaque classe, méthode et constante définie à partir d’un standard <abbr title="Open Geospatial Consortium">OGC</abbr> ou
- <abbr title="International Organization for Standardization">ISO</abbr>, GeoAPI indique sa provenance à l’aide d’annotations
- définies dans le paquet <code class="GeoAPI">org.opengis.annotation</code>.
- En particulier l’annotation <code class="GeoAPI">@UML</code> indique le standard,
- le nom de l’élément dans ce standard ainsi que son niveau d’obligation.
- Par exemple dans l’extrait de code suivant, la première annotation <code class="GeoAPI">@UML</code> indique
- que l’interface Java qui la suit (<code class="GeoAPI">ProjectedCRS</code>) est définie à partir du type
- <code class="OGC">SC_ProjectedCRS</code> du standard <abbr>ISO</abbr> 19111.
- La seconde annotation <code class="GeoAPI">@UML</code>, appliquée cette fois à la méthode
- <code class="GeoAPI">getCoordinateSystem()</code>, indique que la méthode est définie
- à partir de l’association <code class="OGC">coordinateSystem</code> du standard <abbr>ISO</abbr> 19111,
- et que cette association est obligatoire — ce qui, traduit en Java, signifie que la méthode n’est
- pas autorisée à retourner la valeur <code>null</code>.
+Pour chaque classe, méthode et constante définie à partir d’un standard <abbr title="Open Geospatial Consortium">OGC</abbr> ou <abbr title="International Organization for Standardization">ISO</abbr>,
+GeoAPI indique sa provenance à l’aide d’annotations définies dans le paquet <code class="GeoAPI">org.opengis.annotation</code>.
+En particulier l’annotation <code class="GeoAPI">@UML</code> indique le standard,
+le nom de l’élément dans ce standard ainsi que son niveau d’obligation.
+Par exemple dans l’extrait de code suivant, la première annotation <code class="GeoAPI">@UML</code> indique
+que l’interface Java qui la suit (<code class="GeoAPI">ProjectedCRS</code>) est définie à partir du type
+<code class="OGC">SC_ProjectedCRS</code> du standard <abbr>ISO</abbr> 19111.
+La seconde annotation <code class="GeoAPI">@UML</code>, appliquée cette fois à la méthode
+<code class="GeoAPI">getCoordinateSystem()</code>, indique que la méthode est définie
+à partir de l’association <code class="OGC">coordinateSystem</code> du standard <abbr>ISO</abbr> 19111,
+et que cette association est obligatoire — ce qui, traduit en Java, signifie que la méthode n’est
+pas autorisée à retourner la valeur <code>null</code>.
</p>
<pre><b>package</b> <code class="GeoAPI">org.opengis.referencing.crs</code>;
-<code class="comment">
-/**
+
+<code class="comment">/**
* A 2D coordinate reference system used to approximate the shape of the earth on a planar surface.
*/</code>
-<code class="GeoAPI">@UML</code>(<var>specification</var> = ISO_19111,
- <var>identifier</var> = "<code class="OGC">SC_ProjectedCRS</code>")
-<b>public interface</b> <code class="GeoAPI">ProjectedCRS</code> <b>extends</b> <code class="GeoAPI">GeneralDerivedCRS</code> {<code class="comment">
- /**
+@<code class="GeoAPI">UML</code>(specification = ISO_19111,
+ identifier = <i>"<code class="OGC">SC_ProjectedCRS</code>"</i>)
+<b>public</b> <b>interface</b> <code class="GeoAPI">ProjectedCRS</code> <b>extends</b> <code class="GeoAPI">GeneralDerivedCRS</code> {
+ <code class="comment">/**
* Returns the coordinate system, which must be Cartesian.
*/</code>
- <code class="GeoAPI">@UML</code>(<var>obligation</var> = MANDATORY,
- <var>specification</var> = ISO_19111,
- <var>identifier</var> = "<code class="OGC">coordinateSystem</code>")
- <code class="GeoAPI">CartesianCS getCoordinateSystem()</code>;
+ @<code class="GeoAPI">UML</code>(obligation = MANDATORY,
+ specification = ISO_19111,
+ identifier = <i>"<code class="OGC">coordinateSystem</code>"</i>)
+ <code class="GeoAPI">CartesianCS</code> <code class="GeoAPI">getCoordinateSystem()</code>;
}</pre>
<p>
- Les méthodes d’introspections du Java permettent d’accéder à ces informations pendant l’exécution d’une application.
- C’est utile pour obtenir les noms à afficher à des utilisateurs familiers avec les normes de l’<abbr title="Open Geospatial Consortium">OGC</abbr>,
- ou pour écrire des éléments dans un document <abbr>XML</abbr>. L’exemple suivant affiche le nom standard de la
- méthode <code class="GeoAPI">getTitle()</code> de l’interface <code class="GeoAPI">Citation</code>:
+Les méthodes d’introspections du Java permettent d’accéder à ces informations pendant l’exécution d’une application.
+C’est utile pour obtenir les noms à afficher à des utilisateurs familiers avec les normes de l’<abbr>OGC</abbr>,
+ou pour écrire des éléments dans un document <abbr>XML</abbr>. L’exemple suivant affiche le nom standard de la
+méthode <code class="GeoAPI">getTitle()</code> de l’interface <code class="GeoAPI">Citation</code>:
</p>
-<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>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>
+<pre>Class<?> type = <code class="GeoAPI">Citation</code>.<b>class</b>;
+Method method = type.getMethod(<i>"<code class="GeoAPI">getTitle</code>"</i>, (Class<?>[]) <b>null</b>);
+<code class="GeoAPI">UML</code> annot = method.getAnnotation(<code class="GeoAPI">UML</code>.<b>class</b>);
+String id = annot.identifier();
+System.out.println(<i>"Le nom standard de la méthode "</i> + method.getName() + <i>" est "</i> + id);</pre>
<p>
- La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit la méthode de commodité
- <code class="SIS">getStandardName(Class)</code> pour effectuer cette opération.
+La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit la méthode de commodité
+<code class="SIS">getStandardName(Class)</code> pour effectuer cette opération.
</p>
<p>
- L’opération inverse — obtenir la classe et méthode Java d’un nom standard — est un peu plus lourde.
- Elle nécessite la lecture du fichier <code class="GeoAPI">class-index.properties</code> fournit dans le
- paquet <code class="GeoAPI">org.opengis.annotation</code>. L’exemple suivant lit ce fichier juste avant
- de rechercher le nom de l’interface correspondant à <code class="OGC">CI_Citation</code>.
- Toutefois les utilisateurs sont encouragés à ne lire ce fichier qu’une fois et de conserver son contenu dans
- une cache de leur application.
+L’opération inverse — obtenir la classe et méthode Java d’un nom standard — est un peu plus lourde.
+Elle nécessite la lecture du fichier <code class="GeoAPI">class-index.properties</code> fournit dans le
+paquet <code class="GeoAPI">org.opengis.annotation</code>. L’exemple suivant lit ce fichier juste avant
+de rechercher le nom de l’interface correspondant à <code class="OGC">CI_Citation</code>.
+Toutefois les utilisateurs sont encouragés à ne lire ce fichier qu’une fois et de conserver son contenu dans
+une cache de leur application.
</p>
-<pre>Properties <var>isoToGeoAPI</var> = <b>new</b> Properties();
-<b>try</b> (InputStream in = <code class="GeoAPI">UML</code>.class.getResourceAsStream("<code class="GeoAPI">class-index.properties</code>")) {
- <var>isoToGeoAPI</var>.load(in);
+<pre>Properties isoToGeoAPI = <b>new</b> Properties();
+<b>try</b> (InputStream in = <code class="GeoAPI">UML</code>.<b>class</b>.getResourceAsStream(<i>"<code class="GeoAPI">class-index.properties</code>"</i>)) {
+ isoToGeoAPI.load(in);
}
-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 pour le type <abbr>ISO</abbr> " + <var>isoName</var> + " est " + <var>type</var>);</pre>
+String isoName = <i>"<code class="OGC">CI_Citation</code>"</i>;
+String geoName = getProperty(isoName);
+Class<?> type = Class.forName(geoName);
+System.out.println(<i>"L’interface GeoAPI pour le type <abbr>ISO</abbr> "</i> + isoName + <i>" est "</i> + type);</pre>
<p>
- La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit la méthode de commodité
- <code class="SIS">forStandardName(String)</code> pour effectuer cette opération.
+La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit la méthode de commodité
+<code class="SIS">forStandardName(String)</code> pour effectuer cette opération.
</p>
-<h3 id="MappingToJDK">Correspondances implicites avec le <abbr>JDK</abbr> standard</h3>
+<h3 id="MappingToJDK"><span class="section-number">2.1.2.</span> Correspondances implicites avec le <abbr>JDK</abbr> standard</h3>
<p>
- Certaines classes et méthodes n’ont ni annotation <code class="GeoAPI">@UML</code>,
- ni entrée dans le fichier <code class="GeoAPI">class-index.properties</code>.
- Il s’agit soit d’extensions de GeoAPI, ou soit de types définis dans d’autres bibliothèques,
- notamment le <abbr title="Java Development Kit">JDK</abbr> standard.
- Pour ce dernier cas, la correspondance avec les standards <abbr title="International Organization for Standardization">ISO</abbr> est implicite.
- Le tableau suivant décrit cette correspondance pour les types de la norme <abbr>ISO</abbr> 19103.
- Les types primitifs du Java standard sont préférés lorsqu’ils sont applicables,
- mais parfois leurs équivalents sous forme d’objets sont employés lorsqu’il est nécessaire d’autoriser des valeurs nulles.
+Certaines classes et méthodes n’ont ni annotation <code class="GeoAPI">@UML</code>,
+ni entrée dans le fichier <code class="GeoAPI">class-index.properties</code>.
+Il s’agit soit d’extensions de GeoAPI, ou soit de types définis dans d’autres bibliothèques,
+notamment le <abbr title="Java Development Kit">JDK</abbr> standard.
+Pour ce dernier cas, la correspondance avec les standards <abbr title="International Organization for Standardization">ISO</abbr> est implicite.
+Le tableau suivant décrit cette correspondance pour les types de la norme <abbr>ISO</abbr> 19103.
+Les types primitifs du Java standard sont préférés lorsqu’ils sont applicables,
+mais parfois leurs équivalents sous forme d’objets sont employés lorsqu’il est nécessaire d’autoriser des valeurs nulles.
</p>
<table>
- <caption>Correspondances entre <abbr>ISO</abbr> 19103 et <abbr>JDK</abbr></caption>
- <tr>
- <th>Type <abbr>ISO</abbr></th>
- <th>Type <abbr>JDK</abbr></th>
- <th>Remarques</th>
- </tr>
- <tr>
- <td class="separator" colspan="2">Nombres</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Integer</code></td>
- <td><code>int</code></td>
- <td class="leftBorder">Parfois <code>java.lang.Integer</code> pour les attributs optionnels.</td>
- </tr>
- <tr>
- <td><code class="OGC">Integer</code> (certains cas)</td>
- <td><code>long</code></td>
- <td class="leftBorder">Parfois <code>java.lang.Long</code> pour les attributs optionnels.</td>
- </tr>
- <tr>
- <td><code class="OGC">Real</code></td>
- <td><code>double</code></td>
- <td class="leftBorder">Parfois <code>java.lang.Double</code> pour les attributs optionnels.</td>
- </tr>
- <tr>
- <td><code class="OGC">Decimal</code></td>
- <td><code>java.math.BigDecimal</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Number</code></td>
- <td><code>java.lang.Number</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Textes</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">FreeText</code></td>
- <td>(pas d’équivalent)</td>
- <td class="leftBorder">Voir <code class="GeoAPI">org.opengis.util.InternationalString</code> ci-dessous.</td>
- </tr>
- <tr>
- <td><code class="OGC">CharacterString</code></td>
- <td><code>java.lang.String</code></td>
- <td class="leftBorder">Souvent <code class="GeoAPI">org.opengis.util.InternationalString</code> (voir ci-dessous).</td>
- </tr>
- <tr>
- <td><code class="OGC">LocalisedCharacterString</code></td>
- <td><code>java.lang.String</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Sequence<Character></code></td>
- <td><code>java.lang.CharSequence</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Character</code></td>
- <td><code>char</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Dates et heures</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Date</code></td>
- <td><code>java.util.Date</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Time</code></td>
- <td><code>java.util.Date</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">DateTime</code></td>
- <td><code>java.util.Date</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Collections</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Collection</code></td>
- <td><code>java.util.Collection</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Bag</code></td>
- <td><code>java.util.Collection</code></td>
- <td class="leftBorder">Un <code class="OGC">Bag</code> est similaire à un
- <code class="OGC">Set</code> sans la restriction d’unicité.</td>
- </tr>
- <tr>
- <td><code class="OGC">Set</code></td>
- <td><code>java.util.Set</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Sequence</code></td>
- <td><code>java.util.List</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Dictionary</code></td>
- <td><code>java.util.Map</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">KeyValuePair</code></td>
- <td><code>java.util.Map.Entry</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Énumérations</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Enumeration</code></td>
- <td><code>java.lang.Enum</code></td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">CodeList</code></td>
- <td>(pas d’équivalent)</td>
- <td class="leftBorder">Voir <code class="GeoAPI">org.opengis.util.CodeList</code> ci-dessous.</td>
- </tr>
- <tr>
- <td class="separator" colspan="2">Divers</td>
- <td class="leftBorder"></td>
- </tr>
- <tr>
- <td><code class="OGC">Boolean</code></td>
- <td><code>boolean</code></td>
- <td class="leftBorder">Parfois <code>java.lang.Boolean</code> pour les attributs optionnels.</td>
- </tr>
- <tr>
- <td><code class="OGC">Any</code></td>
- <td><code>java.lang.Object</code></td>
- <td class="leftBorder"></td>
- </tr>
+<caption>Correspondances entre <abbr>ISO</abbr> 19103 et <abbr>JDK</abbr></caption>
+<tr>
+<th>Type <abbr>ISO</abbr></th>
+<th>Type <abbr>JDK</abbr></th>
+<th>Remarques</th>
+</tr>
+<tr>
+<td class="separator" colspan="2">Nombres</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Integer</code></td>
+<td><code>int</code></td>
+<td class="leftBorder">Parfois <code>java.lang.Integer</code> pour les attributs optionnels.</td>
+</tr>
+<tr>
+<td><code class="OGC">Integer</code> (certains cas)</td>
+<td><code>long</code></td>
+<td class="leftBorder">Parfois <code>java.lang.Long</code> pour les attributs optionnels.</td>
+</tr>
+<tr>
+<td><code class="OGC">Real</code></td>
+<td><code>double</code></td>
+<td class="leftBorder">Parfois <code>java.lang.Double</code> pour les attributs optionnels.</td>
+</tr>
+<tr>
+<td><code class="OGC">Decimal</code></td>
+<td><code>java.math.BigDecimal</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Number</code></td>
+<td><code>java.lang.Number</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td class="separator" colspan="2">Textes</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">FreeText</code></td>
+<td>(pas d’équivalent)</td>
+<td class="leftBorder">Voir <code class="GeoAPI">org.opengis.util.InternationalString</code> ci-dessous.</td>
+</tr>
+<tr>
+<td><code class="OGC">CharacterString</code></td>
+<td><code>java.lang.String</code></td>
+<td class="leftBorder">Souvent <code class="GeoAPI">org.opengis.util.InternationalString</code> (voir ci-dessous).</td>
+</tr>
+<tr>
+<td><code class="OGC">LocalisedCharacterString</code></td>
+<td><code>java.lang.String</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Sequence<Character></code></td>
+<td><code>java.lang.CharSequence</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Character</code></td>
+<td><code>char</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td class="separator" colspan="2">Dates et heures</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Date</code></td>
+<td><code>java.util.Date</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Time</code></td>
+<td><code>java.util.Date</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">DateTime</code></td>
+<td><code>java.util.Date</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td class="separator" colspan="2">Collections</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Collection</code></td>
+<td><code>java.util.Collection</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Bag</code></td>
+<td><code>java.util.Collection</code></td>
+<td class="leftBorder">Un <code class="OGC">Bag</code> est similaire à un
+<code class="OGC">Set</code> sans la restriction d’unicité.</td>
+</tr>
+<tr>
+<td><code class="OGC">Set</code></td>
+<td><code>java.util.Set</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Sequence</code></td>
+<td><code>java.util.List</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Dictionary</code></td>
+<td><code>java.util.Map</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">KeyValuePair</code></td>
+<td><code>java.util.Map.Entry</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td class="separator" colspan="2">Énumérations</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Enumeration</code></td>
+<td><code>java.lang.Enum</code></td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">CodeList</code></td>
+<td>(pas d’équivalent)</td>
+<td class="leftBorder">Voir <code class="GeoAPI">org.opengis.util.CodeList</code> ci-dessous.</td>
+</tr>
+<tr>
+<td class="separator" colspan="2">Divers</td>
+<td class="leftBorder"/>
+</tr>
+<tr>
+<td><code class="OGC">Boolean</code></td>
+<td><code>boolean</code></td>
+<td class="leftBorder">Parfois <code>java.lang.Boolean</code> pour les attributs optionnels.</td>
+</tr>
+<tr>
+<td><code class="OGC">Any</code></td>
+<td><code>java.lang.Object</code></td>
+<td class="leftBorder"/>
+</tr>
</table>
<p>
- L’équivalent le plus direct de <code class="OGC">CharacterString</code> est la classe <code>String</code>,
- mais GeoAPI emploie souvent l’interface <code class="GeoAPI">InternationalString</code> pour permettre au client de choisir la langue.
- C’est utile par exemple sur un serveur fournissant simultanément des pages dans plusieurs langues.
- En reportant les traductions à l’utilisation des objets plutôt qu’au moment de leur création, on permet à la bibliothèque
- <abbr title="Spatial Information System">SIS</abbr> de fournir les mêmes instances de <code class="GeoAPI">Metadata</code>
- ou <code class="GeoAPI">Coverage</code> (par exemple) pour les mêmes données peu importe la langue du client.
- Les traductions peuvent être faites à la volée à l’aide d’un <code>ResourceBundle</code> de l’application,
- ou être fournies directement avec les données (cas des <code class="GeoAPI">Metadata</code> notamment).
+L’équivalent le plus direct de <code class="OGC">CharacterString</code> est la classe <code>String</code>,
+mais GeoAPI emploie souvent l’interface <code class="GeoAPI">InternationalString</code> pour permettre au client de choisir la langue.
+C’est utile par exemple sur un serveur fournissant simultanément des pages dans plusieurs langues.
+En reportant les traductions à l’utilisation des objets plutôt qu’au moment de leur création, on permet à la bibliothèque
+<abbr title="Spatial Information System">SIS</abbr> de fournir les mêmes instances de <code class="GeoAPI">Metadata</code>
+ou <code class="GeoAPI">Coverage</code> (par exemple) pour les mêmes données peu importe la langue du client.
+Les traductions peuvent être faites à la volée à l’aide d’un <code>ResourceBundle</code> de l’application,
+ou être fournies directement avec les données (cas des <code class="GeoAPI">Metadata</code> notamment).
</p>
<p>
- Les <code class="OGC">Enumeration</code> correspondent aux <code>Enum</code> du Java.
- Ils ont en commun de définir toutes les valeurs autorisées, sans permettre à l’utilisateur d’en ajouter.
- Les <code class="OGC">CodeList</code> sont similaires à ces énumérations, excepté que les utilisateurs peuvent y ajouter leurs propres éléments.
- 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éeront de nouvelles instances si le nom donné ne correspond pas au nom d’une instance existante.
+Les <code class="OGC">Enumeration</code> correspondent aux <code>Enum</code> du Java.
+Ils ont en commun de définir toutes les valeurs autorisées, sans permettre à l’utilisateur d’en ajouter.
+Les <code class="OGC">CodeList</code> sont similaires à ces énumérations, excepté que les utilisateurs peuvent y ajouter leurs propres éléments.
+Le <abbr>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é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>
-<code class="GeoAPI">MediumName</code> <var>usbKey</var> = <code class="GeoAPI">MediumName.valueOf</code>("<code class="GeoAPI">USB_KEY</code>"); <code class="comment">// Aucune constante n’existe pour cette valeur.</code>
-<b>assert</b> <code class="GeoAPI">MediumName.valueOf</code>("<code class="GeoAPI">CD_ROM</code>") == <var>cdRom</var> : "valueOf doit retourner les constantes existantes.";
-<b>assert</b> <code class="GeoAPI">MediumName.valueOf</code>("<code class="GeoAPI">USB_KEY</code>") == <var>usbKey</var> : "valueOf doit cacher les valeurs précédemment demandées.";</pre>
+<pre><code class="GeoAPI">MediumName</code> cdRom = <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">CD_ROM;</code>
+<code class="GeoAPI">MediumName</code> usbKey = <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">USB_KEY</code>"</i>); <code class="comment">// Aucune constante n’existe pour cette valeur.
+</code><b>assert</b> <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">CD_ROM</code>"</i>) == cdRom : <i>"valueOf doit retourner les constantes existantes."</i>;
+<b>assert</b> <code class="GeoAPI">MediumName</code>.<code class="GeoAPI">valueOf</code>(<i>"<code class="GeoAPI">USB_KEY</code>"</i>) == usbKey : <i>"valueOf doit cacher les valeurs précédemment demandées."</i>;</pre>
-<h2 id="ServiceLoader">Obtenir une implémentation des interfaces</h2>
+<h2 id="ServiceLoader"><span class="section-number">2.2.</span> Obtenir une implémentation des interfaces</h2>
<p>
- GeoAPI définit des fabriques (<code class="GeoAPI">Factory</code>) permettant de créer des implémentations de ses interfaces.
- Par exemple <code class="GeoAPI">DatumFactory</code> fournit des méthodes permettant de créer des instances
- implémentant les interfaces du paquet <code class="GeoAPI">org.opengis.referencing.datum</code>.
- Ces <code class="GeoAPI">Factory</code> doivent être implémentées par les bibliothèques géospatiales
- et déclarées comme <i>services</i> tel que défini par la classe standard <code>java.util.ServiceLoader</code>.
- La javadoc de <code>ServiceLoader</code> explique la façon de procéder.
- Mais pour résumer, les bibliothèques doivent créer dans le répertoire <code>META-INF/services/</code>
- un fichier dont le nom correspond au nom complet de l’interface de la fabrique
- (<code class="GeoAPI">org.opengis.referencing.datum.DatumFactory</code> dans l’exemple précédent).
- Ce fichier texte doit contenir sur une ligne le nom complet de la classe implémentant cette interface.
- Il peut s’agir d’une classe cachée aux yeux des utilisateurs, car ils n’ont pas besoin de connaître son existence.
+GeoAPI définit des fabriques (<code class="GeoAPI">Factory</code>) permettant de créer des implémentations de ses interfaces.
+Par exemple <code class="GeoAPI">DatumFactory</code> fournit des méthodes permettant de créer des instances
+implémentant les interfaces du paquet <code class="GeoAPI">org.opengis.referencing.datum</code>.
+Ces <code class="GeoAPI">Factory</code> doivent être implémentées par les bibliothèques géospatiales
+et déclarées comme <i>services</i> tel que défini par la classe standard <code>java.util.ServiceLoader</code>.
+La javadoc de <code>ServiceLoader</code> explique la façon de procéder.
+Mais pour résumer, les bibliothèques doivent créer dans le répertoire <code>META-INF/services/</code>
+un fichier dont le nom correspond au nom complet de l’interface de la fabrique
+(<code class="GeoAPI">org.opengis.referencing.datum.DatumFactory</code> dans l’exemple précédent).
+Ce fichier texte doit contenir sur une ligne le nom complet de la classe implémentant cette interface.
+Il peut s’agir d’une classe cachée aux yeux des utilisateurs, car ils n’ont pas besoin de connaître son existence.
</p>
<p>
- Si la bibliothèque a bien déclaré ses fabriques comme des services, alors
- les utilisateurs peuvent les obtenir en utilisant <code>ServiceLoader</code> comme dans l’exemple ci-dessous.
- Cet exemple ne prend que la première fabrique trouvée; s’il existe plusieurs fabriques,
- par exemple lorsque plusieurs bibliothèques cohabitent, alors le choix est laissé à l’utilisateur.
+Si la bibliothèque a bien déclaré ses fabriques comme des services, alors
+les utilisateurs peuvent les obtenir en utilisant <code>ServiceLoader</code> comme dans l’exemple ci-dessous.
+Cet exemple ne prend que la première fabrique trouvée; s’il existe plusieurs fabriques,
+par exemple lorsque plusieurs bibliothèques cohabitent, alors le choix est laissé à l’utilisateur.
</p>
-<pre><b>import</b> <code class="GeoAPI">org.opengis.referencing.GeodeticDatum</code>;
-<b>import</b> <code class="GeoAPI">org.opengis.referencing.DatumFactory</code>;
+<pre><b>import</b> org.opengis.referencing.<code class="GeoAPI">GeodeticDatum</code>;
+<b>import</b> org.opengis.referencing.<code class="GeoAPI">DatumFactory</code>;
<b>import</b> java.util.ServiceLoader;
-<b>public class</b> MyApplication {
- <b>public void</b> createMyDatum() {
- ServiceLoader <var>loader</var> = ServiceLoader.load(<code class="GeoAPI">DatumFactory</code>.class);
- <code class="GeoAPI">DatumFactory</code> <var>factory</var> = <var>loader</var>.iterator().next();
- <code class="GeoAPI">GeodeticDatum</code> <var>myDatum</var> = <var>factory</var>.<code class="GeoAPI">createGeodeticDatum</code>(…);
+<b>public</b> <b>class</b> MyApplication {
+ <b>public</b> <b>void</b> createMyDatum() {
+ ServiceLoader loader = ServiceLoader.load(<code class="GeoAPI">DatumFactory</code>.<b>class</b>);
+ <code class="GeoAPI">DatumFactory</code> factory = loader.iterator().next();
+ <code class="GeoAPI">GeodeticDatum</code> myDatum = factory.<code class="GeoAPI">createGeodeticDatum</code>(…);
}
}</pre>
-<h3 id="GeoAPI-simple">Fournir sa propre implémentation</h3>
+<h3 id="GeoAPI-simple"><span class="section-number">2.2.1.</span> Fournir sa propre implémentation</h3>
<p>
- Implémenter soi-même GeoAPI n’est pas si difficile si on se contente de besoins bien précis.
- Un développeur peut se concentrer sur une poignée d’interfaces parmi les centaines de disponibles,
- tout en disposant des autres interfaces comme autant de points d’extensions à éventuellement implémenter
- au gré des besoins.
+Implémenter soi-même GeoAPI n’est pas si difficile si on se contente de besoins bien précis.
+Un développeur peut se concentrer sur une poignée d’interfaces parmi les centaines de disponibles,
+tout en disposant des autres interfaces comme autant de points d’extensions à éventuellement implémenter
+au gré des besoins.
</p>
<p>
- Le modèle conceptuel représenté par les interfaces est complexe. Mais cette complexité peut être réduite en combinant certaines interfaces.
- Par exemple plusieurs bibliothèques, même réputées, ne font pas la distinction entre <cite>Système de coordonnées</cite> (<abbr>CS</abbr>)
- et <cite>Système de <u>référence</u> des coordonnées</cite> (<abbr>CRS</abbr>).
- Un développeur qui lui non-plus ne souhaite pas faire cette distinction peut implémenter ces deux interfaces par la même classe.
- Il peut en résulter une implémentation dont la hiérarchie de classes est plus simple que la hiérarchie des interfaces de GeoAPI.
- Le module <code class="GeoAPI">geoapi-examples</code>, discuté plus loin, fournit de telles combinaisons.
- Le tableau suivant énumère quelques combinaisons possibles:
+Le modèle conceptuel représenté par les interfaces est complexe. Mais cette complexité peut être réduite en combinant certaines interfaces.
+Par exemple plusieurs bibliothèques, même réputées, ne font pas la distinction entre <cite>Système de coordonnées</cite> (<abbr>CS</abbr>)
+et <cite>Système de <u>référence</u> des coordonnées</cite> (<abbr title="Coordinate Reference System">CRS</abbr>).
+Un développeur qui lui non-plus ne souhaite pas faire cette distinction peut implémenter ces deux interfaces par la même classe.
+Il peut en résulter une implémentation dont la hiérarchie de classes est plus simple que la hiérarchie des interfaces de GeoAPI.
+Le module <code class="GeoAPI">geoapi-examples</code>, discuté plus loin, fournit de telles combinaisons.
+Le tableau suivant énumère quelques combinaisons possibles:
</p>
<table>
- <tr>
- <th>Interface principale</th>
- <th>Interface auxiliaire</th>
- <th>Usage</th>
- </tr>
- <tr>
- <td><code class="GeoAPI">CoordinateReferenceSystem</code></td>
- <td><code class="GeoAPI">CoordinateSystem</code></td>
- <td>Description d’un système de référence spatial (<abbr title="Coordinate Reference System">CRS</abbr>).</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">GeodeticDatum</code></td>
- <td><code class="GeoAPI">Ellipsoid</code></td>
- <td>Description d’un référentiel geodétique.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">CoordinateOperation</code></td>
- <td><code class="GeoAPI">MathTransform</code></td>
- <td>Opération de transformation de coordonnées.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">IdentifiedObject</code></td>
- <td><code class="GeoAPI">ReferenceIdentifier</code></td>
- <td>Objet (typiquement un <abbr>CRS</abbr>) que l’on peut identifier par un code.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">Citation</code></td>
- <td><code class="GeoAPI">InternationalString</code></td>
- <td>Référence bibliographique composée d’un simple titre.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">GeographicBoundingBox</code></td>
- <td><code class="GeoAPI">Extent</code></td>
- <td>Étendue spatiale en degrés de longitude et de latitude.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">ParameterValue</code></td>
- <td><code class="GeoAPI">ParameterDescriptor</code></td>
- <td>Description d’un paramètre (nom, type) associée à sa valeur.</td>
- </tr>
- <tr>
- <td><code class="GeoAPI">ParameterValueGroup</code></td>
- <td><code class="GeoAPI">ParameterDescriptorGroup</code></td>
- <td>Description d’un ensemble de paramètres associés à leurs valeurs.</td>
- </tr>
+<tr>
+<th>Interface principale</th>
+<th>Interface auxiliaire</th>
+<th>Usage</th>
+</tr>
+<tr>
+<td><code class="GeoAPI">CoordinateReferenceSystem</code></td>
+<td><code class="GeoAPI">CoordinateSystem</code></td>
+<td>Description d’un système de référence spatial (<abbr>CRS</abbr>).</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">GeodeticDatum</code></td>
+<td><code class="GeoAPI">Ellipsoid</code></td>
+<td>Description d’un référentiel geodétique.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">CoordinateOperation</code></td>
+<td><code class="GeoAPI">MathTransform</code></td>
+<td>Opération de transformation de coordonnées.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">IdentifiedObject</code></td>
+<td><code class="GeoAPI">ReferenceIdentifier</code></td>
+<td>Objet (typiquement un <abbr>CRS</abbr>) que l’on peut identifier par un code.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">Citation</code></td>
+<td><code class="GeoAPI">InternationalString</code></td>
+<td>Référence bibliographique composée d’un simple titre.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">GeographicBoundingBox</code></td>
+<td><code class="GeoAPI">Extent</code></td>
+<td>Étendue spatiale en degrés de longitude et de latitude.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">ParameterValue</code></td>
+<td><code class="GeoAPI">ParameterDescriptor</code></td>
+<td>Description d’un paramètre (nom, type) associée à sa valeur.</td>
+</tr>
+<tr>
+<td><code class="GeoAPI">ParameterValueGroup</code></td>
+<td><code class="GeoAPI">ParameterDescriptorGroup</code></td>
+<td>Description d’un ensemble de paramètres associés à leurs valeurs.</td>
+</tr>
</table>
-<h2 id="GeoAPI-modules">Les modules de GeoAPI</h2>
+<h2 id="GeoAPI-modules"><span class="section-number">2.3.</span> Les modules de GeoAPI</h2>
<p>
- Le projet GeoAPI est composé d’une partie standardisée (<code class="GeoAPI">geoapi</code>) et
- d’une partie expérimentale (<code class="GeoAPI">geoapi-pending</code>). Ces deux parties étant
- mutuellement exclusives, les utilisateurs doivent veiller à ne pas les mélanger dans un même projet.
- Cette séparation est garantie pour tous les projets qui ne dépendent que du dépôt central de Maven
- (incluant les versions finales de Apache <abbr title="Spatial Information System">SIS</abbr>),
- car le module <code class="GeoAPI">geoapi-pending</code> n’est jamais déployé sur ce dépôt central.
- En revanche certaines branches de développement de <abbr>SIS</abbr> peuvent dépendre de <code class="GeoAPI">geoapi-pending</code>.
+Le projet GeoAPI est composé d’une partie standardisée (<code class="GeoAPI">geoapi</code>) et
+d’une partie expérimentale (<code class="GeoAPI">geoapi-pending</code>). Ces deux parties étant
+mutuellement exclusives, les utilisateurs doivent veiller à ne pas les mélanger dans un même projet.
+Cette séparation est garantie pour tous les projets qui ne dépendent que du dépôt central de Maven
+(incluant les versions finales de Apache <abbr title="Spatial Information System">SIS</abbr>),
+car le module <code class="GeoAPI">geoapi-pending</code> n’est jamais déployé sur ce dépôt central.
+En revanche certaines branches de développement de <abbr>SIS</abbr> peuvent dépendre de <code class="GeoAPI">geoapi-pending</code>.
</p>
<p>
- Les modules de GeoAPI sont:
+Les modules de GeoAPI sont:
</p>
<ul>
- <li><p>
- <b><code class="GeoAPI">geoapi</code></b> — contient les interfaces couvertes par le
- <a href="http://www.opengeospatial.org/standards/geoapi">standard GeoAPI de l’<abbr title="Open Geospatial Consortium">OGC</abbr></a>.
- Les versions finales de Apache <abbr title="Spatial Information System">SIS</abbr> dépendent de ce module.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-pending</code></b> — contient une
- <em>copie</em> de toutes les interfaces du module <code class="GeoAPI">geoapi</code>
- (non pas une dépendance) avec des ajouts qui n’ont pas encore été approuvés comme un standard <abbr>OGC</abbr>.
- Certains ajouts apparaissent dans des interfaces normalement définies par le module <code class="GeoAPI">geoapi</code>,
- d’où la nécessité de les copier.
- Les branches de développement <code>jdk6</code>,
- <code>jdk7</code> et <code>jdk8</code> de Apache <abbr>SIS</abbr> dépendent de ce module,
- mais cette dépendance est transformée en une dépendance vers le module <code class="GeoAPI">geoapi</code>
- standard au moment de fusionner les branches avec le tronc.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-conformance</code></b> — contient
- une suite de tests JUnit que les développeurs peuvent utiliser pour tester leurs implémentations.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-examples</code></b> — contient des
- exemples d’implémentations relativement simples. Ces exemples sont placés dans le domaine public
- afin d’encourager les utilisateurs à les copier et les adapter à leurs besoins si les services
- de Apache <abbr>SIS</abbr> ne conviennent pas.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-proj4</code></b> — contient une
- implémentation partielle des paquets <code class="GeoAPI">org.opengis.referencing</code>
- sous forme d’adaptateurs basés sur la bibliothèque C/C++ Proj.4.
- Ce module peut être utilisé comme alternative au module <code class="SIS">sis-referencing</code>
- pour certaines fonctions.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-netcdf</code></b> — contient une implémentation partielle des paquets
- <code class="GeoAPI">org.opengis.referencing</code> et <code class="GeoAPI">org.opengis.coverage</code>
- sous forme d’adaptateurs basés sur la bibliothèque <abbr title="Network Common Data Form">NetCDF</abbr>
- de l’<abbr title="University Corporation for Atmospheric Research">UCAR</abbr>.
- La suite de tests de ce module a été conçue de manière à être réutilisable par d’autres projets.
- Apache <abbr>SIS</abbr> l’utilise pour tester son propre module <code class="SIS">sis-netcdf</code>.
- </p></li>
- <li><p>
- <b><code class="GeoAPI">geoapi-openoffice</code></b> — contient
- un <i>add-in</i> pour les suites bureautiques Libre/OpenOffice.org.
- <!--
- Apache <abbr>SIS</abbr> offre son propre <i>add-in</i> dans le module <code class="SIS">sis-openoffice</code>,
- mais utilise les mêmes noms de fonctions que le module de GeoAPI afin d’assurer une certaine compatibilité.
- -->
- </p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi</code></b> — contient les interfaces couvertes par le
+<a href="http://www.opengeospatial.org/standards/geoapi">standard GeoAPI de l’<abbr title="Open Geospatial Consortium">OGC</abbr></a>.
+Les versions finales de Apache <abbr>SIS</abbr> dépendent de ce module.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-pending</code></b> — contient une
+<em>copie</em> de toutes les interfaces du module <code class="GeoAPI">geoapi</code>
+(non pas une dépendance) avec des ajouts qui n’ont pas encore été approuvés comme un standard <abbr>OGC</abbr>.
+Certains ajouts apparaissent dans des interfaces normalement définies par le module <code class="GeoAPI">geoapi</code>,
+d’où la nécessité de les copier.
+Les branches de développement <code>jdk6</code>,
+<code>jdk7</code> et <code>jdk8</code> de Apache <abbr>SIS</abbr> dépendent de ce module,
+mais cette dépendance est transformée en une dépendance vers le module <code class="GeoAPI">geoapi</code>
+standard au moment de fusionner les branches avec le tronc.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-conformance</code></b> — contient
+une suite de tests JUnit que les développeurs peuvent utiliser pour tester leurs implémentations.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-examples</code></b> — contient des
+exemples d’implémentations relativement simples. Ces exemples sont placés dans le domaine public
+afin d’encourager les utilisateurs à les copier et les adapter à leurs besoins si les services
+de Apache <abbr>SIS</abbr> ne conviennent pas.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-proj4</code></b> — contient une
+implémentation partielle des paquets <code class="GeoAPI">org.opengis.referencing</code>
+sous forme d’adaptateurs basés sur la bibliothèque C/C++ Proj.4.
+Ce module peut être utilisé comme alternative au module <code class="SIS">sis-referencing</code>
+pour certaines fonctions.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-netcdf</code></b> — contient une implémentation partielle des paquets
+<code class="GeoAPI">org.opengis.referencing</code> et <code class="GeoAPI">org.opengis.coverage</code>
+sous forme d’adaptateurs basés sur la bibliothèque <abbr title="Network Common Data Form">NetCDF</abbr> de l’<abbr title="University Corporation for Atmospheric Research">UCAR</abbr>.
+La suite de tests de ce module a été conçue de manière à être réutilisable par d’autres projets.
+Apache <abbr>SIS</abbr> l’utilise pour tester son propre module <code class="SIS">sis-netcdf</code>.
+</p></li>
+<li><p>
+<b><code class="GeoAPI">geoapi-openoffice</code></b> — contient
+un <i>add-in</i> pour les suites bureautiques Libre/OpenOffice.org.
+<!--
+ Apache <abbr>SIS</abbr> offre son propre <i>add-in</i> dans le module <code>sis-openoffice</code>,
+ mais utilise les mêmes noms de fonctions que le module de GeoAPI afin d’assurer une certaine compatibilité.
+ -->
+</p></li>
</ul>
-<h3 id="GeoAPI-core">Les modules de définition des interfaces</h3>
+<h3 id="GeoAPI-core"><span class="section-number">2.3.1.</span> Les modules de définition des interfaces</h3>
<p>
- Les modules <code class="GeoAPI">geoapi</code> et <code class="GeoAPI">geoapi-pending</code>
- fournissent les interfaces dérivées des schémas <abbr title="Unified Modeling Language">UML</abbr> des standards internationaux.
- Le modèle conceptuel sera expliqué en détails dans les chapitres décrivant l’implémentation Apache <abbr>SIS</abbr>.
- On peut toutefois avoir un aperçu de son contenu en consultant la page listant les
- <a href="http://www.geoapi.org/3.0/javadoc/content.html">types et méthodes de GeoAPI et les standards d’où ils proviennent</a>.
+Les modules <code class="GeoAPI">geoapi</code> et <code class="GeoAPI">geoapi-pending</code>
+fournissent les interfaces dérivées des schémas <abbr title="Unified Modeling Language">UML</abbr> des standards internationaux.
+Le modèle conceptuel sera expliqué en détails dans les chapitres décrivant l’implémentation Apache <abbr title="Spatial Information System">SIS</abbr>.
+On peut toutefois avoir un aperçu de son contenu en consultant la page listant les
+<a href="http://www.geoapi.org/3.0/javadoc/content.html">types et méthodes de GeoAPI et les standards d’où ils proviennent</a>.
</p>
-<h3 id="GeoAPI-conformance">Le module de tests de conformité</h3>
+<h3 id="GeoAPI-conformance"><span class="section-number">2.3.2.</span> Le module de tests de conformité</h3>
<p>
- Le module <code class="GeoAPI">geoapi-conformance</code> fournit des <i>validateurs</i>, une <i>suite de tests</i> JUnit
- et des <i>générateurs de rapports</i> sous forme de pages <abbr title="Hypertext Markup Language">HTML</abbr>.
- Ce module peut être utilisé avec n’importe quelle implémentation de GeoAPI.
- Pour les développeurs d’une bibliothèque géospatiale, il offre les avantages suivants:
+Le module <code class="GeoAPI">geoapi-conformance</code> fournit des <i>validateurs</i>, une <i>suite de tests</i> JUnit
+et des <i>générateurs de rapports</i> sous forme de pages <abbr title="Hypertext Markup Language">HTML</abbr>.
+Ce module peut être utilisé avec n’importe quelle implémentation de GeoAPI.
+Pour les développeurs d’une bibliothèque géospatiale, il offre les avantages suivants:
</p>
<ul>
- <li>Réduire la fastidieuse tâche d’écriture des tests, en réutilisant des tests existants.</li>
- <li>Accroître la confiance en la validité des tests, du fait que <code class="GeoAPI">geoapi-conformance</code>
- a lui-même sa propre suite de tests et est appliqué à d’autres implémentations.</li>
- <li>Faciliter la comparaison avec les autres implémentations.</li>
+<li>Réduire la fastidieuse tâche d’écriture des tests, en réutilisant des tests existants.</li>
+<li>Accroître la confiance en la validité des tests, du fait que <code class="GeoAPI">geoapi-conformance</code>
+a lui-même sa propre suite de tests et est appliqué à d’autres implémentations.</li>
+<li>Faciliter la comparaison avec les autres implémentations.</li>
</ul>
-<h4 id="GeoAPI-validators">Validations des instances</h4>
+<h4 id="GeoAPI-validators"><span class="section-number">2.3.2.1.</span> Validations des instances</h4>
<p>
- GeoAPI peut valider une instance de ses interfaces en vérifiant que certaines contraintes sont respectées.
- Certaines contraintes ne peuvent pas être exprimées dans la signature de la méthode. Ces contraintes sont
- généralement décrites textuellement dans les spécifications abstraites ou dans la javadoc.
+GeoAPI peut valider une instance de ses interfaces en vérifiant que certaines contraintes sont respectées.
+Certaines contraintes ne peuvent pas être exprimées dans la signature de la méthode. Ces contraintes sont
+généralement décrites textuellement dans les spécifications abstraites ou dans la javadoc.
</p>
<div class="example"><p><b>Exemple:</b>
- La conversion ou transformation d’une coordonnée (<code class="OGC">CC_CoordinateOperation</code>) peut nécessiter l’enchaînement de plusieurs étapes.
- Dans une telle chaîne d’opérations (<code class="OGC">CC_ConcatenatedOperation</code>),
- pour chaque étape (<code class="OGC">CC_SingleOperation</code>) le nombre de dimensions
- en sortie doit être égal au nombre de dimensions attendu en entré par l’opération suivante.
- Exprimée en langage Java, cette contrainte stipule que pour tout index
- 0 < <var>i</var> < <var>n</var> où <var>n</var> est le nombre d’opérations, on a
- <code>coordOperation[i].targetDimensions == coordOperation[i-1].sourceDimensions</code>.
+La conversion ou transformation d’une coordonnée (<code class="OGC">CC_CoordinateOperation</code>) peut nécessiter l’enchaînement de plusieurs étapes.
+Dans une telle chaîne d’opérations (<code class="OGC">CC_ConcatenatedOperation</code>),
+pour chaque étape (<code class="OGC">CC_SingleOperation</code>) le nombre de dimensions
+en sortie doit être égal au nombre de dimensions attendu en entré par l’opération suivante.
+Exprimée en langage Java, cette contrainte stipule que pour tout index
+0 < <var>i</var> < <var>n</var> où <var>n</var> est le nombre d’opérations, on a
+<code>coordOperation[i].targetDimensions == coordOperation[i-1].sourceDimensions</code>.
</p></div>
<p>
- La façon la plus simple d’effectuer ces vérifications est d’appeler les méthodes statiques
- <code class="GeoAPI">validate(…)</code> de la classe <code class="GeoAPI">org.opengis.test.Validators</code>.
- Ces méthodes portant toutes le même nom, il suffit d’écrire “<code>validate(<var>valeur</var>)</code>”
- et de laisser le compilateur choisir la méthode la plus appropriée en fonction du type d’objet donné en argument.
- Si le type d’objet n’est pas connu au moment de la compilation, alors la méthode <code class="GeoAPI">dispatch(Object)</code>
- peut se charger de rediriger le travail à la méthode <code class="GeoAPI">validate(…)</code> appropriée.
+La façon la plus simple d’effectuer ces vérifications est d’appeler les méthodes statiques
+<code class="GeoAPI">validate(…)</code> de la classe <code class="GeoAPI">org.opengis.test.Validators</code>.
+Ces méthodes portant toutes le même nom, il suffit d’écrire “<code>validate(<var>valeur</var>)</code>”
+et de laisser le compilateur choisir la méthode la plus appropriée en fonction du type d’objet donné en argument.
+Si le type d’objet n’est pas connu au moment de la compilation, alors la méthode <code class="GeoAPI">dispatch(Object)</code>
+peut se charger de rediriger le travail à la méthode <code class="GeoAPI">validate(…)</code> appropriée.
</p>
<p>
- Toutes les fonctions <code class="GeoAPI">validate(…)</code> suivent le fil des dépendances,
- c’est-à-dire qu’elles valideront aussi chaque composantes de l’objet à valider.
- 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 souvent problématique.
+Toutes les fonctions <code class="GeoAPI">validate(…)</code> suivent le fil des dépendances,
+c’est-à-dire qu’elles valideront aussi chaque composantes de l’objet à valider.
+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 souvent problématique.
</p>
<p>
- Par défaut, les validations sont aussi strictes que possible. Il est possible toutefois d’assouplir certaines règles.
- L’assouplissement le plus fréquent consiste à tolérer l’absence d’attributs qui étaient sensés être obligatoires.
- Cette règle et quelques autres peuvent être modifiées globalement pour tous les tests exécutés dans la
- <abbr title="Java Virtual Machine">JVM</abbr> courante comme dans l’exemple suivant:
+Par défaut, les validations sont aussi strictes que possible. Il est possible toutefois d’assouplir certaines règles.
+L’assouplissement le plus fréquent consiste à tolérer l’absence d’attributs qui étaient sensés être obligatoires.
+Cette règle et quelques autres peuvent être modifiées globalement pour tous les tests exécutés dans la
+<abbr title="Java Virtual Machine">JVM</abbr> courante comme dans l’exemple suivant:
</p>
-<pre><b>import</b> <code class="GeoAPI">org.opengis.metadata.Metadata</code>;
-<b>import</b> <code class="GeoAPI">org.opengis.test.Validators</code>;
+<pre><b>import</b> org.opengis.metadata.<code class="GeoAPI">Metadata</code>;
+<b>import</b> org.opengis.test.<code class="GeoAPI">Validators</code>;
<b>import</b> org.junit.Test;
-<b>public class</b> MyTest {<code class="comment">
- /*
+<b>public</b> <b>class</b> MyTest {
+ <code class="comment">/*
* Tolérer l’absence d’attributs obligatoires dans les paquets metadata et citation.
* Cette modification s’appliquera à tous les tests exécutés dans la <abbr>JVM</abbr> courante.
* S’il existe plusieurs classes de tests, cette initialisation peut être effectuée
* dans une classe parente à toutes les classes de tests.
*/</code>
<b>static</b> {
- <code class="GeoAPI">Validators.DEFAULT.metadata.requireMandatoryAttributes</code> = <b>false</b>;
- <code class="GeoAPI">Validators.DEFAULT.citation.requireMandatoryAttributes</code> = <b>false</b>;
+ <code class="GeoAPI">Validators</code>.<code class="GeoAPI">DEFAULT.metadata.requireMandatoryAttributes</code> = <b>false</b>;
+ <code class="GeoAPI">Validators</code>.<code class="GeoAPI">DEFAULT.citation.requireMandatoryAttributes</code> = <b>false</b>;
}
@Test
- <b>public void</b> testMyMetadata() {
- <code class="GeoAPI">Metadata</code> <var>myObject</var> = …; <code class="comment">// Construisez un objet ici.</code>
- <code class="GeoAPI">Validators.validate</code>(<var>myObject</var>);
+ <b>public</b> <b>void</b> testMyMetadata() {
+ <code class="GeoAPI">Metadata</code> myObject = …; <code class="comment">// Construisez un objet ici.
+</code> <code class="GeoAPI">Validators</code>.<code class="GeoAPI">validate</code>(myObject);
}
}</pre>
<p>
- Les règles peuvent aussi être modifiées pour une suite de tests particulière,
- sans affecter la configuration par défaut de la <abbr title="Java Virtual Machine">JVM</abbr> courante.
- Cette approche nécessite de créer une nouvelle instance du validateur dont on souhaite modifier la configuration.
+Les règles peuvent aussi être modifiées pour une suite de tests particulière,
+sans affecter la configuration par défaut de la <abbr>JVM</abbr> courante.
+Cette approche nécessite de créer une nouvelle instance du validateur dont on souhaite modifier la configuration.
</p>
-<pre><b>import</b> <code class="GeoAPI">org.opengis.metadata.Metadata</code>;
-<b>import</b> <code class="GeoAPI">org.opengis.test.ValidatorContainer</code>;
+<pre><b>import</b> org.opengis.metadata.<code class="GeoAPI">Metadata</code>;
+<b>import</b> org.opengis.test.<code class="GeoAPI">ValidatorContainer</code>;
<b>import</b> org.junit.Test;
-<b>public class</b> MyTest {
- <b>private final</b> <code class="GeoAPI">ValidatorContainer</code> <var>validators</var>;
+<b>public</b> <b>class</b> MyTest {
+ <b>private</b> <b>final</b> <code class="GeoAPI">ValidatorContainer</code> validators;
<b>public</b> MyTest() {
- <var>validators</var> = <b>new</b> <code class="GeoAPI">ValidatorContainer()</code>;
- <var>validators</var>.<code class="GeoAPI">metadata.requireMandatoryAttributes</code> = <b>false</b>;
- <var>validators</var>.<code class="GeoAPI">citation.requireMandatoryAttributes</code> = <b>false</b>;
+ validators = <b>new</b> <code class="GeoAPI">ValidatorContainer</code>();
+ validators.<code class="GeoAPI">metadata.requireMandatoryAttributes</code> = <b>false</b>;
+ validators.<code class="GeoAPI">citation.requireMandatoryAttributes</code> = <b>false</b>;
}
@Test
- <b>public void</b> testMyMetadata() {
- <code class="GeoAPI">Metadata</code> <var>myObject</var> = …; <code class="comment">// Construisez un objet ici.</code>
- <var>validators</var>.<code class="GeoAPI">validate</code>(<var>myObject</var>);
+ <b>public</b> <b>void</b> testMyMetadata() {
+ <code class="GeoAPI">Metadata</code> myObject = …; <code class="comment">// Construisez un objet ici.
+</code> validators.<code class="GeoAPI">validate</code>(myObject);
}
}</pre>
-<h4 id="GeoAPI-tests">Exécution des tests pré-définis</h4>
+<h4 id="GeoAPI-tests"><span class="section-number">2.3.2.2.</span> Exécution des tests pré-définis</h4>
<p>
- Des classes de tests JUnit sont définies dans des sous-paquets de <code class="GeoAPI">org.opengis.test</code>.
- Toutes les classes de tests portent un nom se terminant en "<code>Test</code>".
- GeoAPI définie aussi une classe <code class="GeoAPI">org.opengis.test.TestSuite</code> englobant l’ensemble
- des tests définis dans le module <code class="GeoAPI">geoapi-conformance</code>,
- mais Apache <abbr title="Spatial Information System">SIS</abbr> ne l’utilise pas.
- Apache <abbr>SIS</abbr> hérite plutôt des classes <code class="GeoAPI">*Test</code> de GeoAPI au cas-par-cas,
- dans les modules appropriées.
- L’exemple ci-dessous donne un exemple de test de GeoAPI personnalisé.
- La <a href="http://www.geoapi.org/geoapi-conformance/apidocs/org/opengis/test/referencing/ParameterizedTransformTest.html">Javadoc
- de la classe parente</a> documente en détails les tests effectués.
- Dans cet exemple, un seul test est modifié et tous les autres tests sont hérités tels quels
- (il n’est pas nécessaire de les répéter dans la sous-classe).
- Toutefois, cet exemple ajoute une vérification supplémentaire, annotée <code>@After</code>,
- qui sera exécutée après chacun des tests.
+Des classes de tests JUnit sont définies dans des sous-paquets de <code class="GeoAPI">org.opengis.test</code>.
+Toutes les classes de tests portent un nom se terminant en "<code>Test</code>".
+GeoAPI définie aussi une classe <code class="GeoAPI">org.opengis.test.TestSuite</code> englobant l’ensemble
+des tests définis dans le module <code class="GeoAPI">geoapi-conformance</code>, mais Apache <abbr title="Spatial Information System">SIS</abbr> ne l’utilise pas.
+Apache <abbr>SIS</abbr> hérite plutôt des classes <code class="GeoAPI">*Test</code> de GeoAPI au cas-par-cas, dans les modules appropriés.
+L’exemple ci-dessous donne un exemple de test de GeoAPI personnalisé.
+La <a href="http://www.geoapi.org/geoapi-conformance/apidocs/org/opengis/test/referencing/ParameterizedTransformTest.html">Javadoc
+de la classe parente</a> documente en détails les tests effectués.
+Dans cet exemple, un seul test est modifié et tous les autres tests sont hérités tels quels
+(il n’est pas nécessaire de les répéter dans la sous-classe).
+Toutefois, cet exemple ajoute une vérification supplémentaire, annotée <code>@After</code>,
+qui sera exécutée après chacun des tests.
</p>
<pre><b>import</b> org.junit.*;
<b>import</b> org.junit.runner.RunWith;
<b>import</b> org.junit.runners.JUnit4;
-<b>import</b> <code class="GeoAPI">org.opengis.test.referencing.ParameterizedTransformTest</code>;
-<b>import static</b> org.junit.Assert.*;
+<b>import</b> org.opengis.test.referencing.<code class="GeoAPI">ParameterizedTransformTest</code>;
+<b>import</b> <b>static</b> org.junit.Assert.*;
-@RunWith(JUnit4.class)
-<b>public class</b> MyTest <b>extends</b> <code class="GeoAPI">ParameterizedTransformTest</code> {<code class="comment">
- /**
+@RunWith(JUnit4.<b>class</b>)
+<b>public</b> <b>class</b> MyTest <b>extends</b> <code class="GeoAPI">ParameterizedTransformTest</code> {
+ <code class="comment">/**
* Spécifie aux tests de GeoAPI notre propre fabrique de transformations de coordonnées.
* GeoAPI testera les objets construits par cette fabrique.
*/</code>
<b>public</b> MyTest() {
<b>super</b>(<b>new</b> MyMathTransformFactory());
}
-<code class="comment">
- /**
+
+ <code class="comment">/**
* Modifie le comportement d’un test. Cet exemple assouplit un peu les exigences de ce test,
* en acceptant des erreurs jusqu’à 10 centimètres plutôt que la valeur par défaut de 1 cm.
* Ce changement ne s’applique qu’à cette méthode est n’affecte pas les autres tests hérités.
*/</code>
@Test
@Override
- <b>public void</b> testLambertAzimuthalEqualArea() <b>throws</b> <code class="GeoAPI">FactoryException</code>, <code class="GeoAPI">TransformException</code> {
- <code class="GeoAPI"><var>tolerance</var></code> = 0.1; // Tolérance de 10 cm.
- <b>super</b>.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>;
+ <b>public</b> <b>void</b> testLambertAzimuthalEqualArea() <b>throws</b> <code class="GeoAPI">FactoryException</code>, <code class="GeoAPI">TransformException</code> {
+ <code class="GeoAPI">tolerance</code> = 0.1; <code class="comment">// Tolérance de 10 cm.
+</code> <b>super</b>.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>;
}
-<code class="comment">
- /**
+
+ <code class="comment">/**
* Vérification supplémentaire effectuée après chaque test, hérité ou non.
* Dans cet exemple, nous vérifions que la transformation qui a été testée
* travaillait bien dans des espaces bi-dimensionnels.
*/</code>
@After
- <b>public void</b> ensureAllTransformAreMath2D() {
- assertTrue(<code class="GeoAPI"><var>transform</var></code> <b>instanceof</b> <code class="GeoAPI">MathTransform2D</code>);
+ <b>public</b> <b>void</b> ensureAllTransformAreMath2D() {
+ assertTrue(<code class="GeoAPI">transform</code> <b>instanceof</b> <code class="GeoAPI">MathTransform2D</code>);
}
}</pre>
-<h3 id="GeoAPI-examples">Les modules d’exemples</h3>
-<p>
- Le module <code class="GeoAPI">geoapi-examples</code> fournit des exemples d’implémentations simples.
- Plusieurs de ces classes implémentent plus d’une interface à la fois afin de proposer un modèle conceptuel plus simple.
- La <a href="http://www.geoapi.org/geoapi-examples/apidocs/overview-summary.html">Javadoc de ce module</a>
- énumère les paquets et classes clés avec les combinaisons effectuées.
- Ce module illustre non-seulement comment GeoAPI peut-être implémenté, mais aussi comment l’implémentation
- peut être testée en utilisant <code class="GeoAPI">geoapi-conformance</code>.
-</p>
-<p>
- Bien que sa mission première soit de servir d’inspiration aux implémenteurs,
- <code class="GeoAPI">geoapi-examples</code> a tout-de-même été conçu de manière à être utilisable
- par des applications ayant des besoins très simples. Tous les exemples étant dans le domaine publique,
- les développeurs sont invités à adapter librement des copies de ces classes si nécessaires.
- Toutefois si des modifications sont apportées hors du cadre du projet GeoAPI, le bon usage veut que les copies
- modifiées soient placées dans un paquet portant un autre nom que <code class="GeoAPI">org.opengis</code>.
-</p>
-<p>
- Pour des besoins un peu plus poussés, les développeurs sont invités à examiner les modules
- <code class="GeoAPI">geoapi-proj4</code> et <code class="GeoAPI">geoapi-netcdf</code>.
- Ces deux modules fournissent des exemples d’adaptateurs permettant d’utiliser, via les interfaces de GeoAPI,
- une partie des fonctionnalités de bibliothèques externes (Proj.4 et <abbr title="Network Common Data Form">NetCDF</abbr>).
- L’avantage de passer par ces interfaces est de disposer d’un modèle unifié pour exploiter deux
- <abbr title="Application Programming Interface">API</abbr> très différents,
- tout en se gardant la possibilité de basculer plus facilement à une autre bibliothèque si désiré.
-</p>
-
-
-
-<h1 id="XML-ISO">Représentation des objets en <abbr>XML</abbr></h1>
-<p>
- Les objets définis par les standards
- <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr title="International Organization for Standardization">ISO</abbr>
- doivent pouvoir être échangés sur internet entre des machines distantes,
- utilisant des logiciels différents écrits dans des langages différents.
- Quelques uns des formats les plus connus sont
- le <abbr>WKT</abbr> (<i>Well Known Text</i>) et
- le <abbr>WKB</abbr> (<i>Well Known Binary</i>).
- Mais le format le plus exhaustif et souvent considéré comme la référence est le <abbr>XML</abbr>,
- au point où la façon de représenter les objets <abbr>ISO</abbr> dans ce format fait parfois l’objet d’un standard international à part entière.
- Ainsi, les classes de méta-données sont décrites dans le standard <abbr>ISO</abbr> 19115-1 (une spécification dite <i>abstraite</i>),
- alors que la représentation de ces classes en <abbr>XML</abbr> est décrite par les standards <abbr>ISO</abbr> 19115-3 et 19139.
-</p>
-<p>
- Les différents standards
- <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr title="International Organization for Standardization">ISO</abbr>
- n’emploient pas tous la même stratégie pour exprimer les objets en <abbr>XML</abbr>.
- Le standard <abbr>ISO</abbr> 19115-3 en particulier emploie une approche plus verbeuse que les autres normes,
- et fera l’objet d’une <a href="#XML-ISO-19115">section particulière</a>.
- Mais la plupart des formats <abbr>XML</abbr> ont en commun de définir des types et des attributs supplémentaires
- qui ne font pas partie des spécifications abstraites d’origines.
- Ces attributs supplémentaires sont habituellement propres au <abbr>XML</abbr> et peuvent ne pas apparaître directement dans
- l’<abbr title="Application Programming Interface">API</abbr> de Apache <abbr title="Spatial Information System">SIS</abbr>.
- Certains de ces attributs, notamment <code class="OGC">id</code>, <code class="OGC">uuid</code> et <code>xlink:href</code>,
- restent toutefois accessibles sous forme de paires clé-valeurs.
-</p>
-<p>
- Les documents <abbr>XML</abbr> peuvent employer les préfixes de leur choix,
- mais les préfixes suivants sont couramment employés dans la pratique.
- Ils apparaissent donc par défaut dans les documents produits par Apache <abbr>SIS</abbr>.
- Ces préfixes sont définis dans la classe <code class="SIS">org.apache.sis.xml.Namespaces</code>.
+<h3 id="GeoAPI-examples"><span class="section-number">2.3.3.</span> Les modules d’exemples</h3>
+<p>
+Le module <code class="GeoAPI">geoapi-examples</code> fournit des exemples d’implémentations simples.
+Plusieurs de ces classes implémentent plus d’une interface à la fois afin de proposer un modèle conceptuel plus simple.
+La <a href="http://www.geoapi.org/geoapi-examples/apidocs/overview-summary.html">Javadoc de ce module</a>
+énumère les paquets et classes clés avec les combinaisons effectuées.
+Ce module illustre non-seulement comment GeoAPI peut-être implémenté, mais aussi comment l’implémentation
+peut être testée en utilisant <code class="GeoAPI">geoapi-conformance</code>.
+</p>
+<p>
+Bien que sa mission première soit de servir d’inspiration aux implémenteurs,
+<code class="GeoAPI">geoapi-examples</code> a tout-de-même été conçu de manière à être utilisable
+par des applications ayant des besoins très simples. Tous les exemples étant dans le domaine publique,
+les développeurs sont invités à adapter librement des copies de ces classes si nécessaires.
+Toutefois si des modifications sont apportées hors du cadre du projet GeoAPI, le bon usage veut que les copies
+modifiées soient placées dans un paquet portant un autre nom que <code class="GeoAPI">org.opengis</code>.
+</p>
+<p>
+Pour des besoins un peu plus poussés, les développeurs sont invités à examiner les modules
+<code class="GeoAPI">geoapi-proj4</code> et <code class="GeoAPI">geoapi-netcdf</code>.
+Ces deux modules fournissent des exemples d’adaptateurs permettant d’utiliser, via les interfaces de GeoAPI,
+une partie des fonctionnalités de bibliothèques externes (Proj.4 et <abbr title="Network Common Data Form">NetCDF</abbr>).
+L’avantage de passer par ces interfaces est de disposer d’un modèle unifié pour exploiter deux <abbr title="Application Programming Interface">API</abbr> très différents,
+tout en se gardant la possibilité de basculer plus facilement à une autre bibliothèque si désiré.
+</p>
+</section>
+<section>
+<header>
+<h1 id="XML-ISO"><span class="section-number">3.</span> Représentation des objets en <abbr>XML</abbr></h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#GeoAPI">Chapitre suivant</a></div><div class="next-chapter"><a href="#Utilities">Chapitre précédent</a> ➡</div></div></nav>
+</header>
+<nav>Dans ce chapitre:<ul class="toc">
+<li><a href="#XML-ISO-19115">Représentation des méta-données selon ISO 19115-3</a><ul>
+<li><a href="#gco-id">Identification d’instances déjà définies</a></li>
+<li><a href="#nilReason">Représentation de valeurs manquantes</a></li></ul></li></ul></nav>
+<p>
+Les objets définis par les standards <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr title="International Organization for Standardization">ISO</abbr> doivent pouvoir être échangés sur internet
+entre des machines distantes, utilisant des logiciels différents écrits dans des langages différents.
+Quelques uns des formats les plus connus sont
+le <abbr>WKT</abbr> (<i>Well Known Text</i>) et
+le <abbr>WKB</abbr> (<i>Well Known Binary</i>).
+Mais le format le plus exhaustif et souvent considéré comme la référence est le <abbr>XML</abbr>,
+au point où la façon de représenter les objets <abbr>ISO</abbr> dans ce format fait parfois l’objet d’un standard international à part entière.
+Ainsi, les classes de méta-données sont décrites dans le standard <abbr>ISO</abbr> 19115-1 (une spécification dite <i>abstraite</i>),
+alors que la représentation de ces classes en <abbr>XML</abbr> est décrite par les standards <abbr>ISO</abbr> 19115-3 et 19139.
+</p>
+<p>
+Les différents standards <abbr>OGC</abbr>/<abbr>ISO</abbr> n’emploient pas tous la même stratégie pour exprimer les objets en <abbr>XML</abbr>.
+Le standard <abbr>ISO</abbr> 19115-3 en particulier emploie une approche plus verbeuse que les autres normes,
+et fera l’objet d’une <a href="#XML-ISO-19115">section particulière</a>.
+Mais la plupart des formats <abbr>XML</abbr> ont en commun de définir des types et des attributs supplémentaires
+qui ne font pas partie des spécifications abstraites d’origines.
+Ces attributs supplémentaires sont habituellement propres au <abbr>XML</abbr> et peuvent ne pas apparaître directement dans l’<abbr title="Application Programming Interface">API</abbr> de Apache <abbr title="Spatial Information System">SIS</abbr>.
+Certains de ces attributs, notamment <code class="OGC">id</code>, <code class="OGC">uuid</code> et <code>xlink:href</code>,
+restent toutefois accessibles sous forme de paires clé-valeurs.
+</p>
+<p>
+Les documents <abbr>XML</abbr> peuvent employer les préfixes de leur choix,
+mais les préfixes suivants sont couramment employés dans la pratique.
+Ils apparaissent donc par défaut dans les documents produits par Apache <abbr>SIS</abbr>.
+Ces préfixes sont définis dans la classe <code class="SIS">org.apache.sis.xml.Namespaces</code>.
</p>
<table>
- <caption>Préfixes d’espaces de noms <abbr>XML</abbr> courants</caption>
- <tr>
- <th>Préfixe</th>
- <th>Espace de nom</th>
- </tr>
- <tr>
- <td><code class="OGC">gco</code></td>
- <td><code>http://www.isotc211.org/2005/gco</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gfc</code></td>
- <td><code>http://www.isotc211.org/2005/gfc</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gmd</code></td>
- <td><code>http://www.isotc211.org/2005/gmd</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gmi</code></td>
- <td><code>http://www.isotc211.org/2005/gmi</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gmx</code></td>
- <td><code>http://www.isotc211.org/2005/gmx</code></td>
- </tr>
- <tr>
- <td><code class="OGC">gml</code></td>
- <td><code>http://www.opengis.net/gml/3.2</code></td>
- </tr>
- <tr>
- <td><code>xlink</code></td>
- <td><code>http://www.w3.org/1999/xlink</code></td>
- </tr>
+<caption>Préfixes d’espaces de noms <abbr>XML</abbr> courants</caption>
+<tr>
+<th>Préfixe</th>
+<th>Espace de nom</th>
+</tr>
+<tr>
+<td><code class="OGC">gco</code></td>
+<td><code>http://www.isotc211.org/2005/gco</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gfc</code></td>
+<td><code>http://www.isotc211.org/2005/gfc</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmd</code></td>
+<td><code>http://www.isotc211.org/2005/gmd</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmi</code></td>
+<td><code>http://www.isotc211.org/2005/gmi</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmx</code></td>
+<td><code>http://www.isotc211.org/2005/gmx</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gml</code></td>
+<td><code>http://www.opengis.net/gml/3.2</code></td>
+</tr>
+<tr>
+<td><code>xlink</code></td>
+<td><code>http://www.w3.org/1999/xlink</code></td>
+</tr>
</table>
<aside>
- <p><b>Outils de lecture et d’écriture de documents <abbr>XML</abbr></b></p>
- <p>
- Apache <abbr title="Spatial Information System">SIS</abbr> emploie différentes bibliothèques pour lire et écrire différents type d’objets.
- La bibliothèque utilisée dépend de la complexité de l’objet et des contraintes de performances.
- Par exemple les annotations de <abbr title="Java Architecture for XML Binding">JAXB</abbr> ont l’avantage d’être proches du code,
- ce qui facilite la maintenance de la correspondance entre le Java et le <abbr>XML</abbr>.
- En revanche <abbr title="Simple API for XML">SAX</abbr> a l’avantage d’être performant.
- De manière générale, Apache <abbr>SIS</abbr> emploie:
- </p>
- <ul>
- <li>
- <abbr title="Java Architecture for XML Binding">JAXB</abbr> pour les objets qui ne sont pas répétés très souvent dans le document
- mais dont la structure est complexe, avec des arborescences profondes.
- L’ensemble des méta-données <abbr>ISO</abbr> 19115-3 est un exemple typique.
- </li>
- <li>
- <abbr title="Simple API for XML">SAX</abbr> pour les objets relativement simples mais pouvant exister en très grand nombre.
- L’ensemble des points dans une géométrie est un exemple typique.
- </li>
- <li>
- <abbr title="Document Object Model">DOM</abbr> comme une alternative à <abbr title="Java Architecture for XML Binding">JAXB</abbr>
- lorsque les éléments <abbr>XML</abbr> ne correspondent pas directement à des attributs Java.
- Les <i>features</i> en sont un exemple, car leur structure est dynamique.
- </li>
- </ul>
+<h2>Outils de lecture et d’écriture de documents <abbr>XML</abbr></h2>
+<p>
+Apache <abbr title="Spatial Information System">SIS</abbr> emploie différentes bibliothèques pour lire et écrire différents type d’objets.
+La bibliothèque utilisée dépend de la complexité de l’objet et des contraintes de performances.
+Par exemple les annotations de <abbr title="Java Architecture for XML Binding">JAXB</abbr> ont l’avantage d’être proches du code,
+ce qui facilite la maintenance de la correspondance entre le Java et le <abbr>XML</abbr>.
+En revanche <abbr title="Simple API for XML">SAX</abbr> a l’avantage d’être performant.
+De manière générale, Apache <abbr>SIS</abbr> emploie:
+</p>
+<ul>
+<li>
+<abbr>JAXB</abbr> pour les objets qui ne sont pas répétés très souvent dans le document
+mais dont la structure est complexe, avec des arborescences profondes.
+L’ensemble des méta-données <abbr title="International Organization for Standardization">ISO</abbr> 19115-3 est un exemple typique.
+</li>
+<li>
+<abbr>SAX</abbr> pour les objets relativement simples mais pouvant exister en très grand nombre.
+L’ensemble des points dans une géométrie est un exemple typique.
+</li>
+<li>
+<abbr title="Document Object Model">DOM</abbr> comme une alternative à <abbr>JAXB</abbr>
+lorsque les éléments <abbr>XML</abbr> ne correspondent pas directement à des attributs Java.
+Les <i>features</i> en sont un exemple, car leur structure est dynamique.
+</li>
+</ul>
</aside>
-<h2 id="XML-ISO-19115">Représentation des méta-données selon <abbr>ISO</abbr> 19115-3</h2>
+<h2 id="XML-ISO-19115"><span class="section-number">3.1.</span> Représentation des méta-données selon <abbr title="International Organization for Standardization">ISO</abbr> 19115-3</h2>
<p>
- Pour chaque classe de méta-donnée, il existe un type <abbr>XML</abbr> portant le même nom que dans la spécification abstraite
- (par exemple <code class="OGC">gmd:MD_Metadata</code> et <code class="OGC">gmd:CI_Citation</code>).
- Tous ces types peuvent être employés comme racine d’un document <abbr>XML</abbr>.
- Ainsi, il est possible d’écrire un document représentant un objet <code class="OGC">MD_Metadata</code> complet,
- ou d’écrire un document représentant seulement un objet <code class="OGC">CI_Citation</code>.
+Pour chaque classe de méta-donnée, il existe un type <abbr>XML</abbr> portant le même nom que dans la spécification abstraite
+(par exemple <code class="OGC">gmd:MD_Metadata</code> et <code class="OGC">gmd:CI_Citation</code>).
+Tous ces types peuvent être employés comme racine d’un document <abbr>XML</abbr>.
+Ainsi, il est possible d’écrire un document représentant un objet <code class="OGC">MD_Metadata</code> complet,
+ou d’écrire un document représentant seulement un objet <code class="OGC">CI_Citation</code>.
</p>
<p>
- Le standard <abbr>ISO</abbr> 19139 dispose le contenu de ces objets d’une manière inhabituelle:
- pour chaque propriété dont le type de la valeur est lui-même une autre classe du standard <abbr>ISO</abbr> 19139,
- la valeur est enveloppée dans un élément qui représente son type plutôt que d’être écrite directement.
- Par exemple dans un objet de type <code class="OGC">CI_Citation</code>,
- la valeur de la propriété <code class="OGC">citedResponsibleParty</code>
- est enveloppée dans un élément <code class="OGC">CI_Responsibility</code>.
- Cette pratique double la profondeur de l’arborescence, en introduisant une duplication
- à tous les niveaux pour chaque valeur, comme dans l’exemple suivant:
+Le standard <abbr>ISO</abbr> 19139 dispose le contenu de ces objets d’une manière inhabituelle:
+pour chaque propriété dont le type de la valeur est lui-même une autre classe du standard <abbr>ISO</abbr> 19139,
+la valeur est enveloppée dans un élément qui représente son type plutôt que d’être écrite directement.
+Par exemple dans un objet de type <code class="OGC">CI_Citation</code>,
+la valeur de la propriété <code class="OGC">citedResponsibleParty</code>
+est enveloppée dans un élément <code class="OGC">CI_Responsibility</code>.
+Cette pratique double la profondeur de l’arborescence, en introduisant une duplication
+à tous les niveaux pour chaque valeur, comme dans l’exemple suivant:
</p>
-<pre><b><MD_Metadata></b>
+
+<pre class="xml"><b><MD_Metadata></b>
<identificationInfo>
<b><MD_DataIdentification></b>
<citation>
@@ -1551,729 +1510,736 @@ System.out.println("L’interface GeoAPI pour le type <abbr>ISO</abbr> " + <var>
<b></MD_Metadata></b></pre>
<p>
- L’exemple précédent, comme tous les documents conformes à <abbr>ISO</abbr> 19139,
- est donc constitué d’une alternance systématique de deux types d’éléments <abbr>XML</abbr> imbriqués:
+L’exemple précédent, comme tous les documents conformes à <abbr>ISO</abbr> 19139,
+est donc constitué d’une alternance systématique de deux types d’éléments <abbr>XML</abbr> imbriqués:
</p>
<ol>
- <li><p>
- Il y a d’abord le nom de la propriété, qui commence toujours par une lettre minuscule (en ignorant les préfixes).
- Dans les <abbr title="Application Programming Interface">API</abbr> Java, chaque propriété correspond à une méthode de la classe englobante.
- Dans l’exemple ci-haut, <code class="OGC">gmd:identificationInfo</code>
- (une propriété de la classe <code class="OGC">MD_Metadata</code>)
- correspond à la méthode <code class="GeoAPI">Metadata.getIdentificationInfo()</code>.
- </p></li>
- <li><p>
- Sous chaque propriété se trouve le type de la valeur, sauf si elle a été remplacée par une référence
- (la <a href="#gco-id">sous-section suivante</a> suivante approfondira ce sujet).
- Le type de la valeur est un élément <abbr>XML</abbr> dont le nom commence toujours par une lettre majuscule, en ignorant les préfixes.
- Dans l’exemple ci-haut nous avions <code class="OGC">MD_DataIdentification</code>, qui correspond à l’interface Java <code class="GeoAPI">DataIdentification</code>.
- C’est cet élément <abbr>XML</abbr> qui contient les valeurs de la propriété.
- </p></li>
+<li><p>
+Il y a d’abord le nom de la propriété, qui commence toujours par une lettre minuscule (en ignorant les préfixes).
+Dans les <abbr title="Application Programming Interface">API</abbr> Java, chaque propriété correspond à une méthode de la classe englobante.
+Dans l’exemple ci-haut, <code class="OGC">gmd:identificationInfo</code> (une propriété de la classe <code class="OGC">MD_Metadata</code>)
+correspond à la méthode <code class="GeoAPI">Metadata.getIdentificationInfo()</code>.
+</p></li>
+<li><p>
+Sous chaque propriété se trouve le type de la valeur, sauf si elle a été remplacée par une référence
+(la <a href="#gco-id">sous-section suivante</a> suivante approfondira ce sujet).
+Le type de la valeur est un élément <abbr>XML</abbr> dont le nom commence toujours par une lettre majuscule, en ignorant les préfixes.
+Dans l’exemple ci-haut nous avions <code class="OGC">MD_DataIdentification</code>, qui correspond à l’interface Java <code class="GeoAPI">DataIdentification</code>.
+C’est cet élément <abbr>XML</abbr> qui contient les valeurs de la propriété.
+</p></li>
</ol>
<p>
- Afin de réduire la complexité des bibliothèques, GeoAPI et Apache <abbr title="Spatial Information System">SIS</abbr>
- n’exposent publiquement qu’une vision unifiée de ces deux types d’éléments.
- L’<abbr title="Application Programming Interface">API</abbr> public correspond essentiellement au
- deuxième groupe. Toutefois, lors de l’écriture d’un document <abbr>XML</abbr>, des éléments du premier groupe
- doivent être temporairement recréés.
- Les classes qui y correspondent sont définies dans des paquets internes de <abbr title="Spatial Information System">SIS</abbr>.
- Ces classes peuvent être ignorées, sauf si le développeur souhaite implémenter ses propres
- classes dont les instances devront être lues et écrites par <abbr title="Java Architecture for XML Binding">JAXB</abbr>.
+Afin de réduire la complexité des bibliothèques, GeoAPI et Apache <abbr title="Spatial Information System">SIS</abbr>
+n’exposent publiquement qu’une vision unifiée de ces deux types d’éléments.
+L’<abbr>API</abbr> public correspond essentiellement au deuxième groupe.
+Toutefois, lors de l’écriture d’un document <abbr>XML</abbr>, des éléments du premier groupe doivent être temporairement recréés.
+Les classes qui y correspondent sont définies dans des paquets internes de <abbr>SIS</abbr>.
+Ces classes peuvent être ignorées, sauf si le développeur souhaite implémenter ses propres classes
+dont les instances devront être lues et écrites par <abbr title="Java Architecture for XML Binding">JAXB</abbr>.
</p>
<aside>
- <p><b>Stratégie d’implémentation dans Apache <abbr>SIS</abbr></b></p>
- <p>
- Les paquets <code class="SIS">org.apache.sis.internal.jaxb.*</code> (non-publiques)
- définissent des adaptateurs <abbr title="Java Architecture for XML Binding">JAXB</abbr> pour tous les types d’objet <abbr>ISO</abbr>.
- Ces adaptateurs sont de toute façon nécessaires pour permettre à <abbr>JAXB</abbr>
- d’obtenir les classes <abbr title="Spatial Information System">SIS</abbr> implémentant les interfaces de GeoAPI.
- De manière opportuniste, <abbr>SIS</abbr> en fait à la fois des adaptateurs <abbr>JAXB</abbr>
- et des objets enveloppants le “vrai” objet à lire ou écrire.
- Cette utilisation double permet d’éviter d’avoir à doubler le nombre de classes
- (déjà très élevé) présents dans les paquets internes.
- </p>
- <p><b>Convention de nommage dans les schémas <abbr>XSD</abbr></b></p>
- <p>
- Les schémas <abbr title="XML Schema Definition">XSD</abbr> de l’<abbr title="Open Geospatial Consortium">OGC</abbr>
- définissent pour chaque élément du premier groupe un type dont le nom se termine par “<code class="OGC">_PropertyType</code>”.
- Pour le second groupe, chaque élément a un type dont le nom se termine par “<code class="OGC">_Type</code>”.
- Les “<code class="OGC">_PropertyType</code>” peuvent avoir un groupe d’attributs
- (notamment <code class="OGC">gmd:idref</code>, <code class="OGC">gco:uuidref</code> et <code>xlink:href</code>)
- que les schémas <abbr>XSD</abbr> nomment collectivement <code class="OGC">gco:ObjectReference</code>.
- Ces attributs n’ont pas de méthodes Java dédiées, mais sont accessibles indirectement via l’interface
- <code class="SIS">IdentifiedObject</code> décrite dans la sous-section suivante.
- </p>
+<h3>Stratégie d’implémentation dans Apache <abbr title="Spatial Information System">SIS</abbr></h3>
+<p>
+Les paquets <code class="SIS">org.apache.sis.internal.jaxb.*</code> (non-publiques)
+définissent des adaptateurs <abbr title="Java Architecture for XML Binding">JAXB</abbr> pour tous les types d’objet <abbr title="International Organization for Standardization">ISO</abbr>.
+Ces adaptateurs sont de toute façon nécessaires pour permettre à <abbr>JAXB</abbr>
+d’obtenir les classes <abbr>SIS</abbr> implémentant les interfaces de GeoAPI.
+De manière opportuniste, <abbr>SIS</abbr> en fait à la fois des adaptateurs <abbr>JAXB</abbr>
+et des objets enveloppants le “vrai” objet à lire ou écrire.
+Cette utilisation double permet d’éviter d’avoir à doubler le nombre de classes
+(déjà très élevé) présents dans les paquets internes.
+</p>
+<h4>Convention de nommage dans les schémas <abbr title="XML Schema Definition">XSD</abbr></h4>
+<p>
+Les schémas <abbr>XSD</abbr> de l’<abbr title="Open Geospatial Consortium">OGC</abbr> définissent pour chaque élément du premier groupe
+un type dont le nom se termine par “<code class="OGC">_PropertyType</code>”.
+Pour le second groupe, chaque élément a un type dont le nom se termine par “<code class="OGC">_Type</code>”.
+Les “<code class="OGC">_PropertyType</code>” peuvent avoir un groupe d’attributs
+(notamment <code class="OGC">gmd:idref</code>, <code class="OGC">gco:uuidref</code> et <code>xlink:href</code>)
+que les schémas <abbr>XSD</abbr> nomment collectivement <code class="OGC">gco:ObjectReference</code>.
+Ces attributs n’ont pas de méthodes Java dédiées, mais sont accessibles indirectement via l’interface
+<code class="SIS">IdentifiedObject</code> décrite dans la sous-section suivante.
+</p>
</aside>
-<h3 id="gco-id">Identification d’instances déjà définies</h3>
+<h3 id="gco-id"><span class="section-number">3.1.1.</span> Identification d’instances déjà définies</h3>
<p>
- L’élément englobant peut contenir un attribut <code class="OGC">id</code>,
- <code class="OGC">uuid</code> ou <code>xlink:href</code>.
- Si un de ces attributs est présent, l’élément englobé peut être complètement omis;
- il sera remplacé au moment de la lecture par l’élément référencé par l’attribut.
- Dans l’exemple suivant, la partie gauche définie un élément associé à l’identifiant “<code>mon_id</code>”,
- alors que la partie droite référence cet élément:
+L’élément englobant peut contenir un attribut <code class="OGC">id</code>,
+<code class="OGC">uuid</code> ou <code>xlink:href</code>.
+Si un de ces attributs est présent, l’élément englobé peut être complètement omis;
+il sera remplacé au moment de la lecture par l’élément référencé par l’attribut.
+Dans l’exemple suivant, la partie gauche définie un élément associé à l’identifiant “<code>mon_id</code>”,
+alors que la partie droite référence cet élément:
</p>
<table class="hidden">
- <tr>
- <th>Définir un identifiant</th>
- <th>Utiliser l’identifiant défini</th>
- </tr>
- <tr>
- <td>
- <pre style="margin-top: 6pt"><MD_MetaData>
+<tr>
+<th>Définir un identifiant</th>
+<th>Utiliser l’identifiant défini</th>
+</tr>
+<tr>
+<td>
+<pre class="xml" style="margin-top: 6pt"><MD_MetaData>
<identificationInfo>
- <MD_DataIdentification id="<b>mon_id</b>">
+ <MD_DataIdentification id=<i>"<b>mon_id</b>"</i>>
<code class="comment"><!-- insérer ici des propriétés filles --></code>
</MD_DataIdentification>
</identificationInfo>
</MD_MetaData></pre>
- </td>
- <td>
- <pre style="margin-top: 6pt"><MD_MetaData>
- <identificationInfo idref="<b>mon_id</b>"/>
+</td>
+<td>
+<pre class="xml" style="margin-top: 6pt"><MD_MetaData>
+ <identificationInfo idref=<i>"<b>mon_id</b>"</i>/>
</MD_MetaData></pre>
- </td>
- </tr>
+</td>
+</tr>
</table>
<p>
- Le choix de l’attribut à utiliser dépend de la portée de l’élément référencé:
+Le choix de l’attribut à utiliser dépend de la portée de l’élément référencé:
</p>
<ul>
- <li>
- <code class="OGC">id</code> n’est valide qu’à l’intérieur du document <abbr>XML</abbr>
- qui définit l’objet ainsi référencé.
- </li>
- <li>
- <code class="OGC">uuid</code> peut être valide à l’extérieur du document <abbr>XML</abbr>,
- mais quelqu’un doit maintenir une base de données fournissant les objets pour chaque UUID donnés.
- </li>
- <li>
- <code>xlink:href</code> peut faire référence à un autre document <abbr>XML</abbr> accessible sur internet.
- </li>
+<li>
+<code class="OGC">id</code> n’est valide qu’à l’intérieur du document <abbr>XML</abbr>
+qui définit l’objet ainsi référencé.
+</li>
+<li>
+<code class="OGC">uuid</code> peut être valide à l’extérieur du document <abbr>XML</abbr>,
+mais quelqu’un doit maintenir une base de données fournissant les objets pour chaque UUID donnés.
+</li>
+<li>
+<code>xlink:href</code> peut faire référence à un autre document <abbr>XML</abbr> accessible sur internet.
+</li>
</ul>
<p>
- Dans la bibliothèque <abbr title="Spatial Information System">SIS</abbr>,
- tous les objets susceptibles d’être identifiés dans un document <abbr>XML</abbr>
- implémentent l’interface <code class="SIS">org.apache.sis.xml.IdentifiedObject</code>.
- Chaque instance de cette interface fournit une vue de ses identifiants sous forme de <code>Map<Citation,String></code>,
- dans lequel la clé <code class="GeoAPI">Citation</code> identifie le type d’identifiant et la valeur est l’identifiant lui-même.
- Quelques constantes représentant différents types d’identifiants sont énumérées dans <code class="SIS">IdentifierSpace</code>,
- notamment <code class="SIS">ID</code>, <code class="SIS">UUID</code> et <code class="SIS">HREF</code>.
- Chacune de ces clés peut être associée à une valeur d’un type différent (habituellement <code>String</code>,
- <code>UUID</code> ou <code>URI</code>) selon la clé.
- Par exemple le code suivant définit une valeur pour l’attribut <code class="OGC">uuid</code>:
+Dans la bibliothèque <abbr title="Spatial Information System">SIS</abbr>, tous les objets susceptibles d’être identifiés dans un document <abbr>XML</abbr>
+implémentent l’interface <code class="SIS">org.apache.sis.xml.IdentifiedObject</code>.
+Chaque instance de cette interface fournit une vue de ses identifiants sous forme de <code>Map<Citation,String></code>,
+dans lequel la clé <code class="GeoAPI">Citation</code> identifie le type d’identifiant et la valeur est l’identifiant lui-même.
+Quelques constantes représentant différents types d’identifiants sont énumérées dans <code class="SIS">IdentifierSpace</code>,
+notamment <code class="SIS">ID</code>, <code class="SIS">UUID</code> et <code class="SIS">HREF</code>.
+Chacune de ces clés peut être associée à une valeur d’un type différent (habituellement <code>String</code>,
+<code>UUID</code> ou <code>URI</code>) selon la clé.
+Par exemple le code suivant définit une valeur pour l’attribut <code class="OGC">uuid</code>:
</p>
-<pre><b>import</b> <code class="SIS">org.apache.sis.metadata.iso.DefaultMetadata</code>;
-<b>import</b> <code class="SIS">org.apache.sis.xml.IdentifierSpace</code>;
+<pre><b>import</b> org.apache.sis.metadata.iso.<code class="SIS">DefaultMetadata</code>;
+<b>import</b> org.apache.sis.xml.<code class="SIS">IdentifierSpace</code>;
<b>import</b> java.util.UUID;
-<b>public class</b> MyClass {
- <b>public void</b> myMethod() {
- UUID <var>identifier</var> = UUID.randomUUID();
- <code class="SIS">DefaultMetadata</code> <var>metadata</var> = <b>new</b> <code class="SIS">DefaultMetadata</code>();
- <var>metadata</var>.<code class="SIS">getIdentifierMap().putSpecialized</code>(<code class="SIS">IdentifierSpace.UUID</code>, <var>identifier</var>);
+<b>public</b> <b>class</b> MyClass {
+ <b>public</b> <b>void</b> myMethod() {
+ UUID identifier = UUID.randomUUID();
+ <code class="SIS"><code class="SIS">DefaultMetadata</code></code> metadata = <b>new</b> <code class="SIS"><code class="SIS">DefaultMetadata</code></code>();
+ metadata.<code class="SIS">getIdentifierMap().putSpecialized</code>(<code class="SIS">IdentifierSpace</code>.UUID, identifier);
}
}</pre>
<p>
- Bien que ce mécanisme aie été définit dans le but de mieux supporter les représentations des
- attributs <abbr>XML</abbr> du groupe <code class="OGC">gco:ObjectIdentification</code>,
- il permet aussi de manière opportuniste de manipuler d’autres types d’identifiants.
- Par exemple les attributs <code class="GeoAPI">ISBN</code> et <code class="GeoAPI">ISSN</code>
- de <code class="GeoAPI">Citation</code> peuvent être manipulés de cette manière.
- Les méthodes de l’interface <code class="SIS">IdentifiedObject</code> fournissent donc un endroit unique
- où peuvent être manipulés tous types d’identifiants (pas seulement <abbr>XML</abbr>) associés à un objet.
+Bien que ce mécanisme aie été définit dans le but de mieux supporter les représentations des
+attributs <abbr>XML</abbr> du groupe <code class="OGC">gco:ObjectIdentification</code>,
+il permet aussi de manière opportuniste de manipuler d’autres types d’identifiants.
+Par exemple les attributs <code class="GeoAPI">ISBN</code> et <code class="GeoAPI">ISSN</code>
+de <code class="GeoAPI">Citation</code> peuvent être manipulés de cette manière.
+Les méthodes de l’interface <code class="SIS">IdentifiedObject</code> fournissent donc un endroit unique
+où peuvent être manipulés tous types d’identifiants (pas seulement <abbr>XML</abbr>) associés à un objet.
</p>
-<h3 id="nilReason">Représentation de valeurs manquantes</h3>
+<h3 id="nilReason"><span class="section-number">3.1.2.</span> Représentation de valeurs manquantes</h3>
<p>
- Lorsqu’une propriété n’est pas définie, la méthode correspondante de GeoAPI retourne généralement <code>null</code>.
- Toutefois les choses se compliquent lorsque la propriété manquante est une valeur considérée comme obligatoire par le standard <abbr>ISO</abbr> 19115.
- Le standard <abbr>ISO</abbr> 19139 autorise l’omission de propriétés obligatoires à la condition d’indiquer pourquoi la valeur est manquante.
- Les raisons peuvent être que la propriété ne s’applique pas (<code class="OGC">inapplicable</code>),
- que la valeur existe probablement mais n’est pas connue (<code class="OGC">unknown</code>),
- que la valeur pourrait ne pas exister (<code class="OGC">missing</code>),
- qu’elle ne peut pas être divulguée (<code class="OGC">withheld</code>), <i>etc.</i>
- La transmission de cette information nécessite l’utilisation d’un objet non-nul même lorsque la valeur est manquante.
- <abbr title="Spatial Information System">SIS</abbr> procède en retournant un objet qui, en plus d’implémenter l’interface GeoAPI attendue,
- implémente aussi l’interface <code class="SIS">org.apache.sis.xml.NilObject</code>.
- Cette interface marque les instances dont toutes les méthodes retournent une collection vide,
- un tableau vide, <code>null</code>, <code>NaN</code>, <code>0</code> ou <code>false</code>,
- dans cet ordre de préférence selon ce que les types de retours des méthodes permettent.
- Chaque instance implémentant <code class="SIS">NilObject</code> fournit une méthode
- <code class="SIS">getNilReason()</code> indiquant pourquoi l’objet est nul.
+Lorsqu’une propriété n’est pas définie, la méthode correspondante de GeoAPI retourne généralement <code>null</code>.
+Toutefois les choses se compliquent lorsque la propriété manquante est une valeur considérée comme obligatoire par le standard <abbr title="International Organization for Standardization">ISO</abbr> 19115.
+Le standard <abbr>ISO</abbr> 19139 autorise l’omission de propriétés obligatoires à la condition d’indiquer pourquoi la valeur est manquante.
+Les raisons peuvent être que la propriété ne s’applique pas (<code class="OGC">inapplicable</code>),
+que la valeur existe probablement mais n’est pas connue (<code class="OGC">unknown</code>),
+que la valeur pourrait ne pas exister (<code class="OGC">missing</code>),
+qu’elle ne peut pas être divulguée (<code class="OGC">withheld</code>), <i>etc.</i>
+La transmission de cette information nécessite l’utilisation d’un objet non-nul même lorsque la valeur est manquante.
+<abbr title="Spatial Information System">SIS</abbr> procède en retournant un objet qui, en plus d’implémenter l’interface GeoAPI attendue,
+implémente aussi l’interface <code class="SIS">org.apache.sis.xml.NilObject</code>.
+Cette interface marque les instances dont toutes les méthodes retournent une collection vide,
+un tableau vide, <code>null</code>, <code>NaN</code>, <code>0</code> ou <code>false</code>,
+dans cet ordre de préférence selon ce que les types de retours des méthodes permettent.
+Chaque instance implémentant <code class="SIS">NilObject</code> fournit une méthode
+<code class="SIS">getNilReason()</code> indiquant pourquoi l’objet est nul.
</p>
<p>
- Dans l’exemple suivant, la partie gauche montre un élément <code class="OGC">CI_Citation</code>
- contenant un élément <code class="OGC">CI_Series</code>, alors que dans la partie droite la série est inconnue.
- Si l’élément <code class="OGC">CI_Series</code> avait été complètement omis,
- alors la méthode <code class="GeoAPI">Citation.getSeries()</code> retournerait <code>null</code> en Java.
- Mais en présence d’un attribut <code class="OGC">nilReason</code>, l’implémentation <abbr title="Spatial Information System">SIS</abbr>
- de <code class="SIS">getSeries()</code> retournera plutôt un objet implémentant à la fois les interfaces
- <code class="GeoAPI">Series</code> et <code class="SIS">NilReason</code>,
- et dont la méthode <code class="SIS">getNilReason()</code> retournera la constante <code class="SIS">UNKNOWN</code>.
+Dans l’exemple suivant, la partie gauche montre un élément <code class="OGC">CI_Citation</code>
+contenant un élément <code class="OGC">CI_Series</code>, alors que dans la partie droite la série est inconnue.
+Si l’élément <code class="OGC">CI_Series</code> avait été complètement omis,
+alors la méthode <code class="GeoAPI">Citation.getSeries()</code> retournerait <code>null</code> en Java.
+Mais en présence d’un attribut <code class="OGC">nilReason</code>, l’implémentation <abbr>SIS</abbr>
+de <code class="SIS">getSeries()</code> retournera plutôt un objet implémentant à la fois les interfaces
+<code class="GeoAPI">Series</code> et <code class="SIS">NilReason</code>,
+et dont la méthode <code class="SIS">getNilReason()</code> retournera la constante <code class="SIS">UNKNOWN</code>.
</p>
<table class="hidden">
- <tr>
- <th>Information présente</th>
- <th>Information absente</th>
- </tr>
- <tr>
- <td>
- <pre style="margin-top: 6pt"><CI_Citation>
+<tr>
+<th>Information présente</th>
+<th>Information absente</th>
+</tr>
+<tr>
+<td>
+<pre class="xml" style="margin-top: 6pt"><CI_Citation>
<series>
<CI_Series>
<code class="comment"><!-- insérer ici des propriétés filles --></code>
</CI_Series>
</series>
</CI_Citation></pre>
- </td>
- <td>
- <pre style="margin-top: 6pt"><CI_Citation>
- <series nilReason="unknown"/>
+</td>
+<td>
+<pre class="xml" style="margin-top: 6pt"><CI_Citation>
+ <series nilReason=<i>"unknown"</i>/>
</CI_Citation></pre>
- </td>
- </tr>
+</td>
+</tr>
</table>
-
-
-
-<h1 id="Utilities">Classes et méthodes utilitaires</h1>
-<p>
- Ce chapitre décrit des aspects de Apache <abbr title="Spatial Information System">SIS</abbr> qui s’appliquent à l’ensemble de la bibliothèque.
- La plupart de ces utilitaires ne sont pas spécifiques aux systèmes d’information spatiales.
-</p>
-
-<h2 id="ComparisonMode">Modes de comparaisons des objets</h2>
-<p>
- Il existe différentes opinions sur la façon d’implémenter la méthode <code>Object.equals(Object)</code> du Java standard.
- Selon certains, il doit être possible de comparer différentes implémentations d’une même interface ou classe de base.
- Mais cette politique nécessite que chaque interface ou classe de base définisse entièrement dans sa Javadoc les critères ou calculs
- que doivent employer les méthodes <code>equals(Object)</code> et <code>hashCode()</code> dans toutes les implémentations.
- Cette approche est choisie notamment par <code>java.util.Collection</code> et ses interfaces filles.
- La transposition de cette approche aux centaines d’interfaces de GeoAPI serait toutefois une entreprise ardue,
- qui risquerait d’être assez peu suivie par les diverses implémentations.
- En outre, elle se fait au détriment de la possibilité de prendre en compte des attributs supplémentaires dans les interfaces filles
- si cette possibilité n’a pas été spécifiée dans l’interface parente.
- Cette contrainte découle des points suivants du contrat des méthodes <code>equals(Object)</code> et <code>hashCode()</code>:
+</section>
+<section>
+<header>
+<h1 id="Utilities"><span class="section-number">4.</span> Classes et méthodes utilitaires</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#XML-ISO">Chapitre suivant</a></div><div class="next-chapter"><a href="#Geometry">Chapitre précédent</a> ➡</div></div></nav>
+</header>
+<nav>Dans ce chapitre:<ul class="toc">
+<li><a href="#ComparisonMode">Modes de comparaisons des objets</a></li>
+<li><a href="#Internationalization">Internationalisation</a><ul>
+<li><a href="#LocalizedString">Chaînes de caractères distinctes pour chaque conventions locales</a></li>
+<li><a href="#InternationalString">Instance unique pour toutes les conventions locales</a></li>
+<li><a href="#Locale.ROOT">Convention Locale.ROOT</a></li>
+<li><a href="#UnicodePoint">Traitement des caractères</a><ul>
+<li><a href="#Whitespaces">Interprétation des espaces blancs</a></li></ul></li></ul></li></ul></nav>
+<p>
+Ce chapitre décrit des aspects de Apache <abbr title="Spatial Information System">SIS</abbr> qui s’appliquent à l’ensemble de la bibliothèque.
+La plupart de ces utilitaires ne sont pas spécifiques aux systèmes d’information spatiales.
+</p>
+
+<h2 id="ComparisonMode"><span class="section-number">4.1.</span> Modes de comparaisons des objets</h2>
+<p>
+Il existe différentes opinions sur la façon d’implémenter la méthode <code>Object.equals(Object)</code> du Java standard.
+Selon certains, il doit être possible de comparer différentes implémentations d’une même interface ou classe de base.
+Mais cette politique nécessite que chaque interface ou classe de base définisse entièrement dans sa Javadoc les critères ou calculs
+que doivent employer les méthodes <code>equals(Object)</code> et <code>hashCode()</code> dans toutes les implémentations.
+Cette approche est choisie notamment par <code>java.util.Collection</code> et ses interfaces filles.
+La transposition de cette approche aux centaines d’interfaces de GeoAPI serait toutefois une entreprise ardue,
+qui risquerait d’être assez peu suivie par les diverses implémentations.
+En outre, elle se fait au détriment de la possibilité de prendre en compte des attributs supplémentaires dans les interfaces filles
+si cette possibilité n’a pas été spécifiée dans l’interface parente.
+Cette contrainte découle des points suivants du contrat des méthodes <code>equals(Object)</code> et <code>hashCode()</code>:
</p>
<ul>
- <li><code>A.equals(B)</code> implique <code>B.equals(A)</code> (symétrie);</li>
- <li><code>A.equals(B)</code> et <code>B.equals(C)</code> implique <code>A.equals(C)</code> (transitivité);</li>
- <li><code>A.equals(B)</code> implique <code>A.hashCode() == B.hashCode()</code>.</li>
+<li><code>A.equals(B)</code> implique <code>B.equals(A)</code> (symétrie);</li>
+<li><code>A.equals(B)</code> et <code>B.equals(C)</code> implique <code>A.equals(C)</code> (transitivité);</li>
+<li><code>A.equals(B)</code> implique <code>A.hashCode() == B.hashCode()</code>.</li>
</ul>
<p>
- Par exemple ces trois contraintes sont violées si <var>A</var> (et éventuellement <var>C</var>)
- peuvent contenir des attributs que <var>B</var> ignore.
- Pour contourner cette difficulté, une approche alternative consiste à exiger que les objets comparés par la méthode
- <code>Object.equals(Object)</code> soient exactement de la même classe, c’est-à-dire que <code>A.getClass() == B.getClass()</code>.
- Cette approche est parfois considérée contraire aux principes de la programmation orientée objets.
- Dans la pratique, pour des applications relativement complexes, l’importance accordée à ces principes dépend du contexte dans lequel les objets sont comparés:
- si les objets sont ajoutés à un <code>HashSet</code> ou utilisés comme clés dans un <code>HashMap</code>,
- alors nous avons besoin d’un strict respect du contrat de <code>equals(Object)</code> et <code>hashCode()</code>.
- Mais si le développeur compare les objets lui-même, par exemple pour vérifier si des informations qui l’intéresse ont changées,
- alors les contraintes de symétrie, transitivité ou de cohérence avec les valeurs de hachages peuvent ne pas être pertinentes pour lui.
- Des comparaisons plus permissives peuvent être souhaitables, allant parfois jusqu’à tolérer de légers écarts dans les valeurs numériques.
+Par exemple ces trois contraintes sont violées si <var>A</var> (et éventuellement <var>C</var>)
+peuvent contenir des attributs que <var>B</var> ignore.
+Pour contourner cette difficulté, une approche alternative consiste à exiger que les objets comparés par la méthode
+<code>Object.equals(Object)</code> soient exactement de la même classe, c’est-à-dire que <code>A.getClass() == B.getClass()</code>.
+Cette approche est parfois considérée contraire aux principes de la programmation orientée objets.
+Dans la pratique, pour des applications relativement complexes, l’importance accordée à ces principes dépend du contexte dans lequel les objets sont comparés:
+si les objets sont ajoutés à un <code>HashSet</code> ou utilisés comme clés dans un <code>HashMap</code>,
+alors nous avons besoin d’un strict respect du contrat de <code>equals(Object)</code> et <code>hashCode()</code>.
+Mais si le développeur compare les objets lui-même, par exemple pour vérifier si des informations qui l’intéresse ont changées,
+alors les contraintes de symétrie, transitivité ou de cohérence avec les valeurs de hachages peuvent ne pas être pertinentes pour lui.
+Des comparaisons plus permissives peuvent être souhaitables, allant parfois jusqu’à tolérer de légers écarts dans les valeurs numériques.
</p>
<p>
- Afin de donner une certaine flexibilité aux développeurs, un grand nombre de classes de la bibliothèque <abbr title="Spatial Information System">SIS</abbr>
- implémentent l’interface <code class="SIS">org.apache.sis.util.LenientComparable</code>, qui défini une méthode <code class="SIS">equals(Object, ComparisonMode)</code>.
- Les principaux modes de comparaisons sont:
+Afin de donner une certaine flexibilité aux développeurs, un grand nombre de classes de la bibliothèque <abbr title="Spatial Information System">SIS</abbr>
+implémentent l’interface <code class="SIS">org.apache.sis.util.LenientComparable</code>, qui défini une méthode <code class="SIS">equals(Object, ComparisonMode)</code>.
+Les principaux modes de comparaisons sont:
</p>
<ul>
- <li><p>
- <b><code class="SIS">STRICT</code></b> — Les objets comparés doivent être de la même classe
- et tous leurs attributs strictement égaux, y compris d’éventuels attributs publics propres à l’implémentation.
- </p></li>
- <li><p>
- <b><code class="SIS">BY_CONTRACT</code></b> — Les objets comparés doivent implémenter la même interface de GeoAPI (ou tout autre standard),
- mais n’ont pas besoin d’être de la même classe d’implémentation. Seuls les attributs définis dans l’interface sont comparés;
- tout autres attributs propres à l’implémentation — même s’ils sont publics — sont ignorés.
- </p></li>
- <li><p>
- <b><code class="SIS">IGNORE_METADATA</code></b> — Comme <code class="SIS">BY_CONTRACT</code>,
- mais ne compare que les attributs qui influencent les opérations (calculs numériques ou autre) effectuées par l’objet.
- Par exemple dans un référentiel géodésique, la longitude (par rapport à Greenwich) du méridien d’origine sera pris en compte
- alors que le nom de ce méridien sera ignoré.
- </p></li>
- <li><p>
- <b><code class="SIS">APPROXIMATIVE</code></b> — Comme <code class="SIS">IGNORE_METADATA</code>,
- mais tolère de légères différences dans les valeurs numériques.
- </p></li>
+<li><p>
+<b><code class="SIS">STRICT</code></b> — Les objets comparés doivent être de la même classe
+et tous leurs attributs strictement égaux, y compris d’éventuels attributs publics propres à l’implémentation.
+</p></li>
+<li><p>
+<b><code class="SIS">BY_CONTRACT</code></b> — Les objets comparés doivent implémenter la même interface de GeoAPI (ou tout autre standard),
+mais n’ont pas besoin d’être de la même classe d’implémentation. Seuls les attributs définis dans l’interface sont comparés;
+tout autres attributs propres à l’implémentation — même s’ils sont publics — sont ignorés.
+</p></li>
+<li><p>
+<b><code class="SIS">IGNORE_METADATA</code></b> — Comme <code class="SIS">BY_CONTRACT</code>,
+mais ne compare que les attributs qui influencent les opérations (calculs numériques ou autre) effectuées par l’objet.
+Par exemple dans un référentiel géodésique, la longitude (par rapport à Greenwich) du méridien d’origine sera pris en compte
+alors que le nom de ce méridien sera ignoré.
+</p></li>
+<li><p>
+<b><code class="SIS">APPROXIMATIVE</code></b> — Comme <code class="SIS">IGNORE_METADATA</code>,
+mais tolère de légères différences dans les valeurs numériques.
+</p></li>
</ul>
<p>
- Le mode par défaut, utilisé par les toutes les méthodes <code>equals(Object)</code> de <abbr title="Spatial Information System">SIS</abbr>,
- est <code class="SIS">STRICT</code>. Ce mode est choisi pour une utilisation sécuritaire — notamment avec <code>HashMap</code> —
- sans nécessiter de définitions rigoureuses des méthodes <code>equals(Object)</code> et <code>hashCode()</code> dans toutes les interfaces.
- Avec ce mode, l’ordre des objets (<code>A.equals(B)</code> ou <code>B.equals(A)</code>) n’a pas d’importance.
- C’est toutefois le seul mode à offrir cette garantie.
- Dans l’expression <code>A.equals(B)</code>, le mode <code class="SIS">BY_CONTRACT</code>
- (et donc par extension tous les autres modes qui en dépendent) ne comparera que les propriétés connues de <code>A</code>,
- sans se soucier de savoir si <code>B</code> en connaît davantage.
+Le mode par défaut, utilisé par les toutes les méthodes <code>equals(Object)</code> de <abbr>SIS</abbr>,
+est <code class="SIS">STRICT</code>. Ce mode est choisi pour une utilisation sécuritaire — notamment avec <code>HashMap</code> —
+sans nécessiter de définitions rigoureuses des méthodes <code>equals(Object)</code> et <code>hashCode()</code> dans toutes les interfaces.
+Avec ce mode, l’ordre des objets (<code>A.equals(B)</code> ou <code>B.equals(A)</code>) n’a pas d’importance.
+C’est toutefois le seul mode à offrir cette garantie.
+Dans l’expression <code>A.equals(B)</code>, le mode <code class="SIS">BY_CONTRACT</code>
+(et donc par extension tous les autres modes qui en dépendent) ne comparera que les propriétés connues de <code>A</code>,
+sans se soucier de savoir si <code>B</code> en connaît davantage.
</p>
-<h2 id="Internationalization">Internationalisation</h2>
+<h2 id="Internationalization"><span class="section-number">4.2.</span> Internationalisation</h2>
<p>
- Dans une architecture où un programme exécuté sur un serveur fournit ses données à plusieurs clients,
- les conventions locales du serveur ne sont pas nécessairement les mêmes que celles des clients.
- Les conventions peuvent différer par la langue, mais aussi par la façon d’écrire les valeurs numériques
- (même entre deux pays parlant la même langue) ainsi que par le fuseau horaire.
- Pour produire des messages conformes aux conventions du client, <abbr title="Spatial Information System">SIS</abbr> emploie
- deux approches qui diffèrent par leur niveau de granularité: au niveau des messages eux-mêmes,
- ou au niveau des objets produisant les messages. L’approche utilisée détermine aussi s’il est
- possible de partager une même instance d’un objet pour toutes les langues.
+Dans une architecture où un programme exécuté sur un serveur fournit ses données à plusieurs clients,
+les conventions locales du serveur ne sont pas nécessairement les mêmes que celles des clients.
+Les conventions peuvent différer par la langue, mais aussi par la façon d’écrire les valeurs numériques
+(même entre deux pays parlant la même langue) ainsi que par le fuseau horaire.
+Pour produire des messages conformes aux conventions du client, <abbr title="Spatial Information System">SIS</abbr> emploie
+deux approches qui diffèrent par leur niveau de granularité: au niveau des messages eux-mêmes,
+ou au niveau des objets produisant les messages. L’approche utilisée détermine aussi s’il est
+possible de partager une même instance d’un objet pour toutes les langues.
</p>
-<h3 id="LocalizedString">Chaînes de caractères distinctes pour chaque conventions locales</h3>
+<h3 id="LocalizedString"><span class="section-number">4.2.1.</span> Chaînes de caractères distinctes pour chaque conventions locales</h3>
<p>
- Certaines classes ne sont conçues que pour fonctionner selon une convention locale à la fois.
- C’est évidemment le cas des implémentations standards de <code>java.text.Format</code>,
- puisqu’elles sont entièrement dédiées au travail d’internationalisation.
- Mais c’est aussi le cas de d’autres classes moins évidentes comme
- <code>javax.imageio.ImageReader</code>/<code>ImageWriter</code> ainsi que les sous-classes de <code>Exception</code>.
- Lorsque une de ces classes est implémentée par <abbr title="Spatial Information System">SIS</abbr>,
- nous l’identifions en implémentant l’interface <code class="SIS">org.apache.sis.util.Localized</code>.
- La méthode <code class="SIS">getLocale()</code> de cette interface permet alors de déterminer
- selon quelles conventions locales l’instance produira ses messages.
+Certaines classes ne sont conçues que pour fonctionner selon une convention locale à la fois.
+C’est évidemment le cas des implémentations standards de <code>java.text.Format</code>,
+puisqu’elles sont entièrement dédiées au travail d’internationalisation.
+Mais c’est aussi le cas de d’autres classes moins évidentes comme
+<code>javax.imageio.ImageReader</code>/<code>ImageWriter</code> ainsi que les sous-classes de <code>Exception</code>.
+Lorsque une de ces classes est implémentée par <abbr title="Spatial Information System">SIS</abbr>,
+nous l’identifions en implémentant l’interface <code class="SIS">org.apache.sis.util.Localized</code>.
+La méthode <code class="SIS">getLocale()</code> de cette interface permet alors de déterminer
+selon quelles conventions locales l’instance produira ses messages.
</p>
<p>
- Certaines sous-classes de <code>Exception</code> définies par <abbr title="Spatial Information System">SIS</abbr>
- implémentent aussi l’interface <code class="SIS">Localized</code>.
- Pour ces exceptions, le message d’erreur peut être produit selon deux conventions locales
- selon qu’il s’adresse à l’administrateur du système ou au client:
- <code>getMessage()</code> retourne le message de l’exception selon les conventions par défaut du système, alors que
- <code>getLocalizedMessage()</code> retourne le message de l’exception selon les conventions locales spécifiées par <code class="SIS">getLocale()</code>.
- Ce <code>Locale</code> sera lui-même déterminé par l’objet <code class="SIS">Localized</code> qui a lancé l’exception.
+Certaines sous-classes de <code>Exception</code> définies par <abbr>SIS</abbr> implémentent aussi l’interface <code class="SIS">Localized</code>.
+Pour ces exceptions, le message d’erreur peut être produit selon deux conventions locales selon qu’il s’adresse à l’administrateur du système ou au client:
+<code>getMessage()</code> retourne le message de l’exception selon les conventions par défaut du système, alors que
+<code>getLocalizedMessage()</code> retourne le message de l’exception selon les conventions locales spécifiées par <code class="SIS">getLocale()</code>.
+Ce <code>Locale</code> sera lui-même déterminé par l’objet <code class="SIS">Localized</code> qui a lancé l’exception.
</p>
<div class="example"><p><b>Exemple:</b>
- Supposons que dans un environnement où la langue par défaut serait l’anglais,
- un objet <code class="SIS">AngleFormat</code> est construit pour lire des angles selon les conventions françaises.
- Si une <code>ParseException</code> est lancée lors de l’utilisation de ce formateur,
- alors <code>getMessage()</code> retournera le message d’erreur en anglais
- tandis que <code>getLocalizedMessage()</code> retournera le message d’erreur en français.
+Supposons que dans un environnement où la langue par défaut serait l’anglais,
+un objet <code class="SIS">AngleFormat</code> est construit pour lire des angles selon les conventions françaises.
+Si une <code>ParseException</code> est lancée lors de l’utilisation de ce formateur,
+alors <code>getMessage()</code> retournera le message d’erreur en anglais
+tandis que <code>getLocalizedMessage()</code> retournera le message d’erreur en français.
</p></div>
<p>
- Les exceptions définies par <abbr title="Spatial Information System">SIS</abbr> n’implémentent pas toutes l’interface <code class="SIS">Localized</code>.
- Seules celles dont le message est le plus susceptible d’être montré à l’utilisateur sont ainsi localisées.
- Les <code>ParseException</code> sont de bonnes candidates puisqu’elles surviennent souvent
- suite à une saisie incorrecte du client. En revanche les <code>NullPointerException</code>
- sont généralement la conséquence d’une erreur de programmation;
- elles peuvent être localisées dans la langue par défaut du système, mais ça sera généralement tout.
+Les exceptions définies par <abbr>SIS</abbr> n’implémentent pas toutes l’interface <code class="SIS">Localized</code>.
+Seules celles dont le message est le plus susceptible d’être montré à l’utilisateur sont ainsi localisées.
+Les <code>ParseException</code> sont de bonnes candidates puisqu’elles surviennent souvent
+suite à une saisie incorrecte du client. En revanche les <code>NullPointerException</code>
+sont généralement la conséquence d’une erreur de programmation;
+elles peuvent être localisées dans la langue par défaut du système, mais ça sera généralement tout.
</p>
<p>
- La classe utilitaire <code class="SIS">org.apache.sis.util.Exceptions</code> fournit
- des méthodes de commodité pour obtenir des messages selon des conventions locales spécifiées
- lorsque cette information est disponible.
+La classe utilitaire <code class="SIS">org.apache.sis.util.Exceptions</code> fournit
+des méthodes de commodité pour obtenir des messages selon des conventions locales spécifiées
+lorsque cette information est disponible.
</p>
-<h3 id="InternationalString">Instance unique pour toutes les conventions locales</h3>
+<h3 id="InternationalString"><span class="section-number">4.2.2.</span> Instance unique pour toutes les conventions locales</h3>
<p>
- Les <abbr title="Application Programming Interface">API</abbr> définit par <abbr title="Spatial Information System">SIS</abbr>
- ou hérités de GeoAPI privilégient plutôt l’utilisation du type <code class="GeoAPI">InternationalString</code>
- là où une valeur de type <code>String</code> serait susceptible d’être localisée.
- Cette approche permet de différer le processus d’internationalisation au moment d’obtenir
- une chaîne de caractères plutôt qu’au moment de construire l’objet qui les contient.
- C’est particulièrement utile pour les classes immutables qui serviront à créer des instances uniques
- indépendamment des conventions locales.
+Les <abbr title="Application Programming Interface">API</abbr> définit par <abbr title="Spatial Information System">SIS</abbr> ou hérités de GeoAPI privilégient plutôt l’utilisation du type
+<code class="GeoAPI">InternationalString</code> là où une valeur de type <code>String</code> serait susceptible d’être localisée.
+Cette approche permet de différer le processus d’internationalisation au moment d’obtenir
+une chaîne de caractères plutôt qu’au moment de construire l’objet qui les contient.
+C’est particulièrement utile pour les classes immutables qui serviront à créer des instances uniques
+indépendamment des conventions locales.
</p>
<div class="example"><p><b>Exemple:</b>
- Il existe dans <abbr title="Spatial Information System">SIS</abbr> une seule instance de type
- <code class="GeoAPI">OperationMethod</code> représentant la projection de Mercator, quelle que soit la langue du client.
- Mais sa méthode <code class="GeoAPI">getName()</code> fournit (indirectement)
- une instance de <code class="GeoAPI">InternationalString</code> telle que
- <code>toString(Locale.ENGLISH)</code> retourne <cite>Mercator Projection</cite>
- alors que <code>toString(Locale.FRENCH)</code> retourne <cite>Projection de Mercator</cite>.
+Il existe dans <abbr>SIS</abbr> une seule instance de type
+<code class="GeoAPI">OperationMethod</code> représentant la projection de Mercator, quelle que soit la langue du client.
+Mais sa méthode <code class="GeoAPI">getName()</code> fournit (indirectement)
+une instance de <code class="GeoAPI">InternationalString</code> telle que
+<code>toString(Locale.ENGLISH)</code> retourne <cite>Mercator Projection</cite>
+alors que <code>toString(Locale.FRENCH)</code> retourne <cite>Projection de Mercator</cite>.
</p></div>
<p>
- En définissant des objets spatiaux indépendemment des conventions locales, on réduit les risques de sur-coûts de calculs.
- Par exemple il est plus facile de détecter que deux cartes emploient la même projection cartographique si cette dernière
- est représentée par la même instance de <code class="GeoAPI">CoordinateOperation</code>, même si la projection
- porte différents noms selon les pays. En outre, certain types de <code class="GeoAPI">CoordinateOperation</code>
- peuvent nécessiter des grilles de transformation de coordonnées, ce qui accroît l’intérêt de partager une instance unique
- pour des raisons d’économie de mémoire.
+En définissant des objets spatiaux indépendemment des conventions locales, on réduit les risques de sur-coûts de calculs.
+Par exemple il est plus facile de détecter que deux cartes emploient la même projection cartographique si cette dernière
+est représentée par la même instance de <code class="GeoAPI">CoordinateOperation</code>, même si la projection
+porte différents noms selon les pays. En outre, certain types de <code class="GeoAPI">CoordinateOperation</code>
+peuvent nécessiter des grilles de transformation de coordonnées, ce qui accroît l’intérêt de partager une instance unique
+pour des raisons d’économie de mémoire.
</p>
-<h3 id="Locale.ROOT">Convention <code>Locale.ROOT</code></h3>
+<h3 id="Locale.ROOT"><span class="section-number">4.2.3.</span> Convention <code>Locale.ROOT</code></h3>
<p>
- Toutes les méthodes <abbr title="Spatial Information System">SIS</abbr> recevant ou retournant une valeur de type <code>Locale</code>
- acceptent la valeur <code>Locale.ROOT</code>. Cette valeur est interprétée comme signifiant de ne pas localiser le texte.
- La notion de <cite>texte non-localisé</cite> est un peu fausse, puisqu’il faut bien choisir une convention de format.
- Mais cette convention, bien que très proche de l’anglais, sera généralement légèrement différente.
- Par exemple:
+Toutes les méthodes <abbr title="Spatial Information System">SIS</abbr> recevant ou retournant une valeur de type <code>Locale</code>
+acceptent la valeur <code>Locale.ROOT</code>. Cette valeur est interprétée comme signifiant de ne pas localiser le texte.
+La notion de <cite>texte non-localisé</cite> est un peu fausse, puisqu’il faut bien choisir une convention de format.
+Mais cette convention, bien que très proche de l’anglais, sera généralement légèrement différente.
+Par exemple:
</p>
<ul>
- <li>
- Les identifiants sont écrits tels qu’ils apparaissent dans les diagrammes <abbr title="Unified Modeling Language">UML</abbr>,
- par exemple <cite>blurredImage</cite> au lieu de <cite>Blurred image</cite>.
- </li>
- <li>
- Les dates sont écrites selon le format <abbr>ISO</abbr> 8601,
- qui ne correspond pas aux conventions anglaises.
- </li>
- <li>
- Les nombres sont écrits à l’aide de leurs méthodes <code>toString()</code> plutôt qu’à l’aide d’un <code>java.text.NumberFormat</code>.
- Il en résulte des différences dans le nombre de chiffres significatifs, l’utilisation de la notation exponentielle et l’absence de séparateur des milliers.
- </li>
+<li>
+Les identifiants sont écrits tels qu’ils apparaissent dans les diagrammes <abbr title="Unified Modeling Language">UML</abbr>,
+par exemple <cite>blurredImage</cite> au lieu de <cite>Blurred image</cite>.
+</li>
+<li>
+Les dates sont écrites selon le format <abbr title="International Organization for Standardization">ISO</abbr> 8601,
+qui ne correspond pas aux conventions anglaises.
+</li>
+<li>
+Les nombres sont écrits à l’aide de leurs méthodes <code>toString()</code> plutôt qu’à l’aide d’un <code>java.text.NumberFormat</code>.
+Il en résulte des différences dans le nombre de chiffres significatifs, l’utilisation de la notation exponentielle et l’absence de séparateur des milliers.
+</li>
</ul>
-<h3 id="UnicodePoint">Traitement des caractères</h3>
+<h3 id="UnicodePoint"><span class="section-number">4.2.4.</span> Traitement des caractères</h3>
<p>
- Les chaînes de caractères en Java utilisent l’encodage UTF-16. Il existe une correspondance directe
- entre les valeurs de type <code>char</code> et la très grande majorité des caractères, ce
- qui facilite l’utilisation des chaînes lorsque ces caractères suffisent.
- Mais certains caractères Unicode ne sont pas représentables par un seul <code>char</code>.
- Ces <i>caractères supplémentaires</i> comprennent certains idéogrammes,
- mais aussi des symboles routiers et géographiques dans la plage 1F680 à 1F700.
- Le support de ces caractères supplémentaires nécessite des itérations un peu plus complexes
- que le cas classique où l’on supposait une correspondance directe.
- Ainsi, au lieu de la boucle de gauche ci-dessous, les applications internationales devraient
- généralement utiliser la boucle de droite:
+Les chaînes de caractères en Java utilisent l’encodage UTF-16. Il existe une correspondance directe
+entre les valeurs de type <code>char</code> et la très grande majorité des caractères, ce
+qui facilite l’utilisation des chaînes lorsque ces caractères suffisent.
+Mais certains caractères Unicode ne sont pas représentables par un seul <code>char</code>.
+Ces <i>caractères supplémentaires</i> comprennent certains idéogrammes,
+mais aussi des symboles routiers et géographiques dans la plage 1F680 à 1F700.
+Le support de ces caractères supplémentaires nécessite des itérations un peu plus complexes
+que le cas classique où l’on supposait une correspondance directe.
+Ainsi, au lieu de la boucle de gauche ci-dessous, les applications internationales devraient
+généralement utiliser la boucle de droite:
</p>
<table class="hidden">
- <tr>
- <th>Boucle à éviter</th>
- <th>Boucle recommandée</th>
- </tr>
- <tr>
- <td>
- <pre style="margin-top: 6pt"><b>for</b> (<b>int</b> <var>i</var>=0; <var>i</var><<var>string</var>.length(); <var>i</var>++) {
- <b>char</b> <var>c</var> = <var>string</var>.charAt(<var>i</var>);
- <b>if</b> (Character.isWhitespace(<var>c</var>)) {
- <code class="comment">// Un espace blanc a été trouvé.</code>
- }
+<tr>
+<th>Boucle à éviter</th>
+<th>Boucle recommandée</th>
+</tr>
+<tr>
+<td>
+<pre style="margin-top: 6pt"><b>for</b> (<b>int</b> i=0; i<string.length(); i++) {
+ <b>char</b> c = string.charAt(i);
+ <b>if</b> (Character.isWhitespace(c)) {
+ <code class="comment">// Un espace blanc a été trouvé.
+</code> }
}</pre>
- </td>
- <td>
- <pre style="margin-top: 6pt"><b>for</b> (<b>int</b> <var>i</var>=0; <var>i</var><<var>string</var>.length();) {
- <b>int</b> <var>c</var> = <var>string</var>.codePointAt(<var>i</var>);
- <b>if</b> (Character.isWhitespace(<var>c</var>)) {
- <code class="comment">// Un espace blanc a été trouvé.</code>
- }
- <var>i</var> += Character.charCount(<var>c</var>);
+</td>
+<td>
+<pre style="margin-top: 6pt"><b>for</b> (<b>int</b> i=0; i<string.length();) {
+ <b>int</b> c = string.codePointAt(i);
+ <b>if</b> (Character.isWhitespace(c)) {
+ <code class="comment">// Un espace blanc a été trouvé.
+</code> }
+ i += Character.charCount(c);
}</pre>
- </td>
- </tr>
+</td>
+</tr>
</table>
<p>
- <abbr title="Spatial Information System">SIS</abbr> supporte les caractères supplémentaires en utilisant la boucle de droite lorsque nécessaire.
- Mais la boucle de gauche reste occasionnellement utilisée lorsqu’il est connu que les caractères recherchés ne sont
- pas des caractères supplémentaires, même si la chaîne dans laquelle on fait la recherche peut en contenir.
+<abbr title="Spatial Information System">SIS</abbr> supporte les caractères supplémentaires en utilisant la boucle de droite lorsque nécessaire.
+Mais la boucle de gauche reste occasionnellement utilisée lorsqu’il est connu que les caractères recherchés ne sont
+pas des caractères supplémentaires, même si la chaîne dans laquelle on fait la recherche peut en contenir.
</p>
-<h4 id="Whitespaces">Interprétation des espaces blancs</h4>
+<h4 id="Whitespaces"><span class="section-number">4.2.4.1.</span> Interprétation des espaces blancs</h4>
<p>
- Le Java standard fournit deux méthodes pour déterminer si un caractères est un espace blanc:
- <code>Character.isWhitespace(…)</code> et <code>Character.isSpaceChar(…)</code>.
- Ces deux méthodes diffèrent dans leurs interprétations des espaces insécables, des tabulations et des retours à la ligne.
- La première méthode est conforme à l’interprétation couramment utilisée dans des langages telles que le Java, C/C++ et <abbr>XML</abbr>,
- qui considère les tabulations et retours à la ligne comme des espaces blancs,
- alors que les espaces insécables sont interprétés comme des caractères non-blanc.
- La seconde méthode — strictement conforme à la définition Unicode — fait l’interprétation inverse.
+Le Java standard fournit deux méthodes pour déterminer si un caractères est un espace blanc:
+<code>Character.isWhitespace(…)</code> et <code>Character.isSpaceChar(…)</code>.
+Ces deux méthodes diffèrent dans leurs interprétations des espaces insécables, des tabulations et des retours à la ligne.
+La première méthode est conforme à l’interprétation couramment utilisée dans des langages telles que le Java, C/C++ et <abbr>XML</abbr>,
+qui considère les tabulations et retours à la ligne comme des espaces blancs,
+alors que les espaces insécables sont interprétés comme des caractères non-blanc.
+La seconde méthode — strictement conforme à la définition Unicode — fait l’interprétation inverse.
</p>
<p>
- <abbr title="Spatial Information System">SIS</abbr> emploie ces deux méthodes dans des contextes différents.
- <code>isWhitespace(…)</code> est utilisée pour <em>séparer</em> les éléments d’une liste (nombres, dates, mots, <i>etc.</i>),
- tandis que <code>isSpaceChar(…)</code> est utilisée pour ignorer les espaces blancs <em>à l’intérieur</em> d’un seul élément.
+<abbr title="Spatial Information System">SIS</abbr> emploie ces deux méthodes dans des contextes différents.
+<code>isWhitespace(…)</code> est utilisée pour <em>séparer</em> les éléments d’une liste (nombres, dates, mots, <i>etc.</i>),
+tandis que <code>isSpaceChar(…)</code> est utilisée pour ignorer les espaces blancs <em>à l’intérieur</em> d’un seul élément.
</p>
<div class="example"><p><b>Exemple:</b>
- Supposons une liste de nombres représentés selon les conventions françaises.
- Chaque nombre peut contenir des <em>espace insécables</em> comme séparateurs des milliers,
- tandis que les différents nombres de la liste peuvent être séparés par des espaces ordinaires, des tabulations ou des retours à la ligne.
- Pendant l’analyse d’un nombre, on veut considérer les espaces insécables comme faisant partie du nombre,
- alors qu’une tabulation ou un retour à la ligne indique très probablement une séparation entre ce nombre et le nombre suivant.
- On utilisera donc <code>isSpaceChar(…)</code>.
- Inversement, lors de la séparation des nombres de la liste, on veut considérer les tabulations et
- les retours à la ligne comme des séparateurs mais pas les espaces insécables.
- On utilisera donc <code>isWhitespace(…)</code>.
- Le rôle des espaces ordinaires, qui pourraient s’appliquer aux deux cas, doit être décidé en amont.
+Supposons une liste de nombres représentés selon les conventions françaises.
+Chaque nombre peut contenir des <em>espace insécables</em> comme séparateurs des milliers,
+tandis que les différents nombres de la liste peuvent être séparés par des espaces ordinaires, des tabulations ou des retours à la ligne.
+Pendant l’analyse d’un nombre, on veut considérer les espaces insécables comme faisant partie du nombre,
+alors qu’une tabulation ou un retour à la ligne indique très probablement une séparation entre ce nombre et le nombre suivant.
+On utilisera donc <code>isSpaceChar(…)</code>.
+Inversement, lors de la séparation des nombres de la liste, on veut considérer les tabulations et
+les retours à la ligne comme des séparateurs mais pas les espaces insécables.
+On utilisera donc <code>isWhitespace(…)</code>.
+Le rôle des espaces ordinaires, qui pourraient s’appliquer aux deux cas, doit être décidé en amont.
</p></div>
<p>
- Dans la pratique, cette distinction se traduit pas une utilisation de <code>isSpaceChar(…)</code>
- dans les implémentations de <code>java.text.Format</code>,
- et une utilisation de <code>isWhitespace(…)</code> dans pratiquement tout le reste
- de la bibliothèque <abbr title="Spatial Information System">SIS</abbr>.
+Dans la pratique, cette distinction se traduit pas une utilisation de <code>isSpaceChar(…)</code>
+dans les implémentations de <code>java.text.Format</code>,
+et une utilisation de <code>isWhitespace(…)</code> dans pratiquement tout le reste
+de la bibliothèque <abbr>SIS</abbr>.
</p>
-
-
-
-<h1 id="Geometry">Géométries</h1>
+</section>
+<section>
+<header>
+<h1 id="Geometry"><span class="section-number">5.</span> Géométries</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Utilities">Chapitre suivant</a></div><div class="next-chapter"><a href="#Coverage">Chapitre précédent</a> ➡</div></div></nav>
+</header>
+<nav>Dans ce chapitre:<ul class="toc">
+<li><a href="#Geometry-root">Classes de base</a><ul>
+<li><a href="#DirectPosition">Points et positions directes</a></li>
+<li><a href="#Envelope">Enveloppes</a><ul>
+<li><a href="#AntiMeridian">Enveloppes traversant l’antiméridien</a></li></ul></li></ul></li></ul></nav>
<p>
- Ce chapitre introduit quelques aspects de la norme <abbr>ISO</abbr> 19107 (<i>Spatial schema</i>)
- et les classes de Apache <abbr title="Spatial Information System">SIS</abbr> qui les implémentent.
+Ce chapitre introduit quelques aspects de la norme <abbr title="International Organization for Standardization">ISO</abbr> 19107 (<i>Spatial schema</i>)
+et les classes de Apache <abbr title="Spatial Information System">SIS</abbr> qui les implémentent.
</p>
-<h2 id="Geometry-root">Classes de base</h2>
+<h2 id="Geometry-root"><span class="section-number">5.1.</span> Classes de base</h2>
<p>
- Chaque objet géométrique est considéré comme un ensemble infini de points.
- En tant qu’ensemble, leurs opérations les plus fondamentales sont de même nature que les opérations standards des collections du Java.
- On pourrait donc voir une géométrie comme une sorte de <code>java.util.Set</code> dont les éléments seraient des points,
- à ceci près que le nombre d’éléments contenus dans cet ensemble est infini (à l’exception des géométries représentant un simple point).
- Pour mieux représenter ce concept, la norme <abbr title="International Organization for Standardization">ISO</abbr> et GeoAPI définissent une interface <code class="OGC">TransfiniteSet</code>
- que l’on peut voir comme un <code>Set</code> de taille infini. Bien qu’un lien de parenté existe conceptuellement entre ces interfaces,
- GeoAPI ne définit pas <code class="GeoAPI">TransfiniteSet</code> comme une sous-interface de <code>java.util.Set</code>
- car la définition de certaines méthodes telles que <code>size()</code> et <code>iterator()</code> serait problématique.
- On y retrouve toutefois des méthodes très similaires telles que <code class="GeoAPI">contains(…)</code> et <code class="GeoAPI">intersects(…)</code>.
+Chaque objet géométrique est considéré comme un ensemble infini de points.
+En tant qu’ensemble, leurs opérations les plus fondamentales sont de même nature que les opérations standards des collections du Java.
+On pourrait donc voir une géométrie comme une sorte de <code>java.util.Set</code> dont les éléments seraient des points,
+à ceci près que le nombre d’éléments contenus dans cet ensemble est infini (à l’exception des géométries représentant un simple point).
+Pour mieux représenter ce concept, la norme <abbr title="International Organization for Standardization">ISO</abbr> et GeoAPI définissent une interface <code class="OGC">TransfiniteSet</code>
+que l’on peut voir comme un <code>Set</code> de taille infini. Bien qu’un lien de parenté existe conceptuellement entre ces interfaces,
+GeoAPI ne définit pas <code class="GeoAPI">TransfiniteSet</code> comme une sous-interface de <code>java.util.Set</code>
+car la définition de certaines méthodes telles que <code>size()</code> et <code>iterator()</code> serait problématique.
+On y retrouve toutefois des méthodes très similaires telles que <code class="GeoAPI">contains(…)</code> et <code class="GeoAPI">intersects(…)</code>.
</p>
<p>
- Toutes les géométries sont des spécialisations de <code class="GeoAPI">TransfiniteSet</code>.
- La classe parente de toutes ces géométries est appelée <code class="OGC">GM_Object</code> dans la norme <abbr>ISO</abbr> 19107.
- Les interfaces de GeoAPI utilisent plutôt le nom <code class="GeoAPI">Geometry</code>, car l’omission du préfixe <code class="OGC">GM_</code>
- (comme le veut la convention dans GeoAPI) aurait laissé un nom trop proche de la classe <code>Object</code> du Java.
+Toutes les géométries sont des spécialisations de <code class="GeoAPI">TransfiniteSet</code>.
+La classe parente de toutes ces géométries est appelée <code class="OGC">GM_Object</code> dans la norme <abbr>ISO</abbr> 19107.
+Les interfaces de GeoAPI utilisent plutôt le nom <code class="GeoAPI">Geometry</code>, car l’omission du préfixe <code class="OGC">GM_</code>
+(comme le veut la convention dans GeoAPI) aurait laissé un nom trop proche de la classe <code>Object</code> du Java.
</p>
-<h3 id="DirectPosition">Points et positions directes</h3>
+<h3 id="DirectPosition"><span class="section-number">5.1.1.</span> Points et positions directes</h3>
<p>
- <abbr>ISO</abbr> 19107 définit deux types de structures pour représenter un point:
- <code class="OGC">GM_Point</code> et <code class="OGC">DirectPosition</code>.
- Le premier type est une véritable géométrie et peut donc être relativement lourd, selon les implémentations.
- Le second type n’est pas considéré formellement comme une géométrie;
- il n’étend ni <code class="OGC">GM_Object</code> ni <code class="OGC">TransfiniteSet</code>.
- Il ne définit pratiquement pas d’opérations autres que le stockage d’une séquence de nombres représentant une coordonnée.
- Il peut donc être un objet plus léger.
+<abbr title="International Organization for Standardization">ISO</abbr> 19107 définit deux types de structures pour représenter un point:
+<code class="OGC">GM_Point</code> et <code class="OGC">DirectPosition</code>.
+Le premier type est une véritable géométrie et peut donc être relativement lourd, selon les implémentations.
+Le second type n’est pas considéré formellement comme une géométrie;
+il n’étend ni <code class="OGC">GM_Object</code> ni <code class="OGC">TransfiniteSet</code>.
+Il ne définit pratiquement pas d’opérations autres que le stockage d’une séquence de nombres représentant une coordonnée.
+Il peut donc être un objet plus léger.
</p>
<p>
- Afin de permettre à l’<abbr title="Application Programming Interface">API</abbr> de travailler indifféremment
- avec ces deux types de positions, <abbr>ISO</abbr> 19107 définit <code class="OGC">Position</code> comme une <cite>union</cite>
- de <code class="OGC">DirectPosition</code> et <code class="OGC">GM_Point</code>.
- Il s’agit d’une union au sens du C/C++. Pour le langage Java, GeoAPI obtient le même effet en définissant
- <code class="GeoAPI">Position</code> comme l’interface parente de
- <code class="GeoAPI">DirectPosition</code> et <code class="GeoAPI">Point</code>.
- Dans la pratique, la grande majorité des <abbr title="Application Programming Interface">API</abbr>
- de Apache <abbr title="Spatial Information System">SIS</abbr> travaillent sur des
- <code class="GeoAPI">DirectPosition</code>, ou occasionnellement des
- <code class="GeoAPI">Position</code> quand il semble utile d’autoriser aussi des points géométriques.
+Afin de permettre à l’<abbr title="Application Programming Interface">API</abbr> de travailler indifféremment avec ces deux types de positions,
+<abbr>ISO</abbr> 19107 définit <code class="OGC">Position</code> comme une <cite>union</cite> de
+<code class="OGC">DirectPosition</code> et <code class="OGC">GM_Point</code>.
+Il s’agit d’une union au sens du C/C++. Pour le langage Java, GeoAPI obtient le même effet en définissant
+<code class="GeoAPI">Position</code> comme l’interface parente de <code class="GeoAPI">DirectPosition</code> et <code class="GeoAPI">Point</code>.
+Dans la pratique, la grande majorité des <abbr>API</abbr> de Apache <abbr title="Spatial Information System">SIS</abbr> travaillent sur des <code class="GeoAPI">DirectPosition</code>,
+ou occasionnellement des <code class="GeoAPI">Position</code> quand il semble utile d’autoriser aussi des points géométriques.
</p>
-<h3 id="Envelope">Enveloppes</h3>
+<h3 id="Envelope"><span class="section-number">5.1.2.</span> Enveloppes</h3>
<p>
- Les enveloppes stockent les valeurs minimales et maximales des coordonnées d’une géométrie.
- Les enveloppes <em>ne sont pas</em> elles-mêmes des géométries; ce ne sont pas des ensembles
- infinis de points (<code class="OGC">TransfiniteSet</code>). Il n’y a aucune garantie
- que toutes les positions contenues dans les limites d’une enveloppe soient géographiquement valides.
- Il faut voir les enveloppes comme une information sur les valeurs extrêmes que peuvent prendre les
- coordonnées d’une géométrie en faisant comme si chaque dimension était indépendante des autres,
- rien de plus. Nous assimilons néanmoins les enveloppes à des rectangles, cubes ou hyper-cubes
- (selon le nombre de dimensions) afin de faciliter la discussion, mais en gardant à l’esprit leur
- nature non-géométrique.
+Les enveloppes stockent les valeurs minimales et maximales des coordonnées d’une géométrie.
+Les enveloppes <em>ne sont pas</em> elles-mêmes des géométries; ce ne sont pas des ensembles
+infinis de points (<code class="OGC">TransfiniteSet</code>). Il n’y a aucune garantie
+que toutes les positions contenues dans les limites d’une enveloppe soient géographiquement valides.
+Il faut voir les enveloppes comme une information sur les valeurs extrêmes que peuvent prendre les
+coordonnées d’une géométrie en faisant comme si chaque dimension était indépendante des autres,
+rien de plus. Nous assimilons néanmoins les enveloppes à des rectangles, cubes ou hyper-cubes
+(selon le nombre de dimensions) afin de faciliter la discussion, mais en gardant à l’esprit leur
+nature non-géométrique.
</p>
<div class="example"><p><b>Exemple:</b>
- Nous pouvons tester si une position est à l’intérieur des limites de l’enveloppe.
- Un résultat positif ne garantie pas que la position est à l’intérieur de la géométrie délimitée par l’enveloppe,
- mais un résultat négatif garantie qu’elle est à l’extérieur. De même on peut effectuer des tests d’intersections.
- En revanche appliquer une rotation n’a pas beaucoup de sens pour une enveloppe, car le résultat peut être très différent
- de celui que nous aurions obtenu en effectuant une rotation de la géométrie originale, puis en recalculant son enveloppe.
+Nous pouvons tester si une position est à l’intérieur des limites de l’enveloppe.
+Un résultat positif ne garantie pas que la position est à l’intérieur de la géométrie délimitée par l’enveloppe,
+mais un résultat négatif garantie qu’elle est à l’extérieur. De même on peut effectuer des tests d’intersections.
+En revanche appliquer une rotation n’a pas beaucoup de sens pour une enveloppe, car le résultat peut être très différent
+de celui que nous aurions obtenu en effectuant une rotation de la géométrie originale, puis en recalculant son enveloppe.
</p></div>
<p>
- Une enveloppe peut être représentée par deux positions correspondant à deux coins opposés
- d’un rectangle, cube ou hyper-cube. On prend souvent comme premier coin celui dont toutes
- les ordonnées ont la valeur minimale (<code class="OGC">lowerCorner</code>), et comme second
- coin celui dont toutes les ordonnées ont la valeur maximale (<code class="OGC">upperCorner</code>).
- Lors d’un affichage utilisant un système de coordonnées classique (valeurs de l’axe des <var>y</var> augmentant vers le haut),
- ces deux positions apparaissent respectivement dans le coin inférieur gauche et dans le coin supérieur droit d’un rectangle.
- Attention toutefois aux différents systèmes de coordonnées, qui peuvent faire varier les positions de ces coins à l’écran.
- Les expressions <i>lower corner</i> et <i>upper corner</i>
- doivent être comprises au sens mathématique plutôt que visuel.
+Une enveloppe peut être représentée par deux positions correspondant à deux coins opposés
+d’un rectangle, cube ou hyper-cube. On prend souvent comme premier coin celui dont toutes
+les ordonnées ont la valeur minimale (<code class="OGC">lowerCorner</code>), et comme second
+coin celui dont toutes les ordonnées ont la valeur maximale (<code class="OGC">upperCorner</code>).
+Lors d’un affichage utilisant un système de coordonnées classique (valeurs de l’axe des <var>y</var> augmentant vers le haut),
+ces deux positions apparaissent respectivement dans le coin inférieur gauche et dans le coin supérieur droit d’un rectangle.
+Attention toutefois aux différents systèmes de coordonnées, qui peuvent faire varier les positions de ces coins à l’écran.
+Les expressions <i>lower corner</i> et <i>upper corner</i>
+doivent être comprises au sens mathématique plutôt que visuel.
</p>
-<h4 id="AntiMeridian">Enveloppes traversant l’antiméridien</h4>
+<h4 id="AntiMeridian"><span class="section-number">5.1.2.1.</span> Enveloppes traversant l’antiméridien</h4>
<p>
- Les minimums et maximums sont les valeurs les plus souvent assignées aux <code class="OGC">lowerCorner</code>
- et <code class="OGC">upperCorner</code>. Mais les choses se compliquent dans le cas d’une enveloppe traversant
- l’antiméridien (-180° ou 180° de longitude). Par exemple, une enveloppe de 10° de largeur peut commencer à 175° de longitude et
- se terminer à -175°. Dans ce cas, la valeur de longitude assignée au <code class="OGC">lowerCorner</code> est
- supérieure à celle qui est assignée à l’<code class="OGC">upperCorner</code>.
- Apache <abbr title="Spatial Information System">SIS</abbr> emploie donc une définition légèrement différente de ces deux coins:
+Les minimums et maximums sont les valeurs les plus souvent assignées aux <code class="OGC">lowerCorner</code>
+et <code class="OGC">upperCorner</code>. Mais les choses se compliquent dans le cas d’une enveloppe traversant
+l’antiméridien (-180° ou 180° de longitude). Par exemple, une enveloppe de 10° de largeur peut commencer à 175° de longitude et
+se terminer à -175°. Dans ce cas, la valeur de longitude assignée au <code class="OGC">lowerCorner</code> est
+supérieure à celle qui est assignée à l’<code class="OGC">upperCorner</code>.
+Apache <abbr title="Spatial Information System">SIS</abbr> emploie donc une définition légèrement différente de ces deux coins:
</p>
<ul>
- <li><b><code class="SIS">lowerCorner</code>:</b>
- le point de départ lorsque l’on parcourt l’intérieur de l’enveloppe dans la direction des valeurs croissantes.
- </li>
- <li><b><code class="SIS">upperCorner</code>:</b>
- le point d’arrivé lorsque l’on a parcouru l’intérieur de l’enveloppe dans la direction des valeurs croissantes.
- </li>
+<li><b><code class="SIS">lowerCorner</code>:</b>
+le point de départ lorsque l’on parcourt l’intérieur de l’enveloppe dans la direction des valeurs croissantes.
+</li>
+<li><b><code class="SIS">upperCorner</code>:</b>
+le point d’arrivé lorsque l’on a parcouru l’intérieur de l’enveloppe dans la direction des valeurs croissantes.
+</li>
</ul>
<p>
- Lorsque l’enveloppe ne traverse par l’antiméridien, ces deux définitions sont équivalentes à la sélection
- des valeurs minimales et maximales respectivement. C’est le cas du rectangle vert dans la figure ci-dessous.
- Lorsque l’enveloppe traverse l’antiméridien, les coins <code class="SIS">lowerCorner</code>
- et <code class="SIS">upperCorner</code> apparaissent encore en bas et en haut du rectangle
- (en supposant un système de coordonnées classique), donc leurs noms restent appropriés d’un point de vue visuel.
- Mais les positions gauche et droite sont interchangées.
- Ce cas est représenté par le rectangle rouge dans la figure ci-dessous.
+Lorsque l’enveloppe ne traverse par l’antiméridien, ces deux définitions sont équivalentes à la sélection
+des valeurs minimales et maximales respectivement. C’est le cas du rectangle vert dans la figure ci-dessous.
+Lorsque l’enveloppe traverse l’antiméridien, les coins <code class="SIS">lowerCorner</code>
+et <code class="SIS">upperCorner</code> apparaissent encore en bas et en haut du rectangle
+(en supposant un système de coordonnées classique), donc leurs noms restent appropriés d’un point de vue visuel.
+Mais les positions gauche et droite sont interchangées.
+Ce cas est représenté par le rectangle rouge dans la figure ci-dessous.
</p>
<center>
- <img src="../../apidocs/org/apache/sis/geometry/doc-files/AntiMeridian.png"
- alt="Exemples d’enveloppes avec et sans croisement de l’antiméridien."/>
+<img alt="Exemples d’enveloppes avec et sans croisement de l’antiméridien." src="../../apidocs/org/apache/sis/geometry/doc-files/AntiMeridian.png"/>
</center>
<p>
- Les notions d’inclusion et d’intersection s’interprètent toutefois de manière légèrement différente dans ces deux cas.
- Dans le cas habituel où l’on ne traverse pas l’antiméridien, le rectangle vert délimite bien une région d’inclusion.
- Les régions exclues de ce rectangle se propagent à l’infini dans toutes les directions.
- En d’autres mots, la région d’inclusion n’est pas répétée tous les 360°.
- Mais dans le cas du rectangle rouge, l’information fournie par l’enveloppe délimite plutôt la région d’exclusion qui
- se trouve entre les deux bords du rectangle. La région d’inclusion se propage à l’infini des côtés gauche et droit.
- Nous pourrions stipuler que toute longitude inférieure à -180° ou supérieure à 180° est considérée exclue,
- mais ça serait une décision arbitraire qui ne serait pas un reflet symétrique du cas habituel (rectangle vert).
- Un développeur pourrait vouloir utiliser ces valeurs, par exemple dans une mosaïque où la carte du monde
- est répétée plusieurs fois horizontalement tout en considérant chaque répétition comme distincte des autres.
- Si un développeur souhaite effectuer des opérations comme si les régions d’inclusions ou d’exclusions étaient
- répétées tous les 360°, alors il doit lui-même ramener ses valeurs de longitudes entre -180° et 180° au préalable.
- Toutes les fonctions <code class="SIS">add(…)</code>, <code class="SIS">contains(…)</code>,
- <code class="SIS">intersect(…)</code>, <i>etc.</i> de toutes les enveloppes
- définies dans le paquet <code class="SIS">org.apache.sis.geometry</code> effectuent leurs calculs selon cette convention.
+Les notions d’inclusion et d’intersection s’interprètent toutefois de manière légèrement différente dans ces deux cas.
+Dans le cas habituel où l’on ne traverse pas l’antiméridien, le rectangle vert délimite bien une région d’inclusion.
+Les régions exclues de ce rectangle se propagent à l’infini dans toutes les directions.
+En d’autres mots, la région d’inclusion n’est pas répétée tous les 360°.
+Mais dans le cas du rectangle rouge, l’information fournie par l’enveloppe délimite plutôt la région d’exclusion qui
+se trouve entre les deux bords du rectangle. La région d’inclusion se propage à l’infini des côtés gauche et droit.
+Nous pourrions stipuler que toute longitude inférieure à -180° ou supérieure à 180° est considérée exclue,
+mais ça serait une décision arbitraire qui ne serait pas un reflet symétrique du cas habituel (rectangle vert).
+Un développeur pourrait vouloir utiliser ces valeurs, par exemple dans une mosaïque où la carte du monde
+est répétée plusieurs fois horizontalement tout en considérant chaque répétition comme distincte des autres.
+Si un développeur souhaite effectuer des opérations comme si les régions d’inclusions ou d’exclusions étaient
+répétées tous les 360°, alors il doit lui-même ramener ses valeurs de longitudes entre -180° et 180° au préalable.
+Toutes les fonctions <code class="SIS">add(…)</code>, <code class="SIS">contains(…)</code>,
+<code class="SIS">intersect(…)</code>, <i>etc.</i> de toutes les enveloppes
+définies dans le paquet <code class="SIS">org.apache.sis.geometry</code> effectuent leurs calculs selon cette convention.
</p>
<aside>
- <p><b>Généralisation à d’autres types d’axes</b></p>
- <p>
- Cette section nomme spécifiquement la longitude car il constitue le cas le plus courant d’axe cyclique.
- Mais dans les enveloppes de Apache <abbr title="Spatial Information System">SIS</abbr>,
- il n’est fait nul part mention explicite du cas de la longitude, ni de son cycle de 360°.
- Les caractéristiques de la plage de valeurs de chaque axe (ses extremums, unités, type de cycle, <i>etc.</i>)
- sont des attributs des objets <code class="GeoAPI">CoordinateSystemAxis</code>,
- indirectement associés aux enveloppes via le système de référence des coordonnées.
- Apache <abbr>SIS</abbr> inspecte ces attributs pour déterminer de quelle façon il doit effectuer ses opérations.
- Ainsi, tout axe associé au code <code class="GeoAPI">RangeMeaning.WRAPAROUND</code> bénéficiera du même traitement que la longitude.
- Cela pourrait être par exemple un axe du temps dans des données climatologiques
- (une “année” représentant la température moyenne de tous les mois de janvier, suivit de la moyenne de tous les mois de février,
- <i>etc.</i>).
- Cette généralisation s’applique aussi aux axes de longitudes définis par une plage de 0° à 360° plutôt que de -180° à 180°.
- </p>
+<h5>Généralisation à d’autres types d’axes</h5>
+<p>
+Cette section nomme spécifiquement la longitude car il constitue le cas le plus courant d’axe cyclique.
+Mais dans les enveloppes de Apache <abbr title="Spatial Information System">SIS</abbr>, il n’est fait nul part mention explicite du cas de la longitude, ni de son cycle de 360°.
+Les caractéristiques de la plage de valeurs de chaque axe (ses extremums, unités, type de cycle, <i>etc.</i>)
+sont des attributs des objets <code class="GeoAPI">CoordinateSystemAxis</code>, indirectement associés aux enveloppes via le système de référence des coordonnées.
+Apache <abbr>SIS</abbr> inspecte ces attributs pour déterminer de quelle façon il doit effectuer ses opérations.
+Ainsi, tout axe associé au code <code class="GeoAPI">RangeMeaning.WRAPAROUND</code> bénéficiera du même traitement que la longitude.
+Cela pourrait être par exemple un axe du temps dans des données climatologiques
+(une “année” représentant la température moyenne de tous les mois de janvier, suivit de la moyenne de tous les mois de février,
+<i>etc.</i>).
+Cette généralisation s’applique aussi aux axes de longitudes définis par une plage de 0° à 360° plutôt que de -180° à 180°.
+</p>
</aside>
<p>
- Pour que les fonctions telles que <code class="SIS">add(…)</code> fonctionnent correctement,
- tous les objets impliqués doivent utiliser le même système de référence des coordonnées, y compris
- la même plage de valeurs. Ainsi, une enveloppe exprimant les longitudes dans la plage [-180 … +180]°
- n’est pas compatible avec une enveloppe exprimant les longitudes dans la plage [0 … 360]°.
- Les conversions, si nécessaires, sont à la charge de l’utilisateur
- (la classe <code class="SIS">Envelopes</code> fournit des méthodes de commodités pour ce faire).
- En outre, les coordonnées de l’enveloppe doivent être comprises dans les limites du système de coordonnées,
- sauf si le développeur souhaite volontairement considérer (par exemple) 300° de longitude
- comme un position distincte de -60°. La classe <code class="SIS">GeneralEnvelope</code>
- fournit une méthode <code class="SIS">normalize()</code> pour ramener les coordonnées
- dans les limites attendues, au prix parfois de valeurs <cite><i>lower</i></cite>
- supérieures à la valeur <cite><i>upper</i></cite>.
+Pour que les fonctions telles que <code class="SIS">add(…)</code> fonctionnent correctement,
+tous les objets impliqués doivent utiliser le même système de référence des coordonnées, y compris
+la même plage de valeurs. Ainsi, une enveloppe exprimant les longitudes dans la plage [-180 … +180]°
+n’est pas compatible avec une enveloppe exprimant les longitudes dans la plage [0 … 360]°.
+Les conversions, si nécessaires, sont à la charge de l’utilisateur
+(la classe <code class="SIS">Envelopes</code> fournit des méthodes de commodités pour ce faire).
+En outre, les coordonnées de l’enveloppe doivent être comprises dans les limites du système de coordonnées,
+sauf si le développeur souhaite volontairement considérer (par exemple) 300° de longitude
+comme un position distincte de -60°. La classe <code class="SIS">GeneralEnvelope</code>
+fournit une méthode <code class="SIS">normalize()</code> pour ramener les coordonnées
+dans les limites attendues, au prix parfois de valeurs <cite><i>lower</i></cite>
+supérieures à la valeur <cite><i>upper</i></cite>.
</p>
<aside>
- <p><b>Le cas particulier de la plage [+0 … -0]</b></p>
- <p>
- le Java (ou de manière plus générale, la norme IEEE 754) définit deux valeurs distinctes de zéro:
- un zéro positif et un zéro négatif. Ces deux valeurs sont considérées égales lorsqu’on les compares avec l’opérateur <code>==</code> du Java.
- Mais dans les enveloppes de <abbr title="Spatial Information System">SIS</abbr>,
- ils peuvent mener à des résultats opposés pour les axes ayant <code class="GeoAPI">RangeMeaning.WRAPAROUND</code>.
- Une enveloppe dont la plage est [0 … 0], [-0 … -0] ou [-0 … +0] sera bien considérée comme une enveloppe vide,
- mais la page [+0 … -0] sera au contraire considérée comme incluant la totalité des valeurs, jusqu’à l’infini.
- Ce comportement est conforme à la définition de <code class="SIS">lowerCorner</code> et <code class="SIS">upperCorner</code>
- qui considère +0 comme le point de départ, et -0 comme le point d’arrivé après avoir fait le tour des valeurs possibles.
- Un tel comportement ne se produit que pour la paire de valeurs +0 et -0, et seulement dans cet ordre.
- Pour toutes les autres valeurs réelles, si la condition <code>lower</code> <code>==</code> <code>upper</code>
- est vrai, alors il est garanti que l’enveloppe est vide.
- </p>
+<h5>Le cas particulier de la plage [+0 … -0]</h5>
+<p>
+le Java (ou de manière plus générale, la norme IEEE 754) définit deux valeurs distinctes de zéro:
+un zéro positif et un zéro négatif. Ces deux valeurs sont considérées égales lorsqu’on les compares avec l’opérateur <code>==</code> du Java.
+Mais dans les enveloppes de <abbr title="Spatial Information System">SIS</abbr>, ils peuvent mener à des résultats opposés pour les axes ayant <code class="GeoAPI">RangeMeaning.WRAPAROUND</code>.
+Une enveloppe dont la plage est [0 … 0], [-0 … -0] ou [-0 … +0] sera bien considérée comme une enveloppe vide,
+mais la page [+0 … -0] sera au contraire considérée comme incluant la totalité des valeurs, jusqu’à l’infini.
+Ce comportement est conforme à la définition de <code class="SIS">lowerCorner</code> et <code class="SIS">upperCorner</code>
+qui considère +0 comme le point de départ, et -0 comme le point d’arrivé après avoir fait le tour des valeurs possibles.
+Un tel comportement ne se produit que pour la paire de valeurs +0 et -0, et seulement dans cet ordre.
+Pour toutes les autres valeurs réelles, si la condition <code>lower</code> <code>==</code> <code>upper</code>
+est vrai, alors il est garanti que l’enveloppe est vide.
+</p>
</aside>
-
-
-
-<h1 id="Coverage">Couvertures de données (<i>Coverages</i>)</h1>
-<p>
- Les images, souvent nommées <i>rasters</i> en anglais, sont des cas particuliers
- d’une structure de données appelée <i>coverages</i>.
- On pourrait traduire ce terme anglais par « couverture de données ».
- Le titre du standard les décrivant, “<i>Coverage geometry and functions</i>”
- (<abbr>ISO</abbr> 19123), résume bien les deux éléments essentiels des couvertures de données:
+</section>
+<section>
+<header>
+<h1 id="Coverage"><span class="section-number">6.</span> Couvertures de données (<i>Coverages</i>)</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Geometry">Chapitre suivant</a></div></div></nav>
+</header>
+<nav>Dans ce chapitre:<ul class="toc"/></nav>
+<p>
+Les images, souvent nommées <i>rasters</i> en anglais, sont des cas particuliers
+d’une structure de données appelée <i>coverages</i>.
+On pourrait traduire ce terme anglais par « couverture de données ».
+Le titre du standard les décrivant, « <i>Coverage geometry and functions</i> »
+(<abbr title="International Organization for Standardization">ISO</abbr> 19123), résume bien les deux éléments essentiels des couvertures de données:
</p>
<ul>
- <li>
- <p>
- Un <i>coverage</i> est une fonction qui, à partir d’une coordonnée spécifiée en entrée,
- retourne une valeur d’attribut. L’ensemble des valeurs pouvant être données en entrée est appelé le domaine
- (<i>domain</i> en anglais), alors que l’ensemble des valeurs pouvant être retournées est appelé <i>range</i> en anglais.
- Le domaine est souvent l’espace spatio-temporel couvert par les données,
- mais rien dans <abbr title="Spatial Information System">SIS</abbr> n’empêche les couvertures de s’étendre à d’autres dimensions.
- Par exemple les études en thermodynamique utilisent souvent un espace dont les dimensions sont la température et la pression.
- </p>
- <div class="example"><p><b>Exemple:</b>
- les valeurs des pixels d’une image pourraient contenir des mesures d’élévation du terrain.
- Si une fonction <var>h</var> = <var>f</var>(φ,λ) permet d’obtenir (éventuellement à l’aide d’interpolations)
- l’élévation <var>h</var> en fonction d’une coordonnée géographique (φ,λ), alors
- l’enveloppe géographique de l’image définie le <i>domain</i>, la fonction <var>f</var> est le <i>coverage</i>,
- et l’ensemble des valeurs de <var>h</var> que peut retourner cette fonction est le <i>range</i>.
- </p></div>
- </li>
- <li>
- <p>
- Les différents types de couvertures peuvent se caractériser par la géométrie de leurs cellules.
- En particulier, une couverture n’est pas nécessairement composée de cellules quadrilatérales.
- Toutefois les cellules quadrilatérales étant de loin les plus fréquentes (puisque c’est la géométrie classique des pixels des images),
- on utilisera souvent le terme <i>grid coverage</i> pour désigner les couvertures composées de telles cellules.
- Dans <abbr title="Spatial Information System">SIS</abbr>, la géométrie de ces couvertures est décrite par la classe <code class="SIS">GridGeometry</code>.
- </p>
- </li>
+<li>
+<p>
+Un <i>coverage</i> est une fonction qui, à partir d’une coordonnée spécifiée en entrée,
+retourne une valeur d’attribut. L’ensemble des valeurs pouvant être données en entrée est appelé le domaine
+(<i>domain</i> en anglais), alors que l’ensemble des valeurs pouvant être retournées est appelé <i>range</i> en anglais.
+Le domaine est souvent l’espace spatio-temporel couvert par les données,
+mais rien dans <abbr title="Spatial Information System">SIS</abbr> n’empêche les couvertures de s’étendre à d’autres dimensions.
+Par exemple les études en thermodynamique utilisent souvent un espace dont les dimensions sont la température et la pression.
+</p>
+<div class="example"><p><b>Exemple:</b>
+les valeurs des pixels d’une image pourraient contenir des mesures d’élévation du terrain.
+Si une fonction <var>h</var> = <var>f</var>(φ,λ) permet d’obtenir (éventuellement à l’aide d’interpolations)
+l’élévation <var>h</var> en fonction d’une coordonnée géographique (φ,λ), alors
+l’enveloppe géographique de l’image définie le <i>domain</i>, la fonction <var>f</var> est le <i>coverage</i>,
+et l’ensemble des valeurs de <var>h</var> que peut retourner cette fonction est le <i>range</i>.
+</p></div>
+</li>
+<li>
+<p>
+Les différents types de couvertures peuvent se caractériser par la géométrie de leurs cellules.
+En particulier, une couverture n’est pas nécessairement composée de cellules quadrilatérales.
+Toutefois les cellules quadrilatérales étant de loin les plus fréquentes (puisque c’est la géométrie classique des pixels des images),
+on utilisera souvent le terme <i>grid coverage</i> pour désigner les couvertures composées de telles cellules.
+Dans <abbr>SIS</abbr>, la géométrie de ces couvertures est décrite par la classe <code class="SIS">GridGeometry</code>.
+</p>
+</li>
</ul>
<p>
- Les caractéristiques du domaine spatial sont définies par le standard <abbr>ISO</abbr> 19123,
- alors que les caractéristiques du <i>range</i> ne font pas parties du standard.
- Le standard mentionne simplement que les <i>ranges</i> peuvent être finis ou infinis,
- et ne sont pas nécessairement numériques.
- Par exemple les valeurs retournées par une couverture peuvent provenir d’une énumération
- (« ceci est une forêt », « ceci est un lac », <i>etc.</i>).
- Toutefois, le standard définit deux grands types de couvertures qui ont un impact
- sur les types de <i>ranges</i> autorisés:
- les couvertures <i>discrètes</i> et les couvertures <i>continues</i>.
- Présentées simplement, les couvertures continues sont des fonctions pouvant utiliser des méthodes d’interpolations.
- Or, les interpolations n’étant possibles qu’avec des valeurs numériques, les <i>ranges</i> de valeurs
- non-numériques ne peuvent être utilisés qu’avec des couvertures de type <code class="OGC">CV_DiscreteCoverage</code>.
- En revanche, les <i>ranges</i> de valeurs numériques peuvent
- être utilisés aussi avec des couvertures de type <code class="OGC">CV_ContinuousCoverage</code>.
+Les caractéristiques du domaine spatial sont définies par le standard <abbr>ISO</abbr> 19123,
+alors que les caractéristiques du <i>range</i> ne font pas parties du standard.
+Le standard mentionne simplement que les <i>ranges</i> peuvent être finis ou infinis,
+et ne sont pas nécessairement numériques.
+Par exemple les valeurs retournées par une couverture peuvent provenir d’une énumération
+(« ceci est une forêt », « ceci est un lac », <i>etc.</i>).
+Toutefois, le standard définit deux grands types de couvertures qui ont un impact
+sur les types de <i>ranges</i> autorisés:
+les couvertures <i>discrètes</i> et les couvertures <i>continues</i>.
+Présentées simplement, les couvertures continues sont des fonctions pouvant utiliser des méthodes d’interpolations.
+Or, les interpolations n’étant possibles qu’avec des valeurs numériques, les <i>ranges</i> de valeurs
+non-numériques ne peuvent être utilisés qu’avec des couvertures de type <code class="OGC">CV_DiscreteCoverage</code>.
+En revanche, les <i>ranges</i> de valeurs numériques peuvent
+être utilisés aussi avec des couvertures de type <code class="OGC">CV_ContinuousCoverage</code>.
</p>
<aside>
- <p><b>La classe <code class="SIS">Range</code> de SIS et sa relation avec les standards</b></p>
- <p>
- La distinction entre les plages de tout type de valeurs et les plages de valeurs numériques est représentée dans <abbr title="Spatial Information System">SIS</abbr>
- par les classes <code class="SIS">Range</code> et <code class="SIS">NumberRange</code> respectivement.
- La classe <code class="SIS">NumberRange</code> est la plus utilisée, et elle est aussi celle qui se rapproche le plus de la
- <a href="http://fr.wikipedia.org/wiki/Intervalle_%28math%C3%A9matiques%29">notion mathématique usuelle d’un intervalle</a>.
- Se représentation textuelle se rapproche des spécifications du standard <abbr>ISO</abbr> 31-11,
- excepté que la virgule est remplacée par le caractère “…” comme séparateur des valeurs minimales et maximales.
- Par exemple “[0 … 256)” représente la plage des valeurs 0 inclusivement à 256 exclusivement.
- </p>
- <p>
- Les objets <code class="SIS">Range</code> ne sont associés aux <i>coverages</i> que indirectement.
- Dans <abbr title="Spatial Information System">SIS</abbr>, les valeurs que peuvent retourner les couvertures sont décrites par des
- objets de type <code class="SIS">SampleDimension</code>. Ce sont ces derniers qui contiendront
- des instances de <code class="SIS">Range</code> ainsi que d’autres informations telles qu’une
- <i>fonction de transfert</i> (décrite plus loin).
- </p>
+<h2>La classe <code class="SIS">Range</code> de SIS et sa relation avec les standards</h2>
+<p>
+La distinction entre les plages de tout type de valeurs et les plages de valeurs numériques est représentée dans <abbr title="Spatial Information System">SIS</abbr>
+par les classes <code class="SIS">Range</code> et <code class="SIS">NumberRange</code> respectivement.
+La classe <code class="SIS">NumberRange</code> est la plus utilisée, et elle est aussi celle qui se rapproche le plus de la
+<a href="http://fr.wikipedia.org/wiki/Intervalle_%28math%C3%A9matiques%29">notion mathématique usuelle d’un intervalle</a>.
+Se représentation textuelle se rapproche des spécifications du standard <abbr title="International Organization for Standardization">ISO</abbr> 31-11,
+excepté que la virgule est remplacée par le caractère “…” comme séparateur des valeurs minimales et maximales.
+Par exemple “[0 … 256)” représente la plage des valeurs 0 inclusivement à 256 exclusivement.
+</p>
+<p>
+Les objets <code class="SIS">Range</code> ne sont associés aux <i>coverages</i> que indirectement.
+Dans <abbr>SIS</abbr>, les valeurs que peuvent retourner les couvertures sont décrites par des
+objets de type <code class="SIS">SampleDimension</code>. Ce sont ces derniers qui contiendront
+des instances de <code class="SIS">Range</code> ainsi que d’autres informations telles qu’une
+<i>fonction de transfert</i> (décrite plus loin).
+</p>
</aside>
-
- <!-- End of shifted indentation. -->
- </body>
-</html>
+</section>
+</main>
+</body>
+</html>
\ No newline at end of file
diff --git a/content/reports.css b/book/tables.css
similarity index 69%
rename from content/reports.css
rename to book/tables.css
index 44e5bd1..2902c3a 100644
--- a/content/reports.css
+++ b/book/tables.css
@@ -1,3 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
p {
text-align: justify;
}
diff --git a/content/CoordinateOperationMethods.html b/book/tables/CoordinateOperationMethods.html
similarity index 99%
rename from content/CoordinateOperationMethods.html
rename to book/tables/CoordinateOperationMethods.html
index eb29a62..8830c3d 100644
--- a/content/CoordinateOperationMethods.html
+++ b/book/tables/CoordinateOperationMethods.html
@@ -8,7 +8,7 @@
<meta charset="UTF-8"/>
<title>Apache SIS Coordinate Operation Methods</title>
<style type="text/css" media="all">
- @import url("./reports.css");
+ @import url("../tables.css");
</style>
</head>
<body>
diff --git a/book/tables/CoordinateReferenceSystems.html b/book/tables/CoordinateReferenceSystems.html
new file mode 100644
index 0000000..936d000
--- /dev/null
+++ b/book/tables/CoordinateReferenceSystems.html
@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<!--
+ This page is automatically generated by the following class in the test directory:
+ org.apache.sis.internal.referencing.provider.CoordinateOperationMethodsHTML
+-->
+<html>
+ <head>
+ <meta charset="UTF-8"/>
+ <title>Apache SIS Coordinate Reference System (CRS) codes</title>
+ <style type="text/css" media="all">
+ @import url("../tables.css");
+ </style>
+ </head>
+ <body>
+ <header>
+ <h1>Apache SIS™ Coordinate Reference System (CRS) codes</h1>
+ <p>
+ To be completed.
+ </p>
+ </header>
+ </body>
+</html>
diff --git a/command-line.html b/command-line.html
index 27c072e..18615c9 100644
--- a/command-line.html
+++ b/command-line.html
@@ -93,9 +93,7 @@
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
-<p>A command-line interface is provided for extracting information from a data file.
-As of SIS 0.6, the command line can only extract ISO 19115 metadata from a NetCDF file.
-More formats and capabilities will be added in future SIS versions.</p>
+<p>A command-line interface is provided for extracting information from a data file.</p>
<div class="toc">
<ul>
<li><a href="#install">Installation</a></li>
diff --git a/index.html b/index.html
index c5a9a27..a26d7b1 100644
--- a/index.html
+++ b/index.html
@@ -112,7 +112,7 @@ The SIS storage modules will provide a common approach to the reading and writin
<li>Well Known Text (WKT) version 1 and 2 (ISO 19162:2015).</li>
<li>Geographic Markup Language (GML) version 3.2 (ISO 19136:2007).</li>
<li>Mercator, Transverse Mercator, Lambert Conic Conformal and Polar stereographic map projections.
- See the list of <a href="content/CoordinateOperationMethods.html">supported operation methods</a>.</li>
+ See the list of <a href="book/tables/CoordinateOperationMethods.html">supported operation methods</a>.</li>
</ul>
</li>
</ul>
diff --git a/release-notes/0.6.html b/release-notes/0.6.html
index 5456a04..6d15422 100644
--- a/release-notes/0.6.html
+++ b/release-notes/0.6.html
@@ -18,7 +18,7 @@
<li>Support of <cite>Geographic Markup Language</cite> (GML) version 3.2 (ISO 19136) for Coordinate Reference System objects,
except <code>DerivedCRS</code>, <code>ConcatenatedOperation</code> and <code>PassThroughOperation</code>.</li>
<li>Support of <cite>Mercator</cite>, <cite>Transverse Mercator</cite>, <cite>Lambert Conic Conformal</cite> and <cite>Polar stereographic</cite> map projections.
- The list of map projection methods supported by latest SIS release can be viewed <a href="../content/CoordinateOperationMethods.html">here</a>.
+ The list of map projection methods supported by latest SIS release can be viewed <a href="../book/tables/CoordinateOperationMethods.html">here</a>.
</li>
</ul>