Platforma Eclipse - manifest wtyczki

Wersja 3.0 - ostatnia aktualizacja: 24 czerwca 2004

To jest zarchiwizowana wersja dokumentu. Wersję aktualną można znaleźć tu.

W przedstawionych poniżej definicjach manifestu zapisanych w języku znaczników są używane różne leksemy i identyfikatory. W celu uniknięcia niejednoznacznoś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, wykorzystując fragmenty 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 wtyczki, definicje innych wtyczek wymaganych przez tę wtyczkę, deklaracje nowych punktów rozszerzeń wprowadzanych przez daną wtyczkę oraz konfiguracje rozszerzeń funkcjonalnych (konfigurowanych przy użyciu punktów rozszerzeń zdefiniowanych przez inne wtyczki lub wprowadzanych przez daną wtyczkę). 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 wtyczka zawierająca tylko definicję środowiska wykonawczego, a pozbawiona deklaracji punktów rozszerzeń i konfiguracji rozszerzeń, jest poprawna (np. wspólne biblioteki używane przez inne wtyczki). Na podobnej zasadzie można powiedzieć, że wtyczka zawierająca tylko konfiguracje rozszerzeń, ale pozbawiona środowiska wykonawczego lub punktów rozszerzeń, także jest poprawna (np. konfigurowanie klas zdefiniowanych w innych wtyczkach na potrzeby punktów rozszerzeń deklarowanych w jeszcze innych wtyczkach).

Sekcja <requires> manifestu zawiera deklaracje wszystkich zależności dotyczących innych wtyczek.

<!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>. Ma on następujące atrybuty:

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

<!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> nie ma atrybutów.

Elementy <library> wspólnie definiują środowisko wykonawcze wtyczki. 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 wtyczki 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 wtyczki i/lub jej 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 lub wniesienie wbudowanego edytora). Oprócz predefiniowanych punktów rozszerzeń, każda dostarczana wtyczka może zawierać dodatkowe ich deklaracje. Deklaracja punktu rozszerzenia we wtyczce oznacza publiczne udostępnienie mechanizmu służącego do konfigurowania funkcji wtyczki przy użyciu zewnętrznych rozszerzeń. Na przykład wtyczka 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 we wtyczce 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 tej wtyczce) 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ę wtyczki, która zadeklarowała punkt rozszerzenia. Platforma nie interpretuje kodu w języku znaczników użytego do konfiguracji. Przekazuje ona tylko informacje o konfiguracji do wtyczki 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 wtyczki. 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 konkretną wtyczką. Powiązana wtyczka jest identyfikowana przy użyciu elementów <plugin-id>, <plugin-version> i <match> (opcjonalnie). Jeśli do tej specyfikacji pasuje więcej niż jedna wtyczka, wybrana zostanie wtyczka z najwyższym numerem wersji.

Komponenty <requires>, <runtime>, <extension-point> i <extension> deklaracji fragmentu zostaną logicznie dodane do pasującej wtyczki.

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