Plug-in-Manifest
der Eclipse-Plattform
Version 0.90 - Letzte Überarbeitung: 15. März 2001
Die unten dargestellten Befehlsdefinitionen in der Manifestdatei
verwenden unterschiedliche Benennungs-Token und Kennungen.
Um eine Mehrdeutigkeit zu vermeiden, hier einige Erstellungsregeln
[auf die im Text verwiesen wird]. Im Allgemeinen wird bei allen
Kennungen die Groß-/Kleinschreibung beachtet.
SimpleToken := Zeichenfolge aus (a-z, A-Z, 0-9)
ComposedToken := SimpleToken | (SimpleToken '.' ComposedToken)
JavaClassName := ComposedToken
PlugInId := ComposedToken
PlugInPrereq := PlugInId | 'export' PlugInId
ExtensionId := SimpleToken
ExtensionPointId := SimpleToken
ExtensionPointReference := ExtensionPointID | (PlugInId '.' ExtensionPointId)
Der Rest dieses Abschnitts beschreibt die Struktur der Datei
"plugin.xml" als Folge aus DTD-Fragmenten.
Die Datei plugin.dtd
stellt die DTD-Definition in ihrer Gesamtheit dar.
<?xml encoding="US-ASCII"?>
<!ELEMENT plugin (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST plugin
name CDATA #REQUIRED
id CDATA #REQUIRED
version CDATA #REQUIRED
vendor-name CDATA #IMPLIED
class CDATA #IMPLIED
>
Das Element <plugin> definiert den Hauptteil des Manifests. Es
enthält optional Definitionen für die Plug-in-Laufzeit, Deklarationen
von neuen Erweiterungspunkten, die durch das Plug-in eingeführt
werden, sowie die Konfiguration von Funktionserweiterungen (die an
Erweiterungspunkten konfiguriert werden, die entweder durch andere
Plug-ins definiert sind oder durch dieses Plug-in eingeführt werden).
Für das Element <plugin> werden die folgenden Attribute verwendet:
-
name: Ein Name für das Plug-in, der vom Benutzer angezeigt
werden kann (übersetzbar).
-
id: Eine eindeutige Kennung für das Plug-in.
-
Um das Risiko von Namensunverträglichkeiten zu verringern, sollte die
Kennung aus der ID der Internet-Domäne des entsprechenden Herstellers
abgeleitet werden (indem die Token des Domänennamens umgekehrt und
weitere Namens-Token durch einen Punkt getrennt (.) angehängt werden).
Der Hersteller "ibm.com" könnte beispielsweise die Plug-in-Kennung
"com.ibm.db2" definieren.
-
[Erstellungsregel: PlugInId]
-
version: Die Versionsnummer des Plug-ins. Ausführliche
Informationen finden Sie unter
org.eclipse.core.runtime.PluginVersionIdentifier.
Das Format der Plug-in-Version lautet
hauptkomponente.untergeordnete_komponente.aktualisierung. Die
Änderung der Hauptkomponente wird als inkompatible Versionsänderung
interpretiert.
Eine Änderung der untergeordneten Komponente wird als kompatible
Versionsänderung interpretiert.
Eine Änderung der Aktualisierungskomponente wird als kumulative
Aktualisierung interpretiert, die auf die untergeordnete Version
angewendet wird.
-
vendor-name: Der Name des Plug-in-Herstellers, der vom
Benutzer angezeigt werden kann.
-
class: Der Name der Plug-in-Klasse für dieses Plug-in. Die
Klasse muss eine Unterklasse
von
org.eclipse.core.runtime.Plugin
sein.
Die XML-DTD-Konstruktionsregel element* bedeutet,
dass Null oder mehr Vorkommen des Elements vorhanden sind.
Die Regel element? bedeutet, dass 0 oder 1
Vorkommen des Elements vorhanden sind, und die
(im Folgenden verwendete) Regel element+
bedeutet, dass eines oder mehrere Vorkommen des Elements vorhanden
sind.
Ausgehend von der oben beschriebenen Definition in <plugin>
bedeutet dies beispielsweise, dass ein Plug-in, das nur eine
Laufzeitdefinition und keine Erweiterungspunktdeklarationen oder
Erweiterungskonfigurationen enthält, gültig ist (z. B. allgemeine
Bibliotheken, von denen andere Plug-ins abhängig sind).
Ähnlich ist auch ein Plug-in gültig, das nur
Erweiterungskonfigurationen und keine Laufzeitdefinition oder
Erweiterungspunkte für sich selbst enthält (z. B. Klassen
konfiguriert, die in anderen Plug-ins für Erweiterungspunkte
bereitgestellt werden, die in anderen Plug-ins definiert sind).
Der Abschnitt <requires> des Manifests deklariert alle
Abhängigkeiten von anderen Plug-ins.
<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
plugin CDATA #REQUIRED
version CDATA #IMPLIED
match (exact | compatible) "compatible"
export (true | false) "false"
>
Jede Abhängigkeit wird durch ein Element <import> angegeben. Es
enthält die folgenden Attribute:
-
plugin: Kennung des erforderlichen Plug-ins.
-
version: Optionale Versionsspezifikation.
-
match: Regel für den Versionsabgleich. Wird ignoriert, wenn
das Attribut "version" nicht angegeben wurde.
Dieses Attribut bestimmt, ob die Abhängigkeit nur durch ein Plug-in
der angegebenen Version erfüllt werden kann (möglicherweise mit einer
zusätzlich angelegten Aktualisierung) oder ob die Abhängigkeit auch
durch eine beliebige kompatible Version (einschließlich einer neueren
untergeordneten Version des Plug-ins) erfüllt werden kann.
-
export: Gibt an, ob die abhängigen Plug-in-Klassen für die
Benutzer dieses Plug-ins sichtbar gemacht und (erneut) exportiert
werden.
In der Standardeinstellung werden abhängige Klassen nicht exportiert
(nicht sichtbar gemacht).
Der Abschnitt <runtime> des Manifests
enthält die Definition von einer oder mehreren Bibliotheken, die die
Plug-in-Laufzeit bilden.
Die Bibliotheken, auf die verwiesen wird, werden durch die
Ausführungsmechanismen der Plattform (das Ladeprogramm für
Plug-in-Klassen) verwendet, um den durch das Plug-in benötigten
korrekten Code zu laden und auszuführen.
<!ELEMENT runtime (library+)>
<!ELEMENT library (export*)>
<!ATTLIST library
name CDATA #REQUIRED
>
<!ELEMENT export EMPTY>
<!ATTLIST export
name CDATA #REQUIRED
>
Das Element <runtime> hat keine Attribute.
Die Elemente <library> definieren zusammen die Plug-in-Laufzeit.
Es muss mindestens ein Element
<library> angegeben werden. Jedes Element <library> hat die
folgenden Attribute:
-
name: Ein Zeichenfolgeverweis auf eine Bibliotheksdatei oder
ein Bibliotheksverzeichnis mit Klassen (bezogen auf das
Installationsverzeichnis des Plug-ins).
Verzeichnisverweise müssen ein abschließendes Dateitrennzeichen
enthalten.
Jedes Element <library> kann angeben, welcher Teil der Bibliothek
exportiert werden soll.
Die Exportregeln werden als Gruppe von Exportmasken angegeben. In der
Standardeinstellung (keine Angabe von Exportregeln) wird die
Bibliothek als privat betrachtet.
Das Element <export> hat die folgenden Attribute:
-
name: Gibt die Exportmaske an. Gültige Werte:
-
*: Gibt an, dass der gesamte Inhalt der Bibliothek exportiert
werden soll (öffentlich).
-
paketname.*: Gibt an, dass alle Klassen im angegebenen Paket
exportiert werden sollen.
Die Regeln für den Abgleich sind mit denen in einer
Java-Importanweisung identisch.
-
klassenname: Der vollständig qualifizierte Name der Java-Klasse.
Die Architektur der Plattform basiert auf dem Konzept von
konfigurierbaren Erweiterungspunkten.
Die Plattform selbst gibt eine Reihe von Erweiterungspunkten vor, mit
denen die Plattform und der Desktop erweitert werden können
(beispielsweise durch das Hinzufügen von Menüaktionen oder das
Ergänzen eines integrierten Editors).
Neben den vordefinierten Erweiterungspunkten können alle
bereitgestellten Plug-ins zusätzliche Erweiterungspunkte deklarieren.
Durch das Deklarieren eines Erweiterungspunkts kündigt das Plug-in im
Wesentlichen die Möglichkeit an, dass die Plug-in-Funktion mit extern
bereitgestellten Erweiterungen konfiguriert werden kann.
Das Plug-in für das Seitenerstellungsprogramm könnte beispielsweise
einen Erweiterungspunkt für das Hinzufügen neuer DTC-Elemente
(Design Time Controls - Steuerelemente für Entwicklungszeit) zur
Palette seines Erstellungsprogramms hinzufügen.
Dies bedeutet, dass das Seitenerstellungsprogramm eine Architektur
für die Bedeutung eines DTC-Elements definiert und den Code
implementiert hat, der nach DTC-Erweiterungen sucht, die an den
Erweiterungspunkten konfiguriert wurden.
<!ELEMENT extension-point EMPTY>
<!ATTLIST extension-point
name CDATA #REQUIRED
id CDATA #REQUIRED
schema CDATA #IMPLIED
>
Das Element <extension-point> hat die folgenden Attribute:
-
name: Ein Name für den Erweiterungspunkt, der vom
Benutzer angezeigt
werden kann (übersetzbar).
-
id: Ein einfaches ID-Token, das innerhalb des Plug-ins
eindeutig ist. Das Token darf weder Punkte
(.) noch Leerzeichen enthalten.
-
[Erstellungsregel: ExtensionPointId]
-
schema: Die Schemaspezifikation für diesen Erweiterungspunkt. Die
genauen Details werden als Teil von PDE
(Plug-In Development
Environment - Umgebung für die Plug-in-Entwicklung) definiert.
Das Schema wird gegenwärtig zur Laufzeit nicht verwendet. Der Verweis
ist ein Dateiname, der auf die Installationsposition des
Plug-ins bezogen ist.
Die eigentlichen Erweiterungen werden im
Abschnitt <extension> an Erweiterungspunkten konfiguriert, die
vordefiniert sind oder in diesem Plug-in neu deklariert
werden. Die Konfigurationsdaten werden in einem gültigen XML-Format
zwischen den Tags
<extension>
und </extension> angegeben. Die Plattform gibt das tatsächliche
Format der Konfigurationsbefehle
(das über das XML-Format hinausgeht) nicht vor.
Die Befehle werden durch den Hersteller des Plug-ins definiert, das
den Erweiterungspunkt deklariert hat.
Die Konfigurationsdaten werden von der Plattform nicht im
eigentlichen Sinn interpretiert.
Die Plattform übergibt lediglich die Konfigurationsdaten an die
Plug-ins im Rahmen der Verarbeitung für den Erweiterungspunkt (wenn
die Logik des Erweiterungspunkts alle konfigurierten Erweiterungen
abfragt).
<!ELEMENT extension ANY>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED
>
Das Element <extension> hat die folgenden Attribute:
-
point: Verweise auf den Erweiterungspunkt, der konfiguriert
wird. Der Erweiterungspunkt kann in diesem Plug-in oder in einem
anderen Plug-in definiert sein.
-
[Erstellungsregel: ExtensionPointReference]
-
id: Optionale Kennung für dieses Konfigurationsexemplar des
Erweiterungspunkts.
Dieses Attribut wird von Erweiterungspunkten verwendet, die die
spezifischen konfigurierten Erweiterungen eindeutig angeben müssen
(und nicht einfach nur aufzählen können).
Die Kennung wird als einfaches Token angegeben, das innerhalb der
Definition des deklarierenden Plug-ins eindeutig sein muss.
Bei einer globalen Verwendung wird die
Plug-in-Kennung als Qualifikationsmerkmal für die Erweiterungskennung
verwendet.
-
[Erstellungsregel: ExtensionId]
-
name: Ein Name für die Erweiterung, der vom
Benutzer angezeigt werden kann (übersetzbar).
Wichtiger Hinweis: Der Inhalt des Elements <extension>
wird mit der
Regel ANY deklariert. Dies bedeutet, dass im Abschnitt mit
der Erweiterungskonfiguration
(zwischen den Tags
<extension> und </extension> tags) jedes beliebige gültige
XML-Format angegeben werden kann.