Modified: sis/site/trunk/book/fr/geoapi.html URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/geoapi.html?rev=1745551&r1=1745550&r2=1745551&view=diff ============================================================================== --- sis/site/trunk/book/fr/geoapi.html (original) +++ sis/site/trunk/book/fr/geoapi.html Thu May 26 00:52:22 2016 @@ -60,157 +60,57 @@ </p></li> </ul> - <article> - <header> - <h1>Historique du projet GeoAPI</h1> - </header> - <p> - En 2001, le consortium <i>Open GIS</i> (lâancien nom du consortium <i>Open Geospatial</i>) publia la spécification dâimplémentation - <a href="http://www.opengeospatial.org/standards/ct";><abbr>OGC</abbr> 01-009: <cite>Coordinate Transformation Services</cite></a>. - Cette spécification, élaborée par <i>Computer Aided Development Corporation</i> (Cadcorp), - était accompagnée dâinterfaces <abbr>COM</abbr>, <abbr>CORBA</abbr> et Java. - à cette époque, la vague des services web nâavait pas encore éclipsé les interfaces de programmation classiques. - Les interfaces de lâ<abbr>OGC</abbr> anticipaient tout de même un monde connecté en réseau, - mais misaient plutôt â dans le cas du Java â sur la technologie <abbr>RMI</abbr> (<i>Remote Method Invocation</i>). - Bien que le projet GeoAPI nâexistait pas encore, nous désignons rétrospectivement ces interfaces historiques sous le nom de - « <a href="http://www.geoapi.org/0.1/index.html";>GeoAPI 0.1</a> ». - Ces interfaces utilisaient déjà le nom de paquet <code>org.opengis</code>, qui sera adopté par GeoAPI. - </p><p> - En 2002, des développeurs de projets libres ont lancé un - <a href="http://web.archive.org/web/20030509104308/http://digitalearth.org/story/2002/10/10/55046/206";>appel à la création dâun <abbr>API</abbr> géo-spatial</a>. - La proposition initiale suscita lâintérêt dâau moins cinq projets libres. - Le projet fut créé sur <a href="http://sourceforge.net/projects/geoapi/";>SourceForge</a>, - qui héberge depuis lors le code source dans un <a href="http://www.geoapi.org/source-repository.html";>dépôt Subversion</a>. - Le projet pris le nom de « GeoAPI » à ce moment là , et utilisa les interfaces de la spécification <abbr>OGC</abbr> 01-009 comme point de départ. - </p><p> - Quelques mois plus tard, lâ<abbr>OGC</abbr> lança le projet - <a href="http://www.opengeospatial.org/standards/go";><abbr>GO-1</abbr>: <i>Geographic Objects</i></a>, - qui poursuivait des buts similaires à ceux de GeoAPI. - Entre-temps, lâ<abbr>OGC</abbr> avait abandonné certaines de leur spécifications en faveur des normes <abbr>ISO</abbr>. - GeoAPI et <abbr>GO-1</abbr> ont joint leurs efforts pour une refonte des interfaces de GeoAPI en les basant sur ces nouvelles normes <abbr>ISO</abbr>. - La première mouture, <a href="http://www.geoapi.org/1.0/index.html";>GeoAPI 1.0</a>, a servit de point de départ - aux premières ébauches de la spécification <abbr>OGC</abbr> 03-064 du groupe de travail <abbr>GO</abbr>-1. - La version finale de cette spécification est devenue un standard <abbr>OGC</abbr> en 2005, et - <a href="http://www.geoapi.org/2.0/index.html";>GeoAPI 2.0</a> a été publiée à cette occasion. - </p><p> - Le projet <abbr>GO</abbr>-1 était porté essentiellement par une compagnie nommée <i>Polexis</i>. - Son rachat par <i>Sys Technology</i> et le changement de priorité des nouveaux propriétaires - ont causé lâarrêt des travaux de <abbr>GO</abbr>-1, et par ricochet un ralentissement des développements de GeoAPI. - Afin de reprendre les développements, un nouveau groupe de travail « GeoAPI 3.0 » a été créé à lâ<abbr>OGC</abbr>. - Ce groupe a réduit les ambitions par rapport à GeoAPI 2.0 en se concentrant sur les interfaces les plus stables, - et en plaçant les autres â notamment les géométries â dans un module nommé « <a href="http://www.geoapi.org/geoapi-pending/index.html";>pending</a> », - pour considérations futures. <a href="http://www.geoapi.org/3.0/index.html";>GeoAPI 3.0</a> est devenu un - <a href="http://www.opengeospatial.org/standards/geoapi";>standard <abbr>OGC</abbr></a> en 2011. - Cette version a été la première à être déployée dans le <a href="http://search.maven.org/#search|ga|1|geoapi">dépôt central de Maven</a>. - </p> - </article> - - - <h2 id="SpecificationToInterfaces">Des spécifications aux interfaces</h2> - <p> - Les standards de lâ<abbr>OGC</abbr> étant définis par des moyens bien éprouvés en génie logiciel, - il est possible de générer automatiquement des interfaces Java à lâaide dâoutils relativement répandus. - Une des approches les plus utilisées est de transformer les <a href="http://schemas.opengis.net/gml/3.3/";>schémas <abbr>XSD</abbr></a> - en interfaces Java à lâaide de lâutilitaire en ligne de commande <code>xjc</code>. - Cet utilitaire étant fournit avec la plupart des distributions du Java (il fait partie des outils de <a href="http://jaxb.java.net";><abbr>JAXB</abbr></a>), - cette approche est choisie par plusieurs projets que lâon trouve sur internet. - Dâautres approches utilisent des outils intégrés à lâenvironnement de développement Eclipse, - ou prennent comme point de départ les schémas <abbr>UML</abbr> plutôt que <abbr>XSD</abbr>. - </p><p> - Une approche similaire avait été tentée dans les débuts du projet GeoAPI, mais a été rapidement abandonnée. - Nous avons privilégié une approche manuelle pour les raisons suivantes: - </p> - <ul> - <li> - <p> - Certains schémas <abbr>XSD</abbr> sont beaucoup plus verbeux que les schémas <abbr>UML</abbr> dâorigines. - Une conversion à partir des schémas <abbr>XSD</abbr> introduit, au moins dans le cas des méta-données, - près du double du nombre dâinterfaces réellement définies par le standard, sans que cela nâapporte de nouvelles fonctionnalités. - Les schémas <abbr>XSD</abbr> définissent aussi des attributs propres aux documents <abbr>XML</abbr> - (<code class="OGC">id</code>, <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), - qui nâexistent pas dans les diagrammes <abbr>UML</abbr> originaux et que lâon ne souhaite pas forcément exposer dans un <abbr>API</abbr> Java. - Une conversion à partir des schémas <abbr>UML</abbr> évite ce problème, mais les outils capable dâeffectuer cette opération sont plus rares. - </p> - <div class="example"><p><b>Exemple:</b> - Les schémas <abbr>XSD</abbr> des méta-données insèrent - un élément <code><gmd:CI_Citation></code> à lâintérieur de <code><gmd:citation></code>, - un élément <code><gmd:CI_OnlineResource></code> à lâintérieur de <code><gmd:onlineResource></code>, - et ainsi de suite pour la centaine de classes définies dans le standard <abbr>ISO</abbr> 19115. - Cette redondance nâest absolument pas nécessaire à un programme Java. - </p></div> - </li> - <li> - <p> - Les standards de lâ<abbr>OGC</abbr> utilisent des conventions de nommage qui sont différentes de celles du Java. - En particulier les noms de presque toutes les classes de lâ<abbr>OGC</abbr> commencent par un préfixe de deux lettres, - comme dans <code>MD_Identifier</code>. Ces préfixes jouent le même rôle que les noms de paquets en Java. - GeoAPI adapte cette pratique en utilisant des noms dâinterfaces sans préfixes, - et en plaçant ces interfaces dans des paquets correspondants aux préfixes mais avec des noms plus descriptifs. - Occasionnellement nous changeons aussi les noms, par exemple pour éviter des acronymes - ou pour se conformer à une convention établie telle que <i>Java beans</i>. - </p> - <div class="example"><p><b>Exemple:</b> - la classe <code>MD_Identifier</code> de lâ<abbr>OGC</abbr> devient - lâinterface <code>Identifier</code> dans le paquet <code>org.opengis.metadata</code>. - La classe <code>SC_CRS</code> de lâ<abbr>OGC</abbr> devient lâinterface <code>CoordinateReferenceSystem</code>, - et lâassociation <code class="OGC">usesDatum</code> devient une méthode <code class="GeoAPI">getDatum()</code> â et non pas - « <code>getUsesDatum()</code> » comme aurait fait un outil de conversion automatique. - Nous ne laissons pas des programmes appliquer aveuglement des règles qui ignorent les conventions de la communauté dont on traduit les schémas. - </p></div> - </li> - <li> + <details> + <summary>Pour en savoir plus sur les origines du projet GeoAPI</summary> + <article> + <header> + <h1>Historique du projet GeoAPI</h1> + </header> <p> - Les standards contiennent parfois des structures qui nâont pas dâéquivalent direct en Java, - notamment les unions telles quâon peut trouver en C/C++. - La stratégie employée pour obtenir une fonctionnalité équivalente en Java dépend du contexte: - multi-héritage des interfaces, modification de la hiérarchie ou simplement omettre lâunion. - Les décisions se font au cas-par-cas en fonction de lâanalyse des besoins. + En 2001, le consortium <i>Open GIS</i> (lâancien nom du consortium <i>Open Geospatial</i>) publia la spécification dâimplémentation + <a href="http://www.opengeospatial.org/standards/ct";><abbr>OGC</abbr> 01-009: <cite>Coordinate Transformation Services</cite></a>. + Cette spécification, élaborée par <i>Computer Aided Development Corporation</i> (Cadcorp), + était accompagnée dâinterfaces <abbr>COM</abbr>, <abbr>CORBA</abbr> et Java. + à cette époque, la vague des services web nâavait pas encore éclipsé les interfaces de programmation classiques. + Les interfaces de lâ<abbr>OGC</abbr> anticipaient tout de même un monde connecté en réseau, + mais misaient plutôt â dans le cas du Java â sur la technologie <abbr>RMI</abbr> (<i>Remote Method Invocation</i>). + Bien que le projet GeoAPI nâexistait pas encore, nous désignons rétrospectivement ces interfaces historiques sous le nom de + « <a href="http://www.geoapi.org/0.1/index.html";>GeoAPI 0.1</a> ». + Ces interfaces utilisaient déjà le nom de paquet <code>org.opengis</code>, qui sera adopté par GeoAPI. + </p><p> + En 2002, des développeurs de projets libres ont lancé un + <a href="http://web.archive.org/web/20030509104308/http://digitalearth.org/story/2002/10/10/55046/206";>appel à la création dâun <abbr>API</abbr> géo-spatial</a>. + La proposition initiale suscita lâintérêt dâau moins cinq projets libres. + Le projet fut créé sur <a href="http://sourceforge.net/projects/geoapi/";>SourceForge</a>, + qui héberge depuis lors le code source dans un <a href="http://www.geoapi.org/source-repository.html";>dépôt Subversion</a>. + Le projet pris le nom de « GeoAPI » à ce moment là , et utilisa les interfaces de la spécification <abbr>OGC</abbr> 01-009 comme point de départ. + </p><p> + Quelques mois plus tard, lâ<abbr>OGC</abbr> lança le projet + <a href="http://www.opengeospatial.org/standards/go";><abbr>GO-1</abbr>: <i>Geographic Objects</i></a>, + qui poursuivait des buts similaires à ceux de GeoAPI. + Entre-temps, lâ<abbr>OGC</abbr> avait abandonné certaines de leur spécifications en faveur des normes <abbr>ISO</abbr>. + GeoAPI et <abbr>GO-1</abbr> ont joint leurs efforts pour une refonte des interfaces de GeoAPI en les basant sur ces nouvelles normes <abbr>ISO</abbr>. + La première mouture, <a href="http://www.geoapi.org/1.0/index.html";>GeoAPI 1.0</a>, a servit de point de départ + aux premières ébauches de la spécification <abbr>OGC</abbr> 03-064 du groupe de travail <abbr>GO</abbr>-1. + La version finale de cette spécification est devenue un standard <abbr>OGC</abbr> en 2005, et + <a href="http://www.geoapi.org/2.0/index.html";>GeoAPI 2.0</a> a été publiée à cette occasion. + </p><p> + Le projet <abbr>GO</abbr>-1 était porté essentiellement par une compagnie nommée <i>Polexis</i>. + Son rachat par <i>Sys Technology</i> et le changement de priorité des nouveaux propriétaires + ont causé lâarrêt des travaux de <abbr>GO</abbr>-1, et par ricochet un ralentissement des développements de GeoAPI. + Afin de reprendre les développements, un nouveau groupe de travail « GeoAPI 3.0 » a été créé à lâ<abbr>OGC</abbr>. + Ce groupe a réduit les ambitions par rapport à GeoAPI 2.0 en se concentrant sur les interfaces les plus stables, + et en plaçant les autres â notamment les géométries â dans un module nommé « <a href="http://www.geoapi.org/geoapi-pending/index.html";>pending</a> », + pour considérations futures. <a href="http://www.geoapi.org/3.0/index.html";>GeoAPI 3.0</a> est devenu un + <a href="http://www.opengeospatial.org/standards/geoapi";>standard <abbr>OGC</abbr></a> en 2011. + Cette version a été la première à être déployée dans le <a href="http://search.maven.org/#search|ga|1|geoapi">dépôt central de Maven</a>. </p> - <div class="example"><p><b>Exemple:</b> - Le standard <abbr>ISO</abbr> 19111 définit différents types de systèmes de coordonnées, tels que sphérique, cylindrique, polaire ou cartésien. - Puis, il définit différents <em>sous-ensembles</em> de ces types de systèmes de coordonnées. - Ces sous-ensembles, représentés par des unions, servent à spécifier quâune classe peut être associée à seulement tel ou tel type de système de coordonnées. - Par exemple lâunion des types pouvant être associés à une image, nommée <code>CS_ImageCS</code>, - ne contient que <code>CS_CartesianCS</code> et <code>CS_AffineCS</code>. - Dans ce cas particulier, nous obtenons en Java lâeffet souhaité par une modification de la hiérarchie des classes: - nous définissons lâinterface <code>CartesianCS</code> comme une spécialisation de <code>AffineCS</code>, ce qui est sémantiquement correct. - Mais il nâest pas possible dâappliquer une stratégie similaire pour les autres unions sans violer la sémantique. - </p></div> - </li> - <li> - <p> - Plusieurs spécifications se chevauchent. GeoAPI effectue un travail dâintégration en remplaçant certaines - structures qui font doublons par des références vers les structures équivalentes du standard qui les définies le mieux. - </p> - <div class="example"><p><b>Exemple:</b> - Le standard <abbr>ISO</abbr> 19115, qui définit des structures de méta-données, sâaventure aussi à décrire quelques - structures représentant les systèmes de références des coordonnées (<abbr title="Coordinate Reference System">CRS</abbr>). - Or ces derniers sont le sujet à part entière dâun autre standard: <abbr>ISO</abbr> 19111. - Dâailleurs le standard <abbr>ISO</abbr> 19111:2007 stipule, dans sa section 3, quâil réutilise tous les éléments - de <abbr>ISO</abbr> 19115 à lâexclusion de <code>MD_CRS</code> et de ses composantes. - Les interfaces de GeoAPI réduisent la redondance en appliquant à lâensemble du projet lâexclusion recommandée par <abbr>ISO</abbr> 19111. - </p></div> - </li> - <li> - <p> - Certains standards ont vu leur complexité sâaccroître pour des raisons historiques plutôt que techniques, - liées au processus de standardisation. GeoAPI réduit la dette technique en concevant les interfaces comme - si chaque élément avait pu être intégré à sa place, sans les contraintes liées à lâordre chronologique - dans lequel les standards ont été publiés. - </p> - <div class="example"><p><b>Exemple:</b> - Le standard <abbr>ISO</abbr> 19115-2 est une extension du standard <abbr>ISO</abbr> 19115-1 ajoutant des structures de méta-données dâimages. - Ces méta-données ont été définies dans un standard séparé parce quâelles nâont pas été prêtes à temps pour la publication de la première partie du standard. - Comme il nâétait pas possible, pour des raisons administratives, dâajouter des attributs dans les classes déjà publiées, - les nouveaux attributs ont été ajoutées dans une sous-classe portant quasiment le même nom. - Ainsi, le standard <abbr>ISO</abbr> 19115-2 définit une classe <code>MI_Band</code> qui étend la - classe <code>MD_Band</code> du standard <abbr>ISO</abbr> 19115-1 en y ajoutant les attributs qui - auraient dû apparaître directement dans la classe parente sâils avaient été prêts à temps. - Dans GeoAPI, nous avons choisis de « réparer » ces anomalies en fusionnant ces deux classes en une seule interface. - </p></div> - </li> - </ul> - <p> + </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>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. @@ -219,9 +119,197 @@ et des fichiers de propriétés, décrits dans la section suivante. </p> + <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>OGC</abbr> aux interfaces Java</h1> + </header> + <p> + 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>XSD</abbr></a> + en interfaces Java à lâaide de lâutilitaire en ligne de commande <code>xjc</code>. + Cet utilitaire étant fournit avec la plupart des distributions du Java (il fait partie des outils de <a href="http://jaxb.java.net";><abbr>JAXB</abbr></a>), + cette approche est choisie par plusieurs projets que lâon trouve sur internet. + Dâautres approches utilisent des outils intégrés à lâenvironnement de développement Eclipse, + ou prennent comme point de départ les schémas <abbr>UML</abbr> plutôt que <abbr>XSD</abbr>. + </p><p> + Une approche similaire avait été tentée dans les débuts du projet GeoAPI, mais a été rapidement abandonnée. + Nous avons privilégié une approche manuelle pour les raisons suivantes: + </p> + <ul> + <li> + <p> + Certains schémas <abbr>XSD</abbr> sont beaucoup plus verbeux que les schémas <abbr>UML</abbr> dâorigines. + Une conversion à partir des schémas <abbr>XSD</abbr> introduit, au moins dans le cas des méta-données, + près du double du nombre dâinterfaces réellement définies par le standard, sans que cela nâapporte de nouvelles fonctionnalités. + Les schémas <abbr>XSD</abbr> définissent aussi des attributs propres aux documents <abbr>XML</abbr> + (<code class="OGC">id</code>, <code class="OGC">uuid</code>, <code>xlink:href</code>, <i>etc.</i>), + qui nâexistent pas dans les diagrammes <abbr>UML</abbr> originaux et que lâon ne souhaite pas forcément exposer dans un <abbr>API</abbr> Java. + Une conversion à partir des schémas <abbr>UML</abbr> évite ce problème, mais les outils capable dâeffectuer cette opération sont plus rares. + </p> + <div class="example"><p><b>Exemple:</b> + Les schémas <abbr>XSD</abbr> des méta-données insèrent + un élément <code><gmd:CI_Citation></code> à lâintérieur de <code><gmd:citation></code>, + un élément <code><gmd:CI_OnlineResource></code> à lâintérieur de <code><gmd:onlineResource></code>, + et ainsi de suite pour la centaine de classes définies dans le standard <abbr>ISO</abbr> 19115. + Cette redondance nâest absolument pas nécessaire à un programme Java. + </p></div> + </li> + <li> + <p> + Les standards de lâ<abbr>OGC</abbr> utilisent des conventions de nommage qui sont différentes de celles du Java. + En particulier les noms de presque toutes les classes de lâ<abbr>OGC</abbr> commencent par un préfixe de deux lettres, + comme dans <code>MD_Identifier</code>. Ces préfixes jouent le même rôle que les noms de paquets en Java. + GeoAPI adapte cette pratique en utilisant des noms dâinterfaces sans préfixes, + et en plaçant ces interfaces dans des paquets correspondants aux préfixes mais avec des noms plus descriptifs. + Occasionnellement nous changeons aussi les noms, par exemple pour éviter des acronymes + ou pour se conformer à une convention établie telle que <i>Java beans</i>. + </p> + <div class="example"><p><b>Exemple:</b> + la classe <code>MD_Identifier</code> de lâ<abbr>OGC</abbr> devient + lâinterface <code>Identifier</code> dans le paquet <code>org.opengis.metadata</code>. + La classe <code>SC_CRS</code> de lâ<abbr>OGC</abbr> devient lâinterface <code>CoordinateReferenceSystem</code>, + et lâassociation <code class="OGC">usesDatum</code> devient une méthode <code class="GeoAPI">getDatum()</code> â et non pas + « <code>getUsesDatum()</code> » comme aurait fait un outil de conversion automatique. + Nous ne laissons pas des programmes appliquer aveuglement des règles qui ignorent les conventions de la communauté dont on traduit les schémas. + </p></div> + </li> + <li> + <p> + Les standards contiennent parfois des structures qui nâont pas dâéquivalent direct en Java, + notamment les unions telles quâon peut trouver en C/C++. + La stratégie employée pour obtenir une fonctionnalité équivalente en Java dépend du contexte: + multi-héritage des interfaces, modification de la hiérarchie ou simplement omettre lâunion. + Les décisions se font au cas-par-cas en fonction de lâanalyse des besoins. + </p> + <div class="example"><p><b>Exemple:</b> + Le standard <abbr>ISO</abbr> 19111 définit différents types de systèmes de coordonnées, tels que sphérique, cylindrique, polaire ou cartésien. + Puis, il définit différents <em>sous-ensembles</em> de ces types de systèmes de coordonnées. + Ces sous-ensembles, représentés par des unions, servent à spécifier quâune classe peut être associée à seulement tel ou tel type de système de coordonnées. + Par exemple lâunion des types pouvant être associés à une image, nommée <code>CS_ImageCS</code>, + ne contient que <code>CS_CartesianCS</code> et <code>CS_AffineCS</code>. + Dans ce cas particulier, nous obtenons en Java lâeffet souhaité par une modification de la hiérarchie des classes: + nous définissons lâinterface <code>CartesianCS</code> comme une spécialisation de <code>AffineCS</code>, ce qui est sémantiquement correct. + Mais il nâest pas possible dâappliquer une stratégie similaire pour les autres unions sans violer la sémantique. + </p></div> + </li> + <li> + <p> + Plusieurs spécifications se chevauchent. GeoAPI effectue un travail dâintégration en remplaçant certaines + structures qui font doublons par des références vers les structures équivalentes du standard qui les définies le mieux. + </p> + <div class="example"><p><b>Exemple:</b> + Le standard <abbr>ISO</abbr> 19115, qui définit des structures de méta-données, sâaventure aussi à décrire quelques + structures représentant les systèmes de références des coordonnées (<abbr title="Coordinate Reference System">CRS</abbr>). + Or ces derniers sont le sujet à part entière dâun autre standard: <abbr>ISO</abbr> 19111. + Dâailleurs le standard <abbr>ISO</abbr> 19111:2007 stipule, dans sa section 3, quâil réutilise tous les éléments + de <abbr>ISO</abbr> 19115 à lâexclusion de <code>MD_CRS</code> et de ses composantes. + Les interfaces de GeoAPI réduisent la redondance en appliquant à lâensemble du projet lâexclusion recommandée par <abbr>ISO</abbr> 19111. + </p></div> + </li> + <li> + <p> + Certains standards ont vu leur complexité sâaccroître pour des raisons historiques plutôt que techniques, + liées au processus de standardisation. GeoAPI réduit la dette technique en concevant les interfaces comme + si chaque élément avait pu être intégré à sa place, sans les contraintes liées à lâordre chronologique + dans lequel les standards ont été publiés. + </p> + <div class="example"><p><b>Exemple:</b> + Le standard <abbr>ISO</abbr> 19115-2 est une extension du standard <abbr>ISO</abbr> 19115-1 ajoutant des structures de méta-données dâimages. + Ces méta-données ont été définies dans un standard séparé parce quâelles nâont pas été prêtes à temps pour la publication de la première partie du standard. + Comme il nâétait pas possible, pour des raisons administratives, dâajouter des attributs dans les classes déjà publiées, + les nouveaux attributs ont été ajoutées dans une sous-classe portant quasiment le même nom. + Ainsi, le standard <abbr>ISO</abbr> 19115-2 définit une classe <code>MI_Band</code> qui étend la + classe <code>MD_Band</code> du standard <abbr>ISO</abbr> 19115-1 en y ajoutant les attributs qui + auraient dû apparaître directement dans la classe parente sâils avaient été prêts à temps. + Dans GeoAPI, nous avons choisis de « réparer » ces anomalies en fusionnant ces deux classes en une seule interface. + </p></div> + </li> + </ul> + </article> + </details> + + <p id="GeoAPI-core"> + GeoAPI est constitué de plusieurs modules. + Les modules <code>geoapi</code> et <code>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>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> + Le projet GeoAPI est composé dâune partie standardisée (<code>geoapi</code>) et + dâune partie expérimentale (<code>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>SIS</abbr>), + car le module <code>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>geoapi-pending</code>. + </p><p> + Les modules de GeoAPI sont: + </p> + <ul> + <li><p> + <b><code>geoapi</code></b> â contient les interfaces couvertes par le + <a href="http://www.opengeospatial.org/standards/geoapi";>standard GeoAPI de lâ<abbr>OGC</abbr></a>. + Les versions finales de Apache <abbr>SIS</abbr> dépendent de ce module. + </p></li> + <li><p> + <b><code>geoapi-pending</code></b> â contient une + <em>copie</em> de toutes les interfaces du module <code>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>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>geoapi</code> + standard au moment de fusionner les branches avec le tronc. + </p></li> + <li><p> + <b><code>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>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>geoapi-proj4</code></b> â contient une + implémentation partielle des paquets <code>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>sis-referencing</code> + pour certaines fonctions. + </p></li> + <li><p> + <b><code>geoapi-netcdf</code></b> â contient une implémentation partielle des paquets + <code>org.opengis.referencing</code> et <code>org.opengis.coverage</code> + sous forme dâadaptateurs basés sur la bibliothèque <abbr>NetCDF</abbr> de lâ<abbr>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>sis-netcdf</code>. + </p></li> + <li><p> + <b><code>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">Correspondances explicitées par lâannotation <code>@UML</code></h3> + <h2 id="UML-annotation">Correspondances entre GeoAPI et les spécifications abstraites</h2> <p> Pour chaque classe, méthode et constante définie à partir dâun standard <abbr>OGC</abbr> ou <abbr>ISO</abbr>, GeoAPI indique sa provenance à lâaide dâannotations définies dans le paquet <code>org.opengis.annotation</code>. @@ -242,61 +330,35 @@ /** * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface. */ -@UML(specification = ISO_19111, - identifier = "<code class="OGC">SC_ProjectedCRS</code>") +@UML(specification=ISO_19111, identifier="<code class="OGC">SC_ProjectedCRS</code>") public interface ProjectedCRS extends GeneralDerivedCRS { /** * Returns the coordinate system, which must be Cartesian. */ - @UML(obligation = MANDATORY, - specification = ISO_19111, - identifier = "<code class="OGC">coordinateSystem</code>") + @UML(obligation=MANDATORY, specification=ISO_19111, identifier="<code class="OGC">coordinateSystem</code>") CartesianCS <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>Citation</code>: - </p> - -<pre>Class<?> type = Citation.class; -Method method = type.getMethod("<code class="GeoAPI">getTitle</code>", (Class<?>[]) null); -UML annot = method.getAnnotation(UML.class); -String id = annot.identifier(); -System.out.println("Le nom standard de la méthode " + method.getName() + " est " + id);</pre> - - <p> - La classe <code>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>org.opengis.annotation</code>. Lâexemple suivant lit ce fichier juste avant - de rechercher le nom de lâinterface correspondant à <code>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>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>org.opengis.referencing.crs.ProjectedCRS</code> est <code>SC_ProjectedCRS</code> »: </p> -<pre>Properties isoToGeoAPI = new Properties(); -try (InputStream in = UML.class.getResourceAsStream("<code class="GeoAPI">class-index.properties</code>")) { - isoToGeoAPI.load(in); -} -String isoName = "<code class="OGC">CI_Citation</code>"; -String geoName = getProperty(isoName); -Class<?> type = Class.forName(geoName); -System.out.println("Lâinterface GeoAPI pour le type <abbr>ISO</abbr> " + isoName + " est " + type);</pre> +<pre>Class<?> type = ProjectedCRS.class; +System.out.println("Le nom standard du type " + type.getName() + " est " + Types.getStandardName(type));</pre> <p> - La classe <code>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">Correspondances implicites avec le <abbr>JDK</abbr> standard</h3> <p> Certaines classes et méthodes nâont ni annotation <code>@UML</code>, @@ -484,369 +546,50 @@ assert MediumName.<code class="GeoAPI">v - <h2 id="ServiceLoader">Obtenir une implémentation des interfaces</h2> - <p> - GeoAPI définit des fabriques (<code>Factory</code>) permettant de créer des implémentations de ses interfaces. - Par exemple <code>DatumFactory</code> fournit des méthodes permettant de créer des instances - implémentant les interfaces du paquet <code>org.opengis.referencing.datum</code>. - Ces <code>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>org.opengis.referencing.datum.DatumFactory</code> dans lâexemple précédent). - Ce fichier texte doit contenir sur une ligne le nom complet de la classe implémentant cette interface. - Il peut sâagir dâune classe cachée aux yeux des utilisateurs, car ils nâont pas besoin de connaître son existence. - </p> - <p> - Si la bibliothèque a bien déclaré ses fabriques comme des services, alors - les utilisateurs peuvent les obtenir en utilisant <code>ServiceLoader</code> comme dans lâexemple ci-dessous. - Cet exemple ne prend que la première fabrique trouvée; sâil existe plusieurs fabriques, - par exemple lorsque plusieurs bibliothèques cohabitent, alors le choix est laissé à lâutilisateur. - </p> - -<pre>import org.opengis.referencing.GeodeticDatum; -import org.opengis.referencing.DatumFactory; -import java.util.ServiceLoader; - -public class MyApplication { - public void createMyDatum() { - ServiceLoader loader = ServiceLoader.load(DatumFactory.class); - DatumFactory factory = loader.iterator().next(); - GeodeticDatum myDatum = factory.<code class="GeoAPI">createGeodeticDatum</code>(â¦); - } -}</pre> - - - - <h3 id="GeoAPI-simple">Fournir sa propre implémentation</h3> - <p> - Implémenter soi-même GeoAPI nâest pas si difficile si on se contente de besoins bien précis. - Un développeur peut se concentrer sur une poignée dâinterfaces parmi les centaines de disponibles, - tout en disposant des autres interfaces comme autant de points dâextensions à éventuellement implémenter - au gré des besoins. - </p> - <p> - Le modèle conceptuel représenté par les interfaces est complexe. Mais cette complexité peut être réduite en combinant certaines interfaces. - Par exemple plusieurs bibliothèques, même réputées, ne font pas la distinction entre <cite>Système de coordonnées</cite> (<abbr>CS</abbr>) - et <cite>Système de <u>référence</u> des coordonnées</cite> (<abbr>CRS</abbr>). - Un développeur qui lui non-plus ne souhaite pas faire cette distinction peut implémenter ces deux interfaces par la même classe. - Il peut en résulter une implémentation dont la hiérarchie de classes est plus simple que la hiérarchie des interfaces de GeoAPI. - Le module <code>geoapi-examples</code>, discuté plus loin, fournit de telles combinaisons. - Le tableau suivant énumère quelques combinaisons possibles: - </p> - <table> - <tr> - <th>Interface principale</th> - <th>Interface auxiliaire</th> - <th>Usage</th> - </tr> - <tr> - <td><code>CoordinateReferenceSystem</code></td> - <td><code>CoordinateSystem</code></td> - <td>Description dâun système de référence spatial (<abbr>CRS</abbr>).</td> - </tr> - <tr> - <td><code>GeodeticDatum</code></td> - <td><code>Ellipsoid</code></td> - <td>Description dâun référentiel geodétique.</td> - </tr> - <tr> - <td><code>CoordinateOperation</code></td> - <td><code>MathTransform</code></td> - <td>Opération de transformation de coordonnées.</td> - </tr> - <tr> - <td><code>IdentifiedObject</code></td> - <td><code>ReferenceIdentifier</code></td> - <td>Objet (typiquement un <abbr>CRS</abbr>) que lâon peut identifier par un code.</td> - </tr> - <tr> - <td><code>Citation</code></td> - <td><code>InternationalString</code></td> - <td>Référence bibliographique composée dâun simple titre.</td> - </tr> - <tr> - <td><code>GeographicBoundingBox</code></td> - <td><code>Extent</code></td> - <td>Ãtendue spatiale en degrés de longitude et de latitude.</td> - </tr> - <tr> - <td><code>ParameterValue</code></td> - <td><code>ParameterDescriptor</code></td> - <td>Description dâun paramètre (nom, type) associée à sa valeur.</td> - </tr> - <tr> - <td><code>ParameterValueGroup</code></td> - <td><code>ParameterDescriptorGroup</code></td> - <td>Description dâun ensemble de paramètres associés à leurs valeurs.</td> - </tr> - </table> - - - - <h2 id="GeoAPI-modules">Les modules de GeoAPI</h2> - <p> - Le projet GeoAPI est composé dâune partie standardisée (<code>geoapi</code>) et - dâune partie expérimentale (<code>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>SIS</abbr>), - car le module <code>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>geoapi-pending</code>. - </p> - <p> - Les modules de GeoAPI sont: - </p> - <ul> - <li><p> - <b><code>geoapi</code></b> â contient les interfaces couvertes par le - <a href="http://www.opengeospatial.org/standards/geoapi";>standard GeoAPI de lâ<abbr>OGC</abbr></a>. - Les versions finales de Apache <abbr>SIS</abbr> dépendent de ce module. - </p></li> - <li><p> - <b><code>geoapi-pending</code></b> â contient une - <em>copie</em> de toutes les interfaces du module <code>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>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>geoapi</code> - standard au moment de fusionner les branches avec le tronc. - </p></li> - <li><p> - <b><code>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>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>geoapi-proj4</code></b> â contient une - implémentation partielle des paquets <code>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>sis-referencing</code> - pour certaines fonctions. - </p></li> - <li><p> - <b><code>geoapi-netcdf</code></b> â contient une implémentation partielle des paquets - <code>org.opengis.referencing</code> et <code>org.opengis.coverage</code> - sous forme dâadaptateurs basés sur la bibliothèque <abbr>NetCDF</abbr> de lâ<abbr>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>sis-netcdf</code>. - </p></li> - <li><p> - <b><code>geoapi-openoffice</code></b> â contient - un <i>add-in</i> pour les suites bureautiques Libre/OpenOffice.org. - <!-- - Apache <abbr>SIS</abbr> offre son propre <i>add-in</i> dans le module <code>sis-openoffice</code>, - mais utilise les mêmes noms de fonctions que le module de GeoAPI afin dâassurer une certaine compatibilité. - --> - </p></li> - </ul> - - <h3 id="GeoAPI-core">Les modules de définition des interfaces</h3> - <p> - Les modules <code>geoapi</code> et <code>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>SIS</abbr>. - On peut toutefois avoir un aperçu de son contenu en consultant la page listant les - <a href="http://www.geoapi.org/3.0/javadoc/content.html";>types et méthodes de GeoAPI et les standards dâoù ils proviennent</a>. - </p> - - - - <h3 id="GeoAPI-conformance">Le module de tests de conformité</h3> - <p> - Le module <code>geoapi-conformance</code> fournit des <i>validateurs</i>, une <i>suite de tests</i> JUnit - et des <i>générateurs de rapports</i> sous forme de pages <abbr title="Hypertext Markup Language">HTML</abbr>. - Ce module peut être utilisé avec nâimporte quelle implémentation de GeoAPI. - Pour les développeurs dâune bibliothèque géospatiale, il offre les avantages suivants: - </p> - <ul> - <li>Réduire la fastidieuse tâche dâécriture des tests, en réutilisant des tests existants.</li> - <li>Accroître la confiance en la validité des tests, du fait que <code>geoapi-conformance</code> - a lui-même sa propre suite de tests et est appliqué à dâautres implémentations.</li> - <li>Faciliter la comparaison avec les autres implémentations.</li> - </ul> - - - - <h4 id="GeoAPI-validators">Validations des instances</h4> - <p> - GeoAPI peut valider une instance de ses interfaces en vérifiant que certaines contraintes sont respectées. - Certaines contraintes ne peuvent pas être exprimées dans la signature de la méthode. Ces contraintes sont - généralement décrites textuellement dans les spécifications abstraites ou dans la javadoc. - </p> - <div class="example"><p><b>Exemple:</b> - La conversion ou transformation dâune coordonnée (<code>CC_CoordinateOperation</code>) peut nécessiter lâenchaînement de plusieurs étapes. - Dans une telle chaîne dâopérations (<code>CC_ConcatenatedOperation</code>), - pour chaque étape (<code>CC_SingleOperation</code>) le nombre de dimensions - en sortie doit être égal au nombre de dimensions attendu en entré par lâopération suivante. - Exprimée en langage Java, cette contrainte stipule que pour tout index - 0 < <var>i</var> < <var>n</var> où <var>n</var> est le nombre dâopérations, on a - <code>coordOperation[i].targetDimensions == coordOperation[i-1].sourceDimensions</code>. - </p></div> - - <p> - La façon la plus simple dâeffectuer ces vérifications est dâappeler les méthodes statiques - <code class="GeoAPI">validate(â¦)</code> de la classe <code>org.opengis.test.Validators</code>. - Ces méthodes portant toutes le même nom, il suffit dâécrire â<code>validate(<var>valeur</var>)</code>â - et de laisser le compilateur choisir la méthode la plus appropriée en fonction du type dâobjet donné en argument. - Si le type dâobjet nâest pas connu au moment de la compilation, alors la méthode <code class="GeoAPI">dispatch(Object)</code> - peut se charger de rediriger le travail à la méthode <code class="GeoAPI">validate(â¦)</code> appropriée. - </p> - <p> - Toutes les fonctions <code class="GeoAPI">validate(â¦)</code> suivent le fil des dépendances, - câest-à -dire quâelles valideront aussi chaque composantes de lâobjet à valider. - Par exemple la validation dâun objet <code>GeographicCRS</code> impliquera - la validation de sa composante <code>GeodeticDatum</code>, qui impliquera elle-même - la validation de sa composante <code>Ellipsoid</code>, et ainsi de suite. - Il est donc inutile de valider soi-même les composantes, à moins de vouloir isoler le test dâun élément souvent problématique. - </p> - <p> - Par défaut, les validations sont aussi strictes que possible. Il est possible toutefois dâassouplir certaines règles. - Lâassouplissement le plus fréquent consiste à tolérer lâabsence dâattributs qui étaient sensés être obligatoires. - Cette règle et quelques autres peuvent être modifiées globalement pour tous les tests exécutés dans la - <abbr title="Java Virtual Machine">JVM</abbr> courante comme dans lâexemple suivant: - </p> - -<pre>import org.opengis.metadata.Metadata; -import org.opengis.test.Validators; -import org.junit.Test; - -public class MyTest { - /* - * 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. - */ - static { - Validators.<code class="GeoAPI">DEFAULT.metadata.requireMandatoryAttributes</code> = false; - Validators.<code class="GeoAPI">DEFAULT.citation.requireMandatoryAttributes</code> = false; - } - - @Test - public void testMyMetadata() { - Metadata myObject = â¦; // Construisez un objet ici. - Validators.<code class="GeoAPI">validate</code>(myObject); - } -}</pre> - - <p> - Les règles peuvent aussi être modifiées pour une suite de tests particulière, - sans affecter la configuration par défaut de la <abbr>JVM</abbr> courante. - Cette approche nécessite de créer une nouvelle instance du validateur dont on souhaite modifier la configuration. - </p> - -<pre>import org.opengis.metadata.Metadata; -import org.opengis.test.ValidatorContainer; -import org.junit.Test; - -public class MyTest { - private final ValidatorContainer validators; - - public MyTest() { - validators = new ValidatorContainer(); - validators.<code class="GeoAPI">metadata.requireMandatoryAttributes</code> = false; - validators.<code class="GeoAPI">citation.requireMandatoryAttributes</code> = false; - } - - @Test - public void testMyMetadata() { - Metadata myObject = â¦; // Construisez un objet ici. - validators.<code class="GeoAPI">validate</code>(myObject); - } -}</pre> - - - - <h4 id="GeoAPI-tests">Exécution des tests pré-définis</h4> - <p> - Des classes de tests JUnit sont définies dans des sous-paquets de <code>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>org.opengis.test.TestSuite</code> englobant lâensemble - des tests définis dans le module <code>geoapi-conformance</code>, mais Apache <abbr>SIS</abbr> ne lâutilise pas. - Apache <abbr>SIS</abbr> hérite plutôt des classes <code class="GeoAPI">*Test</code> de GeoAPI au cas-par-cas, dans les modules appropriés. - Lâexemple ci-dessous donne un exemple de test de GeoAPI personnalisé. - La <a href="http://www.geoapi.org/geoapi-conformance/apidocs/org/opengis/test/referencing/ParameterizedTransformTest.html";>Javadoc - de la classe parente</a> documente en détails les tests effectués. - Dans cet exemple, un seul test est modifié et tous les autres tests sont hérités tels quels - (il nâest pas nécessaire de les répéter dans la sous-classe). - Toutefois, cet exemple ajoute une vérification supplémentaire, annotée <code>@After</code>, - qui sera exécutée après chacun des tests. - </p> - -<pre>import org.junit.*; -import org.junit.runner.RunWith; -import org.junit.runners.JUnit4; -import org.opengis.test.referencing.ParameterizedTransformTest; -import static org.junit.Assert.*; - -@RunWith(JUnit4.class) -public class MyTest extends ParameterizedTransformTest { - /** - * Spécifie aux tests de GeoAPI notre propre fabrique de transformations de coordonnées. - * GeoAPI testera les objets construits par cette fabrique. - */ - public MyTest() { - super(new MyMathTransformFactory()); - } - - /** - * 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. - */ - @Test - @Override - public void testLambertAzimuthalEqualArea() throws FactoryException, TransformException { - <code class="GeoAPI">tolerance</code> = 0.1; // Tolérance de 10 cm. - super.<code class="GeoAPI">testLambertAzimuthalEqualArea()</code>; - } - - /** - * 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. - */ - @After - public void ensureAllTransformAreMath2D() { - assertTrue(<code class="GeoAPI">transform</code> instanceof MathTransform2D); - } -}</pre> - - - - <h3 id="GeoAPI-examples">Les modules dâexemples</h3> - <p> - Le module <code>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>geoapi-conformance</code>. - </p> + <h2 id="GeoAPI-implementation">Implémentations des interfaces</h2> <p> - Bien que sa mission première soit de servir dâinspiration aux implémenteurs, - <code>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>org.opengis</code>. - </p> - <p> - Pour des besoins un peu plus poussés, les développeurs sont invités à examiner les modules - <code>geoapi-proj4</code> et <code>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>NetCDF</abbr>). - Lâavantage de passer par ces interfaces est de disposer dâun modèle unifié pour exploiter deux <abbr>API</abbr> très différents, - tout en se gardant la possibilité de basculer plus facilement à une autre bibliothèque si désiré. + 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>org.opengis.referencing.crs.ProjectedCRS</code> est lâinterface définie par GeoAPI sur la base du standard ISO 19111, et</li> + <li><code>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> + 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>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>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>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>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> </body> </html>
