Au contenu principal

Documentation du Code
Outils de Développement
Structure du Code
Techniques et Standards
Comment Faire
Infos Fonctionnelles
Contexte Infos

Système d'Aide JMRI

Table des Matières Index
Glossaire FAQ *)
Des pages marqué *) sont en Anglais.

Donner à JMRI Faites un don à JMRI.org

JMRI: Utilisation de Schema XML

JMRI utilise XML pour un certains nombres ce but: organiser les définitions de décodeur, pour ses système de rémanence pour la configuration et panneau d'information, et pour créer des parties du site web depuis d'autres fichiers. Cette page décrit comment nous spécifions le contenu de ces fichiers par l'utilisation de schema XML.

Par exemples sur la structure de notre schéma, voir la page d'exemples.

Le schema actuel peut être vue en ligne dans le répertoire schema. Le plus couramment utilisé est le schema pour les fichiers de panneaux layout.xsd. Voir ci-dessous comment ils sont organisés.

Accès aux Définitions de Schéma

JMRI utilise le Schema XML pour définir le format de ses fichiers.

Ces Schémas XML peuvent avoir besoin d'être disponibles pour le programme quand il lit les fichiers, car ils définissent les valeurs par défaut des attributs manquants et autre information nécessaire.

Dans les distributions JMRI, Ils sont stockés dans le répertoire xml/schema Notez qu'ils ne sont pas stockés dans chaque répertoire à côté des fichiers XML. Il y a tout simplement de trop nombreux endroits pour garder un tel ensemble de fichiers de définition de schema à jour. JMRI lui-même, via la classe jmri.jmrit.XmlFile, fournit le support pour localiser ces fichiers quand l'analyseur XML a besoin d'eux.

Modification de Schema JMRI

Cette section explique comment gérer de tous petits changements dans un schema existant, par exemple, ajouter ou enlever un attribut ou un élément. Pour des changements plus important, incluant la création entière de nouveaux types ou nouveaux formats de fichier, voir la section suivante sur le "Développement de Schema JMRI".

Chaque fois que vous changez ce que JMRI écrit ( et donc lit ) dans un fichier XML, Il y a des choses que vous devez faire.

  1. Vous devez changez le code qui fait la lecture et l'écriture.
  2. Vous avez besoin de modifier les fichiers de schema , de sorte que le format XML peut être correctement vérifié.
  3. Vous devez fournir de nouveaux fichiers de test XML pour vous assurer que rien n'a été brisé, et dans certains cas avoir à ajuster les anciens.

SVP ne sautez pas les étapes suivantes. Ils ont matière à une stabilité à long terme du code JMRI.

Si possible, il vaut mieux faire les changements par ajout, pour que les fichiers existants puissent continuer à être lu inchangé. JMRI valorise fortement la compatibilité ascendante, où une version plus récente de JMRI peut encore charger et utiliser un fichier écrit par une ancienne version.

Si vous pouvez faire un changement qui est juste un ajout, alors le processus est:

  1. Changez votre code
  2. Ajoutez les nouveaux éléments et attributs à la version la plus récente du fichier de schema .
  3. Exécutez "ant headlesstest" pour être sûr que les anciens fichiers, toujours présents dans le test peuvent encore être traités. Réparer tout ce qui cassé. ( Vous pouvez découvrir à ce moment que vous ne faites pas actuellement un changement rétro-compatible, auquel cas soit vous le corrigez ou voir plus bas la section sur la "Gestion des versions de Schema " ).
  4. Créez un fichier test avec le nouveau contenu. Idéalement, cela ne nécessitera pas l'utilisation de l'écran, il peut effectivement être chargé et stocké dans le cadre de headlesstest. Dans ce cas, mettez votre fichier dans un sous-répertoire test "load" ( voir ci-dessous ). Au minimum, cependant, mettre votre fichier dans un sous-répertoire test "verify" afin que vos modifications du schema soient testées. Pour plus d'infos, voir ci-dessous

Gestion de Version de Schéma

La "gestion de Version" de Schema nous permet d'avoir différents fichiers de schema du plus ancien au plus récent. Ceci laisse les nouvelles versions de JMRI de continuer à vérifier et lire les fichiers qui ont été écrits par des anciennes versions de JMRI. Cette rétro-compatibilité est une caractéristique importante de JMRI que nous ne devons pas perdre.

En pratique, La "gestion de Version" consiste à avoir de multiples versions mais relatives de versions des fichiers de définition de schema qui sont étiquettées par la première version JMRI qui peut les lire.

Quand avez vous besoin de créer une nouvelle version?

Dans les deux cas, il est important d'inclure suffisamment de fichiers de test pour que les tests unitaires capturent les problèmes avec le nouveau et l'ancien schéma. Voir la section d'essai ci-dessous .

Notez que le schema non libellé est le schema primordial, le plus ancien et désormais obsolète. Par exemple layout.xsd est plus vieux que layout-2-9-6.xsd, et donc ne doit plus être utilisé pour les nouveaux fichiers. Ne supposez pas que layout.xsd est la valeur par défaut pour les nouveaux fichiers!

Vérification de Shema JMRI

Il est important que les définitions shema JMRI conserve une sémantique correcte. Si nous laissons trop de problèmes s'accumuler, nous allons finalement avoir beaucoup de correction à faire. L'outil W3C en ligne outil de validation de schéma est un excellent outil pour vérifier que les changements de schema JMRI sont encore techniquement corrects. Vous devez verifiez vos changements avec lui avant de les soumettre au répertoire. Malheureusement, il ne semble pas vérifier la conformité avec les éléments de schema imbriqués, exemple depuis DocBook ( voir ci-dessous ) ou schema JMRI, mais il est encore un contrôle très utile.

L'utilisation de l'outil JMRI "Validate XML File" dans le menu "Debug" pour valider un fichier .xml ( "instance file" ) qui utilise votre schema nouveau ou réactualisé est une vérification importante des deux. Utlisez le souvent pendant le développement. Vous pouvez aussi l'utiliser depuis les lignes de commande via ex: ./runtest.csh apps/jmrit/XmlFileValidateRunner xml/decoders/0NMRA.xml

Pour une vérification rapide de fichier, les utilisateurs Linux et Mac OS X peuvent valider depuis la ligne de commande avec ex: cd xml xmllint -schema schema /aspecttable.xsd -noout signals/sample-aspects.xml xmllint ne peut pas vérifier le schema fichiers eux-mêmes, malheureusement, parce que leur schema n'est pas quelque chose qu'il peut gérer.

Vos documents schema doivent pointer vers notre stylesheet standard dans leur contenu de tête: <?xml-stylesheet href="schema 2xhtml.xsl" type="text/xsl"?> Stylesheets tourne le code XML comme ce schéma, dans une forme lisible par l'utilisateur quand le XML est analysé et affiché par un navigateur. Pour un exemple, cliquez sur ce lien pour le fichier schéma aspecttable.xsd Notre norme stylesheet est assez basique. Elle montre juste quelques structure basique. Si quelqu'un connaît une meilleur Stylsheet, nous pourront certainement basculer vers elle.

Test JUnit

