Piattaforma Eclipse
Manifest di plug-in
Versione 0.90 - Ultima revisione 15 marzo 2001
Le definizioni dei tag manifest di seguito riportate utilizzano diversi token e identificativi dei nomi. Per evitare equivoci, sono state fornite alcune regole relative alla loro produzione. Di solito, tutti gli identificativi seguono la differenza tra lettere maiuscole e minuscole.
SimpleToken := sequenza dei caratteri '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)
Il resto di questa sezione descrive la struttura del file plugin.xml come una serie di frammenti DTD. Il file plugin.dtd
presenta l'intera definizione DTD.
<?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
>
L'elemento <plugin> definisce il corpo del manifest. Esso può contenere definizioni di esecuzione, dichiarazioni di qualsiasi nuovo punto di estensione introdotto da un plug-in oppure la configurazione di estensioni funzionali (configurate nei punti di estensione definiti da un altro plug-in o introdotti da questo plug-in). Gli attributi <plugin> sono:
-
name - nome visualizzabile per l'utente (traducibile) per il plug-in
-
id - identificativo univoco per il plug-in.
-
Per ridurre i rischi di conflitti tra i nomi, è consigliabile far derivare l'identificativo dall'ID del dominio Internet del fornitore, invertendo i token dei nomi del dominio e aggiungendo ulteriori token dei nomi separati da un punto [.].
Ad esempio, il fornitore ibm.com potrebbe definire l'identificativo di plug-in com.ibm.db2
-
[regola di produzione: PlugInId]
-
version - numero di versione del plug-in. Per ulteriori dettagli, consultare org.eclipse.core.runtime.PluginVersionIdentifier. Il formato di versione del plug-in è major.minor.service. La modifica del componente principale viene considerata come una modifica di versione incompatibile.
La modifica del componente secondario è invece considerata una modifica compatibile.
La modifica del componente di servizio viene considerata un servizio aggiuntivo rispetto alla versione secondaria.
-
vendor-name - nome visualizzabile per l'utente del fornitore del plug-in.
-
class - nome della class di plug-in relativa a questo plug-in. Deve trattarsi di una sottoclasse di org.eclipse.core.runtime.Plugin.
La regola di costruzione DTD XML element* indica nessuna o più occorrenze dell'elemento; element? indica nessuna o una occorrenza dell'elemento; element+ (riportato di seguito) indica una o più occorrenze dell'elemento. Facendo riferimento alla precedente definizione <plugin>, si nota che un plug-in, contenente una sola definizione di esecuzione e nessuna dichiarazione di un punto di estensione o configurazione di estensione, è valido (ad esempio, librerie comuni da cui dipendono altri plug-in).
Analogamente, è valido anche un plug-in che contenga solo configurazioni di estensione e nessuna definizione di esecuzione o punto di estensione, come avviene, ad esempio, quando classi inviate in altri plug-in vengono configurate in punti di estensione dichiarati in altri plug-in.
La sezione del manifest <requires> riporta tutti gli elementi dipendenti da altri plug-in.
<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
plugin CDATA #REQUIRED
version CDATA #IMPLIED
match (exact | compatible) "compatible"
export (true | false) "false"
>
Ogni dipendenza viene specificata utilizzando un elemento <import>, che contiene i seguenti attributi:
-
plugin - identificativo del plug-in
-
version - specifica facoltativa della versione
-
match - regola di corrispondenza della versione. Inutile se non è specificato l'attributo della versione. Determina se la dipendenza si verifica solo con il plug-in della versione specificata, se possibile applicando un servizio ulteriore, oppure con qualsiasi versione compatibile, compresa una versione secondaria più recente del plug-in.
-
export - specifica se le classi del plug-in dipendente debbano essere visualizzate (riesportate) per l'utente dei questo plug-in. Per impostazione predefinita, le classi dipendenti non vengono esportate e quindi non sono visibili.
La sezione <runtime> del manifest contiene una definizione di una o più librerie che compongono l'esecuzione del plug-in.
Queste librerie vengono utilizzate dai meccanismi di esecuzione della piattaforma (il caricatore di classe del plug-in) per caricare ed eseguire il codice esatto necessario al plug-in.
<!ELEMENT runtime (library+)>
<!ELEMENT library (export*)>
<!ATTLIST library
name CDATA #REQUIRED
>
<!ELEMENT export EMPTY>
<!ATTLIST export
name CDATA #REQUIRED
>
L'elemento <runtime> non ha attributi.
Gli elementi <library> definiscono insieme l'esecuzione del plug-in. Almeno un elemento <library> deve essere specificato. Ogni elemento <library> possiede i seguenti attributi:
-
name - riferimento string a un file o a una directory che contiene classi, relative alla directory di installazione del plug-in. Questi riferimenti devono includere dei separatori tra i file.
Ogni elemento <library> può specificare la parte della libreria da esportare. Le regole di esportazione vengono specificate come un gruppo di maschere di esportazione. Per impostazione predefinita, dal momento che non è specificata nessuna regola di esportazione, la libreria viene considerata riservata.
Gli attributi degli elementi <export> sono:
-
name - specifica la maschera di esportazione. I valori validi sono:
-
* - indica che tutti i contenuti di una libreria vengono esportati (pubblica)
-
package-name.* - indica che tutte le classi del pacchetto specificato vengono esportate. Le regole di corrispondenza sono identiche alle regole di importazione Java.
-
class-name - nome completo di classe Java
L'architettura della piattaforma si basa sui punti di estensione configurabili. La piattaforma definisce un gruppo di punti di estensione che svolgono le attività di estensione della piattaforma e del desktop, come ad esempio l'aggiunta di voci di menu o l'inserimento di editor incorporati. In aggiunta ai punti di estensione predefiniti, ogni plug-in supportato può dichiarare ulteriori punti di estensione.
A questo scopo, il plug-in deve poter configurare la funzione plug-in con le estensioni fornite dall'esterno. Ad esempio, il plug-in Page Builder può dichiarare un punto di estensione per l'aggiunta di nuovi DTC (Design Time Control) nella propria tavolozza di costruzione.
In questo modo il plug-in definisce un'architettura per ciò che intende come DTC e implementa il codice che ricerca le estensioni DTC, configurato nei punti di estensione.
<!ELEMENT extension-point EMPTY>
<!ATTLIST extension-point
name CDATA #REQUIRED
id CDATA #REQUIRED
schema CDATA #IMPLIED
>
L'elemento <extension-point> presenta i seguenti attributi:
-
name - nome visualizzabile per l'utente (traducibile) del punto di estensione
-
id - token di ID semplice, univoco nel plug-in. Non può contenere punti (.) o spazi vuoti.
-
[regola di produzione: ExtensionPointId]
-
schema - specifica di schema relativa a questo punto di estensione. I dettagli corretti vengono definiti come parte del PDE (Plug-In Development Environment). Lo schema non viene utilizzato durante l'esecuzione. Il riferimento è un nome di file relativo alla posizione di installazione del plug-in.
Le estensioni attuali sono configurate nei punti di estensione (predefinite o dichiarate dal plug-in) nella sezione <extension>. Le informazioni di configurazione vengono specificate come XML correttamente formattati e contenuti tra i tag <extension> e </extension>. La piattaforma non specifica la forma attuale del tag di configurazione, salvo prevedere la corretta formattazione XML. I tag vengono definiti dalle informazioni ulteriori del plug-in che ha dichiarato il punto di estensione. La piattaforma, nel momento in cui la logica del punto di estensione richiede tutte le proprie estensioni configurate, non analizza i tag di configurazione, ma si limita a inviare le informazioni di configurazione al plug-in, come parte dell'elaborazione del punto di estensione.
<!ELEMENT extension ANY>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED
>
Gli attributi dell'elemento <extension> sono:
-
point - riferimento a un punto di estensione configurato. Il punto di estensione può essere definito sia da questo che da un altro plug-in.
-
[regola di produzione: ExtensionPointReference]
-
id - identificativo opzionale per questa istanza di configurazione del punto di estensione. Questo viene utilizzato da punti di estensione che devono identificare in modo univoco determinate estensioni configurate, senza limitarsi a contarle. L'identificativo viene specificato come un token semplice univoco nella definizione del plug-in che esegue la dichiarazione. Se utilizzato in modo globale, questo identificativo viene qualificato dall'identificativo del plug-in.
-
[regola di produzione: ExtensionId]
-
name - nome visualizzabile per l'utente (traducibile) dell'estensione
Importante: il contenuto dell'elemento <extension> viene dichiarato utilizzando la regola ANY. Così, ogni XML formattato correttamente può essere specificato nella sezione di configurazione dell'estensione (tra i tag <extension>
e </extension>).