Editeur du schéma des points d'extension

Vous pouvez utiliser l'éditeur du schéma des points d'extension de deux façons : pour créer un point d'extension ou pour ouvrir un schéma des points d'extension existant.  Par convention, tout nouveau schéma se voit attribuer le nom de l'id du point d'extension, ainsi que l'extension .exsd. Il est placé dans le répertoire schema de l'arborescence des plug-in.  

Lors de la création d'un point d'extension dans PDE, le fichier de schéma initial est également créé, et l'éditeur de schéma s'ouvre en modification. Vous pouvez définir le schéma à ce moment-là ou le fermer pour l'éditer ultérieurement. La création d'un schéma des points d'extension complet permet à PDE de proposer une assistance automatisée aux utilisateurs du point d'extension.

L'éditeur de schémas PDE s'appuie sur les mêmes concepts que l'éditeur de manifeste de plug-in.  Il comporte deux pages de formulaire et une page source.  Comme le schéma XML est prolixe et peut être difficile à lire dans sa forme source, vous devez passer par les pages de formulaire pour effectuer la plupart des modifications.  La page source est utile pour la lecture du code source ainsi obtenu.

Exemple : Création du schéma du point d'extension "Analyseurs"

Précédemment, nous avons créé le point d'extension "Analyseurs" et le schéma initial. Nous pouvons à présent ouvrir le schéma résidant dans le dossier schema du projet, puis cliquer deux fois sur le fichier parsers.exsd.  L'éditeur de schémas s'exécute.

Nous allons :

  1. Définir les éléments et les attributs XML valides du point d'extension.
  2. Définir la grammaire (modèle du contenu).
  3. Rédiger des extraits de code qui seront fusionnés dans un document de référence.

Tout schéma de point d'extension commence par la déclaration de l'élément "extension".  Nous allons ajouter un nouvel élément XML appelé "parser."

  1. Cliquez sur le bouton Nouvel élément dans la section Eléments des points d'extension.
  2. Dans la vue Propriétés, remplacez le nom "New_Element" par "parser".
  3. Tandis que le nouvel élément est encore sélectionné, cliquez sur le bouton Nouvel attribut. "new_attribute" est créé en tant qu'enfant. Dans la feuille de propriétés, changez son nom (name) en "id" et use en "required".
  4. Dans la feuille de propriétés, cliquez sur "Cloner cet attribut" (dans la barre d'outils locale). L'attribut est alors dupliqué.  Ceci permet de définir rapidement tous les attributs sans quitter la feuille de propriétés.
  5. Changez le nom du nouvel attribut en "name".
  6. Clonez à nouveau l'attribut. Cette fois-ci, changez le nom en "class".  Cet attribut permettra de représenter le nom qualifié complet de la classe Java qui doit mettre en oeuvre une interface Java spécifique. Cette information est nécessaire car elle sera exploitée ultérieurement par PDE. Remplacez la valeur de kind ("string") par "java." . Définissez la propriété basedOn en com.example.xyz.IParser.  (Cette interface n'existe pas encore mais nous allons la créer ultérieurement.)

L'éditeur de schémas doit alors ressembler à ceci :

Editeur de schémas de points d'extension - page des définitions

