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

The alias extension is used to define a usable name for the configuration, at the same time it reduces the risk of clashes in the names of configuration elements in the server.xml file.

The following example shows the ibm:alias: extension:

<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 Extended types.

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))"/>

Extended types

Duration

The duration type is used to express a time. It is described in multiple units of time. For example, "1h30m" would be an hour and a half. "1d5h10s" would be 1 day, 5 hours, and 10 seconds.

The following list shows the available units:

  • d - Days
  • h - Hours
  • m - Minutes
  • s - Seconds
  • ms - Milliseconds

By default, when the type duration is used, the value that is specified by the user is evaluated in milliseconds. For example, "10s" would be a long value of 10000 in the dictionary. Furthermore, if a user specifies a value without any unit, this value is evaluated in milliseconds. For example, a value of "10" would be evaluated as 10 milliseconds. However, you can also specify the duration type such that it evaluates into a different unit. For example, specifying a value of "10" with ibm:type="duration(s)" is evaluated as 10 seconds, and stored as 10 in the dictionary.

The following list shows the possible types:

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

There is no difference between specifying duration and duration(ms).

Remarque :

Best practice: Always include a unit in the value, and express the value with the unit that is easiest to read. For example, instead of specifying a value of "7200" with ibm:type="duration(s)", specify the value as "2h".

The following examples show the duration type:

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

The location type allows UI tools to provide a more helpful presentation of attributes that represent various file and directory locations. It does not affect processing by the runtime environment. The dictionary object is always a String.

The following examples show the possible types:

location
References a file. The reference can be an absolute, relative file, or it can be a url to a file.
location(file)
References a file by using an absolute or relative file path.
location(dir)
References a dir by using an absolute or relative file path.
location(url)
References a file at the end of a url.

The following example shows the location type:

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

The password type is used for password fields. When used, the dictionary object is an instance of com.ibm.wsspi.kernel.service.utils.SerializableProtectedString. The value of the password field is not logged in the trace file. Developer tools display the encoding options that can be used for a password field. Valid encoding options are xor and aes.

The following example shows the password type:

<AD id="password" type="String" ibm:type="password".../>
Hashed password

The passwordHash type is similar to the password type and is used for hashed password fields. When used, the dictionary object is an instance of com.ibm.wsspi.kernel.service.utils.SerializableProtectedString. The value of the hashed password field is not logged in the trace file. Developer tools display the encoding options that can be used for a hashed password field. Valid encoding options are xor, aes, and hash.

Validate a new password against a hashed password by using the PasswordUtil.encode(String, String, Map) method, with the following parameters:
  1. New password.
  2. Hash algorithm, which is obtained by calling the PasswordUtil.getCryptoAlgorithm method. The hash algorithm must match the algorithm of the hashed password.
  3. Properties object, where one of the properties uses PasswordUtil.PROPERTY_HASH_ENCODED for the key and the hashed password for the value.
If the return value of PasswordUtil.encode is the same as the hashed password, then the passwords match.

The following example shows the passwordHash type:

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

The pid type is used to reference another object in the config. It is used with the ibm:reference attribute and supports nesting of elements in the server.xml; see Imbrication des éléments de configuration.

The following example shows the pid type:

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

The onError type results in an instance of the onError enumeration in the dictionary. The possible values are WARN, FAIL, and IGNORE.

The following example shows the onError type:

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

The token type is used to indicate that the value specified in the configuration must be trimmed of any white space that occurs before or after the String.

The following example shows an attribute that is defined by using the token type:

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

User interface metatype extensions

Add this namespace to your metatype.xml file to use the following extensions:
xmlns:ibmui="http://www.ibm.com/xmlns/appservers/osgi/metatype/ui/v1.0.0"
ibmui:localization

The localization extension is used to specify the metatype localization file. The metatype localization file is used to look up the translations for labels and descriptions of other UI extensions. In most cases, the value of the ibmui:localization extension matches the localization attribute on the <Metadata> element.

The following example shows the ibmui:localization extension:

<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). Le libellé de l'extension est d'abord recherché dans extraProperties.<ocd id>.name, puis dans extraProperties.name. La clé de description de l'extension est d'abord recherchée dans extraProperties.<ocd id>.description, puis dans extraProperties.description.

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). Le libellé du groupe est d'abord recherché dans <group>.<ocd id>.name, puis dans <group>.name. La description du groupe est d'abord recherchée dans <group>.<ocd id>.description, puis dans <group>.description.


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

Nom du fichier : rwlp_extensions_osgi_metatype.html