Author: desruisseaux
Date: Thu May 26 16:49:03 2016
New Revision: 1745623
URL: http://svn.apache.org/viewvc?rev=1745623&view=rev
Log:
Move the chapter about XML format to the end.
Modified:
sis/site/trunk/book/en/body.html
sis/site/trunk/book/fr/body.html
sis/site/trunk/content/book/en/developer-guide.html
sis/site/trunk/content/book/fr/developer-guide.html
Modified: sis/site/trunk/book/en/body.html
URL:
http://svn.apache.org/viewvc/sis/site/trunk/book/en/body.html?rev=1745623&r1=1745622&r2=1745623&view=diff
==============================================================================
--- sis/site/trunk/book/en/body.html (original)
+++ sis/site/trunk/book/en/body.html Thu May 26 16:49:03 2016
@@ -44,10 +44,10 @@
<main>
<xi:include href="introduction.html"/>
<xi:include href="geoapi.html"/>
- <xi:include href="xml.html"/>
<xi:include href="utility.html"/>
<xi:include href="geometry.html"/>
<xi:include href="coverage.html"/>
+ <xi:include href="xml.html"/>
<xi:include href="implementation-independence.html"/>
<xi:include href="test.html"/>
</main>
Modified: sis/site/trunk/book/fr/body.html
URL:
http://svn.apache.org/viewvc/sis/site/trunk/book/fr/body.html?rev=1745623&r1=1745622&r2=1745623&view=diff
==============================================================================
--- sis/site/trunk/book/fr/body.html (original)
+++ sis/site/trunk/book/fr/body.html Thu May 26 16:49:03 2016
@@ -44,11 +44,11 @@
<main>
<xi:include href="introduction.html"/>
<xi:include href="geoapi.html"/>
- <xi:include href="xml.html"/>
<xi:include href="utility.html"/>
<xi:include href="referencing.html"/>
<xi:include href="geometry.html"/>
<xi:include href="coverage.html"/>
+ <xi:include href="xml.html"/>
<xi:include href="implementation-independence.html"/>
<xi:include href="test.html"/>
</main>
Modified: sis/site/trunk/content/book/en/developer-guide.html
URL:
http://svn.apache.org/viewvc/sis/site/trunk/content/book/en/developer-guide.html?rev=1745623&r1=1745622&r2=1745623&view=diff
==============================================================================
--- sis/site/trunk/content/book/en/developer-guide.html (original)
+++ sis/site/trunk/content/book/en/developer-guide.html Thu May 26 16:49:03 2016
@@ -13,7 +13,7 @@
<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"/>
+<link href="../book.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<p style="margin-top: 30pt"><span style="font-size: 30pt; font-weight:
900">Introduction to Apache SIS®</span></p>
@@ -34,10 +34,6 @@
<li><a href="#UML-annotation">Mapping Given by @UML Annotations</a><ul>
<li><a href="#MappingToJDK">Implicit Mapping to Standard JDK</a></li></ul></li>
<li><a href="#GeoAPI-implementation">Interface
implementations</a></li></ul></li>
-<li><a href="#XML-ISO">Representing Objects in XML</a><ul>
-<li><a href="#XML-ISO-19115">Representing Metadata According to ISO
19115-3</a><ul>
-<li><a href="#gco-id">Identification of Already-Defined Instances</a></li>
-<li><a href="#nilReason">Representing Missing
Values</a></li></ul></li></ul></li>
<li><a href="#Utilities">Utility Classes and Methods</a><ul>
<li><a href="#ComparisonMode">Comparison Modes of Objects</a></li>
<li><a href="#Internationalization">Internationalization</a><ul>
@@ -52,6 +48,10 @@
<li><a href="#Envelope">Envelopes</a><ul>
<li><a href="#AntiMeridian">Envelopes that Cross the
Antimeridian</a></li></ul></li></ul></li></ul></li>
<li><a href="#Coverage">Data Coverages</a></li>
+<li><a href="#XML-ISO">Representing Objects in XML</a><ul>
+<li><a href="#XML-ISO-19115">Representing Metadata According to ISO
19115-3</a><ul>
+<li><a href="#gco-id">Identification of Already-Defined Instances</a></li>
+<li><a href="#nilReason">Representing Missing
Values</a></li></ul></li></ul></li>
<li><a href="#reduce-direct-dependency">Reduce direct dependency to Apache
SIS</a><ul>
<li><a href="#UML-annotation-geoapi">Mapping Given by @UML Annotations</a></li>
<li><a href="#ServiceLoader">Fetching implementations of GeoAPI
Interfaces</a><ul>
@@ -508,7 +508,7 @@ Text in gray boxes are for information p
<section>
<header>
<h1 id="GeoAPI"><span class="section-number">2.</span> GeoAPI</h1>
-<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#Foreword">Previous chapter</a></div><div class="next-chapter"><a
href="#XML-ISO">Next chapter</a> â¡</div></div></nav>
+<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#Foreword">Previous chapter</a></div><div class="next-chapter"><a
href="#Utilities">Next chapter</a> â¡</div></div></nav>
</header>
<nav>In this chapter:<ul class="toc">
<li><a href="#UML-annotation">Mapping Given by @UML Annotations</a><ul>
@@ -1058,443 +1058,108 @@ However such instantiations should be do
</section>
<section>
<header>
-<h1 id="XML-ISO"><span class="section-number">3.</span> Representing Objects
in <abbr>XML</abbr></h1>
-<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#GeoAPI">Previous chapter</a></div><div class="next-chapter"><a
href="#Utilities">Next chapter</a> â¡</div></div></nav>
+<h1 id="Utilities"><span class="section-number">3.</span> Utility Classes and
Methods</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#GeoAPI">Previous chapter</a></div><div class="next-chapter"><a
href="#Geometry">Next chapter</a> â¡</div></div></nav>
</header>
<nav>In this chapter:<ul class="toc">
-<li><a href="#XML-ISO-19115">Representing Metadata According to ISO
19115-3</a><ul>
-<li><a href="#gco-id">Identification of Already-Defined Instances</a></li>
-<li><a href="#nilReason">Representing Missing
Values</a></li></ul></li></ul></nav>
-<p>
-Objects defined by <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr
title="International Organization for Standardization">ISO</abbr> standards
must be able to communicate with remote machines via the Internet,
-using different software written in different languages.
-Some of the better known formats include <abbr>WKT</abbr> (<i>Well-Known
Text</i>) and <abbr>WKB</abbr> (<i>Well-Known Binary</i>).
-But the most exhaustive and often referred format is <abbr>XML</abbr>,
-to the point where the representation of <abbr>ISO</abbr> objects in this
format is itself sometimes
-the entire focus of an international standard.
-Thus are metadata classes described in <abbr>ISO</abbr> 19115-1 standard (an
abstract specification),
-while the representation of these classes in <abbr>XML</abbr> is described in
<abbr>ISO</abbr> 19115-3 and 19139 standards.
-</p>
-<p>
-Different <abbr>OGC</abbr>/<abbr>ISO</abbr> standards do not always use the
same strategy to express objects in <abbr>XML</abbr>.
-<abbr>ISO</abbr> 19115-3 standard in particular uses a more verbose approach
than other standards,
-and will be the subject of its <a href="#XML-ISO-19115">own section</a>.
-But most <abbr>XML</abbr> formats define supplementary types and attributes
that are not part of the original abstract specifications.
-These supplementary attributes are usually specific to <abbr>XML</abbr> and
may not appear in the <abbr title="Application Programming
Interface">API</abbr> of Apache <abbr title="Spatial Information
System">SIS</abbr>.
-However, some of these attributes, such as <code class="OGC">id</code>, <code
class="OGC">uuid</code> and
-<code>xlink:href</code>, remain accessible in the form of key-value pairs.
-</p>
+<li><a href="#ComparisonMode">Comparison Modes of Objects</a></li>
+<li><a href="#Internationalization">Internationalization</a><ul>
+<li><a href="#LocalizedString">Distinct Character Sequences for Each
Locale</a></li>
+<li><a href="#InternationalString">Single instance for all supported
locales</a></li>
+<li><a href="#Locale.ROOT">Locale.ROOT Convention</a></li>
+<li><a href="#UnicodePoint">Treatment of Characters</a><ul>
+<li><a href="#Whitespaces">The Interpretation of Blank
Spaces</a></li></ul></li></ul></li></ul></nav>
<p>
-<abbr>XML</abbr> documents may use any prefixes,
-but the following prefixes are commonly used.
-They therefore appear by default in documents produced by Apache
<abbr>SIS</abbr>.
-These prefixes are defined in the <code
class="SIS">org.apache.sis.xml.Namespaces</code> class.
+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>
-<table>
-<caption>Common <abbr>XML</abbr> namespace prefixes</caption>
-<tr>
-<th>Prefix</th>
-<th>Namespace</th>
-</tr>
-<tr>
-<td><code class="OGC">gco</code></td>
-<td><code>http://www.isotc211.org/2005/gco</code></td>
-</tr>
-<tr>
-<td><code class="OGC">gfc</code></td>
-<td><code>http://www.isotc211.org/2005/gfc</code></td>
-</tr>
-<tr>
-<td><code class="OGC">gmd</code></td>
-<td><code>http://www.isotc211.org/2005/gmd</code></td>
-</tr>
-<tr>
-<td><code class="OGC">gmi</code></td>
-<td><code>http://www.isotc211.org/2005/gmi</code></td>
-</tr>
-<tr>
-<td><code class="OGC">gmx</code></td>
-<td><code>http://www.isotc211.org/2005/gmx</code></td>
-</tr>
-<tr>
-<td><code class="OGC">gml</code></td>
-<td><code>http://www.opengis.net/gml/3.2</code></td>
-</tr>
-<tr>
-<td><code>xlink</code></td>
-<td><code>http://www.w3.org/1999/xlink</code></td>
-</tr>
-</table>
-<aside>
-<h2>Tools for Reading and Writing <abbr>XML</abbr> Documents</h2>
+<h2 id="ComparisonMode"><span class="section-number">3.1.</span> Comparison
Modes of Objects</h2>
<p>
-Apache <abbr title="Spatial Information System">SIS</abbr> uses different
libraries to read and write different types of objects.
-The library used depends on the complexity of the object and on performance
constraints.
-For example, <abbr title="Java Architecture for XML Binding">JAXB</abbr>
annotations have the advantage of being close to code,
-which makes it easier to maintain mapping between Java and <abbr>XML</abbr>.
-On the other hand, <abbr title="Simple API for XML">SAX</abbr> is more
efficient.
-In general, Apache <abbr>SIS</abbr> uses:
+There are various opinions on how to implement Java standard's
<code>Objectâ.equals(Object)</code> method.
+According to some, it should be possible to compare different implementations
of the same interface or base class.
+But to follow this policy, each interface or base class's javadoc must define
the algorithms that all implementations
+shall use for their <code>equals(Object)</code> and <code>hashCode()</code>
methods.
+This approach is common in <code>java.util.Collection</code> and its child
interfaces.
+Transferring this approach to certain GeoAPI interfaces, however, would be a
difficult task,
+and would probably not be followed in many implementations.
+Moreover, it comes at the expense of being able to take into account
supplementary attributes in the child interfaces,
+unless this possibility has been specified in the parent interface.
+This constraint arises from the following points of the
<code>equals(Object)</code> and <code>hashCode()</code> method contracts:
</p>
<ul>
-<li>
-<abbr>JAXB</abbr> for objects that do not occur very often in <abbr>XML</abbr>
documents, but with complex structures and deep hierarchies.
-The metadata set in <abbr title="International Organization for
Standardization">ISO</abbr> 19115-3 standard is a typical example
-</li>
-<li>
-<abbr>SAX</abbr> for objects that are relatively simple, but which may exist
in very large numbers.
-The set of points in a geometry is a typical example.
-</li>
-<li>
-<abbr title="Document Object Model">DOM</abbr> as an alternative to
<abbr>JAXB</abbr>
-when the <abbr>XML</abbr> elements do not correspond exactly to Java
attributes.
-<i>Features</i> are an example, as their structure is dynamic.
-</li>
+<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>
-</aside>
-
-
-
-<h2 id="XML-ISO-19115"><span class="section-number">3.1.</span> Representing
Metadata According to <abbr title="International Organization for
Standardization">ISO</abbr> 19115-3</h2>
-<p>
-For each metadata class, there is an <abbr>XML</abbr> type with the same name
than in the abstract specification
-(for example, <code class="OGC">gmd:MD_Metadata</code> and <code
class="OGC">gmd:CI_Citation</code>).
-All of these types may be used as the root of an <abbr>XML</abbr> document.
-It is therefore possible to write a document representing a complete <code
class="OGC">MD_Metadata</code> object,
-or to write a document representing only a <code
class="OGC">CI_Citation</code> object.
-</p>
<p>
-<abbr>ISO</abbr> 19115-3 standard arranges the content of these objects in an
unusual way:
-for each property whose value type is itself another class of <abbr>ISO</abbr>
19115,
-the value is wrapped in an element that represents its type, rather than being
written directly.
-For example, in an object of the <code class="OGC">CI_Citation</code> type,
-the value of the <code class="OGC">citedResponsibleParty</code> property is
incorporated
-into a <code class="OGC">CI_Responsibility</code> element.
-This practice doubles the depth of the hierarchy, and introduces duplication
at all levels for each value,
-as in the following example:
+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>
-
-<pre class="xml"><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>
19115-3,
-consists of a systematic alternation of two types of <abbr>XML</abbr> elements:
+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>
-<ol>
+<ul>
<li><p>
-It begins with the name of the property, which always begins with a lower-case
letter (ignoring prefixes).
-In Java <abbr title="Application Programming Interface">API</abbr>s, each
property corresponds to a method in its enclosing class.
-In the example above, <code class="OGC">gmd:identificationInfo</code> (a
property of <code class="OGC">MD_Metadata</code> class)
-corresponds to the <code
class="GeoAPI">Metadataâ.getIdentificationInfo()</code> method.
+<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>
-The value type is included under each property, unless it has been replaced
with a reference
-(the following <a href="#gco-id">sub-section</a> will elaborate on this
subject).
-The value type is an <abbr>XML</abbr> element whose name always begins with an
upper-case letter,
-ignoring prefixes.
-In the example above we had <code class="OGC">MD_DataIdentification</code>,
-which corresponds to the <code class="GeoAPI">DataIdentification</code> Java
interface.
-It is this <abbr>XML</abbr> element that contains the child properties.
+<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>
-</ol>
-
+<li><p>
+<b><code class="SIS">IGNORE_METADATA</code></b>Â â Like <code
class="SIS">BY_CONTRACT</code>,
+but only compares attributes that influence the operations (numeric
calculations or otherwise) performed by the object.
+For example, in a geodesic datum, the longitude (in relation to Greenwich) of
the original meridian
+would be taken into account, while the name of the meridian would be ignored.
+</p></li>
+<li><p>
+<b><code class="SIS">APPROXIMATIVE</code></b>Â â Like <code
class="SIS">IGNORE_METADATA</code>,
+but tolerates minor discrepancies in numerical values.
+</p></li>
+</ul>
<p>
-In order to reduce the complexity of the libraries, GeoAPI and Apache <abbr
title="Spatial Information System">SIS</abbr>
-only expose publicly a single unified view of these two types of elements.
-The public <abbr>API</abbr> basically corresponds to the second group.
-However, when writing an <abbr>XML</abbr> document, elements of the first
group must be temporarily recreated.
-The corresponding classes are defined in internal <abbr>SIS</abbr> packages.
-These classes may be ignored, unless the developer wishes to implement his or
her own classes whose instances must be written in <abbr title="Java
Architecture for XML Binding">JAXB</abbr>.
+The default mode, used in all <code>equals(Object)</code> methods in
<abbr>SIS</abbr>,
+is <code class="SIS">STRICT</code>. This mode is chosen for a safe operation
â particularly with <code>HashMap</code>Â â
+without the need to rigorously define <code>equals(Object)</code> and
<code>hashCode()</code> operations in every interface.
+With this mode, the order of objects (<code>A.equals(B)</code> or
<code>B.equals(A)</code>) is unimportant.
+It is, however, the only mode that offers this guarantee.
+In the expression <code>A.equals(B)</code>, the <code
class="SIS">BY_CONTRACT</code> mode
+(and so by extension all other modes that depend on it) only compares the
properties known to <code>A</code>,
+regardless of whether <code>B</code> knows more.
</p>
-<aside>
-<h3>Implementation Strategy in Apache <abbr title="Spatial Information
System">SIS</abbr></h3>
-<p>
-<code class="SIS">org.apache.sis.internal.jaxb.*</code> packages (non-public)
define <abbr title="Java Architecture for XML Binding">JAXB</abbr> adaptors for
all types of <abbr title="International Organization for
Standardization">ISO</abbr> objects.
-These adaptors are required anyway to allow <abbr>JAXB</abbr> to get
<abbr>SIS</abbr> classes while implementing GeoAPI interfaces.
-Conveniently, <abbr>SIS</abbr> made both <abbr>JAXB</abbr> adaptors and
objects wrapping the ârealâ object to be read or written.
-This double usage avoids having to double the number of classes (already quite
high) present in the internal packages.
-</p>
-<h4>Naming Conventions in <abbr title="XML Schema Definition">XSD</abbr>
Schemas</h4>
+
+
+<h2 id="Internationalization"><span class="section-number">3.2.</span>
Internationalization</h2>
<p>
-For each element of the first group listed above, the <abbr>XSD</abbr> schemas
of the <abbr title="Open Geospatial Consortium">OGC</abbr>
-define a type whose name ends with â<code
class="OGC">_PropertyType</code>â.
-For the second group, each element has a type whose name ends with â<code
class="OGC">_Type</code>â.
-The â<code class="OGC">_PropertyType</code>â elements may have a group of
attributes
-(such as <code class="OGC">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.
+In an architecture where a program executed on a server provides its data to
multiple clients,
+the server's locale conventions are not necessarily the same as those of the
clients.
+Conventions may differ in language, but also in the way they write numeric
values
+(even between two countries that speak the same language) as well in time zone.
+To produce messages that conform to the client's conventions, <abbr
title="Spatial Information System">SIS</abbr> uses
+two approaches, distinguished by their level of granularity: at the level of
the messages themselves,
+or at the level of the objects that create the messages.
+The approach used also determines whether it is possible to share the same
instance of an object for all languages.
</p>
-</aside>
-
-<h3 id="gco-id"><span class="section-number">3.1.1.</span> Identification of
Already-Defined Instances</h3>
-<p>
-The parent element may contain an <code class="OGC">id</code> or <code
class="OGC">uuid</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 class="xml" style="margin-top: 6pt"><MD_MetaData>
- <identificationInfo>
- <MD_DataIdentification id=<i>"<b>my_id</b>"</i>>
- <code class="comment"><!-- insert child properties here --></code>
- </MD_DataIdentification>
- </identificationInfo>
-</MD_MetaData></pre>
-</td>
-<td>
-<pre class="xml" style="margin-top: 6pt"><MD_MetaData>
- <identificationInfo xlink:href=<i>"<b>#my_id</b>"</i>/>
-</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> org.apache.sis.metadata.iso.<code
class="SIS">DefaultMetadata</code>;
-<b>import</b> org.apache.sis.xml.<code class="SIS">IdentifierSpace</code>;
-<b>import</b> java.util.UUID;
-
-<b>public</b> <b>class</b> MyClass {
- <b>public</b> <b>void</b> myMethod() {
- UUID identifier = UUID.randomUUID();
- <code class="SIS"><code class="SIS">DefaultMetadata</code></code>
metadata = <b>new</b> <code class="SIS"><code
class="SIS">DefaultMetadata</code></code>();
- metadata.<code
class="SIS">getIdentifierMap().putSpecialized</code>(<code
class="SIS">IdentifierSpace</code>.UUID, identifier);
- }
-}</pre>
-
-<p>
-Although this mechanism has been defined in order to better support the
representation of <abbr>XML</abbr> attributes
-of the <code class="OGC">gco:ObjectIdentification</code> group,
-it also conveniently allows other types of identifiers to be manipulated.
-For example, the <code class="GeoAPI">ISBN</code> and <code
class="GeoAPI">ISSN</code> attributes of
-<code class="GeoAPI">Citation</code> may be manipulated in this way.
-The methods of the <code class="SIS">IdentifiedObject</code> interface
therefore provides a specific location
-where all types of identifiers (not only <abbr>XML</abbr>) associated with an
object may be manipulated.
-</p>
-
-
-
-<h3 id="nilReason"><span class="section-number">3.1.2.</span> Representing
Missing Values</h3>
-<p>
-When a property is not defined, the corresponding GeoAPI method usually
returns <code>null</code>.
-However, things become complicated when the missing property is a value
considered mandatory by <abbr title="International Organization for
Standardization">ISO</abbr> 19115 standard.
-<abbr>ISO</abbr> 19115-3 allows for the omission of mandatory properties so
long as the reason for the missing value is indicated.
-The reason may be that the property is not applicable (<code
class="OGC">inapplicable</code>),
-that the value probably exists but is not known (<code
class="OGC">unknown</code>),
-that the value cannot exist (<code class="OGC">missing</code>),
-or that the value cannot be revealed (<code class="OGC">withheld</code>),
<i>etc.</i>
-The transmission of this information requires the use of a non-nul object,
even when the value is missing.
-<abbr title="Spatial Information System">SIS</abbr> will then return an object
that, besides implementing the desired GeoAPI interface,
-also implements the <code class="SIS">org.apache.sis.xml.NilObject</code>
interface.
-This interface flags the instances where all methods return an empty
collection, an empty table, <code>null</code>,
-<code>NaN</code>, <code>0</code> or <code>false</code>, in this preference
order, as permitted by the return types of the methods.
-Each instance that implements <code class="SIS">NilObject</code> provides a
<code class="SIS">getNilReason()</code> method
-indicating why the object is nil.
-</p>
-<p>
-In the following example, the left side shows a <code
class="OGC">CI_Citation</code> element containing a
-<code class="OGC">CI_Series</code> element, while on the right side the series
is unknown.
-If the <code class="OGC">CI_Series</code> element had been completely omitted,
-then the <code class="GeoAPI">Citationâ.getSeries()</code> method would
return <code>null</code> in Java.
-But when a <code class="OGC">nilReason</code> is present, the <abbr>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 class="xml" style="margin-top: 6pt"><CI_Citation>
- <series>
- <CI_Series>
- <code class="comment"><!-- insert child properties here --></code>
- </CI_Series>
- </series>
-</CI_Citation></pre>
-</td>
-<td>
-<pre class="xml" style="margin-top: 6pt"><CI_Citation>
- <series nilReason=<i>"unknown"</i>/>
-</CI_Citation></pre>
-</td>
-</tr>
-</table>
-</section>
-<section>
-<header>
-<h1 id="Utilities"><span class="section-number">4.</span> Utility Classes and
Methods</h1>
-<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#XML-ISO">Previous chapter</a></div><div class="next-chapter"><a
href="#Geometry">Next chapter</a> â¡</div></div></nav>
-</header>
-<nav>In this chapter:<ul class="toc">
-<li><a href="#ComparisonMode">Comparison Modes of Objects</a></li>
-<li><a href="#Internationalization">Internationalization</a><ul>
-<li><a href="#LocalizedString">Distinct Character Sequences for Each
Locale</a></li>
-<li><a href="#InternationalString">Single instance for all supported
locales</a></li>
-<li><a href="#Locale.ROOT">Locale.ROOT Convention</a></li>
-<li><a href="#UnicodePoint">Treatment of Characters</a><ul>
-<li><a href="#Whitespaces">The Interpretation of Blank
Spaces</a></li></ul></li></ul></li></ul></nav>
-<p>
-This chapter describes aspects of Apache <abbr title="Spatial Information
System">SIS</abbr> that apply to the entire library.
-Most of these utilities are not specific to spatial information systems.
-</p>
-
-<h2 id="ComparisonMode"><span class="section-number">4.1.</span> Comparison
Modes of Objects</h2>
-<p>
-There are various opinions on how to implement Java standard's
<code>Objectâ.equals(Object)</code> method.
-According to some, it should be possible to compare different implementations
of the same interface or base class.
-But to follow this policy, each interface or base class's javadoc must define
the algorithms that all implementations
-shall use for their <code>equals(Object)</code> and <code>hashCode()</code>
methods.
-This approach is common in <code>java.util.Collection</code> and its child
interfaces.
-Transferring this approach to certain GeoAPI interfaces, however, would be a
difficult task,
-and would probably not be followed in many implementations.
-Moreover, it comes at the expense of being able to take into account
supplementary attributes in the child interfaces,
-unless this possibility has been specified in the parent interface.
-This constraint arises from the following points of the
<code>equals(Object)</code> and <code>hashCode()</code> method contracts:
-</p>
-<ul>
-<li><code>A.equals(B)</code> implies <code>B.equals(A)</code> (symmetry);</li>
-<li><code>A.equals(B)</code> and <code>B.equals(C)</code> implies
<code>A.equals(C)</code> (transitivity);</li>
-<li><code>A.equals(B)</code> implies <code>A.hashCode() ==
B.hashCode()</code>.</li>
-</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 datum, the longitude (in relation to Greenwich) of
the original meridian
-would be taken into account, while the name of the meridian would be ignored.
-</p></li>
-<li><p>
-<b><code class="SIS">APPROXIMATIVE</code></b>Â â Like <code
class="SIS">IGNORE_METADATA</code>,
-but tolerates minor discrepancies in numerical values.
-</p></li>
-</ul>
-<p>
-The default mode, used in all <code>equals(Object)</code> methods in
<abbr>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"><span class="section-number">4.2.</span>
Internationalization</h2>
-<p>
-In an architecture where a program executed on a server provides its data to
multiple clients,
-the server's locale conventions are not necessarily the same as those of the
clients.
-Conventions may differ in language, but also in the way they write numeric
values
-(even between two countries that speak the same language) as well in time zone.
-To produce messages that conform to the client's conventions, <abbr
title="Spatial Information System">SIS</abbr> uses
-two approaches, distinguished by their level of granularity: at the level of
the messages themselves,
-or at the level of the objects that create the messages.
-The approach used also determines whether it is possible to share the same
instance of an object for all languages.
-</p>
-
-<h3 id="LocalizedString"><span class="section-number">4.2.1.</span> Distinct
Character Sequences for Each Locale</h3>
+<h3 id="LocalizedString"><span class="section-number">3.2.1.</span> Distinct
Character Sequences for Each Locale</h3>
<p>
Some classes are only designed to function according to one locale convention
at a time.
This is of course true for the standard implementations of
<code>java.text.Format</code>,
@@ -1535,7 +1200,7 @@ according to the conventions of a given
-<h3 id="InternationalString"><span class="section-number">4.2.2.</span> Single
instance for all supported locales</h3>
+<h3 id="InternationalString"><span class="section-number">3.2.2.</span> Single
instance for all supported locales</h3>
<p>
The <abbr title="Application Programming Interface">API</abbr> conventions
defined by <abbr title="Spatial Information System">SIS</abbr> or inherited by
GeoAPI favour the use of the
<code class="GeoAPI">InternationalString</code> type when the value of a
<code>String</code> type would likely be localized.
@@ -1561,7 +1226,7 @@ so sharing a single instance becomes eve
-<h3 id="Locale.ROOT"><span class="section-number">4.2.3.</span>
<code>Locale.ROOT</code> Convention</h3>
+<h3 id="Locale.ROOT"><span class="section-number">3.2.3.</span>
<code>Locale.ROOT</code> Convention</h3>
<p>
All <abbr title="Spatial Information System">SIS</abbr> methods receiving or
returning the value of a <code>Locale</code> type accept the
<code>Locale.ROOT</code> value.
This value is interpreted as specifying not to localize the text.
@@ -1587,7 +1252,7 @@ use of exponential notation and the abse
-<h3 id="UnicodePoint"><span class="section-number">4.2.4.</span> Treatment of
Characters</h3>
+<h3 id="UnicodePoint"><span class="section-number">3.2.4.</span> Treatment of
Characters</h3>
<p>
In Java, sequences of characters use UTF-16 encoding.
There is a direct correspondence between the values of the <code>char</code>
type and the great majority of characters,
@@ -1634,7 +1299,7 @@ even if some may be present in the seque
-<h4 id="Whitespaces"><span class="section-number">4.2.4.1.</span> The
Interpretation of Blank Spaces</h4>
+<h4 id="Whitespaces"><span class="section-number">3.2.4.1.</span> The
Interpretation of Blank Spaces</h4>
<p>
Standard Java provides two methods for determining whether a character is a
blank space:
<code>Characterâ.isWhitespace(â¦)</code> and
<code>Characterâ.isSpaceChar(â¦)</code>.
@@ -1667,7 +1332,7 @@ or the use of <code>isWhitespace(â¦)
</section>
<section>
<header>
-<h1 id="Geometry"><span class="section-number">5.</span> Geometries</h1>
+<h1 id="Geometry"><span class="section-number">4.</span> Geometries</h1>
<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#Utilities">Previous chapter</a></div><div class="next-chapter"><a
href="#Coverage">Next chapter</a> â¡</div></div></nav>
</header>
<nav>In this chapter:<ul class="toc">
@@ -1682,7 +1347,7 @@ and the Apache <abbr title="Spatial Info
-<h2 id="Geometry-root"><span class="section-number">5.1.</span> Base
Classes</h2>
+<h2 id="Geometry-root"><span class="section-number">4.1.</span> Base
Classes</h2>
<p>
Each geometric object is considered an infinite set of points.
As a set, their most fundamental operations are of the same nature as the
standard operations of Java collections.
@@ -1704,7 +1369,7 @@ prefix (as prescribed in GeoAPI conventi
-<h3 id="DirectPosition"><span class="section-number">5.1.1.</span> Direct
Points and Positions</h3>
+<h3 id="DirectPosition"><span class="section-number">4.1.1.</span> Direct
Points and Positions</h3>
<p>
<abbr title="International Organization for Standardization">ISO</abbr> 19107
defines two types of structures to represent a point:
<code class="OGC">GM_Point</code> and <code class="OGC">DirectPosition</code>.
@@ -1726,7 +1391,7 @@ or occasionally on <code class="GeoAPI">
-<h3 id="Envelope"><span class="section-number">5.1.2.</span> Envelopes</h3>
+<h3 id="Envelope"><span class="section-number">4.1.2.</span> Envelopes</h3>
<p>
Envelopes store minimal and maximal coordinate values of a geometry.
Envelopes are <em>not</em> geometries themselves; they are not infinite sets
of points (<code class="OGC">TransfiniteSet</code>).
@@ -1757,7 +1422,7 @@ The expressions <i>lower corner</i> and
-<h4 id="AntiMeridian"><span class="section-number">5.1.2.1.</span> Envelopes
that Cross the Antimeridian</h4>
+<h4 id="AntiMeridian"><span class="section-number">4.1.2.1.</span> Envelopes
that Cross the Antimeridian</h4>
<p>
Minimums and maximums are the values most often assigned to <code
class="OGC">lowerCorner</code>
and <code class="OGC">upperCorner</code>.
@@ -1850,8 +1515,8 @@ then it is guaranteed that the envelope
</section>
<section>
<header>
-<h1 id="Coverage"><span class="section-number">6.</span> Data Coverages</h1>
-<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#Geometry">Previous chapter</a></div><div class="next-chapter"><a
href="#reduce-direct-dependency">Next chapter</a> â¡</div></div></nav>
+<h1 id="Coverage"><span class="section-number">5.</span> Data Coverages</h1>
+<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#Geometry">Previous chapter</a></div><div class="next-chapter"><a
href="#XML-ISO">Next chapter</a> â¡</div></div></nav>
</header>
<nav>In this chapter:<ul class="toc"/></nav>
<p>
@@ -1921,8 +1586,343 @@ as well as other information such as <i>
</section>
<section>
<header>
+<h1 id="XML-ISO"><span class="section-number">6.</span> Representing Objects
in <abbr>XML</abbr></h1>
+<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#Coverage">Previous chapter</a></div><div class="next-chapter"><a
href="#reduce-direct-dependency">Next chapter</a> â¡</div></div></nav>
+</header>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#XML-ISO-19115">Representing Metadata According to ISO
19115-3</a><ul>
+<li><a href="#gco-id">Identification of Already-Defined Instances</a></li>
+<li><a href="#nilReason">Representing Missing
Values</a></li></ul></li></ul></nav>
+<p>
+Objects defined by <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr
title="International Organization for Standardization">ISO</abbr> standards
must be able to communicate with remote machines via the Internet,
+using different software written in different languages.
+Some of the better known formats include <abbr>WKT</abbr> (<i>Well-Known
Text</i>) and <abbr>WKB</abbr> (<i>Well-Known Binary</i>).
+But the most exhaustive and often referred format is <abbr>XML</abbr>,
+to the point where the representation of <abbr>ISO</abbr> objects in this
format is itself sometimes
+the entire focus of an international standard.
+Thus are metadata classes described in <abbr>ISO</abbr> 19115-1 standard (an
abstract specification),
+while the representation of these classes in <abbr>XML</abbr> is described in
<abbr>ISO</abbr> 19115-3 and 19139 standards.
+</p>
+<p>
+Different <abbr>OGC</abbr>/<abbr>ISO</abbr> standards do not always use the
same strategy to express objects in <abbr>XML</abbr>.
+<abbr>ISO</abbr> 19115-3 standard in particular uses a more verbose approach
than other standards,
+and will be the subject of its <a href="#XML-ISO-19115">own section</a>.
+But most <abbr>XML</abbr> formats define supplementary types and attributes
that are not part of the original abstract specifications.
+These supplementary attributes are usually specific to <abbr>XML</abbr> and
may not appear in the <abbr title="Application Programming
Interface">API</abbr> of Apache <abbr title="Spatial Information
System">SIS</abbr>.
+However, some of these attributes, such as <code class="OGC">id</code>, <code
class="OGC">uuid</code> and
+<code>xlink:href</code>, remain accessible in the form of key-value pairs.
+</p>
+<p>
+<abbr>XML</abbr> documents may use any prefixes,
+but the following prefixes are commonly used.
+They therefore appear by default in documents produced by Apache
<abbr>SIS</abbr>.
+These prefixes are defined in the <code
class="SIS">org.apache.sis.xml.Namespaces</code> class.
+</p>
+<table>
+<caption>Common <abbr>XML</abbr> namespace prefixes</caption>
+<tr>
+<th>Prefix</th>
+<th>Namespace</th>
+</tr>
+<tr>
+<td><code class="OGC">gco</code></td>
+<td><code>http://www.isotc211.org/2005/gco</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gfc</code></td>
+<td><code>http://www.isotc211.org/2005/gfc</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmd</code></td>
+<td><code>http://www.isotc211.org/2005/gmd</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmi</code></td>
+<td><code>http://www.isotc211.org/2005/gmi</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gmx</code></td>
+<td><code>http://www.isotc211.org/2005/gmx</code></td>
+</tr>
+<tr>
+<td><code class="OGC">gml</code></td>
+<td><code>http://www.opengis.net/gml/3.2</code></td>
+</tr>
+<tr>
+<td><code>xlink</code></td>
+<td><code>http://www.w3.org/1999/xlink</code></td>
+</tr>
+</table>
+
+<aside>
+<h2>Tools for Reading and Writing <abbr>XML</abbr> Documents</h2>
+<p>
+Apache <abbr title="Spatial Information System">SIS</abbr> uses different
libraries to read and write different types of objects.
+The library used depends on the complexity of the object and on performance
constraints.
+For example, <abbr title="Java Architecture for XML Binding">JAXB</abbr>
annotations have the advantage of being close to code,
+which makes it easier to maintain mapping between Java and <abbr>XML</abbr>.
+On the other hand, <abbr title="Simple API for XML">SAX</abbr> is more
efficient.
+In general, Apache <abbr>SIS</abbr> uses:
+</p>
+<ul>
+<li>
+<abbr>JAXB</abbr> for objects that do not occur very often in <abbr>XML</abbr>
documents, but with complex structures and deep hierarchies.
+The metadata set in <abbr title="International Organization for
Standardization">ISO</abbr> 19115-3 standard is a typical example
+</li>
+<li>
+<abbr>SAX</abbr> for objects that are relatively simple, but which may exist
in very large numbers.
+The set of points in a geometry is a typical example.
+</li>
+<li>
+<abbr title="Document Object Model">DOM</abbr> as an alternative to
<abbr>JAXB</abbr>
+when the <abbr>XML</abbr> elements do not correspond exactly to Java
attributes.
+<i>Features</i> are an example, as their structure is dynamic.
+</li>
+</ul>
+</aside>
+
+
+
+<h2 id="XML-ISO-19115"><span class="section-number">6.1.</span> Representing
Metadata According to <abbr title="International Organization for
Standardization">ISO</abbr> 19115-3</h2>
+<p>
+For each metadata class, there is an <abbr>XML</abbr> type with the same name
than in the abstract specification
+(for example, <code class="OGC">gmd:MD_Metadata</code> and <code
class="OGC">gmd:CI_Citation</code>).
+All of these types may be used as the root of an <abbr>XML</abbr> document.
+It is therefore possible to write a document representing a complete <code
class="OGC">MD_Metadata</code> object,
+or to write a document representing only a <code
class="OGC">CI_Citation</code> object.
+</p>
+<p>
+<abbr>ISO</abbr> 19115-3 standard arranges the content of these objects in an
unusual way:
+for each property whose value type is itself another class of <abbr>ISO</abbr>
19115,
+the value is wrapped in an element that represents its type, rather than being
written directly.
+For example, in an object of the <code class="OGC">CI_Citation</code> type,
+the value of the <code class="OGC">citedResponsibleParty</code> property is
incorporated
+into a <code class="OGC">CI_Responsibility</code> element.
+This practice doubles the depth of the hierarchy, and introduces duplication
at all levels for each value,
+as in the following example:
+</p>
+
+<pre class="xml"><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>
19115-3,
+consists of a systematic alternation of two types of <abbr>XML</abbr> elements:
+</p>
+<ol>
+<li><p>
+It begins with the name of the property, which always begins with a lower-case
letter (ignoring prefixes).
+In Java <abbr title="Application Programming Interface">API</abbr>s, each
property corresponds to a method in its enclosing class.
+In the example above, <code class="OGC">gmd:identificationInfo</code> (a
property of <code class="OGC">MD_Metadata</code> class)
+corresponds to the <code
class="GeoAPI">Metadataâ.getIdentificationInfo()</code> method.
+</p></li>
+<li><p>
+The value type is included under each property, unless it has been replaced
with a reference
+(the following <a href="#gco-id">sub-section</a> will elaborate on this
subject).
+The value type is an <abbr>XML</abbr> element whose name always begins with an
upper-case letter,
+ignoring prefixes.
+In the example above we had <code class="OGC">MD_DataIdentification</code>,
+which corresponds to the <code class="GeoAPI">DataIdentification</code> Java
interface.
+It is this <abbr>XML</abbr> element that contains the child properties.
+</p></li>
+</ol>
+
+<p>
+In order to reduce the complexity of the libraries, GeoAPI and Apache <abbr
title="Spatial Information System">SIS</abbr>
+only expose publicly a single unified view of these two types of elements.
+The public <abbr>API</abbr> basically corresponds to the second group.
+However, when writing an <abbr>XML</abbr> document, elements of the first
group must be temporarily recreated.
+The corresponding classes are defined in internal <abbr>SIS</abbr> packages.
+These classes may be ignored, unless the developer wishes to implement his or
her own classes whose instances must be written in <abbr title="Java
Architecture for XML Binding">JAXB</abbr>.
+</p>
+
+<aside>
+<h3>Implementation Strategy in Apache <abbr title="Spatial Information
System">SIS</abbr></h3>
+<p>
+<code class="SIS">org.apache.sis.internal.jaxb.*</code> packages (non-public)
define <abbr title="Java Architecture for XML Binding">JAXB</abbr> adaptors for
all types of <abbr title="International Organization for
Standardization">ISO</abbr> objects.
+These adaptors are required anyway to allow <abbr>JAXB</abbr> to get
<abbr>SIS</abbr> classes while implementing GeoAPI interfaces.
+Conveniently, <abbr>SIS</abbr> made both <abbr>JAXB</abbr> adaptors and
objects wrapping the ârealâ object to be read or written.
+This double usage avoids having to double the number of classes (already quite
high) present in the internal packages.
+</p>
+<h4>Naming Conventions in <abbr title="XML Schema Definition">XSD</abbr>
Schemas</h4>
+<p>
+For each element of the first group listed above, the <abbr>XSD</abbr> schemas
of the <abbr title="Open Geospatial Consortium">OGC</abbr>
+define a type whose name ends with â<code
class="OGC">_PropertyType</code>â.
+For the second group, each element has a type whose name ends with â<code
class="OGC">_Type</code>â.
+The â<code class="OGC">_PropertyType</code>â elements may have a group of
attributes
+(such as <code class="OGC">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"><span class="section-number">6.1.1.</span> Identification of
Already-Defined Instances</h3>
+<p>
+The parent element may contain an <code class="OGC">id</code> or <code
class="OGC">uuid</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 class="xml" style="margin-top: 6pt"><MD_MetaData>
+ <identificationInfo>
+ <MD_DataIdentification id=<i>"<b>my_id</b>"</i>>
+ <code class="comment"><!-- insert child properties here --></code>
+ </MD_DataIdentification>
+ </identificationInfo>
+</MD_MetaData></pre>
+</td>
+<td>
+<pre class="xml" style="margin-top: 6pt"><MD_MetaData>
+ <identificationInfo xlink:href=<i>"<b>#my_id</b>"</i>/>
+</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> org.apache.sis.metadata.iso.<code
class="SIS">DefaultMetadata</code>;
+<b>import</b> org.apache.sis.xml.<code class="SIS">IdentifierSpace</code>;
+<b>import</b> java.util.UUID;
+
+<b>public</b> <b>class</b> MyClass {
+ <b>public</b> <b>void</b> myMethod() {
+ UUID identifier = UUID.randomUUID();
+ <code class="SIS"><code class="SIS">DefaultMetadata</code></code>
metadata = <b>new</b> <code class="SIS"><code
class="SIS">DefaultMetadata</code></code>();
+ metadata.<code
class="SIS">getIdentifierMap().putSpecialized</code>(<code
class="SIS">IdentifierSpace</code>.UUID, identifier);
+ }
+}</pre>
+
+<p>
+Although this mechanism has been defined in order to better support the
representation of <abbr>XML</abbr> attributes
+of the <code class="OGC">gco:ObjectIdentification</code> group,
+it also conveniently allows other types of identifiers to be manipulated.
+For example, the <code class="GeoAPI">ISBN</code> and <code
class="GeoAPI">ISSN</code> attributes of
+<code class="GeoAPI">Citation</code> may be manipulated in this way.
+The methods of the <code class="SIS">IdentifiedObject</code> interface
therefore provides a specific location
+where all types of identifiers (not only <abbr>XML</abbr>) associated with an
object may be manipulated.
+</p>
+
+
+
+<h3 id="nilReason"><span class="section-number">6.1.2.</span> Representing
Missing Values</h3>
+<p>
+When a property is not defined, the corresponding GeoAPI method usually
returns <code>null</code>.
+However, things become complicated when the missing property is a value
considered mandatory by <abbr title="International Organization for
Standardization">ISO</abbr> 19115 standard.
+<abbr>ISO</abbr> 19115-3 allows for the omission of mandatory properties so
long as the reason for the missing value is indicated.
+The reason may be that the property is not applicable (<code
class="OGC">inapplicable</code>),
+that the value probably exists but is not known (<code
class="OGC">unknown</code>),
+that the value cannot exist (<code class="OGC">missing</code>),
+or that the value cannot be revealed (<code class="OGC">withheld</code>),
<i>etc.</i>
+The transmission of this information requires the use of a non-nul object,
even when the value is missing.
+<abbr title="Spatial Information System">SIS</abbr> will then return an object
that, besides implementing the desired GeoAPI interface,
+also implements the <code class="SIS">org.apache.sis.xml.NilObject</code>
interface.
+This interface flags the instances where all methods return an empty
collection, an empty table, <code>null</code>,
+<code>NaN</code>, <code>0</code> or <code>false</code>, in this preference
order, as permitted by the return types of the methods.
+Each instance that implements <code class="SIS">NilObject</code> provides a
<code class="SIS">getNilReason()</code> method
+indicating why the object is nil.
+</p>
+<p>
+In the following example, the left side shows a <code
class="OGC">CI_Citation</code> element containing a
+<code class="OGC">CI_Series</code> element, while on the right side the series
is unknown.
+If the <code class="OGC">CI_Series</code> element had been completely omitted,
+then the <code class="GeoAPI">Citationâ.getSeries()</code> method would
return <code>null</code> in Java.
+But when a <code class="OGC">nilReason</code> is present, the <abbr>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 class="xml" style="margin-top: 6pt"><CI_Citation>
+ <series>
+ <CI_Series>
+ <code class="comment"><!-- insert child properties here --></code>
+ </CI_Series>
+ </series>
+</CI_Citation></pre>
+</td>
+<td>
+<pre class="xml" style="margin-top: 6pt"><CI_Citation>
+ <series nilReason=<i>"unknown"</i>/>
+</CI_Citation></pre>
+</td>
+</tr>
+</table>
+</section>
+<section>
+<header>
<h1 id="reduce-direct-dependency"><span class="section-number">7.</span>
Reduce direct dependency to Apache SIS</h1>
-<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#Coverage">Previous chapter</a></div><div class="next-chapter"><a
href="#tests">Next chapter</a> â¡</div></div></nav>
+<nav><div class="chapter-links"><div class="previous-chapter">â¬
<a
href="#XML-ISO">Previous chapter</a></div><div class="next-chapter"><a
href="#tests">Next chapter</a> â¡</div></div></nav>
</header>
<nav>In this chapter:<ul class="toc">
<li><a href="#UML-annotation-geoapi">Mapping Given by @UML Annotations</a></li>
