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.
xmlns:ibm="http://www.ibm.com/xmlns/appservers/osgi/metatype/v1.0.0"
The alias extension is used to define a user-friendly name for the configuration while reducing 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 user-friendly 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 that are installed in the default user location is usr. For product extensions defined to the Liberty profile installation by 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.
<usr_properties username="JANE"/>
<com.ibm.ws.jdbc.dataSource.properties username="JANE"/>
Standard attribute types are defined in the metatype specification. Several IBM® extended types are available. For more information, see Extended types.
The reference attribute specifies the OCD type that a PID references. It is used only with the ibm:pid type and supports nesting of 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".../>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}"/>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 following example shows ibm:variable:
<AD id="traceString" ibm:variable="trace.string" default=*.all=enabled".../>jndiName: use this group on attributes that register a service by using the osgi.jndi.service.name property with the JNDI name. For more information, see Developing with the JNDI default namespace in a Liberty feature
You 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="(&(virtualHost=${id}) (enabled=true))"/>
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 units are globalized, so users enter the values by using abbreviations from their local language.
In English, the following examples show the available units:
By default, 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. However, you can also specify the duration type such that it evaluates into a different unit.
The following examples show the possible types:
There is no difference between duration and duration(ms).
The following examples show the duration type:
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:
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"/>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 displays 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".../>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 displays the encoding options that can be used for a hashed password field. Valid encoding options are xor, aes, and hash.
The following example shows the passwordHash type:
<AD id="hashedPassword" type="String" ibm:type="passwordHash".../>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".../>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".../>xmlns:ibmui="http://www.ibm.com/xmlns/appservers/osgi/metatype/ui/v1.0.0"
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>
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 by 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.
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.
The following examples show the ibmui:group extension:
The group label and description information are looked up in the metatype localization file (if one is specified by 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.