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.

Remarque : Dans le fichier manifeste de fonction, le format des attributs est nom=valeur, et celui des directives est nom:=valeur.

Les en-têtes suivants sont définis :
Tableau 1. En-têtes d'un fichier manifeste de fonction.

Ce tableau affiche les en-têtes d'un fichier manifeste de fonction dans le profil Liberty. La première colonne contient la liste des en-têtes, la deuxième une description de chaque en-tête et la troisième indique si l'en-tête est requis.

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.

Les attributs suivants sont pris en charge :
  • 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.
    Cet attribut est facultatif ; la valeur par défaut est false.

    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.
La directive suivante est prise en charge :
  • 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.
Exemple :
Subsystem-SymbolicName : com.ibm.example.feature-1.0; 
    visibility:=public; superseded=true; superseded-by="com.ibm.example.feature-2.0"
Si un nom de la fonction dans la liste des fonctions obsolètes est placé entre crochets, [], cela signifie que la fonction a été dissociée de la fonction de remplacement. Dans l'exemple suivant, la fonction appSecurity-1.0, qui contient les fonctions servlet-3.0 et ldapRegistry-3.0, est remplacée par la fonction appSecurity-2.0, qui ne contient pas les fonctions servlet-3.0 et ldapRegistry-3.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.
Pratiques recommandées : Si les outils de développement doivent afficher la fonction, la valeur de l'attribut visibility doit être public. Si la fonction est disponible uniquement pour les parties dignes de confiance, la valeur doit être protected. Si la fonction est interne et peut faire l'objet de modifications à tout moment, la valeur doit être private.

Subsystem-Content

Cet en-tête définit le contenu de la fonction, pour l'exécution et pour l'installation. Il respecte la même syntaxe d'en-tête que celle de la spécification de sous-système :
Subsystem-Content ::= content ( ',' content )*
        content ::= unique-name ( ';' parameter )*
        unique-name ::= unique-name        (voir OSGi core spec section 1.3.2)
unique-name utilise la forme de l'en-tête Bundle-SymbolicName ou Subsystem-SymbolicName. Les attributs suivants sont pris en charge :
  • 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.
Les directives suivantes sont prises en charge :
  • 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.
    Vous pouvez aussi configurer des bundles pour qu'ils démarrent juste avant ou juste après ces phases en ajoutant _LATE pour qu'il s'exécute après ou _EARLY pour qu'ils s'exécutent avant la phase principale. Ainsi, si vous voulez procéder à une exécution immédiatement après la phase de conteneur, utilisez CONTAINER_LATE et si vous voulez procéder à l'exécution avant la phase APPLICATION, utilisez APPLICATION_EARLY.
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"
Pour plateformes AIXPour plateformes HP UNIXPour plateformes LINUXPour plateformes SolarisPour plateformes IBM iRéférentiel Liberty[8.5.5.4 ou ultérieure]La directive suivante est prise en charge dans la version 8.5.5.4 et les versions suivantes :
  • 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.

Exemple :
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.

Exemple :
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.

Exemple :
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.

L'attribut suivant est pris en charge :
  • 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.
Exemple :
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.

Sa syntaxe est la suivante :
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.
Exemple :
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.

Exemple :
<?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

Cet en-tête spécifie la version Liberty pour laquelle cette fonction est valable. Indiquez une liste d'éléments séparés par une virgule, au format suivant :
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.

Exemple :
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.

Exemple :
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.

Exemple :
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.

Exemple :
IBM-License-Information: lafiles/LI

IBM-App-ForceRestart

Cet en-tête entraîne le redémarrage des applications lorsque la fonction est installée ou supprimée d'un serveur exécuté. Il admet l'une des valeurs suivantes :
  • 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

L'exemple ci-dessous illustre la définition de la fonction example-1.0. L'attribut de visibilité publique permet à cette fonction d'être spécifiée directement dans les fichiers de configuration du serveur (server.xml) ; elle est également incluse dans la liste déroulante des fonctions qui apparaissent dans la vue Configuration du serveur des outils de développement et peut être inclus dans des fonctions se trouvant dans d'autres extensions de produit. Si cette fonction est installée dans l'extension de produit usr d'une installation d'environnement d'exécution, vous pouvez le configurer sur un serveur en incluant le code suivant dans le fichier server.xml :
<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

Icône indiquant le type de rubrique Rubrique de référence

Dispositions pour les centres de documentation | Commentaires


Icône d'horodatage Dernière mise à jour: Wednesday, 2 September 2015
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=rwlp_feat_definition
Nom du fichier : rwlp_feat_definition.html