Platforma Eclipse - manifest modułu dodatkowego

Wersja 3.0 - ostatnia aktualizacja: 24 czerwca 2004

W przedstawionych poniżej definicjach manifestu zapisanych w języku znaczników są używane różne elementy leksykalne i identyfikatory. W celu uniknięcia dwuznaczności, przedstawiono także reguły ich tworzenia [do których odwołuje się dalszy tekst]. Na ogół we wszystkich identyfikatorach jest rozróżniana wielkość liter.

SimpleToken := sekwencja znaków (dozwolone znaki: a-z, A-Z, 0-9 i znak podkreślenia "_")
ComposedToken := SimpleToken | (SimpleToken '.' ComposedToken)
JavaClassName := ComposedToken
PlugInId := ComposedToken
PlugInPrereq := PlugInId | 'export' PlugInId
ExtensionId := SimpleToken
ExtensionPointId := SimpleToken
ExtensionPointReference := ExtensionPointID | (PlugInId '.' ExtensionPointId)

W pozostałej części tej sekcji opisano strukturę pliku plugin.xml jako szereg fragmentów definicji DTD. Plik plugin.dtd w całości stanowi definicję 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
>

Element <plugin> definiuje treść manifestu. Opcjonalnie zawiera on definicje środowiska wykonawczego modułu dodatkowego, definicje innych modułów dodatkowych wymaganych przez ten moduł, deklaracje nowych punktów rozszerzeń wprowadzanych przez dany moduł dodatkowy oraz konfiguracje rozszerzeń funkcjonalnych (konfigurowanych przy użyciu punktów rozszerzeń zdefiniowanych przez inne moduły dodatkowe lub wprowadzanych przez dany moduł). Element <plugin> ma następujące atrybuty:

Reguła tworzenia definicji DTD w formacie XML element* oznacza zero lub więcej wystąpień elementu. element? oznacza zero lub jedno wystąpienie elementu. element+ (tej reguły użyto poniżej) oznacza jedno lub więcej wystąpień elementu. Na podstawie powyższej definicji elementu <plugin> można stwierdzić, że na przykład moduł dodatkowy zawierający tylko definicję środowiska wykonawczego, a pozbawiony deklaracji punktów rozszerzeń i konfiguracji rozszerzeń, jest poprawny (np. wspólne biblioteki używane przez inne moduły dodatkowe). Na podobnej zasadzie można powiedzieć, że moduł dodatkowy zawierający tylko konfiguracje rozszerzeń, ale pozbawiony środowiska wykonawczego lub punktów rozszerzeń, także jest poprawny (np. konfigurowanie klas zdefiniowanych w innych modułach dodatkowych na potrzeby punktów rozszerzeń deklarowanych w jeszcze innych modułach).

Sekcja <requires> manifestu zawiera deklaracje wszystkich zależności dotyczących innych modułów dodatkowych.

<!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żda zależność jest określana przy użyciu elementu <import>. Zawiera on następujące atrybuty:

Sekcja <runtime> manifestu zawiera definicje jednej lub wielu bibliotek, które składają się na środowisko wykonawcze modułu dodatkowego. Wskazane tu biblioteki są używane przez mechanizmy środowiska wykonawczego platformy (program ładujący klasy modułu dodatkowego) na potrzeby ładowania i wykonywania poprawnego kodu wymaganego przez moduł dodatkowy.

<!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
>

Element <runtime> jest pozbawiony atrybutów.

Elementy <library> wspólnie definiują środowisko wykonawcze modułu dodatkowego. Należy określić co najmniej jeden element <library>. Każdy element <library> ma następujące atrybuty:

Każdy element <library> może definiować, która część biblioteki ma być eksportowana. Reguły eksportowania są definiowane jako zestaw masek eksportu. Jeśli nie określono reguł eksportowania, biblioteka jest domyślnie traktowana jak biblioteka prywatna. Maska eksportu jest określana przy użyciu atrybutu name, który może mieć następujące wartości:

Tylko moduły dodatkowe Eclipse 2.1: W przypadku każdej biblioteki mogą być także określone przedrostki pakietów. Umożliwiają one poprawienie wydajności ładowania klas dla modułu dodatkowego i/lub jego fragmentu. Jeśli nie podano elementu <packages>, to domyślnie nie są używane mechanizmy usprawniające ładowanie klas. Element <packages> ma następujący atrybut:

Architektura platformy jest oparta na koncepcji konfigurowalnych punktów rozszerzeń. W ramach platformy jest dostępny predefiniowany zestaw punktów rozszerzeń, które służą do rozszerzania funkcjonalności platformy i pulpitu (np. przez dodanie akcji menu do wbudowanego edytora). Oprócz predefiniowanych punktów rozszerzeń każdy dostarczany moduł dodatkowy może zawierać dodatkowe ich deklaracje. Deklaracja punktu rozszerzenia w module dodatkowym oznacza publiczne udostępnienie mechanizmu służącego do konfigurowania funkcji modułu przy użyciu zewnętrznych rozszerzeń. Na przykład moduł Page Builder może zawierać deklarację punktu rozszerzenia, która pozwala dodać do palety nowe elementy sterujące Design Time Controls (DTC). Oznacza to, że w module Page Builder zdefiniowano architekturę dla elementów sterujących DTC i zaimplementowano kod służący do wyszukiwania rozszerzeń tego typu skonfigurowanych w punktach rozszerzeń.

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

Element <extension-point> ma następujące atrybuty:

Rzeczywiste rozszerzenia są konfigurowane w punktach rozszerzeń (predefiniowanych lub nowo deklarowanych w tym module dodatkowym) w sekcji <extension>. Informacje o konfiguracji są podawane jako poprawnie sformatowany kod XML zawarty między znacznikami <extension> i </extension>. Platforma nie określa szczegółowej formy kodu w języku znaczników używanego do konfiguracji (poza ogólnym wymogiem, aby był to poprawnie sformatowany kod XML). Kod w języku znaczników jest definiowany przez dostawcę modułu dodatkowego, który zadeklarował punkt rozszerzenia. Platforma nie interpretuje kodu w języku znaczników użytego do konfiguracji. Przekazuje ona tylko informacje o konfiguracji do modułu dodatkowego podczas procesu przetwarzania punktu rozszerzenia (w momencie gdy kod punktu rozszerzenia generuje zapytania o wszystkie skonfigurowane w nim rozszerzenia).

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

Element <extension> ma następujące atrybuty:

Ważne: Treść elementu <extension> jest deklarowana przy użyciu reguły ANY.Oznacza to, że w ramach sekcji konfiguracji rozszerzenia (między znacznikami <extension> i </extension>) można podać dowolny, poprawnie sformatowany kod XML.

Fragmenty są stosowane w celu zwiększania zasięgu modułu dodatkowego. Jako przykład można podać dołączanie komunikatów i etykiet w innym języku.

<?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żdy fragment musi być powiązany z konkretnym modułem dodatkowym. Powiązany moduł dodatkowy jest identyfikowany przy użyciu elementów <plugin-id>, <plugin-version> i <match> (opcjonalnie). Jeśli do tej specyfikacji pasuje więcej niż jeden moduł dodatkowy, wybrany zostanie moduł z najwyższym numerem wersji.

Komponenty <requires>, <runtime>, <extension-point> i <extension> deklaracji fragmentu zostaną logicznie dodane do pasującego modułu dodatkowego.

Element <fragment> ma następujące atrybuty: