Les interfaces Java du projet GeoAPI sont parfois générées à partir d’autres fichiers fournis par l’OGC, tels que les fichiers XSD. 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. Il aurait été possible de générer automatiquement des interfaces Java à partir des standards de l’OGC à l’aide d’outils existants. Par exemple une des approches les plus utilisées est de transformer les schémas XSD en interfaces Java à l’aide de l’utilitaire en ligne de commande xjc. Cet utilitaire étant fournit avec la plupart des distributions du Java (il fait partie des outils de JAXB), 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 UML plutôt que XSD. 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:

• Certains schémas XSD sont beaucoup plus verbeux que les schémas UML d’origines. Une conversion à partir des schémas XSD 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 XSD définissent aussi des attributs propres aux documents XML (id, uuid, xlink:href, etc.), qui n’existent pas dans les diagrammes UML originaux et que l’on ne souhaite pas forcément exposer dans un API Java. Une conversion à partir des schémas UML évite ce problème, mais les outils capable d’effectuer cette opération sont plus rares.

  Exemple: Les schémas XSD des méta-données insèrent un élément <cit:CI_Citation> à l’intérieur de <cit:citation>, un élément <cit:CI_OnlineResource> à l’intérieur de <cit:onlineResource>, et ainsi de suite pour la centaine de classes définies dans le standard ISO 19115. Cette redondance n’est absolument pas nécessaire à un programme Java.

• Les standards de l’OGC utilisent des conventions de nommage qui sont différentes de celles du Java. En particulier les noms de presque toutes les classes de l’OGC commencent par un préfixe de deux lettres, comme dans MD_Identifier. 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 Java beans.

  Exemple: la classe MD_Identifier de l’OGC devient l’interface Identifier dans le paquet org.opengis.metadata. La classe SC_CRS de l’OGC devient l’interface CoordinateReferenceSystem, et l’association usesDatum devient une méthode getDatum() — et non pas « getUsesDatum() » 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.

• 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.

  Exemple: Le standard ISO 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 sous-ensembles 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 CS_ImageCS, ne contient que CS_CartesianCS et CS_AffineCS. 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 CartesianCS comme une spécialisation de AffineCS, 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.

• 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.

  Exemple: Le standard ISO 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 (CRS). Or ces derniers sont le sujet à part entière d’un autre standard: ISO 19111. D’ailleurs le standard ISO 19111:2007 stipule, dans sa section 3, qu’il réutilise tous les éléments de ISO 19115 à l’exclusion de MD_CRS et de ses composantes. Les interfaces de GeoAPI réduisent la redondance en appliquant à l’ensemble du projet l’exclusion recommandée par ISO 19111.

• 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.

  Exemple: Le standard ISO 19115-2 est une extension du standard ISO 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 ISO 19115-2 définit une classe MI_Band qui étend la classe MD_Band du standard ISO 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.

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 une page unique, 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 @UML et des fichiers de propriétés, décrits dans la section suivante.

Correspondances explicites entre GeoAPI et les spécifications abstraites

Pour chaque classe, méthode et constante définie à partir d’un standard OGC ou ISO, GeoAPI indique sa provenance à l’aide d’annotations définies dans le paquet org.opengis.annotation. En particulier l’annotation @UML indique le standard, le nom de l’élément dans ce standard ainsi que son niveau d’obligation. Par exemple dans l’extrait de code suivant, la première annotation @UML indique que l’interface Java qui la suit (ProjectedCRS) est définie à partir du type SC_ProjectedCRS du standard ISO 19111. La seconde annotation @UML, appliquée cette fois à la méthode getCoordinateSystem(), indique que la méthode est définie à partir de l’association coordinateSystem du standard ISO 19111, et que cette association est obligatoire — ce qui, traduit en Java, signifie que la méthode n’est pas autorisée à retourner la valeur null.

package org.opengis.referencing.crs;

/**
 * A 2D coordinate reference system used to approximate the shape of the earth on a planar surface.
 */
@UML(specification=ISO_19111, identifier="SC_ProjectedCRS")
public interface ProjectedCRS extends GeneralDerivedCRS {
    /**
     * Returns the coordinate system, which must be Cartesian.
     */
    @UML(obligation=MANDATORY, specification=ISO_19111, identifier="coordinateSystem")
    CartesianCS getCoordinateSystem();
}

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’OGC, ou pour écrire des éléments dans un document XML. La classe org.apache.sis.util.iso.Types fournit des méthodes de commodité telles que getStandardName(Class) pour effectuer cette opération. Par exemple le code suivant affichera « Le nom standard du type org.opengis.referencing.crs.ProjectedCRS est SC_ProjectedCRS »:

Class<?> type = ProjectedCRS.class;
System.out.println("Le nom standard du type " + type.getName() + " est " + Types.getStandardName(type));

La méthode de commodité Types.forStandardName(String) 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 chapitre séparé.

Correspondances implicites avec le JDK standard

Certaines classes et méthodes n’ont ni annotation @UML, ni entrée dans le fichier class-index.properties. Il s’agit soit d’extensions de GeoAPI, ou soit de types définis dans d’autres bibliothèques, notamment le JDK standard. Pour ce dernier cas, la correspondance avec les standards ISO est implicite. Le tableau suivant décrit cette correspondance pour les types de la norme ISO 19103. Les types primitifs du Java standard sont préférés lorsqu’ils sont applicables, mais parfois leurs équivalents sous forme d’objets sont employés lorsqu’il est nécessaire d’autoriser des valeurs nulles.

L’équivalent le plus direct de CharacterString est la classe String, mais GeoAPI emploie souvent l’interface InternationalString pour permettre au client de choisir la langue. C’est utile par exemple sur un serveur fournissant simultanément des pages dans plusieurs langues. En reportant les traductions à l’utilisation des objets plutôt qu’au moment de leur création, on permet à la bibliothèque SIS de fournir les mêmes instances de Metadata ou Coverage (par exemple) pour les mêmes données peu importe la langue du client. Les traductions peuvent être faites à la volée à l’aide d’un ResourceBundle de l’application, ou être fournies directement avec les données (cas des Metadata notamment).

Les Enumeration correspondent aux Enum du Java. Ils ont en commun de définir toutes les valeurs autorisées, sans permettre à l’utilisateur d’en ajouter. Les CodeList sont similaires à ces énumérations, excepté que les utilisateurs peuvent y ajouter leurs propres éléments. Le JDK standard n’offrant pas cette possibilité, GeoAPI définit une classe abstraite CodeList reproduisant certaines fonctionnalités de Enum tout en étant extensible. Les extensions s’obtiennent par les méthodes statiques valueOf(String) qui, contrairement à celle de Enum, créeront de nouvelles instances si le nom donné ne correspond pas au nom d’une instance existante.

MediumName cdRom  = MediumName.CD_ROM;
MediumName usbKey = MediumName.valueOf("USB_KEY"); // Aucune constante n’existe pour cette valeur.
assert MediumName.valueOf("CD_ROM")  == cdRom  : "valueOf doit retourner les constantes existantes.";
assert MediumName.valueOf("USB_KEY") == usbKey : "valueOf doit cacher les valeurs précédemment demandées.";