Archives de fonctions
Les informations de regroupement des fonctions sont placées dans un
fichier .jar Java distinct.
Les fonctions .jar Java standard sont utilisées pour la création des
archives de fonctions.
Les archives de fonctions font référence à des archives de plug-in
mis en forme séparément (voir section suivante) et à des fichiers
autres que des fichiers de plug-in.Les fonctions
sont identifiées à l'aide d'un identificateur structuré, fondé sur
le nom du domaine Internet du fournisseur. Par exemple,
l'organisation eclipse.org génère la fonction org.eclipse.jdt. Le
jeu de caractères utilisé pour les identificateurs de fonction
correspond à celui spécifié pour les identificateurs de plug-in
(reportez-vous à la rubrique Manifeste des plug-in).
La convention recommandée pour l'attribution du nom des
archives de fonction est la suivante :
<id>_<version>.jar
<id> correspondant à l'identifiant de fonction et
<version> à l'identifiant de la version intégrale contenu
dans le fichier feature.xml respectif.
Cette convention recommandée
minimise les chances de collision, mais elle n'est pas requise par
l'architecture Eclipse. Par exemple, les noms d'archive de fonction suivants sont
valides :
org.eclipse.jdt_2.0.0.jar
org.eclipse.pde_2.0.jar
ma_fonction.jar
En interne, chaque archive de fonction est mise en forme par
rapport à son répertoire de fonctions (mais sans inclure le chemin du répertoire). La structure de l'archive est la suivante :
feature.xml
feature<_locale>.properties (voir "Informations traduites sur les fonctions")
autres sous-répertoires et fichiers de fonctions (à déterminer)
META-INF/
Fichiers de sécurité et de manifeste jar Java
Manifeste de fonctions
Le format du manifeste des fonctions est défini par la DTD
suivante :
<?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
>
Les définitions d'élément et d'attribut sont les suivantes :
-
<feature> : définit la fonction
-
id : identificateur de fonction requis (par exemple,
com.xyz.myfeature)
-
version : version de composant requise (par exemple, 1.0.3)
-
label : libellé (nom) affichable et facultatif. A traduire.
-
provider-name : libellé d'affichage facultatif, identifiant
l'organisation fournissant ce composant. A traduire.
-
image : image facultative à utiliser lors de l'affichage des
informations sur la fonction.
Spécifiée par rapport à feature.xml.
-
os : spécification facultative du système d'exploitation. Liste
de désignateurs de système d'exploitation, séparés par des virgules,
définie par Eclipse (reportez-vous au Javadoc
pour org.eclipse.core.boot.BootLoader).
Indique que cette fonction ne doit être installée que sur l'un des
systèmes d'exploitation spécifiés. Si cet attribut n'est pas indiqué, la fonction peut être
installée sur tous les systèmes (implémentation portable). Ces informations fournissent des
recommandations utiles au support d'installation et de mise à jour
(l'utilisateur peut forcer l'installation
d'une fonction quelle que soit la valeur de ce paramètre).
-
arch : spécification facultative de
l'architecture de la machine. Liste de désignateurs d'architecture,
séparés par des virgules, définie par Eclipse (reportez-vous au
Javadoc pour org.eclipse.core.boot.BootLoader).
Indique que cette fonction ne doit être installée que sur l'un des
systèmes spécifiés. Si cet attribut n'est pas indiqué, la fonction peut être
installée sur tous les systèmes (implémentation portable). Ces informations fournissent des
recommandations utiles au support d'installation et de mise à jour
(l'utilisateur peut forcer l'installation
d'une fonction quelle que soit la valeur de ce paramètre).
-
ws : spécification facultative du système de fenêtrage. Liste de
désignateurs de système de fenêtrage, séparés par des virgules,
définie par Eclipse (reportez-vous au Javadoc
pour org.eclipse.core.boot.BootLoader).
Indique que cette fonction ne doit être installée que sur l'un des
systèmes de fenêtrage spécifiés. Si cet attribut n'est pas indiqué, la fonction peut être
installée sur tous les systèmes (implémentation portable). Ces informations fournissent des
recommandations utiles au support d'installation et de mise à jour
(l'utilisateur peut forcer l'installation
d'une fonction quelle que soit la valeur de ce paramètre).
-
nl : spécification facultative des paramètres régionaux. Liste
de désignateurs de paramètre régional, séparés par des
virgules, définie par Java. Indique que cette fonction ne doit être installée
que sur un système dont les paramètres régionaux sont compatibles
(à l'aide des règles Java pour la correspondance des paramètres
régionaux). Si cet attribut n'est pas indiqué, la fonction peut être
installée sur tous les systèmes (implémentation
indépendante de la langue choisie). Ces informations fournissent des
recommandations utiles au support d'installation et de mise à jour
(l'utilisateur peut forcer l'installation
d'une fonction quelle que soit la valeur de ce paramètre).
-
colocation-affinity : Référence facultative à un autre
identificateur de fonction utilisée permettant de sélectionner le
répertoire d'installation par défaut de cette fonction. Si cette
fonction est installée comme nouvelle fonction (aucune autre version
de cette fonction n'est installée), le système tente de l'installer
dans le même répertoire d'installation que la
fonction référencée.
-
primary : indication facultative spécifiant si cette fonction
peut être utilisée comme fonction principale. Valeur par défaut : false
(fonction non principale).
-
application : identificateur facultatif de l'application Eclipse
à utiliser au démarrage si la fonction de déclaration correspond à
la fonction principale. L'identificateur d'application doit
représenter une application valide enregistrée
dans le point d'extension org.eclipse.core.runtime.applications. Valeur
par défaut : org.eclipse.ui.workbench.
-
plugin (nouveau dans 2.1) : identificateur facultatif qui représente l'ID du plug-in
répertorié dans le dispositif utilisé pour acheminer des informations d'attribution pour le dispositif (images, conversions, écrans d'accueil dans le cas d'un dispositif principal, etc.).
S'il est pas spécifié, l'hypothèse est que le plug-in d'attribution a le même ID que le dispositif.
-
exclusive (nouveau dans 2.1) : indicateur facultatif qui, s'il a la valeur "true", indique que le dispositif ne peut pas être installé dans un groupe avec d'autres dispositifs.
-
<install-handler>
-
library : bibliothèque .jar facultative contenant les
classes du gestionnaire d'installation.
S'il est spécifié, le fichier .jar référencé doit se trouver dans
l'archive des fonctions.
Il est spécifié comme chemin, dans l'archive des fonctions,
par rapport à l'entrée feature.xml. S'il n'est pas spécifié,
l'archive de fonctions est utilisée pour charger les classes
du gestionnaire d'installation. Cet attribut n'est interprété que si
l'attribut class est également spécifié
-
handler : identificateur facultatif du gestionnaire
d'installation. La valeur est interprétée en fonction de la valeur de
l'attribut library. Si l'attribut library
est spécifié, elle est interprétée comme nom complet d'une classe de
la bibliothèque spécifiée. Si library
n'est pas spécifié, la valeur est interprétée comme identificateur de
l'extension enregistrée dans le point d'extension org.eclipse.update.installHandlers. Dans
tous les cas, la classe résultante doit implémenter l'interface IInstallHandler. La
classe est chargée et appelée dynamiquement à des points
spécifiques lors du traitement des fonctions. Le gestionnaire a accès
aux classes de l'API du plug-in de mise à jour et aux plug-in
Eclipse requis par le plug-in de mise à jour.
-
<description> : brève description de composant sous forme de texte
simple. A traduire.
-
url : URL facultative de la description intégrale, sous forme
de fichier HTML. L'URL peut être spécifiée comme complète ou relative. Si elle est relative, elle l'est par
rapport à l'archive des fonctions (dans laquelle elle mise en forme). Pour le traitement des versions localisées, la valeur de l'URL
doit être séparée afin d'autoriser la spécification d'une autre URL
pour chaque langue.
-
<copyright> : copyright des fonctions sous forme de texte simple. A traduire.
-
url : URL facultative de la description intégrale, sous forme
de fichier HTML. L'URL peut être spécifiée comme complète ou relative. Si elle est relative, elle l'est par
rapport à l'archive des fonctions (dans laquelle elle mise en forme). Pour le traitement des versions localisées, la valeur de l'URL
doit être séparée afin d'autoriser la spécification d'une autre URL
pour chaque langue.
-
<license> : licence de fonction "click-through" sous
forme de texte simple. A
traduire. Affichée dans une boîte de dialogue standard avec des
actions [Accept] [Reject] lors du processus de
téléchargement/d'installation. La licence "click-through" doit
être spécifiée pour toute fonction à installer ou mettre à jour
à l'aide du gestionnaire de mise à jour Eclipse. Lors de
l'utilisation de fonctions imbriquées, le texte de la licence
click-through ne doit être défini que sur le parent
imbriquant (fonction sélectionnée pour l'installation ou la mise à
jour). Le texte de la licence
est requis même si l'attribut facultatif url est
spécifié.
-
url : URL facultative de la description intégrale, sous forme
de fichier HTML. L'URL peut être spécifiée comme complète ou relative. Si elle est relative, elle l'est par
rapport à l'archive des fonctions (dans laquelle elle mise en forme). Pour le traitement des versions localisées, la valeur de l'URL doit
être séparée afin d'autoriser la spécification d'une autre URL pour
chaque langue. Le "contenu" de cette URL ne correspond
pas à ce qui qui est présenté comme licence "click-through"
lors du processus d'installation. La licence "click-through"
représente la véritable valeur de l'élément <license> (par
exemple, <license>click through text</license>)
-
<url> : URL facultative, spécifiant un ou des site(s)
contenant des mises à jour de fonction ou de nouvelles
fonctions
-
<update> : URL permettant d'atteindre les
mises à jour de cette fonction
-
url : URL réelle
-
label : libellé affichable (nom) du site référencé
-
<discovery> : URL permettant
d'accéder à de nouvelles fonctions. En règle générale, un fournisseur
peut utiliser cet élément pour faire référence à son ou ses propre(s)
site(s), ou à ceux de partenaires qui offrent des fonctions complémentaires. Eclipse utilise simplement cet élément comme moyen de distribution des nouvelles URL du site aux clients. Les sites qui appartiennent aux dispositifs racine (situé en haut de la hiérarchie) figurent généralement dans le dossier "Sites à visiter" du gestionnaire des mises à jour.
-
url : URL réelle
-
label : libellé affichable (nom) du site référencé
-
type (nouveau dans 2.1) : par défaut, les sites de recherches sont supposés être des sites de mise à jour ("update"). En affectant à cet attribut la valeur "web",
il est possible d'indiquer à Eclipse que l'URL doit être traitée comme un lien hypertexte Web ordinaire pouvant s'afficher directement dans un navigateur approprié.
-
<includes> : référence facultative à une fonction imbriquée
considérée comme faisant partie de cette fonction. Les fonctions
imbriquées doivent se trouver dans le même site de mise à jour que
cette fonction
-
id : identificateur de fonction imbriquée requis
-
version : version de fonction imbriquée requise
-
optional (nouveau dans 2.1) : il est possible d'inclure un dispositif comme étant en option lorsque cet attribut a pour valeur "true". Les utilisateurs sont autorisés à ne pas installer de dispositifs en option ; désactivez-les s'ils sont installés et installez-les plus tard.
Un dispositif en option manquant n'est pas considéré comme unie erreur.
-
name (nouveau dans 2.1) : si un dispositif en option est manquant, Eclipse ne peut pas afficher son nom correctement.
Cet attribut peut être utilisé comme 'marque de réservation' pour autoriser Eclipse
à afficher le nom du dispositif en option lorsque celui-ci n'est pas installé.
-
match (nouveau dans 2.1) : si un dispositif est inclus avec l'attribut match="perfect"
(valeur par défaut), il faut que la version exacte existe pour satisfaire la référence.
En revanche, les autres valeurs ("compatible", "equivalent", etc.)
permettent une certaine souplesse. Il est essentiel d'affecter à cet attribut une valeur autre que "perfect" si vous souhaitez autoriser la mise à jour ou la correction des branches.
-
search-location (nouveau dans 2.1) : si match a une valeur autre que "perfect", un dispositif inclus peut
être mis à jour dans les limites définies par l'attribut "match". Par défaut, la valeur de search location est
"root", ce qui signifie que l'URL spécifiée dans l'élément "update" à l'intérieur de l'élément
"url" du parent sera prise en considération. Si un dispositif inclus
a son propre élément "update" défini, il sera ignoré par défaut.
Si le dispositif parent souhaite autoriser la mise à jour de l'enfant à partir de son propre emplacement, il peut affecter
à cet attribut la valeur "both" ou "self".
-
<requires> : informations facultatives sur les dépendances
des fonctions. Exprimées en termes de dépendances de plug-in. Si
elles sont spécifiées, elles sont appliquées par le support d'installation
et de mise à jour lors de l'installation
-
<import> : entrée de dépendance. La spécification et le
traitement sont des sous-ensembles de la spécification <import>
dans plugin.xml
-
<plugin> : identifie le plug-in référencé
-
id : identificateur de plug-in requis (depuis plugin.xml)
-
version : version de plug-in requise (depuis plugin.xml)
-
fragment : spécification facultative indiquant si cette
entrée correspond à un fragment de plug-in. Valeur par défaut : "false"
-
os : spécification facultative du système d'exploitation. Liste
de désignateurs de système d'exploitation, séparés par des virgules,
définie par Eclipse (reportez-vous au Javadoc
pour org.eclipse.core.boot.BootLoader).
Indique que cette entrée ne doit être installée que sur l'un des
systèmes d'exploitation spécifiés. Si cet attribut n'est pas indiqué, l'entrée peut être
installée sur tous les systèmes (implémentation portable). Ces
informations fournissent des recommandations utiles au support
d'installation et de mise à jour (l'utilisateur peut forcer
l'installation d'une entrée quelle que soit la valeur de ce paramètre).
-
arch : spécification facultative de
l'architecture de la machine. Liste de désignateurs d'architecture,
séparés par des virgules, définie par Eclipse (reportez-vous au
Javadoc pour org.eclipse.core.boot.BootLoader).
Indique que cette fonction ne doit être installée que sur l'un des
systèmes spécifiés. Si cet attribut n'est pas indiqué, la fonction peut être
installée sur tous les systèmes (implémentation portable). Ces informations fournissent des
recommandations utiles au support d'installation et de mise à jour
(l'utilisateur peut forcer l'installation
d'une fonction quelle que soit la valeur de ce paramètre).
-
ws : spécification facultative du système de fenêtrage. Liste de
désignateurs de système de fenêtrage, séparés par des virgules,
définie par Eclipse (reportez-vous au Javadoc
pour org.eclipse.core.boot.BootLoader).
Indique que cette entrée ne doit être installée que sur l'un des
systèmes de fenêtrage spécifiés. Si cet attribut n'est pas indiqué, l'entrée peut être
installée sur tous les systèmes (implémentation portable). Ces
informations fournissent des recommandations utiles au support
d'installation et de mise à jour (l'utilisateur peut forcer
l'installation d'une entrée quelle que soit la valeur de ce paramètre).
-
nl : spécification facultative des paramètres régionaux. Liste
de désignateurs de paramètre régional, séparés par des
virgules, définie par Java. Indique que cette entrée ne doit être
installée que sur un système dont les paramètres régionaux sont
compatibles (à l'aide
des règles Java pour la correspondance des paramètres régionaux). Si
cet attribut n'est pas indiqué, l'entrée peut être installée sur tous
les systèmes (implémentation indépendante de la langue choisie). Ces
informations fournissent des recommandations utiles au support
d'installation et de mise à jour (l'utilisateur peut forcer
l'installation d'une entrée quelle que soit la valeur de ce paramètre).
-
download-size : conseil facultatif fourni par l'outil de mise
en forme, indiquant la taille du téléchargement en kilo-octets de
l'archive de plug-in référencée. Si elle n'est pas spécifiée, la
taille du téléchargement est inconnue (Remarque sur
l'implémentation : l'implémentation doit faire la
différence entre une taille "inconnue" et une taille de 0)
-
install-size : conseil facultatif fourni par l'outil de mise en
forme, indiquant la taille de l'installation en kilo-octets de
l'archive de plug-in référencée. Si elle n'est pas spécifiée, la
taille de l'installation est inconnue (Remarque sur
l'implémentation : l'implémentation doit faire la
différence entre une taille "inconnue" et une taille de 0)
-
<data> : identifie les données autres que les données de
plugin faisant partie de la fonction
-
id : identificateur de données requis, sous la forme de chemin
relatif.
-
os : spécification facultative du système d'exploitation. Liste
de désignateurs de système d'exploitation, séparés par des virgules,
définie par Eclipse (reportez-vous au Javadoc
pour org.eclipse.core.boot.BootLoader).
Indique que cette entrée ne doit être installée que sur l'un des
systèmes d'exploitation spécifiés. Si cet attribut n'est pas indiqué, l'entrée peut être
installée sur tous les systèmes (implémentation portable). Ces
informations fournissent des recommandations utiles au support
d'installation et de mise à jour (l'utilisateur peut forcer
l'installation d'une entrée quelle que soit la valeur de ce paramètre).
-
arch : spécification facultative de
l'architecture de la machine. Liste de désignateurs d'architecture,
séparés par des virgules, définie par Eclipse (reportez-vous au
Javadoc pour org.eclipse.core.boot.BootLoader).
Indique que cette fonction ne doit être installée que sur l'un des
systèmes spécifiés. Si cet attribut n'est pas indiqué, la fonction peut être
installée sur tous les systèmes (implémentation portable). Ces informations fournissent des
recommandations utiles au support d'installation et de mise à jour
(l'utilisateur peut forcer l'installation
d'une fonction quelle que soit la valeur de ce paramètre).
-
ws : spécification facultative du système de fenêtrage. Liste de
désignateurs de système de fenêtrage, séparés par des virgules,
définie par Eclipse (reportez-vous au Javadoc
pour org.eclipse.core.boot.BootLoader).
Indique que cette entrée ne doit être installée que sur l'un des
systèmes de fenêtrage spécifiés. Si cet attribut n'est pas indiqué, l'entrée peut être
installée sur tous les systèmes (implémentation portable). Ces
informations fournissent des recommandations utiles au support
d'installation et de mise à jour (l'utilisateur peut forcer
l'installation d'une entrée quelle que soit la valeur de ce paramètre).
-
nl : spécification facultative des paramètres régionaux. Liste
de désignateurs de paramètre régional, séparés par des
virgules, définie par Java. Indique que cette entrée ne doit être
installée que sur un système dont les paramètres régionaux sont
compatibles (à l'aide
des règles Java pour la correspondance des paramètres régionaux). Si
cet attribut n'est pas indiqué, l'entrée peut être installée sur tous
les systèmes (implémentation indépendante de la langue choisie). Ces
informations fournissent des recommandations utiles au support
d'installation et de mise à jour (l'utilisateur peut forcer
l'installation d'une entrée quelle que soit la valeur de ce paramètre).
-
download-size : conseil facultatif fourni par l'outil de mise en
forme, indiquant la taille du téléchargement en kilo-octets de
l'archive de données référencée. Si elle n'est pas spécifiée, la
taille du téléchargement est inconnue (Remarque sur
l'implémentation : l'implémentation doit faire la
différence entre une taille "inconnue" et une taille de 0)
-
install-size : conseil facultatif fourni par l'outil de mise en
forme, indiquant la taille de l'installation en kilo-octets de
l'archive de données référencée. Si elle n'est pas spécifiée, la
taille de l'installation est inconnue (Remarque sur
l'implémentation : l'implémentation doit faire la
différence entre une taille "inconnue" et une taille de 0)
Si elle interagit avec le site de mise à jour, l'implémentation de
la fonction mappe les éléments <plugin>
et <data> en identificateurs de chemin utilisés par le site
pour déterminer les fichiers à télécharger et installer. L'implémentation
par défaut des fonctions fournie par Eclipse génère les
identificateurs de chemin de la manière suivante :
-
L'élément <plugin> se traduit par une entrée de
chemin sous la forme "plugins/<pluginId>_<pluginVersion>.jar"
(par exemple, "plugins/org.eclipse.core.boot_2.0.0.jar")
-
L'élément <data> se traduit par une entrée de
chemin sous la forme "features/<featureId>_<featureVersion>/<dataId>"
(par exemple, "features/com.xyz.tools_1.0.3/examples.zip")
En général, les documents du manifeste feature.xml doivent
spécifier un encodage UTF-8. Par exemple
<?xml version="1.0" encoding="UTF-8"?>
Le texte traduisible du fichier feature.xml peut être séparé en
fichiers feature<_locale>.properties à l'aide des conventions de
regroupement des propriétés Java.
Les
chaînes traduites sont utilisées lors de l'installation (n'utilisez
donc pas le mécanisme d'exécution des fragments de plug-in).