Extensions du service des métatypes OSGi

Les outils de développement et l'environnement d'exécution Liberty reconnaissent certaines extensions de la spécification de métatypes OSGi pour des configurations plus complexes et une meilleure présentation dans une interface utilisateur.

Extensions de métatype d'exécution

Ajoutez l'espace de nom suivant dans votre fichier metatype.xml afin d'utiliser les extensions suivantes :
xmlns:ibm="http://www.ibm.com/xmlns/appservers/osgi/metatype/v1.0.0"
ibm:alias

L'extension d'alias permet de définir un nom convivial pour la configuration tout en réduisant le risque de conflits entre les noms des éléments de configuration dans le fichier server.xml.

L'exemple suivant illustre l'extension ibm:alias :

<OCD id="com.ibm.ws.jdbc.dataSource.properties"
		  name="%properties" 
		  description="%properties.desc"
    	ibm:alias="properties">
   <AD id="username".../>
</OCD>

Dans cet exemple propriétés est le nom convivial de la configuration. L'alias doit être différent de l'ID.

Lorsque l'entrée ibm:alias est utilisée dans le fichier server.xml, il doit être préfixé avec le nom de l'extension de produit. Le nom de l'extension de produit pour les extensions qui sont installées à l'emplacement utilisateur par défaut est usr. Pour les extensions de produit définies dans l'installation Liberty avec un fichier nom-extension.properties dans le répertoire wlp/etc/extension, le nom de l'extension de produit est le nom choisi pour nom-extension.

Pour le métatype illustré dans l'exemple précédent, si la fonction est installée à l'emplacement usr par défaut, les exemples suivants sont des entrées valides dans le fichier server.xml :
<usr_properties username="JANE"/>
<com.ibm.ws.jdbc.dataSource.properties username="JANE"/> 
ibm:type

Les types d'attribut standard sont définis dans la spécification de métatypes. Plusieurs types étendus IBM® sont disponibles. Pour plus d'informations, voir Types étendus.

ibm:reference

L'attribut de référence spécifie le type OCD qu'un PID référence. Il n'est utilisé qu'avec le type ibm:pid et prend en charge l'imbrication d'éléments dans le fichier server.xml ; voir Imbrication des éléments de configuration.

L'exemple suivant illustre l'extension ibm:reference :

<AD id="fooRef" type="String" ibm:type="pid" ibm:reference="com.ibm.ws.foo".../>
ibm:final

L'attribut final indique que la valeur ne peut pas être spécifiée dans la configuration. A la place, la valeur par défaut provenant du métatype est utilisée systématiquement. Utilisez name="internal" pour indiquer que les outils ne doivent pas afficher cette propriété.

L'exemple suivant illustre l'extension ibm:final :

<AD id="foo" name="internal" ibm:final="true" type="String" default=${someVariable}"/>
ibm:variable

L'attribut de variable est utilisé pour spécifier une variable à utiliser comme valeur par défaut si aucune valeur n'est spécifiée. Le comportement consiste à choisir, dans l'ordre :

  • La valeur qui est spécifiée dans le fichier server.xml
  • La valeur qui est spécifiée comme propriété système, par exemple dans le fichier bootstrap.properties
  • La valeur par défaut provenant du métatype

L'exemple suivant illustre l'extension ibm:variable :

<AD id="traceString" ibm:variable="trace.string" default=*.all=enabled".../>
ibm:unique
L'attribut unique indique qu'une valeur de configuration doit être unique parmi toutes les définitions d'attribut qui utilisent le même groupe d'attributs unique. Les groupes d'attributs uniques suivants sont pris en charge :
Syntaxe de valeur par défaut

Vous pouvez utiliser la syntaxe ${prop-name} dans les expressions par défaut afin de construire des chaînes à partir d'autres propriétés de configuration.

L'exemple suivant illustre une syntaxe de valeur par défaut :

<AD id="httpEndpoint.target"
		  name="internal" description="internal use only" 
		  ibm:final="true" required="false" type="String"
    	default="(&amp;(virtualHost=${id}) (enabled=true))"/>

Types étendus

Duration

