Archivi di funzioni
Le informazioni relative all'impacchettamento 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 assemblati (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, organization 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.
E' 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 è assemblato rispetto
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"
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
url CDATA
#REQUIRED
label CDATA #IMPLIED
>
<!ELEMENT includes EMPTY>
<!ATTLIST includes
id CDATA #REQUIRED
version
CDATA #REQUIRED
>
<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
plugin CDATA #REQUIRED
version
CDATA #IMPLIED
match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"
>
<!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). Deve
essere tradotto.
-
provider-name - etichetta facoltativa di visualizzazione che identifica
l'organizzazione che fornisce questo componente. Deve
essere tradotto.
-
image - immagine facoltativa da utilizzare quando vengono visualizzate
informazioni relative alla funzione. Specificata rispetto alla
funzione.xml.
-
os - specifica facoltativa del sistema operativo. Elenco di identificativi
os, 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 os 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 alle impostazioni internazionali. Elenco
di identificativi delle impostazioni internazionali, 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 la posizione 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 nella
stessa posizione di installazione della funzione di riferimento.
-
primary - indicazione facoltativa che specifica se è possibile
utilizzare questa funzione come funzione principale. Predefinito se
falso (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 predefinito è org.eclipse.ui.workbench.
-
<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
plugin di aggiornamento.
-
<description> - breve descrizione del componente come testo semplice. Deve
essere tradotto.
-
url - URL facoltativo per la descrizione completa come HTML. E' possibile
specificare l'URL come assoluto o relativo. Se relativo, è presumibile che
corrisponda all'archivio di funzioni (e che in questo sia compresso) compresso). Occorre notare che per la gestione di NL il
valore dell'URL dovrebbe essere separato in modo da consentire che siano
specificati URL alternati per ciascuna lingua nazionale.
-
<copyright> - copyright di funzione come testo semplice. Deve
essere tradotto.
-
url - URL facoltativo per la descrizione completa come HTML. E' possibile
specificare l'URL come assoluto o relativo. Se relativo, è presumibile che
corrisponda all'archivio di funzioni (e che in questo sia compresso) compresso). Occorre notare che per la gestione di NL il
valore dell'URL dovrebbe essere separato in modo da consentire che siano
specificati URL alternati per ciascuna lingua nazionale.
-
<license> - funzione di "accettazione a schermo" della licenza come
testo semplice. Deve essere tradotta. Viene visualizzata in una finestra di dialogo standard
con le azioni [Accept] [Reject] durante il processo di download/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. E' possibile
specificare l'URL come assoluto o relativo. Se relativo, è presumibile che
corrisponda all'archivio di funzioni (e che in questo sia compresso) .
Occorre notare che per la gestione di NL il valore dell'URL
dovrebbe essere separato in modo da consentire che siano specificati URL
alternati per ciascuna lingua nazionale. E' 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
provider 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.
-
url - URL corrente
-
label - etichetta visualizzabile (nome) del sito indicato
-
<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 necessario della funzione nidificata
-
<version> - versione necessaria della funzione nidificata
-
<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 - identificativo del plug-in dipendente
-
version - specifica facoltativa della versione del plug-in
-
match - regola di corrispondenza facoltativa. I valori validi e
l'elaborazione sono quelli riportati di seguito:
-
Se l'attributo della versione non viene specificato, l'attributo
di corrispondenza (se specificato) verrà ignorato.
-
perfect - la versione del plug-in dipendente deve
corrispondere esattamente alla versione specificata.
-
equivalent - la versione del plug-in dipendente deve essere
almeno al livello della versione specificata o a un livello di servizio
superiore (i livelli di versione principale e secondario devono
uguagliare la versione specificata).
-
compatible - la versione del plug-in dipendente deve
essere almeno al livello della versione specificata, oppure a un livello di
servizio superiore o a un livello secondario (il livello della versione
principale deve uguagliare la versione specificata).
-
greaterOrEqual - la versione del plug-in dipendente deve
essere almeno al livello della versione specificata, o a un livello
principale o secondario di servizio superiore.
-
<plugin> - identifica il plug-in referenziato
-
id - identificativo necessario del plug-in (da plugin.xml)
-
version - versione necessaria 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
os, 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
os 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 del download in KB dell'archivio di
plug-in a cui si fa riferimento. Se non è specificato, le dimensioni del
download 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 plugin che fanno parte della funzione
-
id - identificativo necessario di dati sotto forma di percorso relativo.
-
os - specifica facoltativa del sistema operativo. Elenco di identificativi
os, 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
os 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 del download in KB dell'archivio di
dati cui si fa riferimento. Se non è specificato, le dimensioni del
download 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"?>
E' possibile separare il testo traducibile contenuto nella
funzione.xml, nei file feature<_locale>.properties utilizzando le
convenzioni dell'insieme delle proprietà Java.
Occorre notare che le stringhe tradotte vengono utilizzate al momento
dell'installazione (ovvero, non utilizzare il meccanismo di run-time
relativo ai frammenti di plug-in).