Nous allons à présent ajouter un attribut acceptant des valeurs d'une liste discrète de choix.  Ceci signifie que nous devons créer une restriction d'énumération du type de base string.  En outre, nous allons définir une valeur par défaut pour l'attribut.

  1. Alors que l'élément "parser" est sélectionné, cliquez  sur le bouton Nouvel attribut. Dans la feuille de propriétés, changez son nom en "mode".
  2. Cliquez sur la cellule de valeur de la propriété "restriction" pour afficher la boîte de dialogue des restrictions. 
  3. Changez le type de restriction de "none" en "enumeration".
  4. Ajoutez les trois choix suivants : "never", "always" et "manual". (Il s'agit des trois modes possibles pour l'extension de l'analyseur.)

La boîte de dialogue doit ressembler à ceci :

Boîte de dialogue Restriction de types

Après avoir refermé la boîte de dialogue, changez l'attribut "use" en "default", et l'attribut "value" en "always". Vous définissez ainsi la valeur par défaut.  Notez que la ligne d'état affiche un message d'erreur lors de la saisie de la valeur, car les valeurs valides se résument alors à trois choix d'énumération. A la fin de la saisie, le message d'erreur doit disparaître, car "always" est une valeur valide.

Nous devons à présent définir la grammaire. Notre objectif est d'indiquer que l'élément "extension" peut posséder autant d'éléments "parser" enfants que nécessaire. 

  1. Sélectionnez l'élément"extension". Son modèle de contenu initial comporte un compositeur de séquence vide.
  2. Sélectionnez le compositeur de séquence, puis la commande Nouveau->Référence->parser dans le menu contextuel. La référence de l'analyseur est alors ajoutée au compositeur de séquence.
  3. La cardinalité par défaut des références est [1,1], ce qui signifie qu'il ne peut exister qu'un élément "parser". Ce n'est pas vraiment ce que nous souhaitons. Nous sélectionnons la référence "parser" et modifions maxOccurs en "unbounded."

Une fois la grammaire définie, l'approximation DTD figurant sous la section grammaire indique à quoi doit ressembler la grammaire de l'élément dans la DTD.  Ces informations permettent d'aider les développeurs qui sont plus à l'aise avec les DTD qu'avec les schémas XML.

Editeur de schémas de point d'extension - grammaire des éléments

Maintenant que nous avons défini des éléments, des attributs et une grammaire valides, nous allons fournir un certain nombre d'informations sur le point d'extension. On distingue les deux types d'extraits de documentation de schéma suivants :

Le premier type d'extrait est fourni dans la page de définition du manifeste de schéma. Durant la sélection des éléments et des attributs, vous avez la possibilité d'ajouter de courts descriptifs dans la section "Description". Le format attendu est de type HTML brut (comme avec Javadoc) et le texte sera copié tel quel dans le document de référence final.

  1. Sélectionnez l'attribut "id" de l'élément "parser", puis tapez ce qui suit dans l'éditeur de description :
    Nom unique utilisé pour référencer cet analyseur.
  2. Sélectionnez l'attribut "name" et ajoutez le texte suivant :
    Nom traduisible de présentation de cet analyseur dans l'IU.
  3. Sélectionnez l'attribut "class", puis ajoutez le texte suivant (sans oublier les balises HTML) :
    Nom qualifié complet de la classe Java implémentant l'interface <samp>com.example.xyz.IParser</samp>.
  4. Sélectionnez l'attribut "mode" et ajoutez le texte suivant :
    Indicateur facultatif de fréquence d'exécution de l'instance de l'analyseur (par défaut, <samp>always</samp>).

Saisissez à présent un court descriptif du point d'extension lui-même. Pour cela, affichez la page Documentation :

  1. Vous devez vous trouver maintenant dans l'onglet "Présentation". Dans l'éditeur de texte, ajoutez le texte suivant :

    Ce point d'extension permet de se connecter à des analyseurs syntaxiques supplémentaires. Ces analyseurs syntaxiques sont inopérants - nous les utilisons simplement comme exemple de schéma de point d'extension.

    Cliquez sur Appliquer.
  2. Cliquez sur l'onglet "Exemples" et ajoutez le texte suivant :

    L'exemple ci-dessous illustre la syntaxe du point d'extension :

       <p>
       <pre>
          <extension point="com.example.xyz.parsers">
             <parser
                id="com.example.xyz.parser1"
                name="Analyseur syntaxique 1"
                class="com.example.xyz.SampleParser1">
             </parser>
          </extension>
       </pre>
       </p>
    

    Cliquez sur Appliquer.

  3. Sélectionnez l'onglet "Informations sur les API" et ajoutez le texte suivant :

    Les plug-in qui doivent étendre ce point d'extension implémenteront l'interface <samp>com.example.xyz.IParser</samp>.

    Cliquez sur Appliquer.
  4. Sélectionnez l'onglet "Implémentation fournie" et ajoutez le texte suivant :

    Le plug-in XYZ fournit l'implémentation par défaut de l'analyseur.

    Cliquez sur Appliquer.
Remarque : Un certain de points importants sont à prendre en compte lors de la définition d'exemples. En principe, PDE traite le texte fourni comme du code HTML brut sans respecter les sauts de ligne et les espaces d'une longueur supérieure à un caractère (c'est-à-dire les espaces blancs non significatifs). Ce comportement convient à du texte standard mais se révèle ennuyeux avec des exemples, dans lesquels l'espacement horizontal et vertical est important pour la disposition du texte. PDE offre un compromis : s'il détecte la balise HTML <pre>, il considère le contenu en l'état (en préservant tous les caractères) jusqu'à la balise de fermeture </pre> suivante. Ceci explique pourquoi nous pouvons fournir un exemple tel que le précédent en étant certains que sa disposition ne sera pas modifiée dans le document de référence final.

Vous avez pu également noter que, à mesure de la saisie de la documentation, le pictogramme "stylo" est associé à un nombre croissant d'éléments dans la vue de l'aperçu de l'éditeur. Le pictogramme indique que ces éléments possèdent du texte et constitue un moyen rapide de vérifier si les éléments sont correctement documentés.

Structure de l'éditeur de schémas de point d'extension

Vous pouvez ensuite consulter la documentation de référence, accessible de deux manières. Pendant toute votre session de travail, vous pouvez visualiser le document de référence en sélectionnant Aperçu du document de référence dans le menu en incrustation. Vous pouvez aussi définir des préférences PDE (Préférences>Développement de plug-in>Compilateurs, sous l'onglet Schéma) pour créer automatiquement une documentation de référence sur chaque modification de fichier de schéma. Quelle que soit la méthode employée pour le créer, le document obtenu pour cet exemple devrait se présenter ainsi.