Fichiers manifeste de fonction Liberty
Une fonction Liberty se compose d'un fichier manifeste de fonction et d'une collection d'un ou de plusieurs bundles OSGi qui fournissent des classes et des services correspondant à une capacité particulière dans l'environnement d'exécution du profil Liberty. Cette rubrique présente le format du manifeste d'une fonction et la signification de chaque en-tête du fichier manifeste.
Le fichier manifeste de fonction dans le profil Liberty utilise le format de métadonnées du service de sous-système dans la spécification OSGi Enterprise R5. Une fonction est définie par un fichier manifeste de fonction (fichier .mf) qui est stocké dans le répertoire lib/features et doit utiliser un type personnalisé de sous-système, osgi.subsystem.feature. Pour plus d'informations sur la syntaxe du manifeste OSGi, voir la section 1.3.2 de la spécification de base OSGi.
En-tête | Description | Requis ? |
---|---|---|
Subsystem-ManifestVersion | Format de version du fichier manifeste de fonction. Il doit s'agir de la valeur 1. | Non |
Subsystem-SymbolicName | Nom symbolique de la fonction et de tout attribut ou directive. | Oui |
Subsystem-Version | Version de la fonction. Voir la section 3.2.5 de la spécification de base OSGi pour des détails sur la façon dont la version est définie. | Non |
Subsystem-Type | Type de sous-système de la fonction. Actuellement, toutes les fonctions ont le même type de sous-système : osgi.subsystem.feature. | Oui |
Subsystem-Content | Contenu du sous-système de la fonction. Il s'agit de la liste de bundles et de sous-systèmes séparés par une virgule qui sont requis pour exécuter cette fonction. Si vous voulez que la fonction automatique soit configurée dans le fichier server.xml, l'en-tête de capacité contenant les fonctions requises doit exister, et ces fonctions doivent être définies dans le contenu du sous-système. | Oui |
Subsytem-Localization | Emplacement des fichiers de localisation de la fonction. | Non |
Subsystem-Name | Nom lisible et abrégé de la fonction. Cette valeur peut être localisée. | Non |
Subsystem-Description | Description de la fonction. Cette valeur peut être localisée. | Non |
IBM-Feature-Version | Version de ce type de sous-système. Il doit s'agir de la valeur 2. | Oui |
IBM-Provision-Capability | En-tête de capacité qui indique si une fonction peut être fournie automatiquement. | Non |
IBM-API-Package | Packages d'API mis à la disposition des applications par cette fonction, des fonctions dans d'autres extensions de produit, et le noyau Liberty. | Non |
IBM-API-Service | Services OSGi qui sont mis à la disposition des applications OSGi par cette fonction. | Non |
IBM-SPI-Package | Packages de SPI mis par cette fonction à la disposition des fonctions dans d'autres extensions de produit et le noyau Liberty. | Non |
IBM-ShortName | Nom abrégé de la fonction. | Non |
IBM-AppliesTo | Version Liberty pour laquelle cette fonction est valable. | Non |
Subsystem-License | Type de licence pour cette fonction. | Non |
IBM-License-Agreement | Préfixe de l'emplacement des fichiers de contrat de licence. | Non |
IBM-License-Information | Préfixe de l'emplacement des fichiers d'informations sur la licence. | Non |
IBM-App-ForceRestart | Indique que les applications doivent être redémarrées lorsque la fonction est installée sur un serveur démarré, ou désinstallée d'un serveur démarré. | Non |
Subsystem-SymbolicName
La syntaxe de cet en-tête correspond à la syntaxe Bundle-SymbolicName d'un bundle. Un nom symbolique suit la syntaxe de style des noms de package et admet éventuellement un ensemble d'attributs et de directives.
- superseded. Cet attribut indique si cette
fonction est obsolète et remplacée par une ou plusieurs fonctions
ou éléments de fonction.
Il peut prendre l'une des valeurs suivantes :
- true - La fonction est obsolète.
- false - La fonction n'est pas obsolète.
Pour plus d'informations, voir Fonctions obsolètes.
- superseded-by. Cet attribut spécifie une liste de fonctions séparées par une virgule qui rend obsolète cette fonction, le cas échéant, et est facultatif.
- visibility. Elle admet l'une des valeurs suivantes :
- public - Fonction considérée comme une API. La fonction est pris en charge par les outils de développement, en vue de son utilisation dans le fichier server.xml ,et son affichage dans les messages.
- protected - Fonction considérée comme une SPI. La fonction n'est pas prise en charge par les outils de développement, en vue de son utilisation dans le fichier server.xml , et de son affichage dans les messages. Il est fourni pour que les extenseurs puissent l'utiliser afin de générer des fonctions de niveau supérieur.
- private - (par défaut) La fonction constitue les éléments internes du produit. Il n'est pas pris en charge en vue de son utilisation dans le fichier server.xml ou de sa référence par les fonctions d'extension. Il peut être modifié à tout moment, y compris entre deux groupes de correctifs.
Subsystem-SymbolicName : com.ibm.example.feature-1.0;
visibility:=public; superseded=true; superseded-by="com.ibm.example.feature-2.0"
IBM-ShortName: appSecurity-1.0
Subsystem-SymbolicName: com.ibm.websphere.appserver.appSecurity-1.0; visibility:=public;
superseded=true; superseded-by="appSecurity-2.0, [servlet-3.0], [ldapRegistry-3.0]"
Pour plus d'informations, voir
Fonctions
dissociés.Subsystem-Content
Subsystem-Content ::= content ( ',' content )*
content ::= unique-name ( ';' parameter )*
unique-name ::= unique-name (voir OSGi core spec section 1.3.2)
- version - Plage de versions à mettre en correspondance lors de la recherche d'un bundle. Seuls les bundles qui correspondent à cette plage sont sélectionnés. Voici un exemple classique : [1,1.0.100).
- type - Type de contenu à fournir.
Vous pouvez spécifier la valeur de votre choix pour indiquer le type
de contenu. Certains types entraînent l'installation et le démarrage
de bundles dans l'infrastructure OSGi d'un serveur utilisant la
fonction ; tous les types entraînent l'ajout du contenu dans un
package d'installation incluant la fonction.
Les valeurs suivantes sont prédéfinies :
- osgi.bundle - Il s'agit de la valeur par défaut. Elle indique un bundle OSGi devant être fourni dans l'infrastructure OSGi du serveur et dans un package d'installation.
- osgi.subsystem.feature - Cette valeur indique que la fonction doit être fournie dans l'infrastructure OSGi du serveur et dans un package d'installation. Ces fonctions doivent utiliser le nom spécifié dans l'en-tête Subsystem-SymbolicName.
- jar - Cette valeur indique qu'un fichier JAR doit être inclus dans un package d'installation et que vous pouvez le sélectionner en indiquant une combinaison de plage de versions et de valeur d'emplacement.
- file - Cette valeur indique que le fichier identifié dans l'attribut location doit être inclus dans un package d'installation.
- location - Emplacement du bundle. Pour un type JAR ou regroupement, cette valeur peut être une liste séparée par des virgules de répertoires utilisée pour identifier les regroupements API et spec dans le répertoire dev, ou une entrée unique pointant directement vers le fichier JAR. Lorsque le type est file, seule une entrée unique est autorisée et elle doit pointer directement vers ce fichier.
- start-phase - Phase de démarrage pendant laquelle le bundle doit démarrer dans le cadre du démarrage du système. La directive start-phase peut prendre une des valeurs
suivantes :
- SERVICE - Cette valeur indique la première phase. Par défaut, elle est mappée à un niveau de démarrage de 9.
- CONTAINER - Il s'agit de la valeur par défaut si la valeur start-phase n'est pas indiquée. Elle indique la phase de conteneur lorsque des conteneurs d'application sont démarrés. Par défaut, elle est mappée à un niveau de démarrage de 12.
- APPLICATION - Cette valeur indique la dernière phase au cours de laquelle des applications sont démarrées.
Subsystem-Content: com.ibm.websphere.appserver.api.basics; version="[1,1.0.100)"; type=jar; location:="dev/api/ibm/,lib/",
com.ibm.websphere.appserver.spi.application;
location:="dev/spi/ibm/com.ibm.websphere.appserver.spi.application_1.0.0.jar"; type="jar",
com.ibm.websphere.appserver.spi.application_1.0.0-javadoc.zip;
location:="dev/spi/ibm/javadoc/com.ibm.websphere.appserver.spi.application_1.0.0-javadoc.zip";
type="file"