Le type de durée est utilisé pour exprimer une durée. Il peut être exprimé dans plusieurs unités de temps. Par exemple, "1h30m" signifie une heure et demie. "1j5h10s" signifie 1 jour, 5 heures et 10 secondes.

La liste suivante répertorie les unités disponibles :

  • j - Jours
  • h - Heures
  • m - Minutes
  • s - Secondes
  • ms - Millisecondes

Par défaut, lorsque vous utilisez le type de durée, la valeur spécifiée par l'utilisateur est évaluée en millisecondes. Ainsi, "10s" correspond à la valeur longue 10000 dans le dictionnaire. Par ailleurs, si un utilisateur spécifie une valeur sans indiquer d'unité, cette valeur est évaluée en millisecondes. Par exemple, la valeur "10" correspond à 10 millisecondes. Toutefois, vous pouvez aussi spécifier le type de durée de sorte qu'elle soit évaluée dans une autre unité. Par exemple, la valeur "10" avec ibm:type="duration(s)" est évaluée comme correspondant à 10 secondes et stockée comme 10 dans le dictionnaire.

La liste suivante répertorie les types possibles :

  • duration(h)
  • duration(m)
  • duration(s)
  • duration(ms)
  • duration

Il n'existe pas de différence entre la spécification de duration et la spécification de duration(ms).

Remarque :

Meilleure pratique : incluez toujours une unité dans la valeur et exprimez la valeur avec l'unité la plus facile à lire. Par exemple, au lieu de spécifier la valeur "7200" avec ibm:type="duration(s)", spécifiez la valeur "2h".

Les exemples suivants illustrent le type de durée :

  • <AD id="timeout" type="String" ibm:type="duration(s)".../>
  • <AD id="timeout" type="String" ibm:type="duration".../>
Emplacement

Le type d'emplacement permet aux outils de l'interface utilisateur d'afficher une présentation plus utile des attributs qui représentent divers emplacements de fichier et de répertoire. Il n'a pas d'impact sur le traitement effectué par l'environnement d'exécution. L'objet dictionnaire est toujours une chaîne.

Les exemples suivants illustrent les types possibles :

location
Référence un fichier. Il peut s'agir d'un chemin d'accès absolu, d'un fichier relatif ou d'une adresse URL désignant un fichier.
location(file)
Référence un fichier en utilisant un chemin relatif ou absolu.
location(dir)
Référence un répertoire en utilisant un chemin relatif ou absolu.
location(url)
Référence un fichier à la fin d'une adresse URL.

L'exemple suivant illustre le type d'emplacement :

<AD id="location" name="%appmgr.location.name" description="%appmgr.location.desc" type="String" required="true" ibm:type="location"/>
Mot de passe

Le type de mot de passe est utilisé pour les zones de mot de passe. Lorsqu'il est utilisé, l'objet dictionnaire est une instance de com.ibm.wsspi.kernel.service.utils.SerializableProtectedString. La valeur de la zone de mot de passe n'est pas journalisée dans le fichier de trace. Les outils de développement affichent les options de codage qui peuvent être utilisées pour une zone de mot de passe. Les options de codage valides sont xor et aes.

L'exemple suivant illustre le type de mot de passe :

<AD id="password" type="String" ibm:type="mot de passe".../>
Mot de passe haché

Le type passwordHash est similaire au type de mot de passe ; il est utilisé pour les zones de mots de passe hachés. Lorsqu'il est utilisé, l'objet dictionnaire est une instance de com.ibm.wsspi.kernel.service.utils.SerializableProtectedString. La valeur de la zone de mot de passe haché n'est pas consignée dans le fichier de trace. Les outils de développement affichent les options de codage qui peuvent être utilisées pour une zone de mot de passe haché. Les options de codage valides sont xor, aes et hash.

Validez un nouveau mot de passe par rapport à un mot de passe haché en utilisant la méthode PasswordUtil.encode(String, String, Map), avec les paramètres suivants :
  1. Nouveau mot de passe.
  2. Algorithme de hachage, qui est obtenu en appelant la méthode PasswordUtil.getCryptoAlgorithm. L'algorithme de hachage doit correspondre à l'algorithme du mot de passe haché.
  3. Objet de propriétés, où une des propriétés utilise PasswordUtil.PROPERTY_HASH_ENCODED pour la clé et le mot de passe haché pour la valeur.
