sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1794656 [9/18] - in /sis/site/trunk/book: en/ en/annex/ en/coverage/ en/geometry/ en/introduction/ en/referencing/ en/utility/ en/xml/ fr/ fr/annex/ fr/coverage/ fr/geometry/ fr/introduction/ fr/referencing/ fr/utility/ fr/xml/
Date Tue, 09 May 2017 23:04:36 GMT
Copied: sis/site/trunk/book/en/utility/ObjectConverters.html (from r1794573, sis/site/trunk/book/en/utility.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/utility/ObjectConverters.html?p2=sis/site/trunk/book/en/utility/ObjectConverters.html&p1=sis/site/trunk/book/en/utility.html&r1=1794573&r2=1794656&rev=1794656&view=diff
==============================================================================
--- sis/site/trunk/book/en/utility.html [UTF-8] (original)
+++ sis/site/trunk/book/en/utility/ObjectConverters.html [UTF-8] Tue May  9 23:04:35 2017
@@ -22,99 +22,20 @@
 
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   <head>
-    <title>Utility classes and methods</title>
+    <title>ObjectConverters</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
   </head>
   <body>
     <!--
-      Content below this point is copied in "../../content/book/en/developer-guide.html"
+      Content below this point is copied in "(…)/content/book/en/developer-guide.html" file
       by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
     -->
     <section>
       <header>
-        <h1 id="Utilities">Utility classes and methods</h1>
+        <h2 id="ObjectConverters">Object converters</h2>
       </header>
       <p>
-        This chapter describes aspects of Apache <abbr>SIS</abbr> that apply to the entire library.
-        Most of these utilities are not specific to spatial information systems.
-      </p>
-
-      <h2 id="ComparisonMode">Comparison modes of objects</h2>
-      <p>
-        There are various opinions on how to implement Java standard’s <code>Object.equals(Object)</code> method.
-        According to some, it should be possible to compare different implementations of the same interface or base class.
-        But to follow this policy, each interface or base class’s javadoc must define the algorithms that all implementations
-        shall use for their <code>equals(Object)</code> and <code>hashCode()</code> methods.
-        This approach is common in <code>java.util.Collection</code> and its child interfaces.
-        Transferring this approach to certain GeoAPI interfaces, however, would be a difficult task,
-        and would probably not be followed in many implementations.
-        Moreover, it comes at the expense of being able to take into account supplementary attributes in the child interfaces,
-        unless this possibility has been specified in the parent interface.
-        This constraint arises from the following points of the <code>equals(Object)</code> and <code>hashCode()</code> method contracts:
-      </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>SIS</abbr>
-        library implement the <code>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="ObjectConverters">Object converters</h2>
-      <p>
         There is sometime a need to convert instances from a <var>source</var> Java type to a <var>target</var> Java type
         while those types are unknown at compile time.
         Various projects (Apache Common Convert, Spring, <i>etc.</i>)
@@ -192,200 +113,6 @@
         If the converter is neither order preserving or order reversing, then range conversion is not allowed at all
         (because it does not contain the same set of values) even if the minimum and maximum values could be converted individually.
       </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 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>SIS</abbr> uses
-        two approaches, distinguished by their level of granularity: at the level of the messages themselves,
-        or at the level of the objects that create the messages.
-        The approach used also determines whether it is possible to share the same instance of an object for all languages.
-      </p>
-
-      <h3 id="LocalizedString">Distinct character sequences for each locale</h3>
-      <p>
-        Some classes are only designed to function according to one locale convention at a time.
-        This is of course true for the standard implementations of <code>java.text.Format</code>,
-        as they are entirely dedicated to the work of internationalization.
-        But it is also the case for other less obvious classes like <code>javax.imageio.ImageReader</code> and <code>ImageWriter</code>.
-        When one of these classes is implemented by <abbr>SIS</abbr>,
-        we identify it by implementing the <code>org.apache.sis.util.Localized</code> interface.
-        The <code class="SIS">getLocale()</code> method of this interface can determine the locale conventions
-        by which the instance produces its message.
-      </p>
-      <p>
-        Another class that provides different methods for different locales is <code>java.lang.Throwable</code>.
-        The standard Java <abbr>API</abbr> defines two methods for getting the error message:
-        <code>getMessage()</code> and <code>getLocalizedMessage()</code>.
-        Usually those two methods return the same character sequences,
-        but some exceptions thrown by Apache <abbr>SIS</abbr> may use different locales.
-        The policy that <abbr>SIS</abbr> tries to apply on a <em>best-effort</em> basis is:
-      </p>
-      <ul>
-        <li><code>getMessage()</code> returns the message in the <abbr title="Java Virtual Machine">JVM</abbr> default locale.
-            In a client-server architecture, this is often the locale on the server side.
-            This is the recommended language for logging messages to be read by system administrators.</li>
-        <li><code>getLocalizedMessage()</code> returns the message in a locale that depends on the context
-            in which the exception has been thrown. This is often the locale used by a particular <code>Format</code>
-            or <code class="SIS">DataStore</code> instance, and can be presumed to be the locale on the client side.
-            This is the recommended language to show in the user application.</li>
-      </ul>
-
-      <div class="example"><p><b>Example:</b>
-        If an error occurred while a Japanese client connected to an European server, the localized message may be sent
-        to the client in Japanese language as given by <code>getLocalizedMessage()</code> while the same error may be
-        logged on the server side in the French (for example) language as given by <code>getMessage()</code>.
-        This allows system administrator to analyze the issue without the need to understand client’s language.
-      </p></div>
-      <p>
-        The utility class <code>org.apache.sis.util.Exceptions</code> provides convenience methods to get messages
-        according to the conventions of a given locale, when this information is available.
-      </p>
-
-
-
-      <h3 id="InternationalString">Single instance for all supported locales</h3>
-      <p>
-        The <abbr>API</abbr> conventions defined by <abbr>SIS</abbr> or inherited by GeoAPI favour the use of the
-        <code>InternationalString</code> type when the value of a <code>String</code> type would likely be localized.
-        This approach allows us to defer the internationalization process to the time when a character sequence is requested,
-        rather than the time when the object that contains them is created.
-        This is particularly useful for immutable classes used for creating unique instances independently of locale conventions.
-      </p>
-      <div class="example"><p><b>Example:</b>
-        <abbr>SIS</abbr> includes only one instance of the <code>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>InternationalString</code>, so that <code>toString(Locale.ENGLISH)</code> returns <cite>Mercator projection</cite>
-        while <code>toString(Locale.FRENCH)</code> returns <cite>Projection de Mercator</cite>.
-      </p></div>
-      <p>
-        When defining spatial objects independently of locale conventions, we reduce the risk of computational overload.
-        For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the
-        same instance of <code>CoordinateOperation</code>,
-        even if the projection has a different name depending on the country.
-        Moreover, certain types of <code>CoordinateOperation</code> may require coordinate transformation matrices,
-        so sharing a single instance becomes even more preferable in order to reduce memory consumption.
-      </p>
-
-
-
-      <h3 id="Locale.ROOT"><code>Locale.ROOT</code> convention</h3>
-      <p>
-        All <abbr>SIS</abbr> methods receiving or returning the value of a <code>Locale</code> type accept the <code>Locale.ROOT</code> value.
-        This value is interpreted as specifying not to localize the text.
-        The notion of a <cite>non-localized text</cite> is a little false, as it is always necessary to chose a formatting convention.
-        This convention however, though very close to English, is usually slightly different.
-        For example:
-      </p>
-      <ul>
-        <li>
-          Identifiers are written as they appear in <abbr>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>
-          <th>Supplementary character examples</th>
-        </tr>
-        <tr>
-          <td>
-
-<pre style="margin-top: 6pt">for (int i=0; i&lt;string.length(); i++) {
-    char c = string.charAt(i);
-    if (Character.isWhitespace(c)) {
-        // A blank space was found.
-    }
-}</pre>
-
-          </td><td>
-
-<pre style="margin-top: 6pt">for (int i=0; i&lt;string.length();) {
-    int c = string.codePointAt(i);
-    if (Character.isWhitespace(c)) {
-        // A blank space was found.
-    }
-    i += Character.charCount(c);
-}</pre>
-
-          </td><td>
-            <center>(rendering depends on browser capabilities)</center>
-            <p style="font-size: 40px">&#x1F689; &#x1F6A5; &#x1F6A7; &#x1F6AB;
-              &#x1F6AF; &#x1F6B8; &#x1F6BA; &#x1F6B9; &#x1F6C4; &#x1F6AD;</p>
-          </td>
-        </tr>
-      </table>
-
-      <p>
-        <abbr>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">Blank spaces interpretation</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>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>SIS</abbr> library.
-      </p>
     </section>
   </body>
 </html>

Copied: sis/site/trunk/book/en/utility/Utilities.html (from r1794573, sis/site/trunk/book/en/utility.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/utility/Utilities.html?p2=sis/site/trunk/book/en/utility/Utilities.html&p1=sis/site/trunk/book/en/utility.html&r1=1794573&r2=1794656&rev=1794656&view=diff
==============================================================================
--- sis/site/trunk/book/en/utility.html [UTF-8] (original)
+++ sis/site/trunk/book/en/utility/Utilities.html [UTF-8] Tue May  9 23:04:35 2017
@@ -20,15 +20,15 @@
   under the License.
 -->
 
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
   <head>
-    <title>Utility classes and methods</title>
+    <title>Utilities</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
   </head>
   <body>
     <!--
-      Content below this point is copied in "../../content/book/en/developer-guide.html"
+      Content below this point is copied in "(…)/content/book/en/developer-guide.html" file
       by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
     -->
     <section>
@@ -40,352 +40,9 @@
         Most of these utilities are not specific to spatial information systems.
       </p>
 
-      <h2 id="ComparisonMode">Comparison modes of objects</h2>
-      <p>
-        There are various opinions on how to implement Java standard’s <code>Object.equals(Object)</code> method.
-        According to some, it should be possible to compare different implementations of the same interface or base class.
-        But to follow this policy, each interface or base class’s javadoc must define the algorithms that all implementations
-        shall use for their <code>equals(Object)</code> and <code>hashCode()</code> methods.
-        This approach is common in <code>java.util.Collection</code> and its child interfaces.
-        Transferring this approach to certain GeoAPI interfaces, however, would be a difficult task,
-        and would probably not be followed in many implementations.
-        Moreover, it comes at the expense of being able to take into account supplementary attributes in the child interfaces,
-        unless this possibility has been specified in the parent interface.
-        This constraint arises from the following points of the <code>equals(Object)</code> and <code>hashCode()</code> method contracts:
-      </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>SIS</abbr>
-        library implement the <code>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="ObjectConverters">Object converters</h2>
-      <p>
-        There is sometime a need to convert instances from a <var>source</var> Java type to a <var>target</var> Java type
-        while those types are unknown at compile time.
-        Various projects (Apache Common Convert, Spring, <i>etc.</i>)
-        have created their own interface for performing object conversions between types known only at runtime.
-        Details vary, but such interfaces typically look like below:
-      </p>
-
-<pre>interface ObjectConverter&lt;S,T&gt; {   // Some projects use only "Converter" as interface name.
-    T apply(S object);             // Another method name commonly found in other projects is "convert".
-}</pre>
-
-      <p>
-        Like other projects, Apache <abbr>SIS</abbr> also defines its own <code>ObjectConverter</code> interface.
-        The main difference between <abbr>SIS</abbr> converter interface and the interfaces found in other projects
-        is that <abbr>SIS</abbr> converters provide some information about their mathematical properties.
-        An Apache <abbr>SIS</abbr> converter can have zero, one or many of the following properties:
-      </p>
-      <dl>
-        <dt><dfn>Injective</dfn></dt>
-        <dd>A function is injective if no pair of <var>S</var> values can produce the same <var>T</var> value.
-          <div class="example"><p><b>Example:</b>
-              the <code>Integer</code> → <code>String</code> conversion performed by <code>Integer.toString()</code>
-              is an <cite>injective</cite> function because if two <code>Integer</code> values are not equal,
-              then it is guaranteed that their conversions will result in different <code>String</code> values.
-              However the <code>String</code> → <code>Integer</code> conversion performed by <code>Integer.valueOf(String)</code>
-              is <strong>not</strong> an injective function
-              because many distinct <code>String</code> values can be converted to the same <code>Integer</code> value.
-              For example converting the "42", "+42" and "0042" character strings all result in the same 42 integer value.
-          </p></div>
-        </dd>
-
-        <dt><dfn>Surjective</dfn></dt>
-        <dd>A function is surjective if each values of <var>T</var> can be created from at least one value of <var>S</var>.
-          <div class="example"><p><b>Example:</b>
-              the <code>String</code> → <code>Integer</code> conversion performed by <code>Integer.valueOf(String)</code>
-              is a <cite>surjective</cite> function because every <code>Integer</code> value can be created from at least one <code>String</code> value.
-              However the <code>Integer</code> → <code>String</code> conversion performed by <code>Integer.toString()</code>
-              is <strong>not</strong> a surjective function because it can not produce all possible <code>String</code> values.
-              For example there is no way to produce the "ABC" value with the <code>Integer.toString()</code> method.
-          </p></div>
-        </dd>
-
-        <dt><dfn>Bijective</dfn></dt>
-        <dd>A function is bijective if there is a one-to-one relationship between <var>S</var> and <var>T</var> values.
-          <div class="example"><p><b>Note:</b>
-            the <cite>bijective</cite> property is defined here for clarity, but actually does not have an explicit item
-            in Apache <abbr>SIS</abbr> <code>FunctionProperty</code> enumeration.
-            It is not necessary since a function that is both <cite>injective</cite> and <cite>surjective</cite> is necessarily bijective.
-          </p></div>
-        </dd>
-
-        <dt><dfn>Order preserving</dfn></dt>
-        <dd>A function is order preserving if any sequence of increasing <var>S</var> values is mapped to a sequence of increasing <var>T</var> values.
-          <div class="example"><p><b>Example:</b>
-            conversion from <code>Integer</code> to <code>Long</code> preserve the natural ordering of elements.
-            However conversions from <code>Integer</code> to <code>String</code> do <strong>not</strong> preserve natural ordering,
-            because some sequences of increasing integer values are ordered differently when their string representations are sorted by lexicographic order.
-            For example 1, 2, 10 become "1", "10", "2".
-          </p></div>
-        </dd>
-
-        <dt><dfn>Order reversing</dfn></dt>
-        <dd>A function is order reversing if any sequence of increasing <var>S</var> values is mapped to a sequence of decreasing <var>T</var> values.
-          <div class="example"><p><b>Example:</b>
-            a conversion that reverses the sign of numbers.
-          </p></div>
-        </dd>
-      </dl>
-      <p>
-        Above information may seem unnecessary when values are converted without taking in account the context in which the values appear.
-        But when the value to convert is part of a bigger object, then above information can affect the way the converted value will be used.
-        For example conversion of a [<var>min</var> … <var>max</var>] range is straightforward when the converter is <cite>order preserving</cite>.
-        But if the converter is <cite>order reversing</cite>, then the minimum and maximum values need to be interchanged.
-        For example if the converter reverses the sign of values, then the converted range is [-<var>max</var> … -<var>min</var>].
-        If the converter is neither order preserving or order reversing, then range conversion is not allowed at all
-        (because it does not contain the same set of values) even if the minimum and maximum values could be converted individually.
-      </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 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>SIS</abbr> uses
-        two approaches, distinguished by their level of granularity: at the level of the messages themselves,
-        or at the level of the objects that create the messages.
-        The approach used also determines whether it is possible to share the same instance of an object for all languages.
-      </p>
-
-      <h3 id="LocalizedString">Distinct character sequences for each locale</h3>
-      <p>
-        Some classes are only designed to function according to one locale convention at a time.
-        This is of course true for the standard implementations of <code>java.text.Format</code>,
-        as they are entirely dedicated to the work of internationalization.
-        But it is also the case for other less obvious classes like <code>javax.imageio.ImageReader</code> and <code>ImageWriter</code>.
-        When one of these classes is implemented by <abbr>SIS</abbr>,
-        we identify it by implementing the <code>org.apache.sis.util.Localized</code> interface.
-        The <code class="SIS">getLocale()</code> method of this interface can determine the locale conventions
-        by which the instance produces its message.
-      </p>
-      <p>
-        Another class that provides different methods for different locales is <code>java.lang.Throwable</code>.
-        The standard Java <abbr>API</abbr> defines two methods for getting the error message:
-        <code>getMessage()</code> and <code>getLocalizedMessage()</code>.
-        Usually those two methods return the same character sequences,
-        but some exceptions thrown by Apache <abbr>SIS</abbr> may use different locales.
-        The policy that <abbr>SIS</abbr> tries to apply on a <em>best-effort</em> basis is:
-      </p>
-      <ul>
-        <li><code>getMessage()</code> returns the message in the <abbr title="Java Virtual Machine">JVM</abbr> default locale.
-            In a client-server architecture, this is often the locale on the server side.
-            This is the recommended language for logging messages to be read by system administrators.</li>
-        <li><code>getLocalizedMessage()</code> returns the message in a locale that depends on the context
-            in which the exception has been thrown. This is often the locale used by a particular <code>Format</code>
-            or <code class="SIS">DataStore</code> instance, and can be presumed to be the locale on the client side.
-            This is the recommended language to show in the user application.</li>
-      </ul>
-
-      <div class="example"><p><b>Example:</b>
-        If an error occurred while a Japanese client connected to an European server, the localized message may be sent
-        to the client in Japanese language as given by <code>getLocalizedMessage()</code> while the same error may be
-        logged on the server side in the French (for example) language as given by <code>getMessage()</code>.
-        This allows system administrator to analyze the issue without the need to understand client’s language.
-      </p></div>
-      <p>
-        The utility class <code>org.apache.sis.util.Exceptions</code> provides convenience methods to get messages
-        according to the conventions of a given locale, when this information is available.
-      </p>
-
-
-
-      <h3 id="InternationalString">Single instance for all supported locales</h3>
-      <p>
-        The <abbr>API</abbr> conventions defined by <abbr>SIS</abbr> or inherited by GeoAPI favour the use of the
-        <code>InternationalString</code> type when the value of a <code>String</code> type would likely be localized.
-        This approach allows us to defer the internationalization process to the time when a character sequence is requested,
-        rather than the time when the object that contains them is created.
-        This is particularly useful for immutable classes used for creating unique instances independently of locale conventions.
-      </p>
-      <div class="example"><p><b>Example:</b>
-        <abbr>SIS</abbr> includes only one instance of the <code>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>InternationalString</code>, so that <code>toString(Locale.ENGLISH)</code> returns <cite>Mercator projection</cite>
-        while <code>toString(Locale.FRENCH)</code> returns <cite>Projection de Mercator</cite>.
-      </p></div>
-      <p>
-        When defining spatial objects independently of locale conventions, we reduce the risk of computational overload.
-        For example, it is easier to detect that two maps use the same cartographic projection if this last is represented by the
-        same instance of <code>CoordinateOperation</code>,
-        even if the projection has a different name depending on the country.
-        Moreover, certain types of <code>CoordinateOperation</code> may require coordinate transformation matrices,
-        so sharing a single instance becomes even more preferable in order to reduce memory consumption.
-      </p>
-
-
-
-      <h3 id="Locale.ROOT"><code>Locale.ROOT</code> convention</h3>
-      <p>
-        All <abbr>SIS</abbr> methods receiving or returning the value of a <code>Locale</code> type accept the <code>Locale.ROOT</code> value.
-        This value is interpreted as specifying not to localize the text.
-        The notion of a <cite>non-localized text</cite> is a little false, as it is always necessary to chose a formatting convention.
-        This convention however, though very close to English, is usually slightly different.
-        For example:
-      </p>
-      <ul>
-        <li>
-          Identifiers are written as they appear in <abbr>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>
-          <th>Supplementary character examples</th>
-        </tr>
-        <tr>
-          <td>
-
-<pre style="margin-top: 6pt">for (int i=0; i&lt;string.length(); i++) {
-    char c = string.charAt(i);
-    if (Character.isWhitespace(c)) {
-        // A blank space was found.
-    }
-}</pre>
-
-          </td><td>
-
-<pre style="margin-top: 6pt">for (int i=0; i&lt;string.length();) {
-    int c = string.codePointAt(i);
-    if (Character.isWhitespace(c)) {
-        // A blank space was found.
-    }
-    i += Character.charCount(c);
-}</pre>
-
-          </td><td>
-            <center>(rendering depends on browser capabilities)</center>
-            <p style="font-size: 40px">&#x1F689; &#x1F6A5; &#x1F6A7; &#x1F6AB;
-              &#x1F6AF; &#x1F6B8; &#x1F6BA; &#x1F6B9; &#x1F6C4; &#x1F6AD;</p>
-          </td>
-        </tr>
-      </table>
-
-      <p>
-        <abbr>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">Blank spaces interpretation</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>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>SIS</abbr> library.
-      </p>
+      <xi:include href="ComparisonModes.html"/>
+      <xi:include href="ObjectConverters.html"/>
+      <xi:include href="Internationalization.html"/>
     </section>
   </body>
 </html>

Copied: sis/site/trunk/book/en/xml/XML-ISO-19115.html (from r1794655, sis/site/trunk/book/en/xml.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/xml/XML-ISO-19115.html?p2=sis/site/trunk/book/en/xml/XML-ISO-19115.html&p1=sis/site/trunk/book/en/xml.html&r1=1794655&r2=1794656&rev=1794656&view=diff
==============================================================================
--- sis/site/trunk/book/en/xml.html [UTF-8] (original)
+++ sis/site/trunk/book/en/xml/XML-ISO-19115.html [UTF-8] Tue May  9 23:04:35 2017
@@ -22,111 +22,20 @@
 
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   <head>
-    <title>Representing objects in XML</title>
+    <title>XML-ISO-19115</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
   </head>
   <body>
     <!--
-      Content below this point is copied in "../../content/book/en/developer-guide.html"
+      Content below this point is copied in "(…)/content/book/en/developer-guide.html" file
       by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
     -->
     <section>
       <header>
-        <h1 id="XML-ISO">Representing objects in <abbr>XML</abbr></h1>
+        <h2 id="XML-ISO-19115">Representing metadata according to <abbr>ISO</abbr> 19115-3</h2>
       </header>
       <p>
-        Objects defined by <abbr>OGC</abbr>/<abbr>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>API</abbr> of Apache <abbr>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>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>gco</code></td>
-          <td><code>http://www.isotc211.org/2005/gco</code></td>
-        </tr>
-        <tr>
-          <td><code>gfc</code></td>
-          <td><code>http://www.isotc211.org/2005/gfc</code></td>
-        </tr>
-        <tr>
-          <td><code>gmd</code></td>
-          <td><code>http://www.isotc211.org/2005/gmd</code></td>
-        </tr>
-        <tr>
-          <td><code>gmi</code></td>
-          <td><code>http://www.isotc211.org/2005/gmi</code></td>
-        </tr>
-        <tr>
-          <td><code>gmx</code></td>
-          <td><code>http://www.isotc211.org/2005/gmx</code></td>
-        </tr>
-        <tr>
-          <td><code>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>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>ISO</abbr> 19115-3 standard is a typical example
-          </li>
-          <li>
-            <abbr>SAX</abbr> for objects that are relatively simple, but which may exist in very large numbers.
-            The set of points in a geometry is a typical example.
-          </li>
-          <li>
-            <abbr title="Document Object Model">DOM</abbr> as an alternative to <abbr>JAXB</abbr>
-            when the <abbr>XML</abbr> elements do not correspond exactly to Java attributes.
-            <i>Features</i> are an example, as their structure is dynamic.
-          </li>
-        </ul>
-      </aside>
-
-
-
-      <h2 id="XML-ISO-19115">Representing metadata according to <abbr>ISO</abbr> 19115-3</h2>
-      <p>
         For each metadata class, there is an <abbr>XML</abbr> type with the same name than in the abstract specification
         (for example, <code>gmd:MD_Metadata</code> and <code>gmd:CI_Citation</code>).
         All of these types may be used as the root of an <abbr>XML</abbr> document.
@@ -205,7 +114,7 @@
         These classes may be ignored, unless the developer wishes to implement his or her own classes whose instances must be written in <abbr>JAXB</abbr>.
       </p>
 
-      <aside>
+      <aside id="XML-SIS">
         <h3>Implementation strategy in Apache <abbr>SIS</abbr></h3>
         <p>
           <code>org.apache.sis.internal.jaxb.*</code> packages (non-public) define <abbr>JAXB</abbr> adaptors for all types of <abbr>ISO</abbr> objects.

Copied: sis/site/trunk/book/en/xml/XML-ISO.html (from r1794573, sis/site/trunk/book/en/xml.html)
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/xml/XML-ISO.html?p2=sis/site/trunk/book/en/xml/XML-ISO.html&p1=sis/site/trunk/book/en/xml.html&r1=1794573&r2=1794656&rev=1794656&view=diff
==============================================================================
--- sis/site/trunk/book/en/xml.html [UTF-8] (original)
+++ sis/site/trunk/book/en/xml/XML-ISO.html [UTF-8] Tue May  9 23:04:35 2017
@@ -20,15 +20,15 @@
   under the License.
 -->
 
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude" xml:lang="en">
   <head>
-    <title>Representing objects in XML</title>
+    <title>XML-ISO</title>
     <meta charset="UTF-8"/>
-    <link rel="stylesheet" type="text/css" href="../../content/book/book.css"/>
+    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
   </head>
   <body>
     <!--
-      Content below this point is copied in "../../content/book/en/developer-guide.html"
+      Content below this point is copied in "(…)/content/book/en/developer-guide.html" file
       by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
     -->
     <section>
@@ -123,249 +123,7 @@
         </ul>
       </aside>
 
-
-
-      <h2 id="XML-ISO-19115">Representing metadata according to <abbr>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>gmd:MD_Metadata</code> and <code>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>MD_Metadata</code> object,
-        or to write a document representing only a <code>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>CI_Citation</code> type,
-        the value of the <code class="OGC">citedResponsibleParty</code> property is incorporated
-        into a <code>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>&lt;MD_Metadata&gt;</b>
-  &lt;identificationInfo&gt;
-    <b>&lt;MD_DataIdentification&gt;</b>
-      &lt;citation&gt;
-        <b>&lt;CI_Citation&gt;</b>
-          &lt;citedResponsibleParty&gt;
-            <b>&lt;CI_Responsibility&gt;</b>
-              &lt;party&gt;
-                <b>&lt;CI_Party&gt;</b>
-                  &lt;contactInfo&gt;
-                    <b>&lt;CI_Contact&gt;</b>
-                      &lt;onlineResource&gt;
-                        <b>&lt;CI_OnlineResource&gt;</b>
-                          &lt;linkage&gt;
-                            &lt;URL&gt;http://www.opengeospatial.org&lt;/URL&gt;
-                          &lt;/linkage&gt;
-                        <b>&lt;/CI_OnlineResource&gt;</b>
-                      &lt;/onlineResource&gt;
-                    <b>&lt;/CI_Contact&gt;</b>
-                  &lt;/contactInfo&gt;
-                <b>&lt;/CI_Party&gt;</b>
-              &lt;/party&gt;
-            <b>&lt;/CI_Responsibility&gt;</b>
-          &lt;/citedResponsibleParty&gt;
-        <b>&lt;/CI_Citation&gt;</b>
-      &lt;/citation&gt;
-    <b>&lt;/MD_DataIdentification&gt;</b>
-  &lt;/identificationInfo&gt;
-<b>&lt;/MD_Metadata&gt;</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>API</abbr>s, each property corresponds to a method in its enclosing class.
-          In the example above, <code>gmd:identificationInfo</code>  (a property of <code>MD_Metadata</code> class)
-          corresponds to the <code>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>MD_DataIdentification</code>,
-          which corresponds to the <code>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>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>JAXB</abbr>.
-      </p>
-
-      <aside>
-        <h3>Implementation strategy in Apache <abbr>SIS</abbr></h3>
-        <p>
-          <code>org.apache.sis.internal.jaxb.*</code> packages (non-public) define <abbr>JAXB</abbr> adaptors for all types of <abbr>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>XSD</abbr> schemas</h4>
-        <p>
-          For each element of the first group listed above, the <abbr>XSD</abbr> schemas of the <abbr>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>gco:uuidref</code> and <code>xlink:href</code>)
-          which the <abbr>XSD</abbr> schemas collectively name <code>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> 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">&lt;MD_MetaData&gt;
-  &lt;identificationInfo&gt;
-    &lt;MD_DataIdentification id="<b>my_id</b>"&gt;
-      &lt;!-- insert child properties here --&gt;
-    &lt;/MD_DataIdentification&gt;
-  &lt;/identificationInfo&gt;
-&lt;/MD_MetaData&gt;</pre>
-
-          </td><td>
-
-<pre class="xml" style="margin-top: 6pt">&lt;MD_MetaData&gt;
-  &lt;identificationInfo xlink:href="<b>#my_id</b>"/&gt;
-&lt;/MD_MetaData&gt;</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>SIS</abbr> library, all objects that can be identified in an <abbr>XML</abbr> document
-        implements the <code>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&lt;Citation,String&gt;</code>,
-        in which the <code>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>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>import org.apache.sis.metadata.iso.DefaultMetadata;
-import org.apache.sis.xml.IdentifierSpace;
-import java.util.UUID;
-
-public class MyClass {
-    public void myMethod() {
-        UUID identifier = UUID.randomUUID();
-        <code class="SIS">DefaultMetadata</code> metadata = new <code class="SIS">DefaultMetadata</code>();
-        metadata.<code class="SIS">getIdentifierMap().putSpecialized</code>(IdentifierSpace.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>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>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> 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>SIS</abbr> will then return an object that, besides implementing the desired GeoAPI interface,
-        also implements the <code>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>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>CI_Citation</code> element containing a
-        <code>CI_Series</code> element, while on the right side the series is unknown.
-        If the <code>CI_Series</code> element had been completely omitted,
-        then the <code>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>Series</code> and <code>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">&lt;CI_Citation&gt;
-  &lt;series&gt;
-    &lt;CI_Series&gt;
-      &lt;!-- insert child properties here --&gt;
-    &lt;/CI_Series&gt;
-  &lt;/series&gt;
-&lt;/CI_Citation&gt;</pre>
-
-        </td><td>
-
-<pre class="xml" style="margin-top: 6pt">&lt;CI_Citation&gt;
-  &lt;series nilReason="unknown"/&gt;
-&lt;/CI_Citation&gt;</pre>
-
-          </td>
-        </tr>
-      </table>
+      <xi:include href="XML-ISO-19115.html"/>
     </section>
   </body>
 </html>



Mime
View raw message