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:04 UTC
[sis-site] 15/39: Publish the English translation of developer
guide (work by Christina Hough).
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 86712f03cbfb75b07744f11a84c8e0eac775b1b4
Author: Martin Desruisseaux <de...@apache.org>
AuthorDate: Tue Sep 2 19:59:48 2014 +0000
Publish the English translation of developer guide (work by Christina Hough).
git-svn-id: https://svn.apache.org/repos/infra/websites/production/sis/content@921055 90ea9780-b833-de11-8433-001ec94261de
---
book/book.css | 181 ++++
book/en/developer-guide.html | 2181 +++++++++++++++++++++++++++++++++++++++
book/fr/developer-guide.html | 2261 +++++++++++++++++++++++++++++++++++++++++
branches.html | 12 +-
build.html | 238 +++++
code-patterns.html | 12 +-
command-line.html | 12 +-
downloads.html | 12 +-
faq.html | 12 +-
index.html | 18 +-
license.html | 12 +-
mail-lists.html | 12 +-
release-management-setup.html | 12 +-
release-management.html | 14 +-
site-management.html | 12 +-
source.html | 42 +-
team-list.html | 14 +-
17 files changed, 4962 insertions(+), 95 deletions(-)
diff --git a/book/book.css b/book/book.css
new file mode 100644
index 0000000..ec67f1e
--- /dev/null
+++ b/book/book.css
@@ -0,0 +1,181 @@
+/*
+ * 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.
+ */
+
+/*
+ * Table of content
+ */
+ul.toc {
+ list-style-type: square;
+}
+
+ul.toc ul {
+ list-style-type: disc;
+ padding-left: 21pt;
+}
+
+/*
+ * Chapters and sections titles (excluding the book titles).
+ */
+h1 {
+ margin-top: 120pt;
+ 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;
+}
+
+h2 {
+ margin-top: 40pt;
+ border-bottom-style: solid;
+ border-bottom-width: 2pt;
+}
+
+h3 {
+ margin-top: 24pt;
+}
+
+h4 {
+ margin-top: 15pt;
+}
+
+p {
+ text-align: justify;
+}
+
+div.example {
+ margin-left: 1.25cm;
+ margin-right: 1.5cm;
+ font-size: smaller;
+}
+
+aside {
+ margin-left: 45pt;
+ margin-right: 45pt;
+ margin-top: 15pt;
+ margin-bottom: 15pt;
+ padding-left: 15pt;
+ padding-right: 15pt;
+ border-style: solid;
+ border-width: 1pt;
+ background-color: #EEEEEE;
+ border-color: #BBBBBB;
+ font-size: smaller;
+}
+
+caption {
+ color: #0086E0;
+ font-weight: bold;
+ padding-top: 9pt;
+ padding-bottom: 3pt;
+}
+
+table {
+ margin-left: auto;
+ margin-right: auto;
+ border-style: solid;
+ border-width: 2pt;
+ border-spacing: 0pt;
+}
+
+table tr th {
+ background-color: #B9DCFF;
+ border-bottom-style: solid;
+ border-bottom-width: 1pt;
+ padding: 3pt;
+}
+
+table tr td {
+ padding-left: 9pt;
+ padding-right: 9pt;
+}
+
+table tr td.leftBorder {
+ border-left-style: solid;
+ border-left-width: 1pt;
+ border-left-color: lightgray;
+}
+
+table tr td.separator {
+ text-align: center;
+ font-weight: bold;
+ background-color: #EEEEFF;
+ border-top-color: LightGray;
+ 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;
+}
+
+table.hidden {
+ border-style: none;
+}
+
+table.hidden tr {
+ vertical-align: top;
+}
+
+table.hidden tr th {
+ border-style: none;
+ background: none;
+ color: #0086E0;
+ font-weight: bold;
+ padding-top: 9pt;
+ padding-bottom: 3pt;
+ padding-left: 0;
+ padding-right: 0;
+}
+
+table.hidden tr td {
+ padding: 0;
+}
+
+pre {
+ margin-left: 30pt;
+ margin-right: 30pt;
+ margin-top: 15pt;
+ margin-bottom: 15pt;
+ padding: 9pt;
+ border: 1pt solid Gray;
+ background: #F8F8F8
+}
+
+/*
+ * OGC/ISO, GeoAPI and SIS legends.
+ */
+code.OGC {
+ color: MediumBlue;
+}
+
+code.GeoAPI {
+ color: Green;
+}
+
+code.SIS {
+ color: SaddleBrown;
+}
+
+code.comment {
+ color: Gray;
+}
diff --git a/book/en/developer-guide.html b/book/en/developer-guide.html
new file mode 100644
index 0000000..632f624
--- /dev/null
+++ b/book/en/developer-guide.html
@@ -0,0 +1,2181 @@
+<?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.
+-->
+
+<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. -->
+
+<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/>
+<i>Christina Hough</i></p>
+<p>This work is licensed under the Apache 2 license.</p>
+<hr/>
+
+<p><b style="font-size: 20pt">Table of content</b></p>
+
+<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">Correspondences Explained in <code>@UML</code> Annotations</a></li>
+ <li><a href="#MappingToJDK">Implicit Correspondences to Standard <abbr>JDK</abbr></a></li>
+ </ul></li>
+ <li><a href="#ServiceLoader">Importing an Implementation of the Interfaces</a><ul>
+ <li><a href="#GeoAPI-simple">Providing the Correct Implementation</a></li>
+ </ul></li>
+ <li><a href="#GeoAPI-modules">GeoAPI Modules</a><ul>
+ <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">Validations of Instances</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> 19139</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 Sequences of Characters for Each Local Convention</a></li>
+ <li><a href="#InternationalString">Single Instance in All Local 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>
+</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 the users of (<abbr>SIS</abbr>)
+ geographic information systems by confronting them with an apparently chaotic variety of data formats and structures.
+ The characteristics of these structures vary according to the phenomenon observed and methods of measurement,
+ as well as the habits of the organizations producing the data.
+ Such a variety represents an obstacle in studies that require heterogeneous combinations of data,
+ especially when they originate in communities that are traditionally distinct.
+ For example, a researcher studying cholera might be interested in populations of shrimp as a propagation vector of the disease.
+ But as doctors and oceanographers are not usually in the habit of sharing their work,
+ the participants of such a study may be limited by the effort required to convert the data.
+</p><p>
+ We cannot impose a uniform format on all the collections of data, as the diversity of formats is tied to factors such as the constraints imposed by the measuring apparatus,
+ 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 would 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 of the standards anticipated difficulties that sometimes escape the engineer at the beginning of a project,
+ but which risk catching up with them before the end.
+</p>
+
+
+
+<h2 id="About">Conventions Used in This Guide</h2>
+<p>
+ The elements defined in an information language, such as classes and methods in Java or elements in an <abbr>XML</abbr> document,
+ 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>
+
+
+
+<h1 id="Standards">Standards and Norms</h1>
+<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:
+</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>
+</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.
+</p><p>
+ Besides these formal standardization organizations, there are organizations that are not officially dedicated
+ to the creation of standards, but whose work has largely been adopted as <i>de facto</i> standards.
+ In particular, the <a href="http://www.epsg.org">EPSG</a> database offers numeric codes which allow the easy identification of coordinates among
+ <a href="../sis-referencing/supported-codes.html">several thousand</a>.
+ 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>
+<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.
+</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.
+</p>
+
+
+
+<h3 id="OGC-SWG">Standard Working Group (<abbr>SWG</abbr>) Procedures</h3>
+<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.
+</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.
+</p><p>
+ As far as possible, the working group must structure the specifications as a nucleus around which various extensions might be built.
+ A series of tests must accompany the standard, allowing implementations to be classified by the level of test passed.
+ There must be at least one <i>reference implementation</i> that passes all the tests in order to demonstrate that the standard is usable.
+</p><p>
+ When the standard is judged ready, the <abbr title="Standard Working Group">SWG</abbr> votes on a motion proposing its submission to a vote of the higher authorities of the <abbr title="Open Geospatial Consortium">OGC</abbr>.
+ 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>
+<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 of 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>.
+</p><p>
+ Certain members of the <abbr title="Open Geospatial Consortium">OGC</abbr> and the <abbr title="Technical Committee">TC</abbr> also act as liaisons with the International Organization for Standardization (<abbr title="International Organization for Standardization">ISO</abbr>).
+ Cooperation between the two organizations goes two ways: the <abbr>OGC</abbr> adopts the <abbr>ISO</abbr> standards as a foundation on which to develop new standards,
+ and certain new <abbr>OGC</abbr> standards become <abbr>ISO</abbr> standards.
+</p>
+
+
+
+
+<h3 id="OGC-RFC">Procedure for the Submission of Proposals for Modification</h3>
+<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>.
+</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.
+</p>
+
+
+
+<h2 id="SpecificationTypes">Different Types of Specifications</h2>
+<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.”
+</p><p>
+ <a href="http://www.opengeospatial.org/standards/as">Abstract specifications</a> do not refer to any specific information 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 exist for <abbr title="Structured Query Language">SQL</abbr>, <abbr title="Common Object Request Broker Architecture">CORBA</abbr>, <abbr title="Component Object Model">COM</abbr>, and Java languages.
+ As these languages are capable of executing procedures, the specifications of this period define not only data structures,
+ but also operations that apply to these structures.
+</p><p>
+ Thereafter, enthusiasm for “Web 2.0” increased interest <abbr>XML</abbr> over other languages.
+ Older implementation specifications were deprecated,
+ and <abbr title="XML Schema Definition">XSD</abbr> schemas became the principle 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:
+</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>
+</ul>
+<p>
+ The Apache <abbr title="Spatial Information System">SIS</abbr> project is based on the most recent specifications, drawing from the archives of the <abbr title="Open Geospatial Consortium">OGC</abbr> to complete certain abstract standards or make them more usable.
+ Some old definitions are preserved as “methods of convenience,” not always bringing new functionality, but facilitating the practical use of a library.
+</p><p>
+ The following table lists the principal 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.
+</p>
+<table>
+ <caption>Principal 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>
+ </tr>
+ <tr>
+ <td class="separator" colspan="4">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>
+ </tr>
+ <tr>
+ <td><abbr>ISO</abbr> 19115</td>
+ <td>Topic 11</td>
+ <td><i>Metadata</i></td>
+ <td><code>org.opengis.metadata</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>
+ </tr>
+ <tr>
+ <td><abbr>ISO</abbr> 19108</td>
+ <td></td>
+ <td><i>Temporal Schema</i></td>
+ <td><code>org.opengis.temporal</code></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>
+ </tr>
+ <tr>
+ <td><abbr>ISO</abbr> 19101</td>
+ <td>Topic 5</td>
+ <td><i>Features</i></td>
+ <td><code>org.opengis.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>
+ </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>
+ </tr>
+ <tr>
+ <td class="separator" colspan="4">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>
+ </tr>
+ <tr>
+ <td><abbr>ISO</abbr> 13249</td>
+ <td></td>
+ <td><i><abbr>SQL</abbr> spatial</i></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>
+ </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>
+ </tr>
+ <tr>
+ <td></td>
+ <td><abbr>SLD</abbr></td>
+ <td><i>Styled Layer Descriptor</i></td>
+ <td><code>org.opengis.style</code></td>
+ </tr>
+ <tr>
+ <td class="separator" colspan="4">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>
+ <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>
+ <td><abbr>WCS</abbr></td>
+ <td><i>Web Coverage Service</i></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td><abbr>WPS</abbr></td>
+ <td><i>Web Processing Service</i></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Open<abbr>LS</abbr></td>
+ <td><i>Location Services</i></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td><abbr>SWE</abbr></td>
+ <td><i>Sensor Web Enablement</i></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td><abbr>SOS</abbr></td>
+ <td><i>Sensor Observation Service</i></td>
+ <td></td>
+ </tr>
+</table>
+
+
+
+<h2 id="DefinitionOfTerms">Definition of Terms</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.
+</p>
+
+
+
+<h1 id="GeoAPI">GeoAPI</h1>
+<p>
+ The <a href="http://www.geoapi.org">GeoAPI</a> project offers a set of Java interfaces for geospatial applications.
+ In a series of <code class = "GeoAPI"> org.opengis.*</code> packages, GeoAPI defines structures representing metadata,
+ reference systems of coordinates and operations that perform cartographic projections.
+ In one part that is not yet standardized — called <i>pending</i> — GeoAPI defines structures that represent geo-referenced images,
+ 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>
+</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 pacet 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.
+</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 display 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> standard 19115.
+ 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> Standard 19111 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 may 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> Standard 19115, 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 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> Standard 19115-2 is an extension of <abbr>ISO</abbr> Standard 19115-1, 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> Standard 19115-2 defines the class <code class="OGC">MI_Band</code>,
+ which extends the class <code class="OGC">MD_Band</code> from <abbr>ISO</abbr> Standard 19115-1 by adding attributes that would have appeared
+ directly in the parent class if there had been time.
+ In GeoAPI, we have chosen to “repair” these anomalies by fusing these two classes into a single interface.
+ </p></div>
+ </li>
+</ul>
+<p>
+ Deviations from the standards are documented in each class and method affected.
+ 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">Correspondences Explained in <code>@UML</code> Annotations</h3>
+<p>
+ For each class, method and constant defined by an <abbr title="Open Geospatial Consortium">OGC</abbr> or <abbr title="International Organization for Standardization">ISO</abbr> standard,
+ GeoAPI indicates its provenance using annotations defined in the <code class="GeoAPI">org.opengis.annotation</code> package.
+ 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> Standard 19111.
+ 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> Standard 19111,
+ 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">
+/**
+ * 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">
+ /**
+ * 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>;
+}</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:
+</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>ident</var> = <var>annot</var>.identifier();
+System.out.println("The standard name for the method " + <var>method</var>.getName() + " is " + <var>ident</var>);</pre>
+
+<p>
+ The class <code class="SIS">org.apache.sis.util.iso.Types</code> provides the commodity method
+ <code class="SIS">getStandardName(Class)</code> to perform this operation.
+</p>
+
+<p>
+ The reverse operation — getting the Java class and method of 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);
+}
+String <var>isoName</var> = "<code class="OGC">CI_Citation</code>";
+String <var>geoName</var> = getProperty(<var>isoName</var>);
+Class<?> <var>type</var> = Class.forName(<var>geoName</var>);
+System.out.println("The GeoAPI interface <abbr>ISO</abbr> " + <var>isoName</var> + " is " + <var>type</var>);</pre>
+
+<p>
+ The class <code class="SIS">org.apache.sis.util.iso.Types</code> provides the commodity method
+ <code class="SIS">forStandardName(String)</code> to perform this operation.
+</p>
+
+
+
+<h3 id="MappingToJDK">Implicit Correspondences to Standard <abbr>JDK</abbr></h3>
+<p>
+ Come classes and methods have neither an <code class="GeoAPI">@UML</code> annotation, nor an entry in the <code class="GeoAPI">class-index.properties</code> file.
+ They are either extensions of GeoAPI, or else types defined in other libraries, such as standard <abbr title="Java Development Kit">JDK</abbr>.
+ In this last case, the correspondence to <abbr title="International Organization for Standardization">ISO</abbr> standards is implicit.
+ The following table describes this correspondance for <abbr>ISO</abbr> Standard 19103 types.
+ Standard Java's original types are preferred when applicable,
+ but where necessary their equivalents in the form of objects are used in order to authorize null values.
+</p>
+<table>
+ <caption>Correspondences Between <abbr>ISO</abbr> 19103 et <abbr>JDK</abbr></caption>
+ <tr>
+ <th>Type <abbr>ISO</abbr></th>
+ <th>Type <abbr>JDK</abbr></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>(pas d’équivalent)</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>
+</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>).
+</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 functions of <code>Enum</code> while being extensible.
+ Extensions are derived from <code class="GeoAPI">valueOf(String)</code> static methods, which, in contrast to <code>Enum</code>,
+ creates new instances if the name provided does not correspond to the name of an existing instance.
+</p>
+
+<pre><code class="GeoAPI">MediumName</code> <var>cdRom</var> = <code class="GeoAPI">MediumName.CD_ROM;</code>
+<code class="GeoAPI">MediumName</code> <var>usbKey</var> = <code class="GeoAPI">MediumName.valueOf</code>("<code class="GeoAPI">USB_KEY</code>"); <code class="comment">// There is no constraint on this value.</code>
+<b>assert</b> <code class="GeoAPI">MediumName.valueOf</code>("<code class="GeoAPI">CD_ROM</code>") == <var>cdRom</var> : "valueOf must return existing constants.";
+<b>assert</b> <code class="GeoAPI">MediumName.valueOf</code>("<code class="GeoAPI">USB_KEY</code>") == <var>usbKey</var> : "valueOf must hide the previously requested values.";</pre>
+
+
+
+<h2 id="ServiceLoader">Importing an Implementation of the Interfaces</h2>
+<p>
+ GeoAPI defines factories (<code class="GeoAPI">Factory</code>) that can create implementations of its interfaces.
+ For example, <code class="GeoAPI">DatumFactory</code> provides methods that can create instances which implement the interfaces of a
+ <code class="GeoAPI">org.opengis.referencing.datum</code> package.
+ A <code class="GeoAPI">Factory</code> must be implemented by a geospatial library,
+ and declared as a <i>service</i> as defined by by the standard <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 existance.
+</p>
+<p>
+ If the library has correctly declared its factories as services,
+ users may import them by using <code>ServiceLoader</code>, as in the example below.
+ This example only takes the first factory located; if there is more than one factory -
+ for example when multiple libraries coexist — then the choice is left to the user.
+</p>
+
+<pre><b>import</b> <code class="GeoAPI">org.opengis.referencing.GeodeticDatum</code>;
+<b>import</b> <code class="GeoAPI">org.opengis.referencing.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>(…);
+ }
+}</pre>
+
+
+
+<h3 id="GeoAPI-simple">Providing the Correct Implementation</h3>
+<p>
+ Implementing GeoAPI oneself in order to meet very specific needs is not difficult.
+ A developer might concentrate on a handful of interfaces among the hundreds available,
+ while keeping other interfaces as extension points to eventually implement as needed.
+</p>
+<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:
+</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 referential.</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 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>
+<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, <i>snapshots</i> of certain <abbr>SIS</abbr> branches may depend on <code class="GeoAPI">geoapi-pending</code>.
+</p>
+<p>
+ 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.
+ <i>Snapshot</i> versions of <code>jdk6</code> branches, and Apache <abbr>SIS</abbr>'s <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 joined 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.
+ <i>Snapshot</i> and <i>milestones</i> versions depend on the <code class="GeoAPI">geoapi-pending</code> module,
+ while the final versions depend on <code class="GeoAPI">geoapi</code>.
+ </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++ library Proj.4.
+ 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="Network Common Data Form">NetCDF</abbr> library
+ of the <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>.
+ 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>
+</ul>
+
+<h3 id="GeoAPI-core">The Interfaces' Definition Modules</h3>
+<p>
+ <code class="GeoAPI">geoapi</code> and <code class="GeoAPI">geoapi-pending</code> modules provide interfaces derived from the
+ <abbr title="Unified Modeling Language">UML</abbr> schemas of the international standards.
+ The conceptual model will be explained in detail in the chapters describing the implementation of Apache <abbr>SIS</abbr>.
+ However, we can get an overview of its content by consulting the page listing
+ <a href="http://www.geoapi.org/3.0/javadoc/content.html">GeoAPI methods with their original standards</a>.
+</p>
+
+
+
+<h3 id="GeoAPI-conformance">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:
+</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>
+</ul>
+
+
+
+<h4 id="GeoAPI-validators">Validations of Instances</h4>
+<p>
+ GeoAPI can validate an instance of its interfaces by checking that certain constraints are observed.
+ These constraints, which may only be expressed in the method signature,
+ are usually described textually in the abstract specifications or in the javadoc.
+</p>
+<div class="example"><p><b>Example:</b>
+ The transformation of a coordinate (<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 dimensions of the output must equal the number of dimensions of the input in the following 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].sourceDimensions == coordOperation[i-1].targetDimensions</code>.
+</p></div>
+
+<p>
+ The easiest way to perform these verifications is to call the static methods <code class="GeoAPI">validate(…)</code> of the class
+ <code class="GeoAPI">org.opengis.test.Validators</code>.
+ As all of these methods bear the same name, it is enough to write “<code>validate(<var>value</var>)</code>” and then allow the compiler
+ to choose the most appropriate method for the type of object given in the argument.
+ If the object type is not known at the time of compilation,
+ the method <code class="GeoAPI">dispatch(Object)</code> may redirect the work to the 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 useless to validate the components themselves, unless you wish to isolate the test for a particular item known to cause problems.
+</p>
+<p>
+ By default, validations are as strict as possible. It is always possible to relax certain rules.
+ The most common is to tolerate the absence of attributes that would normally be mandatory.
+ This rule and a few others may be modified globally for all tests executed by the currently running <abbr title="Java Virtual Machine">JVM</abbr>,
+ as in the following example:
+</p>
+
+<pre><b>import</b> <code class="GeoAPI">org.opengis.metadata.Metadata</code>;
+<b>import</b> <code class="GeoAPI">org.opengis.test.Validators</code>;
+<b>import</b> org.junit.Test;
+
+<b>public 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>;
+ }
+
+ @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>);
+ }
+}</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.
+</p>
+
+<pre><b>import</b> <code class="GeoAPI">org.opengis.metadata.Metadata</code>;
+<b>import</b> <code class="GeoAPI">org.opengis.test.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> 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>;
+ }
+
+ @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>);
+ }
+}</pre>
+
+
+
+<h4 id="GeoAPI-tests">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>".
+ In addition, an <code class="GeoAPI">org.opengis.test.TestSuite</code> class includes all test classes defined in the
+ <code class="GeoAPI">geoapi-conformance</code> module.
+ One way to execute all of these tests at once is to create a sub-class of <code class="GeoAPI">TestSuite</code>,
+ perhaps including a static block performing a configuration of validators as in the previous example,
+ and inherit the tests defined in GeoAPI.
+</p>
+<p>
+ Apache <abbr title="Spatial Information System">SIS</abbr> inherits GeoAPI's <code class="GeoAPI">*Test</code> classes on a case-by-case basis,
+ in the appropriate modules.
+ The <code class="GeoAPI">TestSuite</code> class is used instead in an integration test encompassing all <abbr>SIS</abbr> modules.
+ The example below gives an example of a personalizaed 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 verrification, 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.*;
+
+@RunWith(JUnit4.class)
+<b>public 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">
+ /**
+ * 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; // Tolérance de 10 cm.
+ <b>super</b>.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>;
+ }
+<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>);
+ }
+}</pre>
+
+
+
+<h3 id="GeoAPI-examples">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>.
+</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>.
+</p>
+<p>
+ For more 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>
+<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 to 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> Standard 19115 (an abstract specification),
+ while the representation of these classes in <abbr>XML</abbr> is described in <abbr>ISO</abbr> Standard 19139.
+</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> Standard 19139 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 class <code class="SIS">org.apache.sis.xml.Namespaces</code>.
+</p>
+<table>
+ <caption>Common Namespace Prefixes <abbr>XML</abbr></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 correspondences 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 written with relatively few models,
+ but with complex structures and deep hierarchies.
+ The metadata set in <abbr>ISO</abbr> Standard 19139 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>
+</aside>
+
+
+
+<h2 id="XML-ISO-19115">Representing Metadata According to <abbr>ISO</abbr> 19139</h2>
+<p>
+ For each metadata class, there is an <abbr>XML</abbr> type named 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> Standard 19139 arranges the content of these objects in an unusual way:
+ for each property whose value type is itself another class of <abbr>ISO</abbr> 19139,
+ 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 property <code class="OGC">citedResponsibleParty</code> 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>
+ <identificationInfo>
+ <b><MD_DataIdentification></b>
+ <citation>
+ <b><CI_Citation></b>
+ <citedResponsibleParty>
+ <b><CI_Responsibility></b>
+ <party>
+ <b><CI_Party></b>
+ <contactInfo>
+ <b><CI_Contact></b>
+ <onlineResource>
+ <b><CI_OnlineResource></b>
+ <linkage>
+ <URL>http://www.opengeospatial.org</URL>
+ </linkage>
+ <b></CI_OnlineResource></b>
+ </onlineResource>
+ <b></CI_Contact></b>
+ </contactInfo>
+ <b></CI_Party></b>
+ </party>
+ <b></CI_Responsibility></b>
+ </citedResponsibleParty>
+ <b></CI_Citation></b>
+ </citation>
+ <b></MD_DataIdentification></b>
+ </identificationInfo>
+<b></MD_Metadata></b></pre>
+
+<p>
+ The preceding example, like all documents that conform to <abbr>ISO</abbr> 19139,
+ 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 method <code class="GeoAPI">Metadata.getIdentificationInfo()</code>.
+ </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 Java interface <code class="GeoAPI">DataIdentification</code>.
+ 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 a single unified view of these two types of elements publicly.
+ 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>.
+</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 in any case 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>
+</aside>
+
+
+<h3 id="gco-id">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:
+</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>
+ <identificationInfo>
+ <MD_DataIdentification id="<b>my_id</b>">
+ <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>"/>
+</MD_MetaData></pre>
+ </td>
+ </tr>
+</table>
+
+<p>
+ 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>
+</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:
+</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>;
+<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>);
+ }
+}</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.
+</p>
+
+
+
+<h3 id="nilReason">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> Standard 19115.
+ <abbr>ISO</abbr> Standard 19139 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.xml.NilObject</code> interface.
+ This interface notes 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 the order preference 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 nul.
+</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>.
+</p>
+
+<table class="hidden">
+ <tr>
+ <th>Information Included</th>
+ <th>Missing Information</th>
+ </tr>
+ <tr>
+ <td>
+ <pre 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"/>
+</CI_Citation></pre>
+ </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 criteria or calculations that are required to use the <code>equals(Object)</code> and <code>hashCode()</code> methods in all implementations.
+ This approach is particlarly 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 contract for the <code>equals(Object)</code> and
+ <code>hashCode()</code> methods:
+</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>
+</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:
+</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 referential, 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.
+</p>
+
+
+
+<h2 id="Internationalization">Internationalization</h2>
+<p>
+ In an architecture where a program executed on a server provides its data to multiple clients,
+ the server's local 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 the 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 Sequences of Characters for Each Local Convention</h3>
+<p>
+ Some classes are only designed to function according to one local 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>
+ with some exceptions.
+ 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 is also able to determine the local 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 local 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 local 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, 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.
+</p>
+<p>
+ The utility class <code class="SIS">org.apache.sis.util.Exceptions</code> provides commodity methods to get messages
+ according to the conventions of local data when this information is available.
+</p>
+
+
+
+<h3 id="InternationalString">Single Instance in All Local Conventions</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 sequence of characters is obtained,
+ 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 local 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>.
+</p></div>
+<p>
+ When defining spatial objects independently of local 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 conserve memory.
+</p>
+
+
+
+<h3 id="Locale.ROOT"><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:
+</p>
+<ul>
+ <li>
+ Identifiers are written so that 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>
+</ul>
+
+
+
+<h3 id="UnicodePoint">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:
+</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>
+ }
+}</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>);
+}</pre>
+ </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.
+</p>
+
+
+
+<h4 id="Whitespaces">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.
+</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.
+</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.
+</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.
+</p>
+
+
+
+<h1 id="Geometry">Geometries</h1>
+<p>
+ This chapter introduces a few aspects of <abbr>ISO</abbr> Standard 19107 (<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>
+<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 sort 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.Collection</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>
+ The parent class of all geometries is called <code class="OGC">GM_Object</code> in <abbr>ISO</abbr> Standard 19107.
+ GeoAPI interfaces use the name <code class="GeoAPI">Geometry</code> instead, as the omission of the prefix
+ <code class="OGC">GM_</code> (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>.
+</p>
+
+
+
+<h3 id="DirectPosition">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.
+</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.
+</p>
+
+
+
+<h3 id="Envelope">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.
+</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.
+</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.
+</p>
+
+
+
+<h4 id="AntiMeridian">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:
+</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>
+</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.
+</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."/>
+</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 so as not to cause confusion.
+ 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>
+</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 commodity 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, infinite totality of values.
+ 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 standard that describes them, “Coverage Geometry and Functions,” (<abbr>ISO</abbr> 19123),
+ 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>
+</ul>
+<p>
+ The characteristics of the spatial domain are defined by <abbr>ISO</abbr> Standard 19123,
+ 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://fr.wikipedia.org/wiki/Intervalle_%28math%C3%A9matiques%29">the common mathematical concept of an interval</a>.
+ This textual representation approaches the specifications of <abbr>ISO</abbr> Standard 31-11,
+ 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>
+</aside>
+
+ <!-- End of shifted indentation. -->
+ </body>
+</html>
diff --git a/book/fr/developer-guide.html b/book/fr/developer-guide.html
new file mode 100644
index 0000000..651011f
--- /dev/null
+++ b/book/fr/developer-guide.html
@@ -0,0 +1,2261 @@
+<?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.
+-->
+
+<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. -->
+
+<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/>
+<i>Christina Hough</i> (pour la traduction anglaise)</p>
+<p>Ce document est distribué sous licence Apache 2.</p>
+<hr/>
+
+<p><b style="font-size: 20pt">Table des matières</b></p>
+
+<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> 19139</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>
+</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.
+</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.
+</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.
+</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>
+
+
+
+<h1 id="Standards">Standards et normes</h1>
+<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:
+</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>
+</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.
+</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.
+</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.
+</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.
+</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.
+</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>.
+</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>.
+</p>
+
+
+
+<h3 id="OGC-RFC">Procédure de soumission de propositions de modifications</h3>
+<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>.
+</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.
+</p>
+
+
+
+<h2 id="SpecificationTypes">Les différents types de spécifications</h2>
+<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 ».
+</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.
+</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:
+</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>
+</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.
+</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.
+</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 GeoAPI</th>
+ </tr>
+ <tr>
+ <td class="separator" colspan="4">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>
+ </tr>
+ <tr>
+ <td><abbr>ISO</abbr> 19115</td>
+ <td>Topic 11</td>
+ <td><i>Metadata</i></td>
+ <td><code>org.opengis.metadata</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>
+ </tr>
+ <tr>
+ <td><abbr>ISO</abbr> 19108</td>
+ <td></td>
+ <td><i>Temporal Schema</i></td>
+ <td><code>org.opengis.temporal</code></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>
+ </tr>
+ <tr>
+ <td><abbr>ISO</abbr> 19101</td>
+ <td>Topic 5</td>
+ <td><i>Features</i></td>
+ <td><code>org.opengis.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>
+ </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>
+ </tr>
+ <tr>
+ <td class="separator" colspan="4">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>
+ </tr>
+ <tr>
+ <td><abbr>ISO</abbr> 13249</td>
+ <td></td>
+ <td><i><abbr>SQL</abbr> spatial</i></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>
+ </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>
+ </tr>
+ <tr>
+ <td></td>
+ <td><abbr>SLD</abbr></td>
+ <td><i>Styled Layer Descriptor</i></td>
+ <td><code>org.opengis.style</code></td>
+ </tr>
+ <tr>
+ <td class="separator" colspan="4">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>
+ <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>
+ <td><abbr>WCS</abbr></td>
+ <td><i>Web Coverage Service</i></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td><abbr>WPS</abbr></td>
+ <td><i>Web Processing Service</i></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Open<abbr>LS</abbr></td>
+ <td><i>Location Services</i></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td><abbr>SWE</abbr></td>
+ <td><i>Sensor Web Enablement</i></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></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>
+<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.
+</p>
+
+
+
+<h1 id="GeoAPI">GeoAPI</h1>
+<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>
+</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>.
+</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:
+</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>
+</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.
+</p>
+
+
+
+<h3 id="UML-annotation">Correspondances explicitées par l’annotation <code>@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>.
+</p>
+
+<pre><b>package</b> <code class="GeoAPI">org.opengis.referencing.crs</code>;
+<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">
+ /**
+ * 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>;
+}</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>:
+</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>ident</var> = <var>annot</var>.identifier();
+System.out.println("Le nom standard de la méthode " + <var>method</var>.getName() + " est " + <var>ident</var>);</pre>
+
+<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.
+</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.
+</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);
+}
+String <var>isoName</var> = "<code class="OGC">CI_Citation</code>";
+String <var>geoName</var> = getProperty(<var>isoName</var>);
+Class<?> <var>type</var> = Class.forName(<var>geoName</var>);
+System.out.println("L’interface GeoAPI du type <abbr>ISO</abbr> " + <var>isoName</var> + " est " + <var>type</var>);</pre>
+
+<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.
+</p>
+
+
+
+<h3 id="MappingToJDK">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.
+</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>
+</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).
+</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éera 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>
+
+
+
+<h2 id="ServiceLoader">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.
+</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.
+</p>
+
+<pre><b>import</b> <code class="GeoAPI">org.opengis.referencing.GeodeticDatum</code>;
+<b>import</b> <code class="GeoAPI">org.opengis.referencing.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>(…);
+ }
+}</pre>
+
+
+
+<h3 id="GeoAPI-simple">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.
+</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:
+</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>
+</table>
+
+
+
+<h2 id="GeoAPI-modules">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 les <i>snapshot</i> de certaines branches de <abbr>SIS</abbr> peuvent dépendre de <code class="GeoAPI">geoapi-pending</code>.
+</p>
+<p>
+ 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 versions <i>snapshot</i> des branches <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.
+ Les versions <i>snapshot</i> et les <i>milestones</i> dépendent du module <code class="GeoAPI">geoapi-pending</code>
+ alors que les versions finales dépendent de <code class="GeoAPI">geoapi</code>.
+ </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>
+</ul>
+
+<h3 id="GeoAPI-core">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 avec leurs standards d’origines</a>.
+</p>
+
+
+
+<h3 id="GeoAPI-conformance">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:
+</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>
+</ul>
+
+
+
+<h4 id="GeoAPI-validators">Validations des instances</h4>
+<p>
+ GeoAPI peut valider une instance de ses interfaces en vérifiant que certaines contraintes sont respectées.
+ Ces contraintes, qui ne peuvent pas être exprimées dans la signature de la méthode, 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 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].sourceDimensions == coordOperation[i-1].targetDimensions</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.
+</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
+ connu pour être 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:
+</p>
+
+<pre><b>import</b> <code class="GeoAPI">org.opengis.metadata.Metadata</code>;
+<b>import</b> <code class="GeoAPI">org.opengis.test.Validators</code>;
+<b>import</b> org.junit.Test;
+
+<b>public 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>;
+ }
+
+ @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>);
+ }
+}</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.
+</p>
+
+<pre><b>import</b> <code class="GeoAPI">org.opengis.metadata.Metadata</code>;
+<b>import</b> <code class="GeoAPI">org.opengis.test.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> 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>;
+ }
+
+ @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>);
+ }
+}</pre>
+
+
+
+<h4 id="GeoAPI-tests">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>".
+ En outre, une classe <code class="GeoAPI">org.opengis.test.TestSuite</code> englobe l’ensemble
+ de toutes les classes de tests définies dans le module <code class="GeoAPI">geoapi-conformance</code>.
+ Une façon d’exécuter l’ensemble de ces tests est donc de créer une sous-classe de
+ <code class="GeoAPI">TestSuite</code>, éventuellement y placer un bloc statique effectuant
+ une configuration des validateurs comme dans l’exemple précédent, et d’hériter les tests définis dans GeoAPI.
+</p>
+<p>
+ Apache <abbr title="Spatial Information System">SIS</abbr> hérite des classes <code class="GeoAPI">*Test</code> de GeoAPI au cas-par-cas,
+ dans les modules appropriées. La classe <code class="GeoAPI">TestSuite</code> sera plutôt
+ utilisée dans un test d’intégration englobant l’ensemble des modules de <abbr>SIS</abbr>.
+ 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.*;
+
+@RunWith(JUnit4.class)
+<b>public 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">
+ /**
+ * 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>;
+ }
+<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>);
+ }
+}</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 (une spécification dite <i>abstraite</i>),
+ alors que la représentation de ces classes en <abbr>XML</abbr> est décrite par le standard <abbr>ISO</abbr> 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> 19139 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>
+</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> 19139 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>
+</aside>
+
+
+
+<h2 id="XML-ISO-19115">Représentation des méta-données selon <abbr>ISO</abbr> 19139</h2>
+<p>
+ Pour chaque classe de méta-donnée, il existe un type <abbr>XML</abbr> nommé comme 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:
+</p>
+<pre><b><MD_Metadata></b>
+ <identificationInfo>
+ <b><MD_DataIdentification></b>
+ <citation>
+ <b><CI_Citation></b>
+ <citedResponsibleParty>
+ <b><CI_Responsibility></b>
+ <party>
+ <b><CI_Party></b>
+ <contactInfo>
+ <b><CI_Contact></b>
+ <onlineResource>
+ <b><CI_OnlineResource></b>
+ <linkage>
+ <URL>http://www.opengeospatial.org</URL>
+ </linkage>
+ <b></CI_OnlineResource></b>
+ </onlineResource>
+ <b></CI_Contact></b>
+ </contactInfo>
+ <b></CI_Party></b>
+ </party>
+ <b></CI_Responsibility></b>
+ </citedResponsibleParty>
+ <b></CI_Citation></b>
+ </citation>
+ <b></MD_DataIdentification></b>
+ </identificationInfo>
+<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:
+</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>
+</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>.
+</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>
+</aside>
+
+
+<h3 id="gco-id">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:
+</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>
+ <identificationInfo>
+ <MD_DataIdentification id="<b>mon_id</b>">
+ <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>"/>
+</MD_MetaData></pre>
+ </td>
+ </tr>
+</table>
+
+<p>
+ 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>
+</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>:
+</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>;
+<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>);
+ }
+}</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.
+</p>
+
+
+
+<h3 id="nilReason">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.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>.
+</p>
+
+<table class="hidden">
+ <tr>
+ <th>Information présente</th>
+ <th>Information absente</th>
+ </tr>
+ <tr>
+ <td>
+ <pre 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"/>
+</CI_Citation></pre>
+ </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>:
+</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>
+</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.
+</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:
+</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>
+</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.
+</p>
+
+
+
+<h2 id="Internationalization">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.
+</p>
+
+<h3 id="LocalizedString">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 exceptions.
+ 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.
+</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.
+</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.
+</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 données
+ lorsque cette information est disponible.
+</p>
+
+
+
+<h3 id="InternationalString">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.
+</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>.
+</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.
+</p>
+
+
+
+<h3 id="Locale.ROOT">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:
+</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>
+</ul>
+
+
+
+<h3 id="UnicodePoint">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:
+</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>
+ }
+}</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>);
+}</pre>
+ </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.
+</p>
+
+
+
+<h4 id="Whitespaces">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.
+</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.
+</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.
+</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>.
+</p>
+
+
+
+<h1 id="Geometry">Géométries</h1>
+<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.
+</p>
+
+
+
+<h2 id="Geometry-root">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.Collection</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>
+ La classe parente de toutes les 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>.
+</p>
+
+
+
+<h3 id="DirectPosition">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.
+</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.
+</p>
+
+
+
+<h3 id="Envelope">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.
+</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.
+</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.
+</p>
+
+
+
+<h4 id="AntiMeridian">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:
+</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>
+</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.
+</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."/>
+</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 sans pour autant les confondre.
+ 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>
+</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>.
+</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>
+</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:
+</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>
+</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>.
+</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>
+</aside>
+
+ <!-- End of shifted indentation. -->
+ </body>
+</html>
diff --git a/branches.html b/branches.html
index 2601a15..f40eb5a 100644
--- a/branches.html
+++ b/branches.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -300,7 +298,7 @@ svn commit --message <span class="s2">"Skip JDK7-specific changes."</s
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/build.html b/build.html
new file mode 100644
index 0000000..478936c
--- /dev/null
+++ b/build.html
@@ -0,0 +1,238 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <title>Build from source</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ <link rel="stylesheet" type="text/css" media="screen" href="css/bootstrap.min.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="css/sis.css">
+
+
+
+
+ <!-- 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 applic [...]
+ </head>
+
+ <body>
+ <div class="navbar navbar-inverse navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/index.html"> Apache SIS™ </a>
+ <div class="nav-collapse">
+ <ul class="nav">
+ <li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">About<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="mail-lists.html">Mailing Lists</a></li>
+ <li><a href="license.html">Project License</a></li>
+ <li><a href="team-list.html">Project Team</a></li>
+ </ul>
+ </li>
+ <li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
+ <li><a href="apidocs/index.html">Online Javadoc</a></li>
+ <li><a href="downloads.html">Downloads</a></li>
+ <li><a href="source.html">Source Code</a></li>
+ <li><a href="code-patterns.html">Code patterns</a></li>
+ <li><a href="faq.html">FAQ</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
+ </ul>
+ </li>
+ <li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ <li><a href="http://www.apache.org">The Foundation</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+ </li>
+ </ul>
+ </div> <!-- /.nav-collapse -->
+ </div><!-- /.container -->
+ </div><!-- /.navbar-inner -->
+ </div>
+
+ <div class="container-fluid">
+ <div class="row-fluid">
+ <div class="span2">
+ <img src="img/logo.png"/>
+ <div class="well sidebar-nav">
+ <ul class="nav nav-list">
+ <li class="active"><a href="index.html">Home</a></li>
+ <li><a href="mail-lists.html">Mailing Lists</a></li>
+ <li><a href="license.html">Project License</a></li>
+ <li><a href="team-list.html">Project Team</a></li>
+ <li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
+ <li><a href="apidocs/index.html">Online Javadoc</a></li>
+ <li><a href="downloads.html">Downloads</a></li>
+ <li><a href="source.html">Source Code</a></li>
+ <li><a href="code-patterns.html">Code patterns</a></li>
+ <li><a href="faq.html">FAQ</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
+ <li class="nav-header">ASF</li>
+ <li><a href="http://www.apache.org">The Foundation</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ </ul>
+ </div><!--/.well -->
+ </div><!--/span-->
+ <div class="span10">
+ <section id="content" class="row">
+ <article class="span12">
+ <p class="page-title">Build from source</p>
+ <p>Apache SIS is built by Maven.
+For installing the JAR files in the local Maven repository, execute the following command
+from the SIS project root:</p>
+<div class="codehilite"><pre>mvn install
+</pre></div>
+
+
+<p>The remaining of this page provides more advanced tips for SIS developers.</p>
+<div class="toc">
+<ul>
+<li><a href="#dist">Distribution file and Pack200 bundle</a><ul>
+<li><a href="#pack200">Generating the Pack200 file alone</a></li>
+<li><a href="#limitations">Known limitations</a></li>
+</ul>
+</li>
+<li><a href="#build-helper">SIS-specific Maven plugin</a><ul>
+<li><a href="#resources">Localized resources compiler</a></li>
+<li><a href="#jar-collect">JAR files collector</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<h1 id="dist">Distribution file and Pack200 bundle</h1>
+<p>The Pack200 bundle is a file with the <code>.pack.gz</code> extension containing all SIS modules except <code>sis-webapp</code>
+(because Web applications use an other packaging) together with their dependencies.
+Pack200 files are uncompressed by the <code>unpack200</code> command provided in JDK/JRE installation.
+However for users convenience, we provide a shell script for uncompressing and launching the SIS
+command line tool in a single step. That shell script, together with the Pack200 file and other
+files (<code>README</code>, <code>LICENSE</code>, <etc.>) are bundled in a ZIP file created as below:</p>
+<div class="codehilite"><pre>mvn org.apache.sis.core:sis-build-helper:dist --non-recursive
+</pre></div>
+
+
+<p>Do not forget the <code>--non-recursive</code> option, otherwise the Mojo will waste CPU by executing itself many time.
+Optionally, the Apache SIS version can be inserted as a 4th element between <code>sis-build-helper:</code> and <code>:dist</code>
+if there is many versions of the plugin in the local repository.</p>
+<p>The result will be created in the <code>target/distribution/apache-sis-<version>.zip</code> file.
+To test, uncompress in any directory and execute <code>apache-sis-<version>/bin/sis</code>.
+The Pack200 file will be automatically uncompressed when first needed.</p>
+<h2 id="pack200">Generating the Pack200 file alone</h2>
+<p>If only the Pack200 file is desired, without the distribution ZIP file,
+one can use the following command:</p>
+<div class="codehilite"><pre>mvn org.apache.sis.core:sis-build-helper:pack --non-recursive
+</pre></div>
+
+
+<p>The above command should create a <code>target/distribution/apache-sis-<version>.pack.gz</code> file.
+To uncompress that file, use the following command:</p>
+<div class="codehilite"><pre>unpack200 --remove-pack-file apache-sis-<version>.pack.gz sis.jar
+</pre></div>
+
+
+<p>The Pack200 bundle does not include the <code>sis-webapp</code> module because the later can be downloaded
+as a <code>WAR</code> file from the Maven repository.</p>
+<h2 id="limitations">Known limitations</h2>
+<p>The current plugin implementation has some hard-coded values, especially:</p>
+<ul>
+<li>The ZIP file content is copied from the <code>application/sis-console/src/main/artifact</code> directory.</li>
+<li>The Pack200 file path inside the ZIP file is hard-coded to <code>lib/sis.pack.gz</code>.</li>
+<li>The final filename is hard-coded to <code>apache-sis-<version>.zip</code>.</li>
+</ul>
+<h1 id="build-helper">SIS-specific Maven plugin</h1>
+<p>Apache SIS uses a <code>sis-build-helper</code> plugin for SIS-specific tasks and Javadoc customization.
+This plugin is used automatically by <code>mvn install</code>. Consequently the remaining of this page
+can be safely ignored. This page is provided only as a reference for developers wanting to
+take a closer look to SIS <code>pom.xml</code> file.</p>
+<h2 id="resources">Localized resources compiler</h2>
+<p>Localized resources are provided in <code>*.properties</code> files as specified by the <code>java.util.PropertyResourceBundle</code> standard class.
+However SIS does not use those resources files directly. Instead <code>*.properties</code> files are transformed into binary files having
+the same filename but the <code>.utf</code> extension. This conversion is done for efficiency, for convenience (the compiler applies the
+<code>java.text.MessageFormat</code> <em>doubled single quotes</em> rule itself), and for compile-time safety.</p>
+<p>In addition to generating the <code>*.utf</code> files, the resource compiler may modify the <code>*.java</code> files having the same name than the
+resource files. For example given a set of <code>Vocabulary*.properties</code> files (one for each supported language), the compiler will
+generate the corresponding <code>Vocabulary*.utf</code> files, then look for a <code>Vocabulary.java</code> source file. If such source file is found
+and contains a public static inner class named <code>Keys</code>, then the compiler will rewrite the constants declared in that inner class
+with the list of keys found in the <code>Vocabulary*.properties</code> files.</p>
+<p>The resource compiler is executed at Maven build time if the <code>pom.xml</code> file contains the following declaration. Note that current
+implementation looks only for resources in any package ending with the <code>resources</code> name; all other packages are ignored.</p>
+<div class="codehilite"><pre><span class="nt"><build></span>
+ <span class="nt"><plugins></span>
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.sis.core<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>sis-build-helper<span class="nt"></artifactId></span>
+ <span class="nt"><version></span>${sis.plugin.version}<span class="nt"></version></span>
+ <span class="nt"><executions></span>
+ <span class="nt"><execution></span>
+ <span class="nt"><goals></span>
+ <span class="nt"><goal></span>compile-resources<span class="nt"></goal></span>
+ <span class="nt"></goals></span>
+ <span class="nt"></execution></span>
+ <span class="nt"></executions></span>
+ <span class="nt"></plugin></span>
+ <span class="nt"></plugins></span>
+<span class="nt"></build></span>
+</pre></div>
+
+
+<p>The resources compilation is part of the build process and does not need to be run explicitly.
+However, if necessary the resources compiler can be invoked alone by the following command line
+in the module containing the resources to recompile. This is sometime useful for regenerating
+the constants in the <code>Keys</code> inner class in a feaster way than building the project.</p>
+<div class="codehilite"><pre>mvn org.apache.sis.core:sis-build-helper:compile-resources
+</pre></div>
+
+
+<h2 id="jar-collect">JAR files collector</h2>
+<p>Links or lists all JAR files (including dependencies) in the <code>target/binaries</code> directory of the parent project.
+This plugin performs a work similar to the standard Maven assembly plugin work, with the following differences:</p>
+<ul>
+<li>In multi-modules projects, this plugin does not create anything in the <code>target</code> directory of sub-modules.
+ Instead, this plugin groups everything in the <code>target/binaries</code> directory of the parent module.</li>
+<li>This plugin does not create any ZIP file. It only links or lists JAR files.
+ The JDK7 and above versions of this plugin use hard links on platforms that support them,
+ so execution of this plugin should be very cheap and consume few disk space.</li>
+<li>Dependencies already present in the <code>target/binaries</code> directory are presumed stables and
+ are not overwritten. Only artifacts produced by the Maven build are unconditionally overwritten.</li>
+</ul>
+<p>This plugin can be activated by the following fragment in the parent <code>pom.xml</code> file:</p>
+<div class="codehilite"><pre><span class="nt"><build></span>
+ <span class="nt"><plugins></span>
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.sis.core<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>sis-build-helper<span class="nt"></artifactId></span>
+ <span class="nt"><version></span>${sis.plugin.version}<span class="nt"></version></span>
+ <span class="nt"><executions></span>
+ <span class="nt"><execution></span>
+ <span class="nt"><goals></span>
+ <span class="nt"><goal></span>collect-jars<span class="nt"></goal></span>
+ <span class="nt"></goals></span>
+ <span class="nt"></execution></span>
+ <span class="nt"></executions></span>
+ <span class="nt"></plugin></span>
+ <span class="nt"></plugins></span>
+<span class="nt"></build></span>
+</pre></div>
+ </article>
+ </section>
+ </div><!--/span-->
+ </div><!--/row-fluid-->
+ </div><!--/container-fluid-->
+
+ <footer class="footer">
+ <div class="container">
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
+ Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+ </div>
+ </footer>
+
+ <script src="js/jquery-1.9.1.min.js"></script>
+ <script src="js/bootstrap.min.js"></script>
+
+</body>
+</html>
diff --git a/code-patterns.html b/code-patterns.html
index 44c6f60..f1fca9d 100644
--- a/code-patterns.html
+++ b/code-patterns.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -161,7 +159,7 @@ Consequently, when iterating over characters in a string, the following pattern
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/command-line.html b/command-line.html
index 042d524..123d7cf 100644
--- a/command-line.html
+++ b/command-line.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -194,7 +192,7 @@ a small Java program using the <a href="apidocs/index.html">SIS API</a>.</p>
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/downloads.html b/downloads.html
index 32f6018..7b2367a 100644
--- a/downloads.html
+++ b/downloads.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -183,7 +181,7 @@ Below are examples of declarations in a <code>pom.xml</code> file for building a
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/faq.html b/faq.html
index 5e64eb4..cd17351 100644
--- a/faq.html
+++ b/faq.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -146,7 +144,7 @@ The attribute values will be wrapped automatically as needed by JAXB adapters.</
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/index.html b/index.html
index 1550a8f..6b9f5d3 100644
--- a/index.html
+++ b/index.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
- <title>Apache SIS</title>
+ <title>The Apache SIS™ library</title>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<link rel="stylesheet" type="text/css" media="screen" href="css/bootstrap.min.css">
<link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -83,7 +81,7 @@
<div class="span10">
<section id="content" class="row">
<article class="span12">
- <p class="page-title">Apache SIS</p>
+ <p class="page-title">The Apache SIS™ library</p>
<p>Apache Spatial Information System (SIS) is a free software, Java language library for developing geospatial applications.
SIS enables better representation of coordinates for searching, data clustering, archiving, or any other relevant spatial needs.
The library is an implementation of <a href="http://www.geoapi.org">GeoAPI 3.0</a> interfaces and can be used for desktop or server applications.</p>
@@ -101,6 +99,7 @@ The latest release is 0.4, released April 2014.
The version under development is 0.5-SNAPSHOT.</p>
<ul>
<li><a href="downloads.html">Downloads</a> as a <code>zip</code> files, or as Maven dependencies.</li>
+<li>Developer guide (<a href="book/en/developer-guide.html">English</a> | <a href="book/fr/developer-guide.html">French</a>) - note that this is work in progress.</li>
<li><a href="command-line.html">Command-line interface</a> for an overview of a command-line tool.</li>
<li><a href="http://cwiki.apache.org/confluence/display/SIS">SIS Wiki</a> for "drawing board" and roadmap.</li>
<li><a href="code-patterns.html">Recommended code patterns</a></li>
@@ -108,6 +107,7 @@ The version under development is 0.5-SNAPSHOT.</p>
<h2 id="developer">SIS developer documentation</h2>
<ul>
<li><a href="source.html">Source code</a>: fetching the code, opening in an IDE, developing, formatting.</li>
+<li><a href="build.html">Build</a>: build from the source, create the PACK200 file.</li>
<li><a href="branches.html">Branches</a>: trunk, JDK6, JDK7.</li>
<li><a href="http://issues.apache.org/jira/browse/SIS">Issue tracking</a>: JIRA.</li>
<li><a href="http://reviews.apache.org/groups/sis">Code review</a></li>
@@ -122,7 +122,7 @@ The version under development is 0.5-SNAPSHOT.</p>
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/license.html b/license.html
index 95ef8c2..6f54106 100644
--- a/license.html
+++ b/license.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -268,7 +266,7 @@ limitations under the License.
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/mail-lists.html b/mail-lists.html
index 58a1485..6d33514 100644
--- a/mail-lists.html
+++ b/mail-lists.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -129,7 +127,7 @@ any changes to the sis code and documentation.</p>
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/release-management-setup.html b/release-management-setup.html
index 3cc2455..8a190cc 100644
--- a/release-management-setup.html
+++ b/release-management-setup.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -274,7 +272,7 @@ together with the PGP key name:</p>
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/release-management.html b/release-management.html
index 5312c9b..b755bbe 100644
--- a/release-management.html
+++ b/release-management.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -181,6 +179,8 @@ in this page shall be adjusted accordingly.</p>
<p>Other files to update:</p>
<ul>
<li>Review and update the <code>README</code> file on the <code>trunk</code> source code repository.</li>
+<li>Review and update the <code>src/main/rdf/DOAP.rdf</code> file. Add a new <code><release></code>
+ block for the new release with the estimated release date.</li>
<li>Commit any changes back to SVN.</li>
</ul>
<h2 id="prepare-website">Web site</h2>
@@ -602,7 +602,7 @@ Report the changes manually on the JDK6 and JDK7 branches.</p>
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/site-management.html b/site-management.html
index 859ebb8..a7ae075 100644
--- a/site-management.html
+++ b/site-management.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -259,7 +257,7 @@ Then:</p>
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/source.html b/source.html
index 10b3c1e..752896a 100644
--- a/source.html
+++ b/source.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -263,6 +261,33 @@ a case-by-case basis. Of course, tabular format shall not be abused.</p>
A separated <code>@author</code> tag is added for each developer.
The intend is to allow other developers to know to who to ask questions if needed.</li>
</ul>
+<p>In addition, the <code>sis-build-helper</code> modules provides the following custom javadoc taglets:</p>
+<table>
+<thead>
+<tr>
+<th>Javadoc tag</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>@module</code></td>
+<td>Create links to the module where the class is defined, source code and Maven artifacts.</td>
+</tr>
+<tr>
+<td><code>{@include}</code></td>
+<td>Include the content of a given HTML file below a <code><h2></code> section having the given title.</td>
+</tr>
+<tr>
+<td><code>{@preformat}</code></td>
+<td>An inline taglet for pre-formatted text. The first word inside the taglet shall be one of <code>java</code>, <code>xml</code>, <code>sql</code>, <code>wkt</code>, <code>text</code>, <code>math</code> or <code>shell</code>.</td>
+</tr>
+<tr>
+<td><code>{@section}</code></td>
+<td>An inline taglet for the title of a new section in the javadoc.</td>
+</tr>
+</tbody>
+</table>
<h3 id="html">HTML elements</h3>
<p>HTML tags and entities shall be used only when there is no equivalent Javadoc tag.
In addition to the standard Javadoc tags, a few <a href="http://builds.apache.org/job/sis-trunk/site/sis-build-helper/index.html">SIS-specific Javadoc tags</a> are available.
@@ -286,7 +311,8 @@ For an introduction to MathML, see:</p>
</ul>
<p>MathML is supported natively in Firefox, Safari and Opera.
Internet Explorer users need to <a href="http://www.dessci.com/en/products/mathplayer/download.htm">install a plugin</a>.
-Firefox users can optionally install the <a href="http://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts">fonts for Mozilla's MathML engine</a> for better results.</p>
+Firefox users can optionally install the <a href="http://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts">fonts for Mozilla's MathML engine</a> for better results.
+Note that a <a href="http://www.mathjax.org/">JavaScript display engine</a> is available for all browsers, but not yet used by SIS.</p>
<h3 id="paragraph">Paragraphs</h3>
<p>Usages of the <code><p></code> tag should be relatively rare.
Do <strong>not</strong> use <code><p></code> for the first paragraph in a package, class or member documentation,
@@ -373,7 +399,7 @@ Implementations specialized for a fixed number of dimensions are suffixed with <
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>
diff --git a/team-list.html b/team-list.html
index 00a704b..c63d3ad 100644
--- a/team-list.html
+++ b/team-list.html
@@ -29,14 +29,13 @@
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation<b class="caret"></b></a>
<ul class="dropdown-menu">
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
</ul>
</li>
<li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
@@ -64,14 +63,13 @@
<li><a href="license.html">Project License</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li class="nav-header">Project Documentation</li>
+ <li><a href="book/en/developer-guide.html">Developer guide</a></li>
<li><a href="apidocs/index.html">Online Javadoc</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source.html">Source Code</a></li>
<li><a href="code-patterns.html">Code patterns</a></li>
- <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li><a href="faq.html">FAQ</a></li>
- <li><a href="release-management.html">Release Management</a></li>
- <li><a href="site-management.html">Edit WebSite</a></li>
+ <li><a href="https://issues.apache.org/jira/browse/SIS">Issue Tracker</a></li>
<li class="nav-header">ASF</li>
<li><a href="http://www.apache.org">The Foundation</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
@@ -106,7 +104,7 @@
</ul>
<h2 id="contributors">Contributors</h2>
<ul>
-<li>None at this time</li>
+<li>Christina Hough (translation of developer guide)</li>
</ul>
</article>
</section>
@@ -116,7 +114,7 @@
<footer class="footer">
<div class="container">
- <p>Copyright © 2013 The Apache Software Foundation, Licensed under the
+ <p>Copyright © 2013-2014 The Apache Software Foundation, Licensed under the
<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br />
Apache SIS, Apache, the Apache feather logo are trademarks of The Apache Software Foundation.</p>
</div>