Fichiers manifeste de fonction Liberty
Une fonction Liberty est composée d'un fichier manifeste et d'un ou de plusieurs bundles OSGi qui fournissent des classes et des services correspondant à une capacité spécifique dans l'environnement d'exécution de 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 Liberty utilise le format de métadonnées de service de sous-système de la spécification OSGi Enterprise R5. Une fonction est définie par un fichier manifeste de fonction, ou fichier .mf, qui est stocké dans le répertoire lib/features et doit utiliser un type personnalisé du 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 | Obligatoire ou non |
---|---|---|
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 d'une liste séparée par des virgules des
bundles et des sous-systèmes requis pour utiliser cette fonction. Si vous souhaitez autoriser la configuration
de la fonction automatique dans le fichier
server.xml, l'en-tête Capacity contenant les fonctions requises doit être utilisé
et ces fonctions doivent être définies dans le contenu du sous-système.
|
Oui |
Subsystem-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 Liberty 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 prise 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. Cette fonction est fournie pour une utilisation par les extensions afin de composer des fonctions de plus haut niveau.
- 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.- singleton. Elle admet l'une des valeurs suivantes :
- True. La fonction est un singleton.
- False. La fonction n'est pas un singleton.
L'instruction singleton est facultative. La valeur par défaut est False.
Cette instruction est utilisée pour déclarer qu'une fonction particulière est un singleton. Un singleton signifie qu'une seule version d'une fonction donnée peut être chargée dans l'environnement d'exécution à un moment donné. Par défaut, les fonctions ne sont pas des singletons. Si la fonction est un singleton et que plusieurs versions d'une fonction donnée sont requises par la configuration de serveur, l'environnement d'exécution tente de trouver une version commune tolérée par toutes les fonctions concernées. Pour plus d'informations sur la tolérance de version, voir l'instruction ibm.tolerates sous Subsystem-Content.
Lorsqu'une fonction est un singleton, la valeur de nom symbolique est au format "<singleton feature name >-<singleton version>", où le nom et la version sont séparés par un trait d'union. Le nom de la fonction singleton peut comporter des traits d'union, mais les caractères qui suivent le dernier trait d'union sont interprétés comme désignant la version du singleton. S'il ne s'agit pas d'une version valide, une version de singleton 0.0.0 est utilisée et le nom symbolique complet est utilisé comme nom du singleton. La version de singleton est utilisée lors du traitement de l'instruction "ibm.tolerates directives under Subsystem-Content. Par exemple :Subsystem-SymbolicName: com.ibm.example.feature-1.0; visibility:=public; singleton:=true
Subsystem-Content
Subsystem-Content ::= content ( ',' content )*
content ::= unique-name ( ';' parameter )*
unique-name ::= unique-name (see 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, laquelle indique un bundle OSGi qui doit être présent à la fois dans l'infrastructure OSGi du serveur et dans un package d'installation.
- osgi.subsystem.feature - Cette valeur indique que la fonction doit être présente à la fois 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 sélectionné en indiquant une plage de versions, une valeur d'emplacement, ou les deux.
- file - Cette valeur indique que le fichier identifié dans l'attribut location doit être inclus dans un package d'installation.
- location - Emplacement du bundle. Dans le cas d'un type bundle ou JAR, cette valeur peut être une liste séparée par des virgules de
répertoires représentant un chemin de recherche. Pour tout type, cette valeur peut être une entrée unique
pointant directement sur la ressource et peut être spécifiée sous forme d'URL de fichier.
Les chemins peuvent être absolus ou relatifs. Les chemins relatifs sont résolus par rapport à l'emplacement de l'extension
du produit qui contient la fonction. Dans le cas d'une fonction utilisateur, l'emplacement par défaut de l'extension est utilisé, à savoir
${wlp.user.dir}/extension. Un emplacement d'extension de produit différent de celui par défaut
est déclaré via la propriété com.ibm.websphere.productInstall dans son fichier de propriétés,
dans le répertoire ${wlp.install.dir}/etc/extensions.Exemple :
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"
- start-phase - Phase de démarrage pendant laquelle le bundle doit démarrer au 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.
- ibm.tolerates
- Indique une ou plusieurs versions alternatives d'une fonction de
singleton,type=osgi.subsystem.feature, qui doivent
être mises à disposition sur système en cas de
conflit de version.
Le nom unique spécifie le nom symbolique de la version préférée d'une fonction de singleton. Si la fonction d'inclusion est réputée fonctionner avec d'autres versions de singleton d'une fonction de singleton donnée, ces versions peuvent être spécifiées à l'aide de l'instruction ibm.tolerates. Cela offre une plus grande compatibilité pour la fonction de définition dans le cas où d'autres fonctions définissent les valeurs de version requises en conflit d'une fonction de singleton données.
Les versions de singleton répertoriées dans l'instruction ibm.tolerates ne sont utilisées qu'en cas de conflit de version. L'ordre des versions répertoriées dans l'instruction ibm.tolerates n'a pas d'importance. Toute version mentionnée dans l'instruction ibm.tolerates peut être sélectionnée pour satisfaire les exigences de dépendances.
La ou les versions tolérées d'une fonction de singleton donnée doivent être explicitement répertoriées dans l'instruction ibm.tolerates. Utilisez des virgules pour séparer les éléments d'une liste de versions tolérées. L'indication d'une plage de versions n'est pas prise en charge.
Exemple :Subsystem-Content: com.ibm.websphere.appserver.example.featureA-1.1; ibm.tolerates:="1.2"; type="osgi.subsystem.feature", com.ibm.websphere.appserver.example.featureB-1.1; ibm.tolerates:="1.2, 1.4, 1.6"; type="osgi.subsystem.feature"
Remarque :Les versions tolérées ne sont pas transitives. Ceci permet d'éviter qu'une fonction dont dépend la vôtre soit automatiquement sélectionnée comme gérant un niveau ultérieur d'une fonction, sans test préalable.
Exemple : La fonction utilisateur featureC-1.1 inclut sipServlet-1.1 dans l'en-tête Subsystem-Content de son fichier manifeste. sipServlet-1.1 inclut servlet-3.0 et tolère servlet 3.1. Si featureC-1.1 a été composée avant l'introduction de servlet-3.1 et que servlet-3.1 a été ajoutée et est tolérée par la fonction qui l'utilise (sipServlet-1.1), featureC-1.1 doit pouvoir indiquer si elle tolère aussi servlet-3.1.
Si vous configurez le fichier server.xml afin qu'il comporte les deux fonctions suivantes :
Un message d'erreur similaire au suivant s'affiche :<feature>usr:featureC-1.1</feature> // includes: sipServlet-1.1 <feature>websocket-1.0</feature> // this feature requires servlet-3.1
CWWKF0033E: Les fonctions de singleton servlet-3.0 et servlet-3.1 ne peuvent pas être chargées en même temps. Les fonctions configurées usr:featureC-1.1 et websocket-1.0 incluent une ou plusieurs fonctions qui causent le conflit. Votre configuration n'est pas prise en charge. Mettez à jour le fichier server.xml afin de supprimer les fonctions incompatibles. "
Cette erreur est signalée car featureC-1.1 n'est pas accordé explicitement pour tolérer servlet-3.1, et doit avoir servlet-3.0, et websocket-1.0 ne prend pas en charge servlet-3.0 et doit avoir servlet-3.1.
Cette solution convient pour featureC-1.1 qui doit aussi directement dépendre de servlet-3.0 et tolérer servlet-3.1.





- 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". Pour toute autre
valeur, aucune action n'est engagée. 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
Subsystem-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
Subsystem-Localization (loc.properties dans
l'exemple précédent), sous le format suivant :name=feature_name
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 Subsystem-Localization (loc.properties dans
l'exemple précédent), sous le format suivant :desc=feature_description
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 désire utiliser les services fournis par l'en-tête IBM-API-Service, l'application doit inclure une référence Blueprint au service afin que le service soit provisionné 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 services OSGi à l'aide de l'interface OSGi BundleContext ou de 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. Cependant, si vous souhaitez qu'un package de votre fonction soit accessible par une fonction installée dans une autre extension du produit, vous devez répertorier le nom du package dans l'en-tête de IBM-SPI-Package.
Tout package répertorié dans l'en-tête IBM-SPI-Package doit être exporté par un bundle dans la fonction Liberty, en étant répertorié 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
product_id; productVersion=product_version; productInstallType=product_install_type; productEdition=product_editions
Si vous indiquez plus d'un élément, la valeur de id_produit doit être différente pour chaque élément.
La valeur de productVersion peut être une version exacte, telle que 8.5.5.7, ou une version minimum, dénotée par un signe plus qui suit son nom, comme 8.5.5.7+.
La valeur de productEdition peut correspondre à une édition unique ou à une liste d'éditions séparées par des virgules et encadrées par des guillemets.
IBM-AppliesTo: com.ibm.websphere.appserver; productVersion=8.5.5.6; productInstallType=Archive; productEdition="BASE,DEVELOPERS,ND"
Subsystem-License
Cet en-tête définit le type de licence pour la fonction. Si vous fournissez une valeur pour l'en-tête Subsystem-License et ne fournissez aucune valeur pour les en-têtes IBM-License-Agreement et IBM-License-Information, la valeur de l'en-tête Subsystem-License s'affiche à l'utilisateur pour son acceptation lors de l'installation.
Si une fonction déjà installée utilise la même valeur d'en-tête Subsystem-License, la licence n'est pas affichée, et son approbation n'est pas réclamée lors 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 lorsque vous installez 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 lorsque vous installez la fonction. Les fichiers de licence sont copiés dans le répertoire d'installation Liberty.
IBM-License-Information: lafiles/LI
![[18.0.0.1 and later]](../ng_v18001plus.gif)
IBM-Maven-Dependency
IBM-Maven-Dependency: javax.servlet:javax.servlet-api:3.1.0
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 entraîne l'installation et le démarrage du bundle spécifié,
com.ibm.example.bundle1, 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,
hormis les applications Java EE 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 SPI,
com.ibm.example.spi.utils et com.acme.spi.spiservices, sont visibles
par tout le code de fonction du serveur, tout 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