Si la valeur de retour de PasswordUtil.encode est la même que le mot de passe haché, les mots de passe correspondent.

L'exemple suivant illustre le type passwordHash :

<AD id="hashedPassword" type="String" ibm:type="passwordHash".../>
Pid

Le type de PID est utilisé pour référencer un autre objet dans la configuration. Il n'est utilisé qu'avec l'attribut ibm:reference et prend en charge l'imbrication d'éléments dans le fichier server.xml ; voir Imbrication des éléments de configuration.

L'exemple suivant illustre le type de PID :

<AD id="fooRef" type="String" ibm:type="pid" ibm:reference="com.ibm.ws.foo".../>
OnError

Le type onError génère une instance de l'énumération onError dans le dictionnaire. Les valeurs possibles sont WARN, FAIL et IGNORE.

L'exemple suivant illustre le type onError :

<AD id="errorBehavior" type="String" ibm:type="onError".../>
Jeton

Le type de jeton est utilisé pour indiquer que la valeur spécifiée dans la configuration doit être nettoyée de tout espace blanc affiché avant ou après la chaîne.

L'exemple suivant illustre un attribut défini à l'aide du type de jeton :

<AD id="name" type="String" ibm:type="token" .../>

Extensions de métatype d'interface utilisateur

Ajoutez l'espace de nom suivant dans votre fichier metatype.xml afin d'utiliser les extensions suivantes :
xmlns:ibmui="http://www.ibm.com/xmlns/appservers/osgi/metatype/ui/v1.0.0"
ibmui:localization

L'extension de localisation permet de spécifier le fichier de localisation de métatypes. Il est utilisé pour rechercher les traductions des libellés et des descriptions d'autres extensions d'interface utilisateur. Dans la plupart des cas, la valeur de l'extension ibmui:localization correspond à l'attribut de localisation dans l'élément <Metadata>.

L'exemple suivant illustre l'extension ibmui:localization :

<OCD id="com.ibm.ws.jdbc.dataSource.properties"
		  name="%properties" 
		  description="%properties.desc"
    	ibmui:localization="OSGI-INF/l10n/metatype">
   <AD id="username".../>
</OCD>
ibmui:extraProperties

L'extension extraProperties est utilisée pour indiquer qu'un ensemble arbitraire d'attributs de configuration peut être défini pour cette configuration.

L'exemple suivant illustre l'extension ibmui:extraproperties :

<OCD id="com.ibm.ws.jdbc.dataSource.properties"
		  name="%properties" 
		  description="%properties.desc"
    	ibmui:extraProperties="true">
   <AD id="username".../>
</OCD>

Le libellé et la description qui sont associés à l'extension sont recherchés dans le fichier de localisation de métatypes (si un tel fichier est spécifié avec l'extension ibmui:localization). La clé du libellé de l'extension est d'abord recherchée dans extraProperties.<ocd id>.name, puis les clés extraProperties.name sont vérifiées. La clé de la description de l'extension est d'abord recherchée dans extraProperties.<ocd id>.description, puis les clés extraProperties.description sont vérifiées.

ibmui:group

L'extension de groupe permet de spécifier que l'attribut appartient à un groupe. Dans l'interface utilisateur, les attributs qui sont annotés avec le même groupe sont regroupés.

L'exemple suivant illustre l'extension ibmui:group :

  • <AD id="username" ibmui:group="userInfo".../>
  • <AD id="password" ibmui:group="userInfo".../>
  • <AD id="port" ibmui:group="hostInfo".../>

Les informations de libellé et de description de groupe sont recherchées dans le fichier de localisation de métatypes (si un tel fichier est spécifié avec l'extension ibmui:localization). Pour le libellé du groupe, les clés <group>.<ocd id>.name sont d'abord vérifiées, puis <group>.name. Pour la description du groupe, les clés <group>.<ocd id>.description sont d'abord vérifiées, puis <group>.description.


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



Icône d'horodatage Dernière mise à jour: Tuesday, 6 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwlp_extensions_osgi_metatype
Nom du fichier : rwlp_extensions_osgi_metatype.html