Editor für Erweiterungspunktschema

Den Editor für das Erweiterungspunktschema können Sie auf zwei unterschiedlichen Wegen öffnen: als Nebenprodukt bei der Erstellung eines neuen Erweiterungspunktes oder durch das Öffnen eines vorhandenen Erweiterungspunktschemas.  Gemäß der Konvention ist der Name eines neuen Schemas mit der Erweiterungspunkt-ID identisch, an die die Dateierweiterung .exsd angehängt wird. Solche Schemata werden in das Verzeichnis schema der Verzeichnisstruktur Ihres Plug-ins gestellt.  

Sobald in PDE ein neues Erweiterungspunktschema erstellt wird, wird auch die Schemadatei erstellt und der Schemaeditor wird zur Bearbeitung geöffnet. Sie können das Schema sofort definieren, aber auch schließen und später bearbeiten. Durch die Angabe eines vollständigen Erweiterungsschemas kann PDE den Benutzern Ihres Erweiterungspunkts eine automatisierte Unterstützung anbieten.

Der PDE-Schemaeditor basiert auf denselben Konzepten wie der Editor für Plug-in-Manifeste.  Er enthält zwei Formatseiten und eine Quellenseite.  Da das XML-Schema sehr ausführlich und in der Quellenform möglicherweise nur schwer lesbar ist, sollten Sie den Großteil der Bearbeitung auf den Formatseiten vornehmen.  Die Quellenseite ist für das Lesen des resultierenden Quellcodes nützlich.

Beispiel: Schema für den Erweiterungspunkt "Beispiel-Parser" erstellen

Sie haben bereits den Erweiterungspunkt "Beispiel-Parser" und das Ausgangsschema erstellt. Jetzt können Sie das Schema öffnen, indem Sie in den Ordner schema Ihres Projekts wechseln und auf die Datei parsers.exsd doppelklicken.  Daraufhin wird der Schemaeditor geöffnet.

Jetzt werden Sie Folgendes ausführen:

  1. Gültige XML-Elemente und -Attribute für den Erweiterungspunkt definieren.
  2. Grammatik (Inhaltsmodell) definieren.
  3. Dokumentationsausschnitte angeben, die in ein Referenzdokument gemischt werden.

Jedes Erweiterungspunktschema beginnt mit der Deklaration des Elements "extension". Sie fügen ein neues XML-Element namens "parser" hinzu.

  1. Wählen Sie im Abschnitt mit den Erweiterungspunktelementen die Schaltfläche Neues Element aus.
  2. Wechseln Sie in die Sicht "Eigenschaften" und ändern Sie den Namen von "New_Element" in "parser"
  3. Lassen Sie das neue Element ausgewählt und wählen Sie die Schaltfläche Neues Attribut aus. Hierdurch wird "new_attribute" als untergeordnetes Element des Elements erstellt. Ändern Sie auf der Eigenschaftenseite seinen Namen in "id" und den Wert für die Verwendung (use) in "required" (= erforderlich).
  4. Wählen Sie bei aktivierter Eigenschaftenseite die Schaltfläche "Attribut klonen" aus, die in der lokalen Symbolleiste verfügbar ist. Hierdurch wird eine Kopie des Attributs erstellt.  Dies ist hilfreich, weil somit alle Attribute ganz schnell erstellt werden können, ohne dass ein Verlassen der Eigenschaftenseite erforderlich ist.
  5. Ändern Sie den Namen des neuen Attributs in "name".
  6. Klonen Sie das Attribut erneut. Ändern Sie den Namen dieses Mal in "class" . Mit diesem Attribut wird der vollständig qualifizierte Name der Java-Klasse angegeben, die eine spezifische Java-Schnittstelle implementieren muss. Dieser Wert muss angegeben werden, damit PDE die Schnittstelle später nutzen kann. Ändern Sie den Wert für kind von "string" in "java."  Setzen Sie die Eigenschaft basedOn auf com.example.xyz.IParser.  (Diese Schnittstelle ist zwar noch nicht vorhanden, wird aber später noch von Ihnen erstellt.)

Bis hierher sollte der Schemaeditor etwa so aussehen:

Editor für Erweiterungspunktschema - Definitionsseite

Jetzt fügen Sie ein zusätzliche Attribut hinzu, das Werte aus einer diskreten Auswahlliste annimmt.Das bedeutet, dass Sie eine Aufzählungseinschränkung für den Basistyp string erstellen müssen.Außerdem legen Sie einen Standardwert für das Attribut fest.

  1. Wählen Sie bei ausgewähltem Element "parser" die Schaltfläche Neues Attribut aus. Ändern Sie seinen Namen auf der Eigenschaftenseite in "mode".
  2. Klicken Sie auf die Wertzelle der Eigenschaft "restriction", um den Dialog "Einschränkung" aufzurufen. 
  3. Ändern Sie den Einschränkungstyp von "none" in "enumeration."
  4. Fügen Sie die folgenden drei Optionen hinzu: "never" (= nie), "always" (= immer) und "manual" (= manuell). (Dies sind die drei hypothetischen Moduswerte für die Parser-Erweiterung.

Der Dialog "Einschränkung" sollte etwa so aussehen:

Dialog 'Typeinschränkung'

Wenn der Dialog geschlossen wurde, ändern Sie das Attribut "use" in "default" und das Attribut "value" in "always." Hierdurch wird der Standardwert definiert.Sie werden bemerken, dass in der Statuszeile einen Fehlernachricht erscheint, wenn Sie den Wert eingeben, da die gültigen Werte auf die drei Optionen für "enumeration" beschränkt sind. Sobald Sie die Eingabe beendet haben, wird die Fehlernachricht jedoch ausgeblendet, da "always" ein gültiger Wert ist.

Nachdem Sie alle Elemente und Attribute angegeben haben, müssen Sie jetzt die Grammatik definieren. Ziel der Definition ist es, dass das Element "extension" eine beliebige Anzahl von Elementen "parser" als untergeordnete Elemente enthalten kann. 

  1. Wählen Sie das Element "extension" aus. Sein anfängliches Inhaltsmodell zeigt ein leeres Objekt für die Folgeerstellung an.
  2. Wählen Sie das Objekt für die Folgeerstellung aus und wählen Sie im Kontextmenü die Optionen Neu > Verweis > parser aus. Hierdurch wird der Parser-Verweis zum Objekt für die Folgeerstellung hinzugefügt.
  3. Die Standardbeziehungsart von Verweisen ist [1,1]. Dies bedeutet, dass genau 1 Element "parser" vorhanden sein kann. Dies ist von Ihnen jedoch nicht beabsichtigt. Wählen Sie daher den Verweis "parser" aus und ändern die Eigenschaft maxOccurs in "unbounded" (=unbegrenzt).

Nachdem Sie die Grammatik definiert haben, zeigt die DTD-Annäherung unter dem Grammatikabschnitt an, wie die Grammatik für das ausgewählte Element in DTD aussehen würde. Diese Informationen sind für Entwickler gedacht, die mit DTDs vertrauter als mit XML-Schemata sind.

Editor für Erweiterungspunktschema - Element 'grammar'

Nachdem Sie gültige Elemente, Attribute und die Grammatik definiert haben, müssen Sie jetzt einige Informationen zum Erweiterungspunkt angeben. Es gibt zwei Typen von Dokumentationsausschnitten für Schemata:

Der erste Ausschnitttyp wird auf der Seite "Definition" des Schemamanifests angegeben. Wenn Sie Elemente und Attribute auswählen, können Sie im Abschnitt "Beschreibung" einen kurzen Text über sie hinzufügen. Das erwartete Format sind HTML-Rohdaten (wie bei Javadoc). Der Text wird so in das endgültige Referenzdokument kopiert, wie er hier angegeben ist.

  1. Wählen Sie das Attribut "id" des Elements "parser" aus und geben Sie im Editor "Beschreibung" Folgendes ein:
    Ein eindeutiger Name, mit dem auf diesen Parser verwiesen wird.
  2. Wählen Sie das Attribut "name" aus und fügen Sie den folgenden Text hinzu:
    Ein umsetzbarer Name, der in der Benutzerschnittstelle für diesen Parser verwendet wird.
  3. Wählen Sie das Attribut "class" aus und fügen Sie den folgenden Text hinzu (achten Sie auf die HTML-Tags):
    Der vollständig qualifizierte Name einer Java-Klasse, die die Schnittstelle <samp>com.example.xyz.IParser</samp> implementiert.
  4. Wählen Sie das Attribut "mode" aus und fügen Sie Folgendes hinzu:
    Eine optionale Markierung, die angibt, wie oft dieses Parser-Exemplar ausgeführt wird. Die Standardeinstellung ist <samp>always</samp> (= immer).

Jetzt müssen Sie noch eine kurze Textbeschreibung für den eigentlichen Erweiterungspunkt angeben. Hierzu wechseln Sie auf die Seite "Dokumentation":

  1. Die Registerkarte "Übersicht" sollte angezeigt werden. Fügen Sie im Texteditor folgenden Text hinzu:

    An diesem Erweiterungspunkt können zusätzliche Parser integriert werden. Die Parser führen keine Aktionen aus. Sie wurden lediglich als Beispiel für ein Erweiterungspunktschema hinzugefügt.

    Klicken Sie auf Anwenden.
  2. Klicken Sie auf die Registerkarte "Beispiele" und fügen Sie den folgenden Text hinzu:

    Das folgende Beispiel veranschaulicht die Verwendung des Erweiterungspunktes:

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

    Klicken Sie auf Anwenden.

  3. Wählen Sie "API-Informationen" aus und fügen Sie den folgenden Text hinzu:

    Plug-ins, die diesen Erweiterungspunkt erweitern sollen, müssen die Schnittstelle <samp>com.example.xyz.IParser</samp> implementieren.

    Klicken Sie auf Anwenden.
  4. Wählen Sie "Bereitgestellte Implementierung" aus und fügen Sie den folgenden Text hinzu:

    Das Plug-in "XYZ" stellt eine Standardimplementierung des Parsers zur Verfügung.

    Klicken Sie auf Anwenden.
Hinweis: Beim Angeben von Beispielen müssen besondere Aspekte beachtet werden. Normalerweise behandelt PDE den angegebenen Text als HTML-Rohdaten und respektiert weder neue Zeilen noch Leerräume, die mehr als ein Zeichen umfassen (Leerräume werden also ignoriert). Bei herkömmlichem Text ist diese Funktionsweise erwünscht. Wenn Sie Beispiele angeben wollen, bei denen zur optimalen Darstellung Tabulatorschritte und vertikale Ausrichtungen eingesetzt werden müssen, kann dies jedoch ziemlich lästig sein. PDE bietet für diese Situation einen Kompromiss: Falls PDE das HTML-Tag <pre> findet, wird der Inhalt wie vorliegend übernommen (alle Zeichen bleiben unverändert erhalten), bis das abschließende Tag </pre> erreicht wird. Auf dieses Weise können Sie ein Beispiel wie oben darstellt angeben und sich darauf verlassen, dass es auch im endgültigen Referenzdokument gut aussieht.

Vielleicht haben Sie beim Eingeben der Dokumentation bereits bemerkt, dass immer mehr Elemente im Editor der Sicht "Gliederung" durch ein Stift-Image überlagert wurden. Dieser kleine Anzeige weist Sie darauf hin, dass dem betreffenden Element Text zugeordnet ist. Auf diese Weise können Sie ganz schnell überprüfen, ob im Dokument noch Dokumentation fehlt.

Editor für Erweiterungspunktschema - Gliederung

Nachdem Sie die Dokumentation fertig gestellt haben, können Sie sich nun mit den Referenzinformationen befassen. Hierzu haben Sie zwei Möglichkeiten. Während der gesamten Bearbeitungszeit können Sie das Referenzdokument voranzeigen, indem Sie im Kontextmenü die Option "Vorschau auf Verweisdokument" auswählen. Alternativ können Sie auch die PDE-Benutzervorgaben ("Benutzervorgaben > Plug-in-Entwicklung > Compiler", Registerkarte "Schema") so definieren, dass bei jeder Änderung der Schemadatei die Referenzdokumentation automatisch erstellt wird. Unabhängig davon, mit welcher Methode Sie das Referenzdokument erstellen, entsteht ein Ergebnis, das Sie durch Auswahl dieses Links anzeigen können.