![[8.5.5.4 ou ultérieure]](../ng_v8554.gif)
- ibm.executable - Ajoute le droit d'exécution
au fichier associé, en fonction du paramètre umask en cours, lorsque
la valeur est définie sur "true". Avec toute autre
valeur, aucune action ne sera prise. Le tableau suivant indique les
valeurs umask en cours et précise si la classe obtient le droit
d'exécution.
Tableau 2. Exemples de valeurs umask et de classes avec les droits d'exécution définis par ibm.executable Umask Droits d'exécution accordés à la classe 022 propriétaire, groupe, autre 023 propriétaire, groupe 055 propriétaire
Subsytem-Localization
Cet en-tête spécifie l'emplacement des fichiers de localisation pour la fonction.
Subsystem-Localization: OSGI-INF/l10n/loc
Subsystem-Name
Utilisez cet en-tête afin de fournir un nom lisible et abrégé pour la fonction. Vous pouvez spécifier une chaîne littérale ou un nom de propriété. Si vous spécifiez un nom de propriété, la valeur peut être localisée.
Subsystem-Name: %name
où la valeur de name est définie dans un fichier de propriétés à l'emplacement spécifié par l'en-tête Subsytem-Localization (loc.properties dans l'exemple précédent), au format suivant :name=nom_fonction
Subsystem-Description
Utilisez cet en-tête pour fournir une description de la fonction. Vous pouvez spécifier une chaîne littérale ou un nom de propriété. Si vous spécifiez un nom de propriété, la valeur peut être localisée.
Subsystem-Description: %desc
où la valeur de desc est définie dans un fichier de propriétés à l'emplacement spécifié par l'en-tête Subsytem-Localization (loc.properties dans l'exemple précédent), au format suivant :desc=description_fonction
IBM-Provision-Capability
Les fonctions approvisionnées automatiquement sont des fonctions avec un en-tête IBM-Provision-Capability dans le manifeste. Cet en-tête décrit d'autres fonctions devant être approvisionnées pour le provisionnement automatique de cette fonction. Lorsque vous répertoriez les autres fonctions, utilisez l'en-tête Subsystem-SymbolicName de la fonction. Lorsque des fonctions sont configurées dans le fichier server.xml, runtime détermine si les capacités des fonctions approvisionnées automatiquement ont été satisfaites et, le cas échéant, l'approvisionnement automatique a lieu.
Le format de l'en-tête IBM-Provision-Capability utilise des filtres LDAP OSGi standard.
IBM-API-Package
Cet en-tête permet d'indiquer les packages d'API qui sont visibles dans les applications. Il suit la syntaxe de l'en-tête Export-Package. Cela signifie qu'il correspond à une liste de packages d'API séparés par une virgule, mais que chaque package d'API peut être associé à des attributs.
- type - Type du package d'API. L'attribut type prend l'une des valeurs suivantes :
- spec - Indique une API fournie par un corps standard, comme javax.servlet ou org.osgi.framework.
- ibm-api - Indique une API à valeur ajoutée fournie par IBM®.
- api - Indique une API définie par l'utilisateur. Il s'agit de la valeur par défaut.
- third-party - Indique une API qu'IBM peut voir mais ne contrôle pas. En général, il s'agit de packages à code source ouvert.
- internal - Indique des packages autres que des API qui doivent être exposés aux applications pour qu'elles puissent fonctionner. Ils peuvent être utilisés si le code Java™ est amélioré au niveau du bytecode, ou tissé, pour ajouter des références au code interne à l'exécution.
IBM-API-Package: javax.servlet; type="spec",
com.ibm.websphere.servlet.session; type="ibm-api",
com.ibm.wsspi.webcontainer.annotation; type="internal"
IBM-API-Service
Cet en-tête permet d'indiquer les services de la fonction qui sont visibles dans les applications OSGi. La fonction doit également enregistrer le service dans le registre de services OSGi.
IBM-API-Service ::= service ( ',' service )*
service ::= service-name ( ';' attribute )*
service-name ::= unique-name
service-name est le nom d'interface ou de classe
Java du service. Les attributs sont interprétés comme propriétés de service pour les services.IBM-API-Service : com.ibm.example.service.FeatureServiceOne;
myServiceAttribute=myAttributeValue,
com.ibm.example.service.FeatureServiceTwo
Si une application OSGi souhaite utiliser les services fournis par l'en-tête IBM-API-Service, l'application doit inclure une référence Blueprint dans le service afin que le service soit approvisionné dans l'application.
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
<reference id="FeatureServiceOneRef"
interface="com.ibm.example.service.FeatureServiceOne" />
</blueprint>
Pour qu'un service soit utilisable par un bundle dans une application OSGi, le package d'interface doit être disponible dans le bundle, ce qui signifie que le package d'interface doit être spécifié par un en-tête Import-Package dans le manifeste du fichier du bundle. Le package d'interface doit également être spécifié par un en-tête Export-Package dans un bundle de fonction et spécifié dans l'en-tête IBM-API-Package du fichier de manifeste de la fonction. Le service fourni par une fonction doit être enregistré dans le registre de service OSGi en utilisant l'interface OSGi BundleContext ou tout autre mécanisme tel que Services déclaratifs ou Blueprint. Pour plus d'informations, voir Développement d'un bundle OSGi avec activation simple et Composition de fonctions complexes à l'aide des services déclaratifs OSGi.
IBM-SPI-Package
Lorsque vous créez votre propre fonction Liberty, vous l'installez dans l'extension de produit utilisateur. Tous les packages de votre fonction sont accessibles par les autres fonctions qui sont installées dans l'extension de produit utilisateur. Toutefois, si vous voulez qu'une fonction qui est installée dans une autre extension de produit puisse accéder à un package dans votre fonction, vous devez répertorier le nom du package dans l'en-tête IBM-SPI-Package.
Les packages répertoriés dans l'en-tête IBM-SPI-Package doivent être exportés par un bundle dans la fonction Liberty en étant répertoriés dans l'en-tête Export-Package du fichier manifeste du bundle.
IBM-ShortName
Cet en-tête est un nom abrégé de fonction que vous pouvez utiliser pour spécifier une fonction dans le fichier server.xml. Si le fichier manifeste ne comporte pas d'en-tête IBM-ShortName, Subsystem-SymbolicName est utilisé par défaut. L'en-tête IBM-ShortName est valide uniquement pour les fonctions publiques.
IBM-AppliesTo
id_produit; productVersion=version_produit; productInstallType=type_install_produit; productEdition=éditions_produit
Si vous indiquez plus d'un élément, la valeur de id_produit doit être différente pour chaque élément.
La valeur de éditions_produit peut correspondre à une seule édition ou à une liste d'éditions séparées par une virgule entre guillemets.
IBM-AppliesTo: com.ibm.websphere.appserver; productVersion=8.5.5; productInstallType=Archive; productEdition="BASE,DEVELOPERS,EXPRESS,ND"
Subsystem-License
Cet en-tête définit le type de licence pour la fonction. Si vous indiquez une valeur pour l'en-tête Subsystem-License et ne fournissez pas de valeurs pour les en-têtes IBM-License-Agreement et IBM-License-Information, la valeur de l'en-tête Subsystem-License s'affiche pour l'utilisateur en vue de l'acceptation au cours de l'installation.
Si une fonction dont la valeur de l'en-tête Subsystem-License est la même est déjà installée, la licence ne s'affiche pas et son approbation n'est pas requise au cours de l'installation. Si des dépendances dans l'en-tête Subsystem-Content signifient que plusieurs fonctions en cours d'installation possèdent la même valeur pour l'en-tête Subsystem-License, il suffit que l'utilisateur accepte la licence une fois au cours de l'installation.
Subsystem-License: L-JTHS-93TMHH
Subsystem-License: http://www.apache.org/licenses/LICENSE-2.0.html
IBM-License-Agreement
Cet en-tête spécifie le préfixe de l'emplacement des fichiers de contrat de licence. Indiquez le chemin d'accès dans l'archive de sous-système aux fichiers LA_langue, jusqu'au caractère "_", sans l'inclure (le code de langue est ajouté par l'outil d'installation). Si cette licence n'a pas été acceptée, l'utilisateur doit l'accepter lorsqu'il installe la fonction. Les fichiers de licence sont copiés dans le répertoire d'installation Liberty.
IBM-License-Agreement: lafiles/LA
IBM-License-Information
Cet en-tête spécifie le préfixe de l'emplacement des fichiers d'informations sur la licence. Indiquez le chemin d'accès dans l'archive de sous-système aux fichiers LI_langue, jusqu'au caractère "_", sans l'inclure (le code de langue est ajouté par l'outil d'installation). Si cette licence n'a pas été acceptée, l'utilisateur doit l'accepter lorsqu'il installe la fonction. Les fichiers de licence sont copiés dans le répertoire d'installation Liberty.
IBM-License-Information: lafiles/LI
IBM-App-ForceRestart
- install - redémarrer les applications lorsque la fonction est installée.
- uninstall - redémarrer les applications lorsque la fonction est désinstallée.
- install,uninstall - redémarrer les applications lorsque la fonction est installée ou désinstallée.
Exemple de fichier manifeste de fonction
<featureManager>
<feature>usr:example-1.0</feature>
</featureManager>
La configuration de cette fonction
sur un serveur génère le bundle spécifié,
com.ibm.example.bundle1, qui est installé et
démarré dans l'infrastructure OSGi de l'environnement d'exécution du
serveur. Le package d'API unique, com.ibm.example.publicapi, est visible dans toutes les applications de ce serveur,
sauf dans les applications Java EE qui sont configurées sans visibilité du type de package api.
Les applications OSGi doivent importer explicitement le package si elles veulent l'utiliser. Les deux packages de SPI, com.ibm.example.spi.utils et com.acme.spi.spiservices, sont visibles dans l'intégralité du code de fonction sur le serveur, comme le package d'API.IBM-Feature-Version: 2
Subsystem-ManifestVersion: 1.0
Subsystem-SymbolicName: com.ibm.example-1.0; visibility:=public
Subsystem-Version: 1.0.0.qualifier
Subsystem-Type: osgi.subsystem.feature
Subsystem-Content: com.ibm.example.bundle1; version="1.0.0"
Subsystem-Localization: OSGI-INF/l10n/loc
Manifest-Version: 1.0
Subsystem-Name: %name
Subsystem-Description: %desc
IBM-API-Package: com.ibm.example.publicapi; type="api"
IBM-SPI-Package: com.ibm.example.spi.utils, com.ibm.example.spi.spiservices
IBM-ShortName: example-1.0