Archivi di funzioni
Le informazioni relative alla creazione di pacchetti delle funzioni si
trovano in un .jar Java separato.
Le funzionalità standard dei jar Java vengono utilizzate per la
costruzione degli archivi di funzioni.
Gli archivi di funzioni fanno un riferimento separato agli archivi di
plug-in in pacchetti (consultare la sezione successiva) e ai file che non sono
plug-in.Le
funzioni vengono identificate mediante l'utilizzo di un
identificativo di struttura basato sul nome di dominio del provider
internet. Ad esempio, l'organizzazione eclipse.org produce la funzione
org.eclipse.jdt. L'insieme
di caratteri utilizzato per gli identificativi delle funzioni corrisponde
a quello utilizzato per gli identificativi di plug-in (consultare
Manifest di plug-in).
La convenzione consigliata per la denominazione degli archivi di
funzione è
<id>_<version>.jar
Dove <id> è l'identificativo della funzione e <version>
è l'identificativo della versione completa contenuta nella
rispettiva funzione.xml.
È importante notare che questa è una convenzione consigliata per ridurre
le probabilità di conflitto, ma non è richiesta dall'architettura di
Eclipse. Ad esempio, di seguito sono riportati alcuni nomi di archivi di
funzioni validi
org.eclipse.jdt_2.0.0.jar
org.eclipse.pde_2.0.jar
my_feature.jar
All'interno, ciascun archivio di funzioni è creato in pacchetti relativi
alla directory della funzione (ma senza includere l'elemento percorso directory). La struttura dell'archivio è quella riportata di seguito
feature.xml
feature<_locale>.properties (consultare "Translated Feature
Information")
altri file di funzione e sottodirectory (TBD)
META-INF/
manifest di jar Java e file di protezione
Manifest di funzione
Il formato del manifest di funzione viene definito dalla seguente
dichiarazione DTD:
<?xml encoding="ISO-8859-1"?>
<!ELEMENT feature (install-handler? | description? | copyright? |
license? | url? | includes* | requires? | plugin* | data*)>
<!ATTLIST feature
id CDATA #REQUIRED
version
CDATA #REQUIRED
label CDATA #IMPLIED
provider-name CDATA #IMPLIED
image
CDATA #IMPLIED
os CDATA
#IMPLIED
arch CDATA
#IMPLIED
ws CDATA
#IMPLIED
nl CDATA
#IMPLIED
colocation-affinity
CDATA #IMPLIED
primary
(true | false) "false"
exclusive (true | false)
"false"
plugin CDATA
#IMPLIED
application CDATA #IMPLIED
>
<!ELEMENT install-handler EMPTY>
<!ATTLIST install-handler
library
CDATA #IMPLIED
handler
CDATA #IMPLIED
>
<!ELEMENT description (#PCDATA)>
<!ATTLIST description
url
CDATA #IMPLIED
>
<!ELEMENT copyright (#PCDATA)>
<!ATTLIST copyright
url
CDATA #IMPLIED
>
<!ELEMENT license (#PCDATA)>
<!ATTLIST license
url
CDATA #IMPLIED
>
<!ELEMENT url (update?, discovery*)>
<!ELEMENT update EMPTY>
<!ATTLIST update
url
CDATA #REQUIRED
label CDATA #IMPLIED
>
<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
type
(web | update) "update"
url
CDATA #REQUIRED
label CDATA #IMPLIED
>
<!ELEMENT includes EMPTY>
<!ATTLIST includes
id CDATA #REQUIRED
version CDATA #REQUIRED
name
CDATA #IMPLIED
optional (true | false)
"false"
search-location (root | self | both)
"root"
match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"
>
<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
plugin
CDATA #IMPLIED
feature CDATA #IMPLIED
version
CDATA #IMPLIED
match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"
patch (true |
false) "false"
>
<!ELEMENT plugin EMPTY>
<!ATTLIST plugin
id CDATA #REQUIRED
version
CDATA #REQUIRED
fragment (true
| false) "false"
os CDATA
#IMPLIED
arch CDATA
#IMPLIED
ws CDATA
#IMPLIED
nl CDATA
#IMPLIED
download-size CDATA #IMPLIED
install-size CDATA #IMPLIED
>
<!ELEMENT data EMPTY>
<!ATTLIST data
id CDATA #REQUIRED
os CDATA
#IMPLIED
arch CDATA
#IMPLIED
ws CDATA
#IMPLIED
nl CDATA
#IMPLIED
download-size CDATA #IMPLIED
install-size CDATA #IMPLIED
>
Di seguito sono riportate le definizioni degli elementi e degli attributi:
-
<feature> - definisce la funzione
-
id - identificativo necessario della funzione (ad esempio com.xyz.myfeature)
-
version - versione necessaria del componente (ad esempio 1.0.3)
-
label - etichetta facoltativa visualizzabile (nome). Da utilizzare per la
traduzione.
-
provider-name - etichetta facoltativa di visualizzazione che identifica
l'organizzazione che fornisce questo componente. Da utilizzare per la
traduzione.
-
image - immagine facoltativa da utilizzare quando vengono visualizzate
informazioni relative alla funzione.
Specificata rispetto a feature.xml.
-
os - specifica facoltativa del sistema operativo. Elenco di identificativi del
sistema operativo, separati da una virgola, definito da Eclipse (consultare
Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa funzione dovrebbe essere installata solo su uno dei
sistemi operativi specificati. Se tale attributo non è specificato, è possibile
installare la funzione su tutti i sistemi (implementazione trasferibile). Questa informazione viene utilizzata come suggerimento dal
supporto di installazione e di aggiornamento (l'utente può forzare
l'installazione della funzione senza tener conto di tale impostazione).
-
arch - specifica facoltativa relativa all'architettura del computer. Elenco
di identificativi di architetture, separati da una virgola, definito da
Eclipse (consultare Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa funzione dovrebbe essere installata solo su uno dei
sistemi specificati. Se tale attributo non è specificato, è possibile
installare la funzione su tutti i sistemi (implementazione trasferibile). Questa informazione viene utilizzata come suggerimento dal
supporto di installazione e di aggiornamento (l'utente può forzare
l'installazione della funzione senza tener conto di tale impostazione).
-
ws - specifica facoltativa relativa ai sistemi a finestre. Elenco di
identificativi ws, separati da virgola, definito da Eclipse (consultare
Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa funzione dovrebbe essere installata solo su uno dei
sistemi ws specificati. Se tale attributo non è specificato, è possibile
installare la funzione su tutti i sistemi (implementazione trasferibile). Questa informazione viene utilizzata come suggerimento dal
supporto di installazione e di aggiornamento (l'utente può forzare
l'installazione della funzione senza tener conto di tale impostazione).
-
nl - specifica facoltativa relativa alla locale. Elenco
di identificativi della locale, separati da virgola,
definito da Java. Indica che questa funzione dovrebbe essere installata
solo su un sistema che utilizza un'impostazione internazionale compatibile
(che utilizza le regole di corrispondenza delle impostazioni
internazionali di Java). Se tale attributo non è specificato, è possibile
installare la funzione su tutti i sistemi (implementazione lingua di
sistema). Questa informazione viene utilizzata come suggerimento dal
supporto di installazione e di aggiornamento (l'utente può forzare
l'installazione della funzione senza tener conto di tale impostazione).
-
colocation-affinity - riferimento facoltativo a un altro
identificativo di funzione utilizzato per selezionare il percorso di
installazione predefinita per questa funzione. Quando questa funzione
viene installata come nuova funzione (non esistono altre versioni
installate), viene fatto un tentativo di installare tale funzione nello stesso
percorso di installazione della funzione di riferimento.
-
primary - indicazione facoltativa che specifica se è possibile
utilizzare questa funzione come funzione principale. Il valore predefinito è
false (non è una funzione principale).
-
application - identificativo facoltativo dell'applicazione Eclipse da
utilizzare durante la fase di avvio quando la funzione che viene dichiarata
è la funzione principale. L'identificativo dell'applicazione deve
rappresentare un'applicazione valida registrata nel punto di estensione
org.eclipse.core.runtime.applications. Il valore predefinito è
org.eclipse.ui.workbench.
-
plugin (nuovo in 2.1) - identificativo facoltativo che rappresenta l'id del
plug-in elencato nella funzione utilizzata per trasportare informazioni di
attribuzione sulla funzione (immagini, traduzioni, schermata iniziale nel caso di
funzione primaria, ecc.).
Se non specificato, si assume che il plug-in di attribuzione abbia lo stesso id
della funzione.
-
exclusive (nuovo in 2.1) - indicatore facoltativo che, se assume il
valore "true", indica che la funzione non può essere installata in un
gruppo con altre funzioni.
-
<install-handler>
-
library - libreria .jar facoltativa, contenente le classi del gestore di
installazione.
Se specificato, il .jar a cui si fa riferimento deve essere contenuto
nell'archivio di funzioni.
Viene specificato come un percorso all'interno dell'archivio di funzioni,
relativo alla voce feature.xml. Se invece non è specificato, sarà
utilizzato l'archivio di funzioni per caricare le classi del gestore di
installazione. Questo attributo viene interpretato solo se viene
specificato anche l'attributo class
-
handler - identificativo facoltativo del gestore di installazione. Il
valore viene interpretato relativamente al valore dell'attributo library. Se
library è specificato, il valore viene interpretato come il
nome completo di una classe contenuta nel library specificato. Se
invece library non è specificato, il valore viene interpretato come
un identificativo di estensione registrato nel punto di estensione
org.eclipse.update.installHandlers. In entrambi i casi la classe
risultante deve implementare l'interfaccia IInstallHandler. La
classe viene caricata in maniera dinamica e chiamata in punti specifici
durante l'elaborazione della funzione. Il gestore ha accesso alle classi
API dal plug-in di aggiornamento e dai plug-in di Eclipse richiesti dal plug-in di aggiornamento.
-
<description> - breve descrizione del componente come testo semplice. Da
utilizzare per la traduzione.
-
url - URL facoltativo per la descrizione completa come HTML. È possibile
specificare l'URL come assoluto o relativo. Se relativo, è presumibile che
corrisponda all'archivio di funzioni (e che sia nel relativo pacchetto). Si
noti che per la gestione delle lingue nazionali il valore di URL deve essere
separato per consentire di specificare URL alternativi per ciascuna lingua.
-
<copyright> - copyright di funzione come testo semplice. Da utilizzare per
la traduzione.
-
url - URL facoltativo per la descrizione completa come HTML. È possibile
specificare l'URL come assoluto o relativo. Se relativo, è presumibile che
corrisponda all'archivio di funzioni (e che sia nel relativo pacchetto). Si
noti che per la gestione delle lingue nazionali il valore di URL deve essere
separato per consentire di specificare URL alternativi per ciascuna lingua.
-
<license> - funzione di "accettazione a schermo" della licenza come
testo semplice. Da utilizzare per la traduzione. Viene visualizzata in una finestra di dialogo standard
con le azioni [Accept] [Reject] durante il processo di
scaricamento/installazione. Occorre
notare che l'accettazione a schermo della licenza deve essere specificata
per qualsiasi funzione che verrà selezionata per l'installazione o
l'aggiornamento con il gestore aggiornamenti di Eclipse. Quando vengono
utilizzate funzioni nidificate, è necessario che solo la nidificazione
principale (ad esempio la funzione selezionata per l'installazione o
l'aggiornamento) abbia un testo definito di licenza con accettazione a schermo. Il
testo della licenza è richiesto anche nel caso in cui venga specificato
l'attributo facoltativo url.
-
url - URL facoltativo per la descrizione completa come HTML. È possibile
specificare l'URL come assoluto o relativo. Se relativo, è presumibile che
corrisponda all'archivio di funzioni (e che sia nel relativo pacchetto). Si
noti che per la gestione delle lingue nazionali il valore di URL deve essere
separato per consentire di specificare URL alternativi per ciascuna lingua. È necessario inoltre notare
che il "contenuto" di questo URL non corrisponde a quello che
viene presentato come la licenza con accettazione a schermo durante il
processo di installazione. La licenza con accettazione a schermo
rappresenta il valore effettivo dell'elemento <license>
(ad esempio <license>click
through text</license>)
-
<url> - URL facoltativo che specifica i siti che contengono
aggiornamenti delle funzioni o nuove funzioni
-
<update> - URL cui collegarsi per aggiornare questa funzione
-
url - URL corrente
-
label - etichetta visualizzabile (nome) del sito indicato
-
<discovery> - URL cui collegarsi per nuove funzioni. In genere un
fornitore utilizza questo collegamento per fare riferimento al proprio
sito o ai siti dei partner che offrono funzioni complementari. La piattaforma
Eclipse utilizza questo elemento semplicemente per distribuire nuovi URL ai
client. I siti che appartengono a funzioni principali (al livello superiore
della gerarchia) sono generalmente visualizzati in "Siti da visitare" in
Gestore aggiornamenti.
-
url - URL corrente
-
label - etichetta visualizzabile (nome) del sito indicato
-
type (nuovo in 2.1) - per impostazione predefinita, i siti di
esplorazione sono considerati siti di aggiornamento ("update"). Impostando
il valore di questo attributo a "web", è possibile indicare a Eclipse
che l'URL deve essere considerata un normale collegamento Web ipertestuale che
può essere visualizzato direttamente in un browser.
-
<includes> - riferimento facoltativo a una funzione nidificata
che viene considerata parte di questa funzione. Le funzioni nidificate
devono essere posizionate nello stesso sito di aggiornamento di questa
funzione
-
id - identificativo della funzione nidificata obbligatorio
-
version - versione della funzione nidificata obbligatoria
-
optional (nuovo in 2.1) - se questo attributo è "true", è possibile
includere una funzione come facoltativa. Gli utenti possono non installare le
funzioni facoltative, disabilitarle se sono installate e installarle
successivamente. Una funzione facoltativa mancante non è considerata un errore.
-
name (nuovo in 2.1) - se manca una funzione facoltativa, Eclipse non può
utilizzare il nome correttamente. Questo attributo può essere utilizzato
come "segnaposto" per consentire a Eclipse di gestire il nome della funzione
facoltativa quando questa non è installata.
-
match (nuovo in 2.1) - se una funzione è inclusa con match="perfect"
(il valore predefinito), deve esistere la versione esatta per soddisfare la
condizione.
Al contrario, altri valori ("compatible", "equivalent" ecc.) consentono
una maggiore flessibilità. Impostare l'attributo ad un valore diverso da
"perfect" è essenziale se si vuole consentire l'aggiornamento o la
creazione di sezioni.
-
search-location (nuovo in 2.1) - se match è impostato ad un valore diverso da
"perfect", una funzione inclusa può essere aggiornata entro i limiti
posti dall'attributo "match". Per impostazione predefinita, il
percorso di ricerca è "root", ovvero verrà considerato l'URL
specificato nell'elemento "update" all'interno dell'elemento
"url" principale. Se una funzione inclusa ha definito
un proprio elemento "update", questo sarà ignorato.
Se la funzione principale vuole consentire alla funzione secondaria di essere
aggiornata dal proprio percorso, deve impostare questo attributo a
"both" o "self".
-
<requires> - informazioni facoltative sulle dipendenze della funzione. Vengono
espresse in termini di dipendenze dei plug-in. Se specificato, vengono
imposte dal supporto di installazione e aggiornamento al momento
dell'installazione
-
<import> - voce di dipendenza. Specifica ed elaborazione rappresentano un
sottoinsieme della specifica <import> nel plugin.xml
-
<plugin> - identifica il plug-in referenziato
-
id - identificativo obbligatorio del plug-in (da plugin.xml)
-
version - versione obbligatoria del plug-in (da plugin.xml)
-
fragment - specifica facoltativa che indica se questa voce è un frammento
di plug-in. Il valore predefinito è "falso"
-
os - specifica facoltativa del sistema operativo. Elenco di identificativi
di sistemi operativi, separati da una virgola, definito da Eclipse (consultare
Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa voce dovrebbe essere installata solo su uno dei sistemi
operativi specificati. Se tale attributo non è specificato, è possibile
installare la voce su tutti i sistemi (implementazione trasferibile). Questa informazione
viene utilizzata come suggerimento dal supporto di installazione e di
aggiornamento (l'utente può forzare
l'installazione della voce senza tener conto di tale impostazione).
-
arch - specifica facoltativa relativa all'architettura del computer. Elenco
di identificativi di architetture, separati da una virgola, definito da
Eclipse (consultare Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa funzione dovrebbe essere installata solo su uno dei
sistemi specificati. Se tale attributo non è specificato, è possibile
installare la funzione su tutti i sistemi (implementazione trasferibile). Questa informazione viene utilizzata come suggerimento dal
supporto di installazione e di aggiornamento (l'utente può forzare
l'installazione della funzione senza tener conto di tale impostazione).
-
ws - specifica facoltativa relativa ai sistemi a finestre. Elenco di
identificativi ws, separati da virgola, definito da Eclipse (consultare
Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa voce dovrebbe essere installata solo su uno dei sistemi
ws specificati. Se tale attributo non è specificato, è possibile
installare la voce su tutti i sistemi (implementazione trasferibile). Questa informazione
viene utilizzata come suggerimento dal supporto di installazione e di
aggiornamento (l'utente può forzare
l'installazione della voce senza tener conto di tale impostazione).
-
nl - specifica facoltativa relativa alle impostazioni internazionali. Elenco
di identificativi delle impostazioni internazionali, separati da virgola,
definito da Java. Indica che questa voce dovrebbe essere installata solo
su un sistema che utilizza un'impostazione internazionale compatibile
(che utilizza le regole di corrispondenza delle impostazioni internazionali di Java). Se tale attributo non è specificato, è possibile installare la voce su
tutti i sistemi (implementazione lingua di sistema). Questa informazione
viene utilizzata come suggerimento dal supporto di installazione e di
aggiornamento (l'utente può forzare
l'installazione della voce senza tener conto di tale impostazione).
-
download-size - suggerimento facoltativo fornito dal packager della
funzione, che indica le dimensioni in KB dell'archivio di
plug-in da scaricare. Se non è specificato, le dimensioni non sono note (Nota di implementazione: è necessario che
l'implementazione distingua tra "non noto" e dimensione 0)
-
install-size - suggerimento facoltativo fornito dal packager della
funzione, che indica le dimensioni di installazione in KB dell'archivio di
plug-in a cui si fa riferimento. Se non è specificato, le
dimensioni di installazione non sono note (Nota di implementazione:
è necessario che l'implementazione distingua tra "non noto" e dimensione 0)
-
<data> - identifica dati non di plug-in che fanno parte della funzione
-
id - identificativo necessario di dati sotto forma di percorso relativo.
-
os - specifica facoltativa del sistema operativo. Elenco di identificativi del
sistema operativo, separati da una virgola, definito da Eclipse (consultare
Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa voce dovrebbe essere installata solo su uno dei sistemi
operativi specificati. Se tale attributo non è specificato, è possibile
installare la voce su tutti i sistemi (implementazione trasferibile). Questa informazione
viene utilizzata come suggerimento dal supporto di installazione e di
aggiornamento (l'utente può forzare
l'installazione della voce senza tener conto di tale impostazione).
-
arch - specifica facoltativa relativa all'architettura del computer. Elenco
di identificativi di architetture, separati da una virgola, definito da
Eclipse (consultare Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa funzione dovrebbe essere installata solo su uno dei
sistemi specificati. Se tale attributo non è specificato, è possibile
installare la funzione su tutti i sistemi (implementazione trasferibile). Questa informazione viene utilizzata come suggerimento dal
supporto di installazione e di aggiornamento (l'utente può forzare
l'installazione della funzione senza tener conto di tale impostazione).
-
ws - specifica facoltativa relativa ai sistemi a finestre. Elenco di
identificativi ws, separati da virgola, definito da Eclipse (consultare
Javadoc per org.eclipse.core.boot.BootLoader).
Indica che questa voce dovrebbe essere installata solo su uno dei sistemi
ws specificati. Se tale attributo non è specificato, è possibile
installare la voce su tutti i sistemi (implementazione trasferibile). Questa informazione
viene utilizzata come suggerimento dal supporto di installazione e di
aggiornamento (l'utente può forzare
l'installazione della voce senza tener conto di tale impostazione).
-
nl - specifica facoltativa relativa alle impostazioni internazionali. Elenco
di identificativi delle impostazioni internazionali, separati da virgola,
definito da Java. Indica che questa voce dovrebbe essere installata solo
su un sistema che utilizza un'impostazione internazionale compatibile
(che utilizza le regole di corrispondenza delle impostazioni internazionali di Java). Se tale attributo non è specificato, è possibile installare la voce su
tutti i sistemi (implementazione lingua di sistema). Questa informazione
viene utilizzata come suggerimento dal supporto di installazione e di
aggiornamento (l'utente può forzare
l'installazione della voce senza tener conto di tale impostazione).
-
download-size - suggerimento facoltativo fornito dal packager della
funzione, che indica le dimensioni in KB dell'archivio di
dati cui si fa riferimento. Se non è specificato, le dimensioni non sono note (Nota di implementazione: è necessario che
l'implementazione distingua tra "non noto" e dimensione 0)
-
install-size - suggerimento facoltativo fornito dal packager della
funzione, che indica le dimensioni di installazione in KB
dell'archivio di dati cui si fa riferimento. Se non è specificato, le
dimensioni di installazione non sono note (Nota di implementazione:
è necessario che l'implementazione distingua tra "non noto" e dimensione 0)
Quando si interagisce con il sito di aggiornamento, l'implementazione
della funzione associa gli elementi <plugin> e
<data> in identificativi di percorso utilizzati dal sito
per determinare quali siano i file effettivi da scaricare e installare. L'implementazione
della funzione predefinita fornita da Eclipse costruisce gli
identificativi di percorso come riportato di seguito:
-
L'elemento <plugin> determina una voce di percorso nel formato
"plugins/<pluginId>_<pluginVersion>.jar"
(ad esempio, "plugins/org.eclipse.core.boot_2.0.0.jar")
-
L'elemento <data> determina una voce di percorso nel formato
"features/<featureId>_<featureVersion>/<dataId>"
(ad esempio, "features/com.xyz.tools_1.0.3/examples.zip")
In generale, i documenti manifest di funzione.xml devono specificare
la codifica UTF-8. Ad esempio
<?xml version="1.0" encoding="UTF-8"?>
È possibile separare il testo traducibile contenuto nella
funzione.xml, nei file feature<_locale>.properties utilizzando le
convenzioni dell'insieme delle proprietà Java.
Si noti che le stringhe tradotte vengono utilizzate al momento dell'installazione (ad esempio, non adoperano il meccanismo di run-time del frammento di plug-in).