Modified: sis/site/trunk/content/book/fr/developer-guide.html URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/fr/developer-guide.html?rev=1745551&r1=1745550&r2=1745551&view=diff ============================================================================== --- sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] (original) +++ sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] Thu May 26 00:52:22 2016 @@ -27,22 +27,13 @@ <nav> <ul class="toc"> <li><a href="#Foreword">Préface</a><ul> -<li><a href="#Standards">Standards et normes</a><ul> -<li><a href="#SpecificationTypes">Les types de spécifications</a></li></ul></li> +<li><a href="#Standards">Standards et normes</a></li> <li><a href="#About">Conventions utilisées dans ce guide</a><ul> <li><a href="#CodeColors">Code de couleurs</a></li></ul></li></ul></li> <li><a href="#GeoAPI">GeoAPI</a><ul> -<li><a href="#SpecificationToInterfaces">Des spécifications aux interfaces</a><ul> -<li><a href="#UML-annotation">Correspondances explicitées par l’annotation @UML</a></li> +<li><a href="#UML-annotation">Correspondances entre GeoAPI et les spécifications abstraites</a><ul> <li><a href="#MappingToJDK">Correspondances implicites avec le JDK standard</a></li></ul></li> -<li><a href="#ServiceLoader">Obtenir une implémentation des interfaces</a><ul> -<li><a href="#GeoAPI-simple">Fournir sa propre implémentation</a></li></ul></li> -<li><a href="#GeoAPI-modules">Les modules de GeoAPI</a><ul> -<li><a href="#GeoAPI-core">Les modules de définition des interfaces</a></li> -<li><a href="#GeoAPI-conformance">Le module de tests de conformité</a><ul> -<li><a href="#GeoAPI-validators">Validations des instances</a></li> -<li><a href="#GeoAPI-tests">Exécution des tests pré-définis</a></li></ul></li> -<li><a href="#GeoAPI-examples">Les modules d’exemples</a></li></ul></li></ul></li> +<li><a href="#GeoAPI-implementation">Implémentations des interfaces</a></li></ul></li> <li><a href="#XML-ISO">Représentation des objets en XML</a><ul> <li><a href="#XML-ISO-19115">Représentation des méta-données selon ISO 19115-3</a><ul> <li><a href="#gco-id">Identification d’instances déjà définies</a></li> @@ -84,6 +75,13 @@ <li><a href="#Envelope">Enveloppes</a><ul> <li><a href="#AntiMeridian">Enveloppes traversant l’antiméridien</a></li></ul></li></ul></li></ul></li> <li><a href="#Coverage">Couvertures de données (Coverages)</a></li> +<li><a href="#reduce-direct-dependency">Réduire la dépendance directe envers Apache SIS</a><ul> +<li><a href="#UML-annotation-geoapi">Correspondances entre GeoAPI et les spécifications abstraites</a></li> +<li><a href="#ServiceLoader">Obtenir une implémentation des interfaces de GeoAPI</a><ul> +<li><a href="#GeoAPI-simple">Fournir sa propre implémentation</a></li></ul></li></ul></li> +<li><a href="#tests">Les suites de tests</a><ul> +<li><a href="#GeoAPI-validators">Validations des instances</a></li> +<li><a href="#GeoAPI-tests">Exécution des tests pré-définis</a></li></ul></li> </ul> </nav> @@ -94,8 +92,7 @@ <nav><div class="chapter-links"><div class="next-chapter"><a href="#GeoAPI">Chapitre suivant</a> ➡</div></div></nav> </header> <nav>Dans ce chapitre:<ul class="toc"> -<li><a href="#Standards">Standards et normes</a><ul> -<li><a href="#SpecificationTypes">Les types de spécifications</a></li></ul></li> +<li><a href="#Standards">Standards et normes</a></li> <li><a href="#About">Conventions utilisées dans ce guide</a><ul> <li><a href="#CodeColors">Code de couleurs</a></li></ul></li></ul></nav> <p> @@ -171,16 +168,6 @@ Les organismes de normalisation ne fabri les utilisateurs doivent choisir un des produits conformes disponibles sur le marché ou développer leur propres solutions. C’est le respect volontaire de ces spécifications qui permet à des communautés à priori indépendantes d’échanger plus facilement des informations géographiques. -</p><p> -Outre ces organisations formelles de normalisation, il existe aussi des organisations qui ne sont pas officiellement -dédiées à l’élaboration de normes mais dont les travaux ont été largement adoptés comme standards de fait. -En particulier, la base de données <a href="http://www.epsg.org";>EPSG</a> fournit des codes numériques permettant d’identifier -facilement un système de référence des coordonnées parmi <a href="../../tables/CoordinateReferenceSystems.html">plusieurs milliers</a>. -Cette base de données est offerte par des compagnies pétrolières qui ont vu leur intérêt à ce que leurs prospections se fassent -bien à l’endroit voulu, sachant qu’elles ne contrôlent pas toujours la production des cartes sur lesquelles elles se positionnent. -D’autres exemples de standards de fait sont les formats -<a href="http://geotiff.osgeo.org";>GeoTIFF</a> pour les données réparties sur une grille (les images), et -<a href="http://fr.wikipedia.org/wiki/Shapefile";>Shapefile</a> pour les données vectorielles (les géométries). </p> @@ -268,14 +255,22 @@ hébergés en dehors des structures de l -<h3 id="SpecificationTypes"><span class="section-number">1.1.1.</span> Les types de spécifications</h3> <p> -Les standards <abbr title="Open Geospatial Consortium">OGC</abbr> sont spécifiés dans plusieurs dizaines de documents. +Outre ces organisations formelles de normalisation, il existe aussi des organisations qui ne sont pas officiellement +dédiées à l’élaboration de normes mais dont les travaux ont été largement adoptés comme standards de fait. +En particulier, la base de données <a href="http://www.epsg.org";>EPSG</a> fournit des codes numériques permettant d’identifier +facilement un système de référence des coordonnées parmi <a href="../../tables/CoordinateReferenceSystems.html">plusieurs milliers</a>. +Cette base de données est offerte par des compagnies pétrolières qui ont vu leur intérêt à ce que leurs prospections se fassent +bien à l’endroit voulu, sachant qu’elles ne contrôlent pas toujours la production des cartes sur lesquelles elles se positionnent. +D’autres exemples de standards de fait sont les formats +<a href="http://geotiff.osgeo.org";>GeoTIFF</a> pour les données réparties sur une grille (les images), et +<a href="http://fr.wikipedia.org/wiki/Shapefile";>Shapefile</a> pour les données vectorielles (les géométries). +</p><p> +Les standards <abbr>OGC</abbr> sont spécifiés dans plusieurs dizaines de documents. Chaque document élabore un service, par exemple les transformations de coordonnées. Le fonctionnement de chaque service est décrit par un ensemble de classes d’objets et leurs interactions. Ces éléments sont illustrés par des diagrammes <abbr>UML</abbr> (<i>Unified Modeling Language</i>) dans des spécifications dites « abstraites ». -</p><p> Les <a href="http://www.opengeospatial.org/standards/as";>spécifications abstraites</a> ne font référence à aucun langage informatique concret. Leurs concepts peuvent se concrétiser dans un langage de programmation, une base de données ou un schéma <abbr>XML</abbr> de manière plus ou moins directe. Il existe toutefois une part d’arbitraire dans la façon de concrétiser une spécification abstraite, étant donné que des ajustements sont souvent nécessaires @@ -569,17 +564,9 @@ Le lecteur peut ignorer ces boîtes gris <nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#Foreword">Chapitre précédent</a></div><div class="next-chapter"><a href="#XML-ISO">Chapitre suivant</a> ➡</div></div></nav> </header> <nav>Dans ce chapitre:<ul class="toc"> -<li><a href="#SpecificationToInterfaces">Des spécifications aux interfaces</a><ul> -<li><a href="#UML-annotation">Correspondances explicitées par l’annotation @UML</a></li> +<li><a href="#UML-annotation">Correspondances entre GeoAPI et les spécifications abstraites</a><ul> <li><a href="#MappingToJDK">Correspondances implicites avec le JDK standard</a></li></ul></li> -<li><a href="#ServiceLoader">Obtenir une implémentation des interfaces</a><ul> -<li><a href="#GeoAPI-simple">Fournir sa propre implémentation</a></li></ul></li> -<li><a href="#GeoAPI-modules">Les modules de GeoAPI</a><ul> -<li><a href="#GeoAPI-core">Les modules de définition des interfaces</a></li> -<li><a href="#GeoAPI-conformance">Le module de tests de conformité</a><ul> -<li><a href="#GeoAPI-validators">Validations des instances</a></li> -<li><a href="#GeoAPI-tests">Exécution des tests pré-définis</a></li></ul></li> -<li><a href="#GeoAPI-examples">Les modules d’exemples</a></li></ul></li></ul></nav> +<li><a href="#GeoAPI-implementation">Implémentations des interfaces</a></li></ul></nav> <p> Le projet <a href="http://www.geoapi.org";>GeoAPI</a> offre un ensemble d’interfaces Java pour les applications géo-spatiales. Dans une séries de paquets <code class="GeoAPI">org.opengis.*</code>, GeoAPI définit des structures représentant des méta-données, @@ -611,6 +598,8 @@ quitte à obtenir une valeur nulle en at </p></li> </ul> +<details> +<summary>Pour en savoir plus sur les origines du projet GeoAPI</summary> <article> <header> <h1>Historique du projet GeoAPI</h1> @@ -655,12 +644,27 @@ pour considérations futures. <a href="h Cette version a été la première à être déployée dans le <a href="http://search.maven.org/#search|ga|1|geoapi">dépôt central de Maven</a>. </p> </article> +</details> +<p>Les interfaces Java du projet GeoAPI sont parfois générées à partir d’autres fichiers fournis par l’<abbr>OGC</abbr>, +tels que les fichiers <abbr title="XML Schema Definition">XSD</abbr>. Mais il y a toujours une révision manuelle, et très souvent des modifications +par rapport aux fichiers générés par des processus automatiques. +Les écarts par rapport aux normes sont documentés dans chaque classe et chaque méthode concernées. +Chaque mention d’un écart est aussi recopiée dans <a href="http://www.geoapi.org/3.0/javadoc/departures.html";>une page unique</a>, +pour donner une vue d’ensemble. +Étant donné que ces écarts brouillent les liens qui existent entre les standards et certaines interfaces Java, +la correspondance entre ces langages est explicitée par des annotations <code class="GeoAPI">@UML</code> +et des fichiers de propriétés, décrits dans la section suivante. +</p> -<h2 id="SpecificationToInterfaces"><span class="section-number">2.1.</span> Des spécifications aux interfaces</h2> +<details> +<summary>Pour en savoir plus sur les raisons d’une définition manuelle des interfaces Java</summary> +<article id="SpecificationToInterfaces"> +<header> +<h1>Des spécifications de l’<abbr title="Open Geospatial Consortium">OGC</abbr> aux interfaces Java</h1> +</header> <p> -Les standards de l’<abbr title="Open Geospatial Consortium">OGC</abbr> étant définis par des moyens bien éprouvés en génie logiciel, -il est possible de générer automatiquement des interfaces Java à l’aide d’outils relativement répandus. +Il est possible de générer automatiquement des interfaces Java à partir des standards de l’<abbr>OGC</abbr> à l’aide d’outils existants. Une des approches les plus utilisées est de transformer les <a href="http://schemas.opengis.net/gml/3.3/";>schémas <abbr title="XML Schema Definition">XSD</abbr></a> en interfaces Java à l’aide de l’utilitaire en ligne de commande <code>xjc</code>. Cet utilitaire étant fournit avec la plupart des distributions du Java (il fait partie des outils de <a href="http://jaxb.java.net";><abbr>JAXB</abbr></a>), @@ -761,18 +765,89 @@ Dans GeoAPI, nous avons choisis de « r </p></div> </li> </ul> +</article> +</details> + +<p id="GeoAPI-core"> +GeoAPI est constitué de plusieurs modules. +Les modules <code class="GeoAPI">geoapi</code> et <code class="GeoAPI">geoapi-pending</code> +fournissent les interfaces dérivées des schémas <abbr>UML</abbr> des standards internationaux. +Le modèle conceptuel sera expliqué en détails dans les chapitres décrivant l’implémentation Apache <abbr title="Spatial Information System">SIS</abbr>. +On peut toutefois avoir un aperçu de son contenu en consultant la page listant les +<a href="http://www.geoapi.org/3.0/javadoc/content.html";>types et méthodes de GeoAPI et les standards d’où ils proviennent</a>. +</p> + +<details> +<summary>Pour en savoir plus sur les modules de GeoAPI</summary> +<article id="GeoAPI-modules"> +<h1>Les modules de GeoAPI</h1> <p> -Les écarts par rapport aux normes sont documentés dans chaque classe et chaque méthode concernées. -Chaque mention d’un écart est aussi recopiée dans <a href="http://www.geoapi.org/3.0/javadoc/departures.html";>une page unique</a>, -pour donner une vue d’ensemble. -Étant donné que ces écarts brouillent les liens qui existent entre les standards et certaines interfaces Java, -la correspondance entre ces langages est explicitée par des annotations <code class="GeoAPI">@UML</code> -et des fichiers de propriétés, décrits dans la section suivante. +Le projet GeoAPI est composé d’une partie standardisée (<code class="GeoAPI">geoapi</code>) et +d’une partie expérimentale (<code class="GeoAPI">geoapi-pending</code>). Ces deux parties étant +mutuellement exclusives, les utilisateurs doivent veiller à ne pas les mélanger dans un même projet. +Cette séparation est garantie pour tous les projets qui ne dépendent que du dépôt central de Maven +(incluant les versions finales de Apache <abbr title="Spatial Information System">SIS</abbr>), +car le module <code class="GeoAPI">geoapi-pending</code> n’est jamais déployé sur ce dépôt central. +En revanche certaines branches de développement de <abbr>SIS</abbr> peuvent dépendre de <code class="GeoAPI">geoapi-pending</code>. +</p><p> +Les modules de GeoAPI sont: </p> +<ul> +<li><p> +<b><code class="GeoAPI">geoapi</code></b> — contient les interfaces couvertes par le +<a href="http://www.opengeospatial.org/standards/geoapi";>standard GeoAPI de l’<abbr title="Open Geospatial Consortium">OGC</abbr></a>. +Les versions finales de Apache <abbr>SIS</abbr> dépendent de ce module. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-pending</code></b> — contient une +<em>copie</em> de toutes les interfaces du module <code class="GeoAPI">geoapi</code> +(non pas une dépendance) avec des ajouts qui n’ont pas encore été approuvés comme un standard <abbr>OGC</abbr>. +Certains ajouts apparaissent dans des interfaces normalement définies par le module <code class="GeoAPI">geoapi</code>, +d’où la nécessité de les copier. +Les branches de développement <code>jdk6</code>, +<code>jdk7</code> et <code>jdk8</code> de Apache <abbr>SIS</abbr> dépendent de ce module, +mais cette dépendance est transformée en une dépendance vers le module <code class="GeoAPI">geoapi</code> +standard au moment de fusionner les branches avec le tronc. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-conformance</code></b> — contient +une suite de tests JUnit que les développeurs peuvent utiliser pour tester leurs implémentations. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-examples</code></b> — contient des +exemples d’implémentations relativement simples. Ces exemples sont placés dans le domaine public +afin d’encourager les utilisateurs à les copier et les adapter à leurs besoins si les services +de Apache <abbr>SIS</abbr> ne conviennent pas. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-proj4</code></b> — contient une +implémentation partielle des paquets <code class="GeoAPI">org.opengis.referencing</code> +sous forme d’adaptateurs basés sur la bibliothèque C/C++ Proj.4. +Ce module peut être utilisé comme alternative au module <code class="SIS">sis-referencing</code> +pour certaines fonctions. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-netcdf</code></b> — contient une implémentation partielle des paquets +<code class="GeoAPI">org.opengis.referencing</code> et <code class="GeoAPI">org.opengis.coverage</code> +sous forme d’adaptateurs basés sur la bibliothèque <abbr title="Network Common Data Form">NetCDF</abbr> de l’<abbr title="University Corporation for Atmospheric Research">UCAR</abbr>. +La suite de tests de ce module a été conçue de manière à être réutilisable par d’autres projets. +Apache <abbr>SIS</abbr> l’utilise pour tester son propre module <code class="SIS">sis-netcdf</code>. +</p></li> +<li><p> +<b><code class="GeoAPI">geoapi-openoffice</code></b> — contient +un <i>add-in</i> pour les suites bureautiques Libre/OpenOffice.org. +<!-- + Apache <abbr>SIS</abbr> offre son propre <i>add-in</i> dans le module <code>sis-openoffice</code>, + mais utilise les mêmes noms de fonctions que le module de GeoAPI afin d’assurer une certaine compatibilité. + --> +</p></li> +</ul> +</article> +</details> -<h3 id="UML-annotation"><span class="section-number">2.1.1.</span> Correspondances explicitées par l’annotation <code class="GeoAPI">@UML</code></h3> +<h2 id="UML-annotation"><span class="section-number">2.1.</span> Correspondances entre GeoAPI et les spécifications abstraites</h2> <p> Pour chaque classe, méthode et constante définie à partir d’un standard <abbr title="Open Geospatial Consortium">OGC</abbr> ou <abbr title="International Organization for Standardization">ISO</abbr>, GeoAPI indique sa provenance à l’aide d’annotations définies dans le paquet <code class="GeoAPI">org.opengis.annotation</code>. @@ -793,62 +868,36 @@ pas autorisée à retourner la valeur <c <code class="comment">/** * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface. */</code> -@<code class="GeoAPI">UML</code>(specification = ISO_19111, - identifier = <i>"<code class="OGC">SC_ProjectedCRS</code>"</i>) +@<code class="GeoAPI">UML</code>(specification=ISO_19111, identifier=<i>"<code class="OGC">SC_ProjectedCRS</code>"</i>) <b>public</b> <b>interface</b> <code class="GeoAPI">ProjectedCRS</code> <b>extends</b> <code class="GeoAPI">GeneralDerivedCRS</code> { <code class="comment">/** * Returns the coordinate system, which must be Cartesian. */</code> - @<code class="GeoAPI">UML</code>(obligation = MANDATORY, - specification = ISO_19111, - identifier = <i>"<code class="OGC">coordinateSystem</code>"</i>) + @<code class="GeoAPI">UML</code>(obligation=MANDATORY, specification=ISO_19111, identifier=<i>"<code class="OGC">coordinateSystem</code>"</i>) <code class="GeoAPI">CartesianCS</code> <code class="GeoAPI">getCoordinateSystem()</code>; }</pre> <p> Les méthodes d’introspections du Java permettent d’accéder à ces informations pendant l’exécution d’une application. C’est utile pour obtenir les noms à afficher à des utilisateurs familiers avec les normes de l’<abbr>OGC</abbr>, -ou pour écrire des éléments dans un document <abbr>XML</abbr>. L’exemple suivant affiche le nom standard de la -méthode <code class="GeoAPI">getTitle()</code> de l’interface <code class="GeoAPI">Citation</code>: -</p> - -<pre>Class<?> type = <code class="GeoAPI">Citation</code>.<b>class</b>; -Method method = type.getMethod(<i>"<code class="GeoAPI">getTitle</code>"</i>, (Class<?>[]) <b>null</b>); -<code class="GeoAPI">UML</code> annot = method.getAnnotation(<code class="GeoAPI">UML</code>.<b>class</b>); -String id = annot.identifier(); -System.out.println(<i>"Le nom standard de la méthode "</i> + method.getName() + <i>" est "</i> + id);</pre> - -<p> -La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit la méthode de commodité -<code class="SIS">getStandardName(Class)</code> pour effectuer cette opération. -</p> - -<p> -L’opération inverse — obtenir la classe et méthode Java d’un nom standard — est un peu plus lourde. -Elle nécessite la lecture du fichier <code class="GeoAPI">class-index.properties</code> fournit dans le -paquet <code class="GeoAPI">org.opengis.annotation</code>. L’exemple suivant lit ce fichier juste avant -de rechercher le nom de l’interface correspondant à <code class="OGC">CI_Citation</code>. -Toutefois les utilisateurs sont encouragés à ne lire ce fichier qu’une fois et de conserver son contenu dans -une cache de leur application. +ou pour écrire des éléments dans un document <abbr>XML</abbr>. +La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit des méthodes de commodité +telles que <code class="SIS">getStandardName(Class)</code> pour effectuer cette opération. +Par exemple le code suivant affichera +« Le nom standard du type <code class="GeoAPI">org.opengis.referencing.crs.ProjectedCRS</code> est <code class="OGC">SC_ProjectedCRS</code> »: </p> -<pre>Properties isoToGeoAPI = <b>new</b> Properties(); -<b>try</b> (InputStream in = <code class="GeoAPI">UML</code>.<b>class</b>.getResourceAsStream(<i>"<code class="GeoAPI">class-index.properties</code>"</i>)) { - isoToGeoAPI.load(in); -} -String isoName = <i>"<code class="OGC">CI_Citation</code>"</i>; -String geoName = getProperty(isoName); -Class<?> type = Class.forName(geoName); -System.out.println(<i>"L’interface GeoAPI pour le type <abbr>ISO</abbr> "</i> + isoName + <i>" est "</i> + type);</pre> +<pre>Class<?> type = <code class="GeoAPI">ProjectedCRS</code>.<b>class</b>; +System.out.println(<i>"Le nom standard du type "</i> + type.getName() + <i>" est "</i> + Types.getStandardName(type));</pre> <p> -La classe <code class="SIS">org.apache.sis.util.iso.Types</code> fournit la méthode de commodité -<code class="SIS">forStandardName(String)</code> pour effectuer cette opération. +La méthode de commodité <code class="SIS">Types.forStandardName(String)</code> effectue l’opération inverse. +Les applications qui souhaiteraient effectuer ces opérations sans utiliser les méthodes de commodités de Apache SIS +trouveront des indications dans un <a href="#UML-annotation-geoapi">chapitre séparé</a>. </p> - -<h3 id="MappingToJDK"><span class="section-number">2.1.2.</span> Correspondances implicites avec le <abbr>JDK</abbr> standard</h3> +<h3 id="MappingToJDK"><span class="section-number">2.1.1.</span> Correspondances implicites avec le <abbr>JDK</abbr> standard</h3> <p> Certaines classes et méthodes n’ont ni annotation <code class="GeoAPI">@UML</code>, ni entrée dans le fichier <code class="GeoAPI">class-index.properties</code>. @@ -1035,750 +1084,431 @@ contrairement à celle de <code>Enum</co -<h2 id="ServiceLoader"><span class="section-number">2.2.</span> Obtenir une implémentation des interfaces</h2> +<h2 id="GeoAPI-implementation"><span class="section-number">2.2.</span> Implémentations des interfaces</h2> <p> -GeoAPI définit des fabriques (<code class="GeoAPI">Factory</code>) permettant de créer des implémentations de ses interfaces. -Par exemple <code class="GeoAPI">DatumFactory</code> fournit des méthodes permettant de créer des instances -implémentant les interfaces du paquet <code class="GeoAPI">org.opengis.referencing.datum</code>. -Ces <code class="GeoAPI">Factory</code> doivent être implémentées par les bibliothèques géospatiales -et déclarées comme <i>services</i> tel que défini par la classe standard <code>java.util.ServiceLoader</code>. -La javadoc de <code>ServiceLoader</code> explique la façon de procéder. -Mais pour résumer, les bibliothèques doivent créer dans le répertoire <code>META-INF/services/</code> -un fichier dont le nom correspond au nom complet de l’interface de la fabrique -(<code class="GeoAPI">org.opengis.referencing.datum.DatumFactory</code> dans l’exemple précédent). -Ce fichier texte doit contenir sur une ligne le nom complet de la classe implémentant cette interface. -Il peut s’agir d’une classe cachée aux yeux des utilisateurs, car ils n’ont pas besoin de connaître son existence. +Apache SIS implémente la plupart des interfaces de GeoAPI avec une classe du même nom que l’interface, +mais préfixée de « <code>Abstract</code> », « <code>Default</code> » ou « <code>General</code> ». +Les classes de Apache SIS qui sont préfixées par « <code>Default</code> » peuvent être instanciées directement +par une instruction <code>new DefaultXXX(…)</code> ou par la méthode <code>createXXX(…)</code> correspondante d’une fabrique. </p> +<div class="example"><b>Example:</b> pour représenter un système de référence de coordonnées projetées (Mercator, Lambert, <i>etc</i>): +<ul> +<li><code class="GeoAPI">org.opengis.referencing.crs.ProjectedCRS</code> est l’interface définie par GeoAPI sur la base du standard ISO 19111, et</li> +<li><code class="SIS">org.apache.sis.referencing.crs.DefaultProjectedCRS</code> est l’implémentation fournie par Apache SIS.</li> +</ul> +Une instance peut être créée par: +<ul> +<li><code>ProjectedCRS crs = new DefaultProjectedCRS(…)</code>, ou</li> +<li><code>ProjectedCRS crs = CRSFactory.createProjectedCRS(…)</code>.</li> +</ul> +Les deux approches attendent les mêmes arguments (omis dans cet exemple). +</div> <p> -Si la bibliothèque a bien déclaré ses fabriques comme des services, alors -les utilisateurs peuvent les obtenir en utilisant <code>ServiceLoader</code> comme dans l’exemple ci-dessous. -Cet exemple ne prend que la première fabrique trouvée; s’il existe plusieurs fabriques, -par exemple lorsque plusieurs bibliothèques cohabitent, alors le choix est laissé à l’utilisateur. +Dans la configuration par défaut de Apache SIS, +utiliser <code>CRSFactory.createXXX(…)</code> ou <code>new DefaultXXX(…)</code> revient presque au même +excepté que les <code class="GeoAPI">Factory</code> peuvent retourner des instances existantes +plutôt que de créer systématiquement de nouvelles instances, +et que les exceptions en cas d’arguments invalides sont de types différents. +Dans des configurations plus avancées, l’usage des <code class="GeoAPI">Factory</code> permet de +<a href="#ServiceLoader">réduire la dépendance directe d’une application envers SIS</a> +et de permettre une inversion de contrôle. +</p><p> +Le préfix « <code>General</code> » est parfois utilisé à la place de « <code>Default</code> » +afin de signaler que des implémentations alternatives existent pour des cas spécifiques. +Par exemple l’interface <code>Envelope</code> est implémentée par au moins deux classes de Apache SIS: +<code class="SIS">GeneralEnvelope</code> et <code>Envelope2D</code>. +La première implémentation peut représenter des enveloppes de n’importe quelle dimension +alors que la seconde implémentation est spécialisée pour les enveloppes à deux dimensions. +</p><p> +Les classes de Apache SIS qui sont préfixées par « <code>Abstract</code> » ne doivent pas – en principe – être instanciées. +Il faut plutôt instancier une sous-classe non-abstraites. +Toutefois plusieurs classes de SIS ne sont abstraites que conceptuellement, +sans que la définition de la classe ne contienne le mot-clé <code>abstract</code> du Java. +Ces classes peuvent être instanciées par l’instruction <code>new AbstractXXX(…)</code> +– mais pas par les <code class="GeoAPI">Factory</code> – malgré qu’elles soient conceptuellement abstraites. +Mais ces instanciations ne devraient être faites qu’en dernier recours, +lorsqu’il n’est vraiment pas possible de déterminer le sous-type exact. </p> - -<pre><b>import</b> org.opengis.referencing.<code class="GeoAPI">GeodeticDatum</code>; -<b>import</b> org.opengis.referencing.<code class="GeoAPI">DatumFactory</code>; -<b>import</b> java.util.ServiceLoader; - -<b>public</b> <b>class</b> MyApplication { - <b>public</b> <b>void</b> createMyDatum() { - ServiceLoader loader = ServiceLoader.load(<code class="GeoAPI">DatumFactory</code>.<b>class</b>); - <code class="GeoAPI">DatumFactory</code> factory = loader.iterator().next(); - <code class="GeoAPI">GeodeticDatum</code> myDatum = factory.<code class="GeoAPI">createGeodeticDatum</code>(…); - } -}</pre> - - - -<h3 id="GeoAPI-simple"><span class="section-number">2.2.1.</span> Fournir sa propre implémentation</h3> +</section> +<section> +<header> +<h1 id="XML-ISO"><span class="section-number">3.</span> Représentation des objets en <abbr>XML</abbr></h1> +<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#GeoAPI">Chapitre précédent</a></div><div class="next-chapter"><a href="#Utilities">Chapitre suivant</a> ➡</div></div></nav> +</header> +<nav>Dans ce chapitre:<ul class="toc"> +<li><a href="#XML-ISO-19115">Représentation des méta-données selon ISO 19115-3</a><ul> +<li><a href="#gco-id">Identification d’instances déjà définies</a></li> +<li><a href="#nilReason">Représentation de valeurs manquantes</a></li></ul></li></ul></nav> <p> -Implémenter soi-même GeoAPI n’est pas si difficile si on se contente de besoins bien précis. -Un développeur peut se concentrer sur une poignée d’interfaces parmi les centaines de disponibles, -tout en disposant des autres interfaces comme autant de points d’extensions à éventuellement implémenter -au gré des besoins. +Les objets définis par les standards <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr title="International Organization for Standardization">ISO</abbr> doivent pouvoir être échangés sur internet +entre des machines distantes, utilisant des logiciels différents écrits dans des langages différents. +Quelques uns des formats les plus connus sont +le <abbr>WKT</abbr> (<i>Well-Known Text</i>) et +le <abbr>WKB</abbr> (<i>Well-Known Binary</i>). +Mais le format le plus exhaustif et souvent considéré comme la référence est le <abbr>XML</abbr>, +au point où la façon de représenter les objets <abbr>ISO</abbr> dans ce format fait parfois l’objet d’un standard international à part entière. +Ainsi, les classes de méta-données sont décrites dans le standard <abbr>ISO</abbr> 19115-1 (une spécification dite <i>abstraite</i>), +alors que la représentation de ces classes en <abbr>XML</abbr> est décrite par les standards <abbr>ISO</abbr> 19115-3 et 19139. </p> <p> -Le modèle conceptuel représenté par les interfaces est complexe. Mais cette complexité peut être réduite en combinant certaines interfaces. -Par exemple plusieurs bibliothèques, même réputées, ne font pas la distinction entre <cite>Système de coordonnées</cite> (<abbr>CS</abbr>) -et <cite>Système de <u>référence</u> des coordonnées</cite> (<abbr title="Coordinate Reference System">CRS</abbr>). -Un développeur qui lui non-plus ne souhaite pas faire cette distinction peut implémenter ces deux interfaces par la même classe. -Il peut en résulter une implémentation dont la hiérarchie de classes est plus simple que la hiérarchie des interfaces de GeoAPI. -Le module <code class="GeoAPI">geoapi-examples</code>, discuté plus loin, fournit de telles combinaisons. -Le tableau suivant énumère quelques combinaisons possibles: +Les différents standards <abbr>OGC</abbr>/<abbr>ISO</abbr> n’emploient pas tous la même stratégie pour exprimer les objets en <abbr>XML</abbr>. +Le standard <abbr>ISO</abbr> 19115-3 en particulier emploie une approche plus verbeuse que les autres normes, +et fera l’objet d’une <a href="#XML-ISO-19115">section particulière</a>. +Mais la plupart des formats <abbr>XML</abbr> ont en commun de définir des types et des attributs supplémentaires +qui ne font pas partie des spécifications abstraites d’origines. +Ces attributs supplémentaires sont habituellement propres au <abbr>XML</abbr> et peuvent ne pas apparaître directement dans l’<abbr title="Application Programming Interface">API</abbr> de Apache <abbr title="Spatial Information System">SIS</abbr>. +Certains de ces attributs, notamment <code class="OGC">id</code>, <code class="OGC">uuid</code> et <code>xlink:href</code>, +restent toutefois accessibles sous forme de paires clé-valeurs. +</p> +<p> +Les documents <abbr>XML</abbr> peuvent employer les préfixes de leur choix, +mais les préfixes suivants sont couramment employés dans la pratique. +Ils apparaissent donc par défaut dans les documents produits par Apache <abbr>SIS</abbr>. +Ces préfixes sont définis dans la classe <code class="SIS">org.apache.sis.xml.Namespaces</code>. </p> <table> +<caption>Préfixes d’espaces de noms <abbr>XML</abbr> courants</caption> <tr> -<th>Interface principale</th> -<th>Interface auxiliaire</th> -<th>Usage</th> +<th>Préfixe</th> +<th>Espace de nom</th> </tr> <tr> -<td><code class="GeoAPI">CoordinateReferenceSystem</code></td> -<td><code class="GeoAPI">CoordinateSystem</code></td> -<td>Description d’un système de référence spatial (<abbr>CRS</abbr>).</td> +<td><code class="OGC">gco</code></td> +<td><code>http://www.isotc211.org/2005/gco</code></td> </tr> <tr> -<td><code class="GeoAPI">GeodeticDatum</code></td> -<td><code class="GeoAPI">Ellipsoid</code></td> -<td>Description d’un référentiel geodétique.</td> +<td><code class="OGC">gfc</code></td> +<td><code>http://www.isotc211.org/2005/gfc</code></td> </tr> <tr> -<td><code class="GeoAPI">CoordinateOperation</code></td> -<td><code class="GeoAPI">MathTransform</code></td> -<td>Opération de transformation de coordonnées.</td> +<td><code class="OGC">gmd</code></td> +<td><code>http://www.isotc211.org/2005/gmd</code></td> </tr> <tr> -<td><code class="GeoAPI">IdentifiedObject</code></td> -<td><code class="GeoAPI">ReferenceIdentifier</code></td> -<td>Objet (typiquement un <abbr>CRS</abbr>) que l’on peut identifier par un code.</td> +<td><code class="OGC">gmi</code></td> +<td><code>http://www.isotc211.org/2005/gmi</code></td> </tr> <tr> -<td><code class="GeoAPI">Citation</code></td> -<td><code class="GeoAPI">InternationalString</code></td> -<td>Référence bibliographique composée d’un simple titre.</td> +<td><code class="OGC">gmx</code></td> +<td><code>http://www.isotc211.org/2005/gmx</code></td> </tr> <tr> -<td><code class="GeoAPI">GeographicBoundingBox</code></td> -<td><code class="GeoAPI">Extent</code></td> -<td>Étendue spatiale en degrés de longitude et de latitude.</td> +<td><code class="OGC">gml</code></td> +<td><code>http://www.opengis.net/gml/3.2</code></td> </tr> <tr> -<td><code class="GeoAPI">ParameterValue</code></td> -<td><code class="GeoAPI">ParameterDescriptor</code></td> -<td>Description d’un paramètre (nom, type) associée à sa valeur.</td> -</tr> -<tr> -<td><code class="GeoAPI">ParameterValueGroup</code></td> -<td><code class="GeoAPI">ParameterDescriptorGroup</code></td> -<td>Description d’un ensemble de paramètres associés à leurs valeurs.</td> +<td><code>xlink</code></td> +<td><code>http://www.w3.org/1999/xlink</code></td> </tr> </table> - - -<h2 id="GeoAPI-modules"><span class="section-number">2.3.</span> Les modules de GeoAPI</h2> -<p> -Le projet GeoAPI est composé d’une partie standardisée (<code class="GeoAPI">geoapi</code>) et -d’une partie expérimentale (<code class="GeoAPI">geoapi-pending</code>). Ces deux parties étant -mutuellement exclusives, les utilisateurs doivent veiller à ne pas les mélanger dans un même projet. -Cette séparation est garantie pour tous les projets qui ne dépendent que du dépôt central de Maven -(incluant les versions finales de Apache <abbr title="Spatial Information System">SIS</abbr>), -car le module <code class="GeoAPI">geoapi-pending</code> n’est jamais déployé sur ce dépôt central. -En revanche certaines branches de développement de <abbr>SIS</abbr> peuvent dépendre de <code class="GeoAPI">geoapi-pending</code>. -</p> +<aside> +<h2>Outils de lecture et d’écriture de documents <abbr>XML</abbr></h2> <p> -Les modules de GeoAPI sont: +Apache <abbr title="Spatial Information System">SIS</abbr> emploie différentes bibliothèques pour lire et écrire différents type d’objets. +La bibliothèque utilisée dépend de la complexité de l’objet et des contraintes de performances. +Par exemple les annotations de <abbr title="Java Architecture for XML Binding">JAXB</abbr> ont l’avantage d’être proches du code, +ce qui facilite la maintenance de la correspondance entre le Java et le <abbr>XML</abbr>. +En revanche <abbr title="Simple API for XML">SAX</abbr> a l’avantage d’être performant. +De manière générale, Apache <abbr>SIS</abbr> emploie: </p> <ul> -<li><p> -<b><code class="GeoAPI">geoapi</code></b> — contient les interfaces couvertes par le -<a href="http://www.opengeospatial.org/standards/geoapi";>standard GeoAPI de l’<abbr title="Open Geospatial Consortium">OGC</abbr></a>. -Les versions finales de Apache <abbr>SIS</abbr> dépendent de ce module. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-pending</code></b> — contient une -<em>copie</em> de toutes les interfaces du module <code class="GeoAPI">geoapi</code> -(non pas une dépendance) avec des ajouts qui n’ont pas encore été approuvés comme un standard <abbr>OGC</abbr>. -Certains ajouts apparaissent dans des interfaces normalement définies par le module <code class="GeoAPI">geoapi</code>, -d’où la nécessité de les copier. -Les branches de développement <code>jdk6</code>, -<code>jdk7</code> et <code>jdk8</code> de Apache <abbr>SIS</abbr> dépendent de ce module, -mais cette dépendance est transformée en une dépendance vers le module <code class="GeoAPI">geoapi</code> -standard au moment de fusionner les branches avec le tronc. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-conformance</code></b> — contient -une suite de tests JUnit que les développeurs peuvent utiliser pour tester leurs implémentations. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-examples</code></b> — contient des -exemples d’implémentations relativement simples. Ces exemples sont placés dans le domaine public -afin d’encourager les utilisateurs à les copier et les adapter à leurs besoins si les services -de Apache <abbr>SIS</abbr> ne conviennent pas. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-proj4</code></b> — contient une -implémentation partielle des paquets <code class="GeoAPI">org.opengis.referencing</code> -sous forme d’adaptateurs basés sur la bibliothèque C/C++ Proj.4. -Ce module peut être utilisé comme alternative au module <code class="SIS">sis-referencing</code> -pour certaines fonctions. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-netcdf</code></b> — contient une implémentation partielle des paquets -<code class="GeoAPI">org.opengis.referencing</code> et <code class="GeoAPI">org.opengis.coverage</code> -sous forme d’adaptateurs basés sur la bibliothèque <abbr title="Network Common Data Form">NetCDF</abbr> de l’<abbr title="University Corporation for Atmospheric Research">UCAR</abbr>. -La suite de tests de ce module a été conçue de manière à être réutilisable par d’autres projets. -Apache <abbr>SIS</abbr> l’utilise pour tester son propre module <code class="SIS">sis-netcdf</code>. -</p></li> -<li><p> -<b><code class="GeoAPI">geoapi-openoffice</code></b> — contient -un <i>add-in</i> pour les suites bureautiques Libre/OpenOffice.org. -<!-- - Apache <abbr>SIS</abbr> offre son propre <i>add-in</i> dans le module <code>sis-openoffice</code>, - mais utilise les mêmes noms de fonctions que le module de GeoAPI afin d’assurer une certaine compatibilité. - --> -</p></li> +<li> +<abbr>JAXB</abbr> pour les objets qui ne sont pas répétés très souvent dans le document +mais dont la structure est complexe, avec des arborescences profondes. +L’ensemble des méta-données <abbr title="International Organization for Standardization">ISO</abbr> 19115-3 est un exemple typique. +</li> +<li> +<abbr>SAX</abbr> pour les objets relativement simples mais pouvant exister en très grand nombre. +L’ensemble des points dans une géométrie est un exemple typique. +</li> +<li> +<abbr title="Document Object Model">DOM</abbr> comme une alternative à <abbr>JAXB</abbr> +lorsque les éléments <abbr>XML</abbr> ne correspondent pas directement à des attributs Java. +Les <i>features</i> en sont un exemple, car leur structure est dynamique. +</li> </ul> - -<h3 id="GeoAPI-core"><span class="section-number">2.3.1.</span> Les modules de définition des interfaces</h3> -<p> -Les modules <code class="GeoAPI">geoapi</code> et <code class="GeoAPI">geoapi-pending</code> -fournissent les interfaces dérivées des schémas <abbr title="Unified Modeling Language">UML</abbr> des standards internationaux. -Le modèle conceptuel sera expliqué en détails dans les chapitres décrivant l’implémentation Apache <abbr title="Spatial Information System">SIS</abbr>. -On peut toutefois avoir un aperçu de son contenu en consultant la page listant les -<a href="http://www.geoapi.org/3.0/javadoc/content.html";>types et méthodes de GeoAPI et les standards d’où ils proviennent</a>. -</p> +</aside> -<h3 id="GeoAPI-conformance"><span class="section-number">2.3.2.</span> Le module de tests de conformité</h3> +<h2 id="XML-ISO-19115"><span class="section-number">3.1.</span> Représentation des méta-données selon <abbr title="International Organization for Standardization">ISO</abbr> 19115-3</h2> <p> -Le module <code class="GeoAPI">geoapi-conformance</code> fournit des <i>validateurs</i>, une <i>suite de tests</i> JUnit -et des <i>générateurs de rapports</i> sous forme de pages <abbr title="Hypertext Markup Language">HTML</abbr>. -Ce module peut être utilisé avec n’importe quelle implémentation de GeoAPI. -Pour les développeurs d’une bibliothèque géospatiale, il offre les avantages suivants: +Pour chaque classe de méta-donnée, il existe un type <abbr>XML</abbr> portant le même nom que dans la spécification abstraite +(par exemple <code class="OGC">gmd:MD_Metadata</code> et <code class="OGC">gmd:CI_Citation</code>). +Tous ces types peuvent être employés comme racine d’un document <abbr>XML</abbr>. +Ainsi, il est possible d’écrire un document représentant un objet <code class="OGC">MD_Metadata</code> complet, +ou d’écrire un document représentant seulement un objet <code class="OGC">CI_Citation</code>. +</p> +<p> +Le standard <abbr>ISO</abbr> 19139 dispose le contenu de ces objets d’une manière inhabituelle: +pour chaque propriété dont le type de la valeur est lui-même une autre classe du standard <abbr>ISO</abbr> 19139, +la valeur est enveloppée dans un élément qui représente son type plutôt que d’être écrite directement. +Par exemple dans un objet de type <code class="OGC">CI_Citation</code>, +la valeur de la propriété <code class="OGC">citedResponsibleParty</code> +est enveloppée dans un élément <code class="OGC">CI_Responsibility</code>. +Cette pratique double la profondeur de l’arborescence, en introduisant une duplication +à tous les niveaux pour chaque valeur, comme dans l’exemple suivant: </p> -<ul> -<li>Réduire la fastidieuse tâche d’écriture des tests, en réutilisant des tests existants.</li> -<li>Accroître la confiance en la validité des tests, du fait que <code class="GeoAPI">geoapi-conformance</code> -a lui-même sa propre suite de tests et est appliqué à d’autres implémentations.</li> -<li>Faciliter la comparaison avec les autres implémentations.</li> -</ul> - +<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> -<h4 id="GeoAPI-validators"><span class="section-number">2.3.2.1.</span> Validations des instances</h4> <p> -GeoAPI peut valider une instance de ses interfaces en vérifiant que certaines contraintes sont respectées. -Certaines contraintes ne peuvent pas être exprimées dans la signature de la méthode. Ces contraintes sont -généralement décrites textuellement dans les spécifications abstraites ou dans la javadoc. +L’exemple précédent, comme tous les documents conformes à <abbr>ISO</abbr> 19139, +est donc constitué d’une alternance systématique de deux types d’éléments <abbr>XML</abbr> imbriqués: </p> -<div class="example"><p><b>Exemple:</b> -La conversion ou transformation d’une coordonnée (<code class="OGC">CC_CoordinateOperation</code>) peut nécessiter l’enchaînement de plusieurs étapes. -Dans une telle chaîne d’opérations (<code class="OGC">CC_ConcatenatedOperation</code>), -pour chaque étape (<code class="OGC">CC_SingleOperation</code>) le nombre de dimensions -en sortie doit être égal au nombre de dimensions attendu en entré par l’opération suivante. -Exprimée en langage Java, cette contrainte stipule que pour tout index -0 < <var>i</var> < <var>n</var> où <var>n</var> est le nombre d’opérations, on a -<code>coordOperation[i].targetDimensions == coordOperation[i-1].sourceDimensions</code>. -</p></div> +<ol> +<li><p> +Il y a d’abord le nom de la propriété, qui commence toujours par une lettre minuscule (en ignorant les préfixes). +Dans les <abbr title="Application Programming Interface">API</abbr> Java, chaque propriété correspond à une méthode de la classe englobante. +Dans l’exemple ci-haut, <code class="OGC">gmd:identificationInfo</code> (une propriété de la classe <code class="OGC">MD_Metadata</code>) +correspond à la méthode <code class="GeoAPI">Metadata.getIdentificationInfo()</code>. +</p></li> +<li><p> +Sous chaque propriété se trouve le type de la valeur, sauf si elle a été remplacée par une référence +(la <a href="#gco-id">sous-section suivante</a> suivante approfondira ce sujet). +Le type de la valeur est un élément <abbr>XML</abbr> dont le nom commence toujours par une lettre majuscule, en ignorant les préfixes. +Dans l’exemple ci-haut nous avions <code class="OGC">MD_DataIdentification</code>, qui correspond à l’interface Java <code class="GeoAPI">DataIdentification</code>. +C’est cet élément <abbr>XML</abbr> qui contient les valeurs de la propriété. +</p></li> +</ol> <p> -La façon la plus simple d’effectuer ces vérifications est d’appeler les méthodes statiques -<code class="GeoAPI">validate(…)</code> de la classe <code class="GeoAPI">org.opengis.test.Validators</code>. -Ces méthodes portant toutes le même nom, il suffit d’écrire “<code>validate(<var>valeur</var>)</code>” -et de laisser le compilateur choisir la méthode la plus appropriée en fonction du type d’objet donné en argument. -Si le type d’objet n’est pas connu au moment de la compilation, alors la méthode <code class="GeoAPI">dispatch(Object)</code> -peut se charger de rediriger le travail à la méthode <code class="GeoAPI">validate(…)</code> appropriée. +Afin de réduire la complexité des bibliothèques, GeoAPI et Apache <abbr title="Spatial Information System">SIS</abbr> +n’exposent publiquement qu’une vision unifiée de ces deux types d’éléments. +L’<abbr>API</abbr> public correspond essentiellement au deuxième groupe. +Toutefois, lors de l’écriture d’un document <abbr>XML</abbr>, des éléments du premier groupe doivent être temporairement recréés. +Les classes qui y correspondent sont définies dans des paquets internes de <abbr>SIS</abbr>. +Ces classes peuvent être ignorées, sauf si le développeur souhaite implémenter ses propres classes +dont les instances devront être lues et écrites par <abbr title="Java Architecture for XML Binding">JAXB</abbr>. </p> + +<aside> +<h3>Stratégie d’implémentation dans Apache <abbr title="Spatial Information System">SIS</abbr></h3> <p> -Toutes les fonctions <code class="GeoAPI">validate(…)</code> suivent le fil des dépendances, -c’est-à-dire qu’elles valideront aussi chaque composantes de l’objet à valider. -Par exemple la validation d’un objet <code class="GeoAPI">GeographicCRS</code> impliquera -la validation de sa composante <code class="GeoAPI">GeodeticDatum</code>, qui impliquera elle-même -la validation de sa composante <code class="GeoAPI">Ellipsoid</code>, et ainsi de suite. -Il est donc inutile de valider soi-même les composantes, à moins de vouloir isoler le test d’un élément souvent problématique. +Les paquets <code class="SIS">org.apache.sis.internal.jaxb.*</code> (non-publiques) +définissent des adaptateurs <abbr title="Java Architecture for XML Binding">JAXB</abbr> pour tous les types d’objet <abbr title="International Organization for Standardization">ISO</abbr>. +Ces adaptateurs sont de toute façon nécessaires pour permettre à <abbr>JAXB</abbr> +d’obtenir les classes <abbr>SIS</abbr> implémentant les interfaces de GeoAPI. +De manière opportuniste, <abbr>SIS</abbr> en fait à la fois des adaptateurs <abbr>JAXB</abbr> +et des objets enveloppants le “vrai” objet à lire ou écrire. +Cette utilisation double permet d’éviter d’avoir à doubler le nombre de classes +(déjà très élevé) présents dans les paquets internes. </p> +<h4>Convention de nommage dans les schémas <abbr title="XML Schema Definition">XSD</abbr></h4> <p> -Par défaut, les validations sont aussi strictes que possible. Il est possible toutefois d’assouplir certaines règles. -L’assouplissement le plus fréquent consiste à tolérer l’absence d’attributs qui étaient sensés être obligatoires. -Cette règle et quelques autres peuvent être modifiées globalement pour tous les tests exécutés dans la -<abbr title="Java Virtual Machine">JVM</abbr> courante comme dans l’exemple suivant: +Les schémas <abbr>XSD</abbr> de l’<abbr title="Open Geospatial Consortium">OGC</abbr> définissent pour chaque élément du premier groupe +un type dont le nom se termine par “<code class="OGC">_PropertyType</code>”. +Pour le second groupe, chaque élément a un type dont le nom se termine par “<code class="OGC">_Type</code>”. +Les “<code class="OGC">_PropertyType</code>” peuvent avoir un groupe d’attributs +(notamment <code class="OGC">gco:uuidref</code> et <code>xlink:href</code>) +que les schémas <abbr>XSD</abbr> nomment collectivement <code class="OGC">gco:ObjectReference</code>. +Ces attributs n’ont pas de méthodes Java dédiées, mais sont accessibles indirectement via l’interface +<code class="SIS">IdentifiedObject</code> décrite dans la sous-section suivante. </p> +</aside> -<pre><b>import</b> org.opengis.metadata.<code class="GeoAPI">Metadata</code>; -<b>import</b> org.opengis.test.<code class="GeoAPI">Validators</code>; -<b>import</b> org.junit.Test; - -<b>public</b> <b>class</b> MyTest { - <code class="comment">/* - * Tolérer l’absence d’attributs obligatoires dans les paquets metadata et citation. - * Cette modification s’appliquera à tous les tests exécutés dans la <abbr>JVM</abbr> courante. - * S’il existe plusieurs classes de tests, cette initialisation peut être effectuée - * dans une classe parente à toutes les classes de tests. - */</code> - <b>static</b> { - <code class="GeoAPI">Validators</code>.<code class="GeoAPI">DEFAULT.metadata.requireMandatoryAttributes</code> = <b>false</b>; - <code class="GeoAPI">Validators</code>.<code class="GeoAPI">DEFAULT.citation.requireMandatoryAttributes</code> = <b>false</b>; - } - - @Test - <b>public</b> <b>void</b> testMyMetadata() { - <code class="GeoAPI">Metadata</code> myObject = …; <code class="comment">// Construisez un objet ici. -</code> <code class="GeoAPI">Validators</code>.<code class="GeoAPI">validate</code>(myObject); - } -}</pre> +<h3 id="gco-id"><span class="section-number">3.1.1.</span> Identification d’instances déjà définies</h3> <p> -Les règles peuvent aussi être modifiées pour une suite de tests particulière, -sans affecter la configuration par défaut de la <abbr>JVM</abbr> courante. -Cette approche nécessite de créer une nouvelle instance du validateur dont on souhaite modifier la configuration. +L’élément englobant peut contenir un attribut <code class="OGC">id</code> ou <code class="OGC">uuid</code>. +Si un de ces attributs est présent, l’élément englobé peut être complètement omis; +il sera remplacé au moment de la lecture par l’élément référencé par l’attribut. +Dans l’exemple suivant, la partie gauche définie un élément associé à l’identifiant “<code>mon_id</code>”, +alors que la partie droite référence cet élément: </p> -<pre><b>import</b> org.opengis.metadata.<code class="GeoAPI">Metadata</code>; -<b>import</b> org.opengis.test.<code class="GeoAPI">ValidatorContainer</code>; -<b>import</b> org.junit.Test; +<table class="hidden"> +<tr> +<th>Définir un identifiant</th> +<th>Utiliser l’identifiant défini</th> +</tr> +<tr> +<td> +<pre class="xml" style="margin-top: 6pt"><MD_MetaData> + <identificationInfo> + <MD_DataIdentification id=<i>"<b>mon_id</b>"</i>> + <code class="comment"><!-- insérer ici des propriétés filles --></code> + </MD_DataIdentification> + </identificationInfo> +</MD_MetaData></pre> +</td> +<td> +<pre class="xml" style="margin-top: 6pt"><MD_MetaData> + <identificationInfo xlink:href=<i>"<b>#mon_id</b>"</i>/> +</MD_MetaData></pre> +</td> +</tr> +</table> -<b>public</b> <b>class</b> MyTest { - <b>private</b> <b>final</b> <code class="GeoAPI">ValidatorContainer</code> validators; +<p> +Le choix de l’attribut à utiliser dépend de la portée de l’élément référencé: +</p> +<ul> +<li> +<code class="OGC">id</code> n’est valide qu’à l’intérieur du document <abbr>XML</abbr> +qui définit l’objet ainsi référencé. +</li> +<li> +<code class="OGC">uuid</code> peut être valide à l’extérieur du document <abbr>XML</abbr>, +mais quelqu’un doit maintenir une base de données fournissant les objets pour chaque UUID donnés. +</li> +<li> +<code>xlink:href</code> peut faire référence à un autre document <abbr>XML</abbr> accessible sur internet. +</li> +</ul> +<p> +Dans la bibliothèque <abbr title="Spatial Information System">SIS</abbr>, tous les objets susceptibles d’être identifiés dans un document <abbr>XML</abbr> +implémentent l’interface <code class="SIS">org.apache.sis.xml.IdentifiedObject</code>. +Chaque instance de cette interface fournit une vue de ses identifiants sous forme de <code>Map<Citation,String></code>, +dans lequel la clé <code class="GeoAPI">Citation</code> identifie le type d’identifiant et la valeur est l’identifiant lui-même. +Quelques constantes représentant différents types d’identifiants sont énumérées dans <code class="SIS">IdentifierSpace</code>, +notamment <code class="SIS">ID</code>, <code class="SIS">UUID</code> et <code class="SIS">HREF</code>. +Chacune de ces clés peut être associée à une valeur d’un type différent (habituellement <code>String</code>, +<code>UUID</code> ou <code>URI</code>) selon la clé. +Par exemple le code suivant définit une valeur pour l’attribut <code class="OGC">uuid</code>: +</p> - <b>public</b> MyTest() { - validators = <b>new</b> <code class="GeoAPI">ValidatorContainer</code>(); - validators.<code class="GeoAPI">metadata.requireMandatoryAttributes</code> = <b>false</b>; - validators.<code class="GeoAPI">citation.requireMandatoryAttributes</code> = <b>false</b>; - } +<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; - @Test - <b>public</b> <b>void</b> testMyMetadata() { - <code class="GeoAPI">Metadata</code> myObject = …; <code class="comment">// Construisez un objet ici. -</code> validators.<code class="GeoAPI">validate</code>(myObject); +<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> - - -<h4 id="GeoAPI-tests"><span class="section-number">2.3.2.2.</span> Exécution des tests pré-définis</h4> <p> -Des classes de tests JUnit sont définies dans des sous-paquets de <code class="GeoAPI">org.opengis.test</code>. -Toutes les classes de tests portent un nom se terminant en "<code>Test</code>". -GeoAPI définie aussi une classe <code class="GeoAPI">org.opengis.test.TestSuite</code> englobant l’ensemble -des tests définis dans le module <code class="GeoAPI">geoapi-conformance</code>, mais Apache <abbr title="Spatial Information System">SIS</abbr> ne l’utilise pas. -Apache <abbr>SIS</abbr> hérite plutôt des classes <code class="GeoAPI">*Test</code> de GeoAPI au cas-par-cas, dans les modules appropriés. -L’exemple ci-dessous donne un exemple de test de GeoAPI personnalisé. -La <a href="http://www.geoapi.org/geoapi-conformance/apidocs/org/opengis/test/referencing/ParameterizedTransformTest.html";>Javadoc -de la classe parente</a> documente en détails les tests effectués. -Dans cet exemple, un seul test est modifié et tous les autres tests sont hérités tels quels -(il n’est pas nécessaire de les répéter dans la sous-classe). -Toutefois, cet exemple ajoute une vérification supplémentaire, annotée <code>@After</code>, -qui sera exécutée après chacun des tests. +Bien que ce mécanisme aie été définit dans le but de mieux supporter les représentations des +attributs <abbr>XML</abbr> du groupe <code class="OGC">gco:ObjectIdentification</code>, +il permet aussi de manière opportuniste de manipuler d’autres types d’identifiants. +Par exemple les attributs <code class="GeoAPI">ISBN</code> et <code class="GeoAPI">ISSN</code> +de <code class="GeoAPI">Citation</code> peuvent être manipulés de cette manière. +Les méthodes de l’interface <code class="SIS">IdentifiedObject</code> fournissent donc un endroit unique +où peuvent être manipulés tous types d’identifiants (pas seulement <abbr>XML</abbr>) associés à un objet. </p> -<pre><b>import</b> org.junit.*; -<b>import</b> org.junit.runner.RunWith; -<b>import</b> org.junit.runners.JUnit4; -<b>import</b> org.opengis.test.referencing.<code class="GeoAPI">ParameterizedTransformTest</code>; -<b>import</b> <b>static</b> org.junit.Assert.*; - -@RunWith(JUnit4.<b>class</b>) -<b>public</b> <b>class</b> MyTest <b>extends</b> <code class="GeoAPI">ParameterizedTransformTest</code> { - <code class="comment">/** - * Spécifie aux tests de GeoAPI notre propre fabrique de transformations de coordonnées. - * GeoAPI testera les objets construits par cette fabrique. - */</code> - <b>public</b> MyTest() { - <b>super</b>(<b>new</b> MyMathTransformFactory()); - } - - <code class="comment">/** - * Modifie le comportement d’un test. Cet exemple assouplit un peu les exigences de ce test, - * en acceptant des erreurs jusqu’à 10 centimètres plutôt que la valeur par défaut de 1 cm. - * Ce changement ne s’applique qu’à cette méthode est n’affecte pas les autres tests hérités. - */</code> - @Test - @Override - <b>public</b> <b>void</b> testLambertAzimuthalEqualArea() <b>throws</b> <code class="GeoAPI">FactoryException</code>, <code class="GeoAPI">TransformException</code> { - <code class="GeoAPI">tolerance</code> = 0.1; <code class="comment">// Tolérance de 10 cm. -</code> <b>super</b>.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>; - } - - <code class="comment">/** - * Vérification supplémentaire effectuée après chaque test, hérité ou non. - * Dans cet exemple, nous vérifions que la transformation qui a été testée - * travaillait bien dans des espaces bi-dimensionnels. - */</code> - @After - <b>public</b> <b>void</b> ensureAllTransformAreMath2D() { - assertTrue(<code class="GeoAPI">transform</code> <b>instanceof</b> <code class="GeoAPI">MathTransform2D</code>); - } -}</pre> - -<h3 id="GeoAPI-examples"><span class="section-number">2.3.3.</span> Les modules d’exemples</h3> -<p> -Le module <code class="GeoAPI">geoapi-examples</code> fournit des exemples d’implémentations simples. -Plusieurs de ces classes implémentent plus d’une interface à la fois afin de proposer un modèle conceptuel plus simple. -La <a href="http://www.geoapi.org/geoapi-examples/apidocs/overview-summary.html";>Javadoc de ce module</a> -énumère les paquets et classes clés avec les combinaisons effectuées. -Ce module illustre non-seulement comment GeoAPI peut-être implémenté, mais aussi comment l’implémentation -peut être testée en utilisant <code class="GeoAPI">geoapi-conformance</code>. -</p> +<h3 id="nilReason"><span class="section-number">3.1.2.</span> Représentation de valeurs manquantes</h3> <p> -Bien que sa mission première soit de servir d’inspiration aux implémenteurs, -<code class="GeoAPI">geoapi-examples</code> a tout-de-même été conçu de manière à être utilisable -par des applications ayant des besoins très simples. Tous les exemples étant dans le domaine publique, -les développeurs sont invités à adapter librement des copies de ces classes si nécessaires. -Toutefois si des modifications sont apportées hors du cadre du projet GeoAPI, le bon usage veut que les copies -modifiées soient placées dans un paquet portant un autre nom que <code class="GeoAPI">org.opengis</code>. +Lorsqu’une propriété n’est pas définie, la méthode correspondante de GeoAPI retourne généralement <code>null</code>. +Toutefois les choses se compliquent lorsque la propriété manquante est une valeur considérée comme obligatoire par le standard <abbr title="International Organization for Standardization">ISO</abbr> 19115. +Le standard <abbr>ISO</abbr> 19139 autorise l’omission de propriétés obligatoires à la condition d’indiquer pourquoi la valeur est manquante. +Les raisons peuvent être que la propriété ne s’applique pas (<code class="OGC">inapplicable</code>), +que la valeur existe probablement mais n’est pas connue (<code class="OGC">unknown</code>), +que la valeur pourrait ne pas exister (<code class="OGC">missing</code>), +qu’elle ne peut pas être divulguée (<code class="OGC">withheld</code>), <i>etc.</i> +La transmission de cette information nécessite l’utilisation d’un objet non-nul même lorsque la valeur est manquante. +<abbr title="Spatial Information System">SIS</abbr> procède en retournant un objet qui, en plus d’implémenter l’interface GeoAPI attendue, +implémente aussi l’interface <code class="SIS">org.apache.sis.xml.NilObject</code>. +Cette interface marque les instances dont toutes les méthodes retournent une collection vide, +un tableau vide, <code>null</code>, <code>NaN</code>, <code>0</code> ou <code>false</code>, +dans cet ordre de préférence selon ce que les types de retours des méthodes permettent. +Chaque instance implémentant <code class="SIS">NilObject</code> fournit une méthode +<code class="SIS">getNilReason()</code> indiquant pourquoi l’objet est nul. </p> <p> -Pour des besoins un peu plus poussés, les développeurs sont invités à examiner les modules -<code class="GeoAPI">geoapi-proj4</code> et <code class="GeoAPI">geoapi-netcdf</code>. -Ces deux modules fournissent des exemples d’adaptateurs permettant d’utiliser, via les interfaces de GeoAPI, -une partie des fonctionnalités de bibliothèques externes (Proj.4 et <abbr title="Network Common Data Form">NetCDF</abbr>). -L’avantage de passer par ces interfaces est de disposer d’un modèle unifié pour exploiter deux <abbr title="Application Programming Interface">API</abbr> très différents, -tout en se gardant la possibilité de basculer plus facilement à une autre bibliothèque si désiré. +Dans l’exemple suivant, la partie gauche montre un élément <code class="OGC">CI_Citation</code> +contenant un élément <code class="OGC">CI_Series</code>, alors que dans la partie droite la série est inconnue. +Si l’élément <code class="OGC">CI_Series</code> avait été complètement omis, +alors la méthode <code class="GeoAPI">Citation.getSeries()</code> retournerait <code>null</code> en Java. +Mais en présence d’un attribut <code class="OGC">nilReason</code>, l’implémentation <abbr>SIS</abbr> +de <code class="SIS">getSeries()</code> retournera plutôt un objet implémentant à la fois les interfaces +<code class="GeoAPI">Series</code> et <code class="SIS">NilReason</code>, +et dont la méthode <code class="SIS">getNilReason()</code> retournera la constante <code class="SIS">UNKNOWN</code>. </p> + +<table class="hidden"> +<tr> +<th>Information présente</th> +<th>Information absente</th> +</tr> +<tr> +<td> +<pre class="xml" style="margin-top: 6pt"><CI_Citation> + <series> + <CI_Series> + <code class="comment"><!-- insérer ici des propriétés filles --></code> + </CI_Series> + </series> +</CI_Citation></pre> +</td> +<td> +<pre class="xml" style="margin-top: 6pt"><CI_Citation> + <series nilReason=<i>"unknown"</i>/> +</CI_Citation></pre> +</td> +</tr> +</table> </section> <section> <header> -<h1 id="XML-ISO"><span class="section-number">3.</span> Représentation des objets en <abbr>XML</abbr></h1> -<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#GeoAPI">Chapitre précédent</a></div><div class="next-chapter"><a href="#Utilities">Chapitre suivant</a> ➡</div></div></nav> +<h1 id="Utilities"><span class="section-number">4.</span> Classes et méthodes utilitaires</h1> +<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#XML-ISO">Chapitre précédent</a></div><div class="next-chapter"><a href="#Referencing">Chapitre suivant</a> ➡</div></div></nav> </header> <nav>Dans ce chapitre:<ul class="toc"> -<li><a href="#XML-ISO-19115">Représentation des méta-données selon ISO 19115-3</a><ul> -<li><a href="#gco-id">Identification d’instances déjà définies</a></li> -<li><a href="#nilReason">Représentation de valeurs manquantes</a></li></ul></li></ul></nav> +<li><a href="#ComparisonMode">Modes de comparaisons des objets</a></li> +<li><a href="#Internationalization">Internationalisation</a><ul> +<li><a href="#LocalizedString">Chaînes de caractères distinctes pour chaque conventions locales</a></li> +<li><a href="#InternationalString">Instance unique pour toutes les conventions locales</a></li> +<li><a href="#Locale.ROOT">Convention Locale.ROOT</a></li> +<li><a href="#UnicodePoint">Traitement des caractères</a><ul> +<li><a href="#Whitespaces">Interprétation des espaces blancs</a></li></ul></li></ul></li></ul></nav> <p> -Les objets définis par les standards <abbr title="Open Geospatial Consortium">OGC</abbr>/<abbr title="International Organization for Standardization">ISO</abbr> doivent pouvoir être échangés sur internet -entre des machines distantes, utilisant des logiciels différents écrits dans des langages différents. -Quelques uns des formats les plus connus sont -le <abbr>WKT</abbr> (<i>Well-Known Text</i>) et -le <abbr>WKB</abbr> (<i>Well-Known Binary</i>). -Mais le format le plus exhaustif et souvent considéré comme la référence est le <abbr>XML</abbr>, -au point où la façon de représenter les objets <abbr>ISO</abbr> dans ce format fait parfois l’objet d’un standard international à part entière. -Ainsi, les classes de méta-données sont décrites dans le standard <abbr>ISO</abbr> 19115-1 (une spécification dite <i>abstraite</i>), -alors que la représentation de ces classes en <abbr>XML</abbr> est décrite par les standards <abbr>ISO</abbr> 19115-3 et 19139. +Ce chapitre décrit des aspects de Apache <abbr title="Spatial Information System">SIS</abbr> qui s’appliquent à l’ensemble de la bibliothèque. +La plupart de ces utilitaires ne sont pas spécifiques aux systèmes d’information spatiales. </p> + +<h2 id="ComparisonMode"><span class="section-number">4.1.</span> Modes de comparaisons des objets</h2> <p> -Les différents standards <abbr>OGC</abbr>/<abbr>ISO</abbr> n’emploient pas tous la même stratégie pour exprimer les objets en <abbr>XML</abbr>. -Le standard <abbr>ISO</abbr> 19115-3 en particulier emploie une approche plus verbeuse que les autres normes, -et fera l’objet d’une <a href="#XML-ISO-19115">section particulière</a>. -Mais la plupart des formats <abbr>XML</abbr> ont en commun de définir des types et des attributs supplémentaires -qui ne font pas partie des spécifications abstraites d’origines. -Ces attributs supplémentaires sont habituellement propres au <abbr>XML</abbr> et peuvent ne pas apparaître directement dans l’<abbr title="Application Programming Interface">API</abbr> de Apache <abbr title="Spatial Information System">SIS</abbr>. -Certains de ces attributs, notamment <code class="OGC">id</code>, <code class="OGC">uuid</code> et <code>xlink:href</code>, -restent toutefois accessibles sous forme de paires clé-valeurs. +Il existe différentes opinions sur la façon d’implémenter la méthode <code>Object.equals(Object)</code> du Java standard. +Selon certains, il doit être possible de comparer différentes implémentations d’une même interface ou classe de base. +Mais cette politique nécessite que chaque interface ou classe de base définisse entièrement dans sa Javadoc les critères ou calculs +que doivent employer les méthodes <code>equals(Object)</code> et <code>hashCode()</code> dans toutes les implémentations. +Cette approche est choisie notamment par <code>java.util.Collection</code> et ses interfaces filles. +La transposition de cette approche aux centaines d’interfaces de GeoAPI serait toutefois une entreprise ardue, +qui risquerait d’être assez peu suivie par les diverses implémentations. +En outre, elle se fait au détriment de la possibilité de prendre en compte des attributs supplémentaires dans les interfaces filles +si cette possibilité n’a pas été spécifiée dans l’interface parente. +Cette contrainte découle des points suivants du contrat des méthodes <code>equals(Object)</code> et <code>hashCode()</code>: </p> -<p> -Les documents <abbr>XML</abbr> peuvent employer les préfixes de leur choix, -mais les préfixes suivants sont couramment employés dans la pratique. -Ils apparaissent donc par défaut dans les documents produits par Apache <abbr>SIS</abbr>. -Ces préfixes sont définis dans la classe <code class="SIS">org.apache.sis.xml.Namespaces</code>. -</p> -<table> -<caption>Préfixes d’espaces de noms <abbr>XML</abbr> courants</caption> -<tr> -<th>Préfixe</th> -<th>Espace de nom</th> -</tr> -<tr> -<td><code class="OGC">gco</code></td> -<td><code>http://www.isotc211.org/2005/gco</code></td> -</tr> -<tr> -<td><code class="OGC">gfc</code></td> -<td><code>http://www.isotc211.org/2005/gfc</code></td> -</tr> -<tr> -<td><code class="OGC">gmd</code></td> -<td><code>http://www.isotc211.org/2005/gmd</code></td> -</tr> -<tr> -<td><code class="OGC">gmi</code></td> -<td><code>http://www.isotc211.org/2005/gmi</code></td> -</tr> -<tr> -<td><code class="OGC">gmx</code></td> -<td><code>http://www.isotc211.org/2005/gmx</code></td> -</tr> -<tr> -<td><code class="OGC">gml</code></td> -<td><code>http://www.opengis.net/gml/3.2</code></td> -</tr> -<tr> -<td><code>xlink</code></td> -<td><code>http://www.w3.org/1999/xlink</code></td> -</tr> -</table> - -<aside> -<h2>Outils de lecture et d’écriture de documents <abbr>XML</abbr></h2> -<p> -Apache <abbr title="Spatial Information System">SIS</abbr> emploie différentes bibliothèques pour lire et écrire différents type d’objets. -La bibliothèque utilisée dépend de la complexité de l’objet et des contraintes de performances. -Par exemple les annotations de <abbr title="Java Architecture for XML Binding">JAXB</abbr> ont l’avantage d’être proches du code, -ce qui facilite la maintenance de la correspondance entre le Java et le <abbr>XML</abbr>. -En revanche <abbr title="Simple API for XML">SAX</abbr> a l’avantage d’être performant. -De manière générale, Apache <abbr>SIS</abbr> emploie: -</p> -<ul> -<li> -<abbr>JAXB</abbr> pour les objets qui ne sont pas répétés très souvent dans le document -mais dont la structure est complexe, avec des arborescences profondes. -L’ensemble des méta-données <abbr title="International Organization for Standardization">ISO</abbr> 19115-3 est un exemple typique. -</li> -<li> -<abbr>SAX</abbr> pour les objets relativement simples mais pouvant exister en très grand nombre. -L’ensemble des points dans une géométrie est un exemple typique. -</li> -<li> -<abbr title="Document Object Model">DOM</abbr> comme une alternative à <abbr>JAXB</abbr> -lorsque les éléments <abbr>XML</abbr> ne correspondent pas directement à des attributs Java. -Les <i>features</i> en sont un exemple, car leur structure est dynamique. -</li> -</ul> -</aside> - - - -<h2 id="XML-ISO-19115"><span class="section-number">3.1.</span> Représentation des méta-données selon <abbr title="International Organization for Standardization">ISO</abbr> 19115-3</h2> -<p> -Pour chaque classe de méta-donnée, il existe un type <abbr>XML</abbr> portant le même nom que dans la spécification abstraite -(par exemple <code class="OGC">gmd:MD_Metadata</code> et <code class="OGC">gmd:CI_Citation</code>). -Tous ces types peuvent être employés comme racine d’un document <abbr>XML</abbr>. -Ainsi, il est possible d’écrire un document représentant un objet <code class="OGC">MD_Metadata</code> complet, -ou d’écrire un document représentant seulement un objet <code class="OGC">CI_Citation</code>. -</p> -<p> -Le standard <abbr>ISO</abbr> 19139 dispose le contenu de ces objets d’une manière inhabituelle: -pour chaque propriété dont le type de la valeur est lui-même une autre classe du standard <abbr>ISO</abbr> 19139, -la valeur est enveloppée dans un élément qui représente son type plutôt que d’être écrite directement. -Par exemple dans un objet de type <code class="OGC">CI_Citation</code>, -la valeur de la propriété <code class="OGC">citedResponsibleParty</code> -est enveloppée dans un élément <code class="OGC">CI_Responsibility</code>. -Cette pratique double la profondeur de l’arborescence, en introduisant une duplication -à tous les niveaux pour chaque valeur, comme dans l’exemple suivant: -</p> - -<pre 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> -L’exemple précédent, comme tous les documents conformes à <abbr>ISO</abbr> 19139, -est donc constitué d’une alternance systématique de deux types d’éléments <abbr>XML</abbr> imbriqués: -</p> -<ol> -<li><p> -Il y a d’abord le nom de la propriété, qui commence toujours par une lettre minuscule (en ignorant les préfixes). -Dans les <abbr title="Application Programming Interface">API</abbr> Java, chaque propriété correspond à une méthode de la classe englobante. -Dans l’exemple ci-haut, <code class="OGC">gmd:identificationInfo</code> (une propriété de la classe <code class="OGC">MD_Metadata</code>) -correspond à la méthode <code class="GeoAPI">Metadata.getIdentificationInfo()</code>. -</p></li> -<li><p> -Sous chaque propriété se trouve le type de la valeur, sauf si elle a été remplacée par une référence -(la <a href="#gco-id">sous-section suivante</a> suivante approfondira ce sujet). -Le type de la valeur est un élément <abbr>XML</abbr> dont le nom commence toujours par une lettre majuscule, en ignorant les préfixes. -Dans l’exemple ci-haut nous avions <code class="OGC">MD_DataIdentification</code>, qui correspond à l’interface Java <code class="GeoAPI">DataIdentification</code>. -C’est cet élément <abbr>XML</abbr> qui contient les valeurs de la propriété. -</p></li> -</ol> - -<p> -Afin de réduire la complexité des bibliothèques, GeoAPI et Apache <abbr title="Spatial Information System">SIS</abbr> -n’exposent publiquement qu’une vision unifiée de ces deux types d’éléments. -L’<abbr>API</abbr> public correspond essentiellement au deuxième groupe. -Toutefois, lors de l’écriture d’un document <abbr>XML</abbr>, des éléments du premier groupe doivent être temporairement recréés. -Les classes qui y correspondent sont définies dans des paquets internes de <abbr>SIS</abbr>. -Ces classes peuvent être ignorées, sauf si le développeur souhaite implémenter ses propres classes -dont les instances devront être lues et écrites par <abbr title="Java Architecture for XML Binding">JAXB</abbr>. -</p> - -<aside> -<h3>Stratégie d’implémentation dans Apache <abbr title="Spatial Information System">SIS</abbr></h3> -<p> -Les paquets <code class="SIS">org.apache.sis.internal.jaxb.*</code> (non-publiques) -définissent des adaptateurs <abbr title="Java Architecture for XML Binding">JAXB</abbr> pour tous les types d’objet <abbr title="International Organization for Standardization">ISO</abbr>. -Ces adaptateurs sont de toute façon nécessaires pour permettre à <abbr>JAXB</abbr> -d’obtenir les classes <abbr>SIS</abbr> implémentant les interfaces de GeoAPI. -De manière opportuniste, <abbr>SIS</abbr> en fait à la fois des adaptateurs <abbr>JAXB</abbr> -et des objets enveloppants le “vrai” objet à lire ou écrire. -Cette utilisation double permet d’éviter d’avoir à doubler le nombre de classes -(déjà très élevé) présents dans les paquets internes. -</p> -<h4>Convention de nommage dans les schémas <abbr title="XML Schema Definition">XSD</abbr></h4> -<p> -Les schémas <abbr>XSD</abbr> de l’<abbr title="Open Geospatial Consortium">OGC</abbr> définissent pour chaque élément du premier groupe -un type dont le nom se termine par “<code class="OGC">_PropertyType</code>”. -Pour le second groupe, chaque élément a un type dont le nom se termine par “<code class="OGC">_Type</code>”. -Les “<code class="OGC">_PropertyType</code>” peuvent avoir un groupe d’attributs -(notamment <code class="OGC">gco:uuidref</code> et <code>xlink:href</code>) -que les schémas <abbr>XSD</abbr> nomment collectivement <code class="OGC">gco:ObjectReference</code>. -Ces attributs n’ont pas de méthodes Java dédiées, mais sont accessibles indirectement via l’interface -<code class="SIS">IdentifiedObject</code> décrite dans la sous-section suivante. -</p> -</aside> - - -<h3 id="gco-id"><span class="section-number">3.1.1.</span> Identification d’instances déjà définies</h3> -<p> -L’élément englobant peut contenir un attribut <code class="OGC">id</code> ou <code class="OGC">uuid</code>. -Si un de ces attributs est présent, l’élément englobé peut être complètement omis; -il sera remplacé au moment de la lecture par l’élément référencé par l’attribut. -Dans l’exemple suivant, la partie gauche définie un élément associé à l’identifiant “<code>mon_id</code>”, -alors que la partie droite référence cet élément: -</p> - -<table class="hidden"> -<tr> -<th>Définir un identifiant</th> -<th>Utiliser l’identifiant défini</th> -</tr> -<tr> -<td> -<pre class="xml" style="margin-top: 6pt"><MD_MetaData> - <identificationInfo> - <MD_DataIdentification id=<i>"<b>mon_id</b>"</i>> - <code class="comment"><!-- insérer ici des propriétés filles --></code> - </MD_DataIdentification> - </identificationInfo> -</MD_MetaData></pre> -</td> -<td> -<pre class="xml" style="margin-top: 6pt"><MD_MetaData> - <identificationInfo xlink:href=<i>"<b>#mon_id</b>"</i>/> -</MD_MetaData></pre> -</td> -</tr> -</table> - -<p> -Le choix de l’attribut à utiliser dépend de la portée de l’élément référencé: -</p> -<ul> -<li> -<code class="OGC">id</code> n’est valide qu’à l’intérieur du document <abbr>XML</abbr> -qui définit l’objet ainsi référencé. -</li> -<li> -<code class="OGC">uuid</code> peut être valide à l’extérieur du document <abbr>XML</abbr>, -mais quelqu’un doit maintenir une base de données fournissant les objets pour chaque UUID donnés. -</li> -<li> -<code>xlink:href</code> peut faire référence à un autre document <abbr>XML</abbr> accessible sur internet. -</li> -</ul> -<p> -Dans la bibliothèque <abbr title="Spatial Information System">SIS</abbr>, tous les objets susceptibles d’être identifiés dans un document <abbr>XML</abbr> -implémentent l’interface <code class="SIS">org.apache.sis.xml.IdentifiedObject</code>. -Chaque instance de cette interface fournit une vue de ses identifiants sous forme de <code>Map<Citation,String></code>, -dans lequel la clé <code class="GeoAPI">Citation</code> identifie le type d’identifiant et la valeur est l’identifiant lui-même. -Quelques constantes représentant différents types d’identifiants sont énumérées dans <code class="SIS">IdentifierSpace</code>, -notamment <code class="SIS">ID</code>, <code class="SIS">UUID</code> et <code class="SIS">HREF</code>. -Chacune de ces clés peut être associée à une valeur d’un type différent (habituellement <code>String</code>, -<code>UUID</code> ou <code>URI</code>) selon la clé. -Par exemple le code suivant définit une valeur pour l’attribut <code class="OGC">uuid</code>: -</p> - -<pre><b>import</b> 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> -Bien que ce mécanisme aie été définit dans le but de mieux supporter les représentations des -attributs <abbr>XML</abbr> du groupe <code class="OGC">gco:ObjectIdentification</code>, -il permet aussi de manière opportuniste de manipuler d’autres types d’identifiants. -Par exemple les attributs <code class="GeoAPI">ISBN</code> et <code class="GeoAPI">ISSN</code> -de <code class="GeoAPI">Citation</code> peuvent être manipulés de cette manière. -Les méthodes de l’interface <code class="SIS">IdentifiedObject</code> fournissent donc un endroit unique -où peuvent être manipulés tous types d’identifiants (pas seulement <abbr>XML</abbr>) associés à un objet. -</p> - - - -<h3 id="nilReason"><span class="section-number">3.1.2.</span> Représentation de valeurs manquantes</h3> -<p> -Lorsqu’une propriété n’est pas définie, la méthode correspondante de GeoAPI retourne généralement <code>null</code>. -Toutefois les choses se compliquent lorsque la propriété manquante est une valeur considérée comme obligatoire par le standard <abbr title="International Organization for Standardization">ISO</abbr> 19115. -Le standard <abbr>ISO</abbr> 19139 autorise l’omission de propriétés obligatoires à la condition d’indiquer pourquoi la valeur est manquante. -Les raisons peuvent être que la propriété ne s’applique pas (<code class="OGC">inapplicable</code>), -que la valeur existe probablement mais n’est pas connue (<code class="OGC">unknown</code>), -que la valeur pourrait ne pas exister (<code class="OGC">missing</code>), -qu’elle ne peut pas être divulguée (<code class="OGC">withheld</code>), <i>etc.</i> -La transmission de cette information nécessite l’utilisation d’un objet non-nul même lorsque la valeur est manquante. -<abbr title="Spatial Information System">SIS</abbr> procède en retournant un objet qui, en plus d’implémenter l’interface GeoAPI attendue, -implémente aussi l’interface <code class="SIS">org.apache.sis.xml.NilObject</code>. -Cette interface marque les instances dont toutes les méthodes retournent une collection vide, -un tableau vide, <code>null</code>, <code>NaN</code>, <code>0</code> ou <code>false</code>, -dans cet ordre de préférence selon ce que les types de retours des méthodes permettent. -Chaque instance implémentant <code class="SIS">NilObject</code> fournit une méthode -<code class="SIS">getNilReason()</code> indiquant pourquoi l’objet est nul. -</p> -<p> -Dans l’exemple suivant, la partie gauche montre un élément <code class="OGC">CI_Citation</code> -contenant un élément <code class="OGC">CI_Series</code>, alors que dans la partie droite la série est inconnue. -Si l’élément <code class="OGC">CI_Series</code> avait été complètement omis, -alors la méthode <code class="GeoAPI">Citation.getSeries()</code> retournerait <code>null</code> en Java. -Mais en présence d’un attribut <code class="OGC">nilReason</code>, l’implémentation <abbr>SIS</abbr> -de <code class="SIS">getSeries()</code> retournera plutôt un objet implémentant à la fois les interfaces -<code class="GeoAPI">Series</code> et <code class="SIS">NilReason</code>, -et dont la méthode <code class="SIS">getNilReason()</code> retournera la constante <code class="SIS">UNKNOWN</code>. -</p> - -<table class="hidden"> -<tr> -<th>Information présente</th> -<th>Information absente</th> -</tr> -<tr> -<td> -<pre class="xml" style="margin-top: 6pt"><CI_Citation> - <series> - <CI_Series> - <code class="comment"><!-- insérer ici des propriétés filles --></code> - </CI_Series> - </series> -</CI_Citation></pre> -</td> -<td> -<pre 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> Classes et méthodes utilitaires</h1> -<nav><div class="chapter-links"><div class="previous-chapter">⬅ <a href="#XML-ISO">Chapitre précédent</a></div><div class="next-chapter"><a href="#Referencing">Chapitre suivant</a> ➡</div></div></nav> -</header> -<nav>Dans ce chapitre:<ul class="toc"> -<li><a href="#ComparisonMode">Modes de comparaisons des objets</a></li> -<li><a href="#Internationalization">Internationalisation</a><ul> -<li><a href="#LocalizedString">Chaînes de caractères distinctes pour chaque conventions locales</a></li> -<li><a href="#InternationalString">Instance unique pour toutes les conventions locales</a></li> -<li><a href="#Locale.ROOT">Convention Locale.ROOT</a></li> -<li><a href="#UnicodePoint">Traitement des caractères</a><ul> -<li><a href="#Whitespaces">Interprétation des espaces blancs</a></li></ul></li></ul></li></ul></nav> -<p> -Ce chapitre décrit des aspects de Apache <abbr title="Spatial Information System">SIS</abbr> qui s’appliquent à l’ensemble de la bibliothèque. -La plupart de ces utilitaires ne sont pas spécifiques aux systèmes d’information spatiales. -</p> - -<h2 id="ComparisonMode"><span class="section-number">4.1.</span> Modes de comparaisons des objets</h2> -<p>
[... 584 lines stripped ...]