Vous devez ajoutez aussi un test JUnit qui vérifie un fichier typique Il y a trois sortes de vérifications qui peuvent être faites:
  1. Vous devriez toujours avoir une classe qui valide un fichier typique contre le schéma.
    Cela se fait en ayant une classe Schema Test dans votre paquet d'arbre de test ( voir par exemple: test/jmri/configurexml/Schema Test.java qui vérifie tous les fichiers XML conservés là. Si cela est en place, mettez juste une copie du ( nouveau ) fichier typique XML dans le sous-répertoire "verify" existant.
    Pour vérifier plus largement votre schéma, vous pouvez vérifier qu'il met en défaut les fichiers XML que vous pensez n'être pas valides. Il y a beaucoup de façons de ne pas être valable, et vous ne devez pas tout vérifier, mais s'il y a quelque chose de spécifique dont vous voulez être sûr, mettez un exemple de ceci dans le sous-répertoire "invalid". Ces fichiers sont attendus en échec pour une raison spécifique. Vous devez documenter cette raison par l'intermédiaire des commentaires dans le fichier lui-même afin que vos collègues puissent le comprendre plus tard.
  2. S'il n'y a pas de sous-répertoire "verify", créez en un et ajoutez le à la fin de de la classe Schema Test dans ce paquet. S'il n'y a pas de classe Schema Test, créez en une en dupliquant une existante, voir lien ci-dessous. N'oubliez pas de l'ajouter dans le PackageTest pour qu'elle soit appelée!
  3. Si vous travaillez sur les fichiers configurexml ( fichiers panneau ) , et que votre nouveau code n'est pas appelé dans l'affichage actuel des panneaux ( ex: peut fonctionner dans le cadre d'headlesstest ), vous devez ajouter un test pour qu'un exemple de fichier puissent être téléchargé et restocké avec succès. ( nous exécutons ces tests headless comme une part de Jenkins, donc SVP n'ajoutez pas de test qui font apparaître des fenêtres, cela causerait des erreurs ).
    Cela se fait en ayant une classe LoadAndStoreTest dans votre paquet test-tree ( voir ex: test/jmri/configurexml/LoadAndStoreTest.java ) qui vérifie tous les fichiers XML gardés là. Si c'est en place, mettez juste une copie d'un ( nouveau ) fichier XML typique dans le sous-répertoire existant "load"
    S'il ny a pas de sous-répertoire "load", créez en un en dupliquant un existant, à la fin de la classe LoadAndStoreTest à la fin de ce paquet. S'il n'y a pas de classe LoadAndStoreTest, créez en une en dupliquant une existante. voir le lien ci-dessous. N'oubliez pas de l'ajouter dans PackageTest pour qu'elle puisse être appelée!
    Quand LoadAndStoreTest s'exécute, il charge les fichiers dans le répertoire "load" un par un, stocker chaque retour vers le répertoire "temp" au sein du répertoire des préférences locales, et ensuite compare les fichier d'entrées et sorties. Parfois ce processus de charge-et-stockage a comme conséquence quelque chose qui est dans un ordre différent, ou contient plus d'infos( ex: les attributs manquants depuis le fichier sont écrits avec les valeurs par défaut dans les fichiers de sortie ). Si la comparaison échoue, mais le fichier de sortie est encore OK quand vous l'inspecter manuellement, copiez ce fichier de sortie dans le répertoire "loadref" (créez le si nécessaire ) au sein de votre paquet test. Voir test/jmri/configurexml/loadref comme exemple. LoadAndStoreTest comparera aux dossiers qu'il trouve ici, au lieu du fichier original dans le sous-répertoire "load".
    Si vos changements de code provoque l'échec de ce test avec l'ancienne version de ce fichier, ne pas changer l'ancienne version. À la place, soit mettre une référence de sortie actualisée dans le répertoire "loadref", versionner le schema pour permettre à l'ancien fichier de se charger, ou réparez votre code. La compatibilité ascendante est importante!
  4. Vous pouvez aussi ajouter un test JUnit personnalisé qui lit votre dossier témoin et veille que les objets appropriés ont été créés, qu'ils ont les données et les états corrects, etc. Ceci pourrait être quelque chose d'une "chargez et vérifiez que les nouveaux beans existent dans le nouveau gestionnaire" pour quelque chose de beaucoup plus étendue.
Au minimum, SVP veuillez faire les contrôles de schéma. Ils sont faciles, et épargneront un bon nombre d'ennuis à l'avenir. Si votre nouvelle fonction n'appelle pas d'affichage sur l'écran, l'ajout de des vérification charger et stocker est aussi valable, et ce n'est pas si dur.

Note: Ne pas supprimer ou modifier un fichier XML existant vérifié. Ceux-ci conservent les anciennes versions des fichiers de travail! Si votre nouveau code et/ou schema casse le processus de fichiers existants, vous devez soit corriger votre code ou numéroter la version du schéma pour permettre à de multiple formats de coexister.

Developpement du Schema JMRI

Pour quelques exemples des structures de schema XML décrit ici, voir la page séparée Exemples Schema XML

Notre organisation préférée pour les schema XML est basée sur la structure du code sous-jacent: Une classe particulière *XML est l'unité de réutilisation.

Un bon nombre de classes descendent de jmri.configurexml.XmAdapter: ( voir JavaDoc )

Par convention, fournir <xsd:annotation><xsd:appinfo> élément contenant le nom de classe qui lit et écrit l'élément: 


    <xs:annotation>
        <xs:documentation>
        Some human readable docs go here
        </xs:documentation>
        <xs:appinfo>
            <jmri:usingclass configurexml="false">jmri.managers.DefaultSignalSystemManager</jmri:usingclass>
        </xs:appinfo>
    </xs:annotation>

Le Motif de Stores Vénitiens

Nous nous dirigeons vers la structuration de notre XML en utilisant le "Motif de Stores Vénitiens". Dans ce style, les éléments de niveau supérieur qui sont écrits par classe ont des types définis. Tous les éléments qui se trouvent dans ceux-ci sont définis de façon anonyme, au sein de ces éléments. Pour un exemple, voir le fichier types/sensors.xsd qui définit un type pour l'élément "sensors",écrit pour SensorManagers. Dans ce cadre, il est inclus une définition d'un élément capteur,et un élément "comment" dans ce contexte.

Ceci limite le nombre de types et garde les fichiers schema à peu près alignés avec les classes qui font la lecture et l'écriture.

Il y a quelques éléments (éléments et groupes d'attributs) qui s'étendent sur plusieurs types. Ils sont définis dans le fichier types/general.xsd .

Plus d'informations sur les modèles de conception de schémas XML est disponible à DeveloperWorks et le Site web Java Oracle.

Sur des Éléments contre des Attributs

Lors de la définition comment stocker de nouvelles classes ou mises à jour des classes, les questions de bases sont: JMRI XML à l'origine se pencha fortement sur les attributs en raison des limitations dans la bibliothèque JDOM. Ces limitations ont disparu depuis longtemps, et nous sommes en train de passer en direction d'utilisation des éléments de la bonne façon.

Types Définis Disponibles

Le schema JMRI fournit un grand nombre de types de données prédéfinies. Celle-ci (En général) vérifient leur contenu, et seront maintenue à l'avenir comme des changements de contenu valides, il est donc préférable d'utiliser ceux-ci, si possible, au lieu de définir les votre.

Une liste partielle des types prédéfinis:

systemNameType
Noms Système, à terme, être renforcé dans un véritable test de validité
userNameType
Noms utilisateur, le nom vide n'est pas inclut
nullUserNameType
Noms utilisateur, avec la valeur vide autorisée
beanNameType
Soit nom utilisateur ou nom système
turnoutStateType
closed, thrown
signalColorType
red, yellow, et
trueFalseType
true, false
yesNoType
yes, no
yesNoMaybeType
yes, no, maybe
Pour d'autres, naviguer sur les types généraux de schema.

Normes Externes et Travaux Futurs

le collaboration OASIS définit un certain nombre de schema et d'éléments de schema qui sont devenus des normes bien connu. Où c'est possible, nous devrions utiliser les éléments standard pour améliorer l'inter-opérabilité. Les premiers intérêts sont: Apprendre à utiliser ceux-ci, demandera un peu de travail, comme nous ne pouvons pas supposer que les ordinateurs utilisant JMRI ont accès à Internet, on ne peut donc pas simplement référencer l'ensemble du schema comme des entités distantes.

Droit d'auteur, Auteur et Information de Révision

Pour diverses raisons, nous devons passer au format DocBook pour le Copyrignt, Auteur et Informations de Révision dans nos fichiers XML (fichiers d'instance).

Exemple XML: <db: copyright > <db: année > 2009 </db: année > <db: année > 2010 </db: année > < db: support > JMRI </db: support > </db: copyright > <db:authorgroup> <db:author> <db:personname><db:firstname>Sample</db:firstname><db:surname>Name</db:surname></db:personname> <db:email>name@com.domain</db:email> </db:author> </db:authorgroup> <db:revhistory> <db:revision> <db:revnumber>1</db:revnumber> <db:date>2009-12-28</db:date> <db:authorinitials>initials</db:authorinitials> </db:revision> </db:revhistory>

Description de l'échantillon du schéma: (Mais voir le vrai, qui est prévu dans le schema /docbook ) <xs: element ref =: minOccurs "docbook copyright" = "1" maxOccurs = "1" > <xs: annotation > < xs: documentation > élément (s) DocBook fournissant des informations de copyright sous forme standard. Doit être présent. </xs: documentation > </xs: annotation > </xs: element > <xs: element ref =: minOccurs "docbook AuthorGroup" = "1" maxOccurs = "unbounded" > <xs: annotation > <xs: documentation > élément DocBook (s) décrivant les auteurs en forme standard </xs: documentation > </xs: annotation > </xs: element > <xs:element ref="docbook:revhistory" minOccurs="1" maxOccurs="unbounded" > <xs:annotation><xs:documentation> élément(s) DocBook décrivant l'historique des révisions en forme standard </xs:documentation></xs:annotation> </xs:element>