Manifest modulu plug-in pro platformu Eclipse

Verze 3.0 - Poslední revize 24. června 2004

Níže uvedené markupové definice souboru manifest využívají pro pojmenování různé tokeny a identifikátory. K vyloučení dvojznačnosti jsou zde pro ně uvedena určitá produkční pravidla [v níže uvedeném textu jsou na ně odkazy]. Všechny identifikátory obecně rozlišují velká a malá písmena.

SimpleToken := posloupnost znaků z řady ('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)

Zbytek tohoto oddílu popisuje strukturu souboru plugin.xml jako sérii fragmentů DTD. Soubor plugin.dtd obsahuje úplnou definici DTD.

<?xml encoding="US-ASCII"?>
<!ELEMENT plugin (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST plugin
 name                CDATA #REQUIRED
 id                  CDATA #REQUIRED
 version             CDATA #REQUIRED
 provider-name       CDATA #IMPLIED
 class               CDATA #IMPLIED
>

Prvek <plugin> definuje tělo souboru manifest. Volitelně obsahuje definice běhové komponenty modulů plug-in, definice dalších modulů plug-in vyžadovaných touto komponentou, deklarace jakýchkoli nových bodů rozšíření zavedených tímto modulem plug-in i konfigurace funkčních rozšíření (zkonfigurovaných do bodů rozšíření definovaných jinými moduly plug-in nebo zavedených tímto modulem plug-in). Atributy prvku <plugin>:

Konstrukční pravidlo DTD pro XML element* znamená žádný nebo více výskytů prvku; element? znamená žádný nebo jeden výskyt prvku a element+ (použito níže) znamená jeden nebo více výskytů prvku. Na základě výše uvedené definice <plugin> to například znamená, že modul plug-in obsahující pouze definici běhové komponenty a žádné deklarace bodů rozšíření ani konfigurace rozšíření je platný (například společné knihovny, na nichž jsou závislé další moduly plug-in). Stejně tak modul plug-in obsahující pouze konfigurace rozšíření a žádnou běhovou komponenta ani vlastní body rozšíření je také platný (například konfigurační třídy dodávané v jiných modulech plug-in do bodů rozšíření deklarované v jiných modulech plug-in).

Oddíl <requires> souboru manifest deklaruje jakékoli závislosti na jiných modulech plug-in.

<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
 plugin              CDATA #REQUIRED
 version             CDATA #IMPLIED
 match               (perfect | equivalent | compatible | greaterOrEqual) "compatible"
 export              (true | false) "false"
 optional            (true | false) "false"
>

Každá závislost je určena prvkem <import>. Obsahuje následující atributy:

Oddíl <runtime> souboru manifest obsahuje definici jedné nebo více knihoven, jež vytvářejí běhovou komponentu modulu plug-in. Odkazované knihovny slouží spouštěcím mechanizmům platformy (zavaděči tříd modulu plug-in) k zavedení a spuštění správného kódu vyžadovaného modulem plug-in.

<!ELEMENT runtime (library+)>
<!ELEMENT library (export*, packages?)>
<!ATTLIST library
 name                CDATA #REQUIRED
 type                (code | resource) "code"
>
<!ELEMENT export EMPTY>
<!ATTLIST export
 name                CDATA #REQUIRED
>
<!ELEMENT packages EMPTY>
<!ATTLIST packages
  prefixes           CDATA #REQUIRED
>

Prvek <runtime> nemá žádné atributy.

Prvky <library> kolektivně definují běhovou komponentu modulu plug-in. Musí být specifikován alespoň jeden prvek <library>. Každý prvek <library> má následující atributy:

Každý prvek <library> může určit, která část knihovny by měla být exportována. Exportní pravidla jsou určena jako sada exportních masek. Standardně (bez určených exportních pravidel) se knihovna považuje za soukromou. Každá exportní maska je určena atributem name, jenž může mít následující hodnoty:

Pouze moduly plug-in pro Eclipse 2.1: Každá knihovna může také uvést předpony balíčků. Ty slouží ke zvýšení výkonu načítání tříd modulu plug-in nebo jeho fragmentu. Není-li prvek <packages> zadán, předpony k vylepšení načítání tříd nejsou standardně použity. Prvek <packages> má následující atribut:

Architektura platformy je založena na základě principu konfigurovatelných bodů rozšíření. Sama platforma předem definuje sadu bodů rozšíření, jež plní úlohu rozšíření platformy a pracovní plochu (například přidání akcí nabídek, doplnění zabudovaného editoru). Kromě předdefinovaných bodů rozšíření může každý dodaný modul plug-in deklarovat přídavné body rozšíření. Deklarací bodu rozšíření modul plug-in v podstatě inzeruje schopnost zkonfigurovat svou funkci pomocí externě dodaných rozšíření. Například modul plug-in Page Builder může deklarovat bod rozšíření pro přidávání nových obslužných prvků DTC (Design Time Control) do své palety tvůrců. To znamená, že Page Builder definoval architekturu pro to, co představuje DTC, a implementoval programový kód vyhledávající rozšíření DTC, jež byly zkonfigurovány do bodů rozšíření.

<!ELEMENT extension-point EMPTY>
<!ATTLIST extension-point
 name                CDATA #REQUIRED
 id                  CDATA #REQUIRED
 schema              CDATA #IMPLIED
>

Prvek <extension-point> má následující atributy:

Vlastní rozšíření jsou zkonfigurována do bodů rozšíření (předdefinovaných nebo nově deklarovaných v tomto modulu plug-in) v oddílu <extension>. Konfigurační informace jsou uvedeny jako dobře zformátovaný kód XML obsažený mezi značkami <extension> a </extension>. Platforma neuvádí vlastní tvar konfiguračního markupu (kromě požadavku na dobře zformátovaný kód XML). Markup je definován dodavatelem modulu plug-in, který deklaroval bod rozšíření. Platforma ve skutečnosti neinterpretuje konfigurační markup. Ta pouze předává konfigurační informace modulu plug-in jako součást zpracování bodu rozšíření (v té době se logika bodu rozšíření dotazuje na všechna zkonfigurovaná rozšíření).

<!ELEMENT extension ANY>
<!ATTLIST extension
 point               CDATA #REQUIRED
 id                  CDATA #IMPLIED
 name                CDATA #IMPLIED
>

Prvek <extension> má následující atributy:

Důležité: Obsah prvku <extension> je deklarován pomocí pravidla ANY.To znamená, že jakýkoli dobře zformátovaný kód XML může být zadán v rámci oddílu konfigurace rozšíření (mezi značkami <extension> a </extension>).

Fragmenty se používají ke zvětšení rozsahu platnosti modulu plug-in. Příkladem může být zahrnutí dat, jako jsou zprávy nebo štítky v jiném jazyce.

<?xml encoding="US-ASCII"?> 
<!ELEMENT fragment (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST fragment
 name                CDATA #REQUIRED
 id                  CDATA #REQUIRED
 version             CDATA #REQUIRED
 provider-name       CDATA #IMPLIED
 plugin-id           CDATA #REQUIRED
 plugin-version      CDATA #REQUIRED
 match               (perfect | equivalent | compatible | greaterOrEqual) "compatible"
>

Každý fragment musí být asociován s konkrétním modulem plug-in. Asociovaný modul plug-in je identifikován prvkem <plugin-id>, <plugin-version> a volitelně <match>. Poznámka: pokud tato specifikace odpovídá více než jednomu modulu plug-in, dojde k použití odpovídajícího modulu plug-in s nejvyšším číslem verze.

Komponenty <requires>, <runtime>, <extension-point> a <extension> daného fragmentu budou logicky přidány do odpovídajícího modulu plug-in.

Atributy prvku <fragment>: