Extensions to the OSGi metatype service

The Liberty runtime environment and developer tools recognize some extensions to the OSGi metatype specification for more complex configurations and a better presentation in a user interface.


Runtime metatype extensions

Add this namespace to your metatype.xml file to use the following extensions: 

    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>

    In this example properties is the usable name for the configuration. The alias must be different from the id.

    When the ibm:alias entry is used in the server.xml file, it must be prefixed with the product extension name. The product extension name for extensions installed in the default user location is usr. For product extensions defined to the Liberty installation using an extension-name.properties file in the wlp/etc/extension directory, the product extension name is the name that is chosen for extension-name. For the metatype shown in the previous example, if the feature is installed in the default usr location then the following are examples of valid server.xml entries: 

      <usr_properties username="JANE"/>

      <com.ibm.ws.jdbc.dataSource.properties username="JANE"/>

    ibm:type

    Standard attribute types are defined in the metatype specification. Several IBM extended types are available.

    See Extended types.

    ibm:reference

    The reference attribute specifies the OCD type that a PID references. The reference attribute is used only with the ibm:pid type and supports non-nested and nested elements in the server.xml file.

    See Nesting configuration elements.

    The following example shows the ibm:reference extension: <AD id="fooRef" type="String" ibm:type="pid" ibm:reference="com.ibm.ws.foo".../>

    ibm:final

    The final attribute indicates that the value cannot be specified in the config. Instead, the default value from the metatype is always used. Use name="internal" to indicate that tools not display this property.

    The following example shows the ibm:final extension: <AD id="foo" name="internal" ibm:final="true" type="String" default=${someVariable}"/>

    ibm:variable

    The variable attribute is used to specify a variable to be used for the default value if one is not specified. The behavior is to choose, in order:

    • The value specified in server.xml

    • The value specified as a system property, for example in bootstrap.properties

    • The default value from the metatype

    The following example shows ibm:variable: <AD id="traceString" ibm:variable="trace.string" default="*=all".../>

    ibm:unique

    The unique attribute indicates that a configuration value must be unique across all attribute definitions that use the same unique attribute group. The following unique attribute groups are supported:

    ibm:service

    The service extension is used with the objectClass extension to define an attribute that can reference several different configuration types. The service extension is similar to the reference extension because both extensions are used with ibm:type="PID" to define acceptable configuration types for the attribute. However, the reference extension can point only to a single configuration type. The service extension identifies a particular objectClass extension rather than a specific configuration PID type like the reference extension does. Multiple configuration types can have a specific object class, which is defined by the ibm:objectClass extension on the OCD.

    Although the attribute that uses the ibm:service extension can reference multiple configuration types, it cannot reference two different types with the same ID.

    The following example shows the ibm:service extension: 

      <AD id="toolRef" type="String" cardinality="5" ibm:type="pid" ibm:service="com.ibm.ws.toolType" name="Tools" description="Different types of Tools"/>

    ibm:objectClass

    The objectClass extension identifies that an OCD belongs to a specific class of objects. Multiple configuration types can use the same objectClass value. This extension is used only with the ibm:service extension to identify the configuration types that a specific attribute definition can reference.

    Show the ibm:objectClass extensions: 

      <OCD id="com.ibm.ws.tool.hammer" ibm:objectClass="com.ibm.ws.toolType" name="Hammer" description="A Hammer">
<OCD id="com.ibm.ws.tool.screwdriver" ibm:objectClass="com.ibm.ws.toolType" name="Screwdriver" description="A Screwdriver">

    ibm:serviceFilter

    The serviceFilter extension is used with the service extension to specify more filters for selecting objectClass references. The serviceFilter extension must be a valid OSGi filter. A serviceFilter extension is typically used to limit potential matching PID types.

    The following example shows the ibm:serviceFilter extension: 

      <AD id="hammersRef" type="String" ibm:type="pid" ibm:service="com.ibm.ws.toolType" ibm:serviceFilter="(service.pid=com.ibm.ws.tool.hammer)" name="Hammers" description="Tools, but only hammers"/>

    default value syntax

    We can use ${prop-name} syntax in default expressions to construct strings out of other configuration properties.

    The following example shows a default value syntax: 

      <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 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, we 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).

    Note:

    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".

    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 using an absolute or relative file path.

      location(dir)

      References a dir 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 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 used for a hashed password field. Valid encoding options are xor, aes, and hash. Validate a new password against a hashed password 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 Nesting configuration elements.

    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 blank space that occurs before or after the String.

    The following example shows an attribute defined 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

    The extraProperties extension is used to indicate that an arbitrary set of configuration attributes can be set on this configuration.

    The following example shows the ibmui:extraproperties extension: 

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

    The label and description that is associated with extension is looked up in the metatype localization file (if one is specified using the ibmui:localization extension). For the extension label, first extraProperties.<ocd id>.name and then extraProperties.name keys are checked. For the extension description, first extraProperties.<ocd id>.description and then extraProperties.description keys are checked.

    ibmui:group

    The group extension is used to specify that the attribute belongs to a group. In the user interface, the attributes that are annotated with the same group are grouped.

    Show the ibmui:group extension:

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

    The group label and description information are looked up in the metatype localization file (if one is specified using the ibmui:localization extension). For the group label, first <group>.<ocd id>.name and then <group>.name keys are checked. For the group description, first <group>.<ocd id>.description and then <group>.description keys are checked.