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 (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 |
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. Elle est fournie 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.- 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 essaie de trouver une version commune qui est 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 fonction de singleton peut contenir des traits d'union, mais les caractères suivant le dernier trait d'union seront interprétés en tant que version de singleton. Si les caractères suivant le dernier trait d'union n'indiquent pas une version valide, la version de singleton 0.0.0 est utilisée et le nom symbolique complet est utilisé comme nom de singleton. La version de singleton est utilisée lors du traitement des instructions "ibm.tolerates sous 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. 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.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 de singleton 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 sont uniquement utilisées dans le cas d'un conflit de version. Le classement des versions répertoriées dans l'instruction ibm.tolerates n'a pas d'importance. Toute version répertoriée dans l'instruction ibm.tolerates peut être sélectionnée pour répondre aux exigences de dépendance.
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. Cela permet d'éviter qu'une fonction dont dépend votre fonction ne soit automatiquement accordée explicitement pour la prise en charge d'un niveau de fonction ultérieur, 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é écrit alors que servlet-3.1 n'existait pas, servlet-3.1 a été ajouté et toléré par la fonction utilisé par celui-ci (pour sipServlet-1.1), featureC-1.1, il doit être indiqué s'il doit aussi tolérer servlet-3.1.
Si vous configurez le fichier server.xml afin qu'il comporte les deux fonctions suivantes :
Un message semblable 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 fonction 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". 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
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), au 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), au 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 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
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 le version se terminant par un signe plus, +, comme 8.5.5.7+.
La valeur de productEdition 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.6; productInstallType=Archive; productEdition="BASE,DEVELOPERS,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