OSGi 元类型服务的扩展
Liberty 运行时环境和开发者工具可以识别 OSGi 元类型规范的一些扩展,这些扩展可以用来实现更复杂的配置以及在用户界面中获得更好的表示效果。
运行时元类型扩展
xmlns:ibm="http://www.ibm.com/xmlns/appservers/osgi/metatype/v1.0.0"
- ibm:alias
别名扩展用于为配置定义可用的名称,同时降低 server.xml 文件中配置元素的名称产生冲突的风险。
以下示例显示了 ibm:alias 扩展:
<OCD id="com.ibm.ws.jdbc.dataSource.properties" name="%properties" description="%properties.desc" ibm:alias="properties"> <AD id="username".../> </OCD>
在此示例中,properties 是配置的可用名称。别名和标识必须不同。
在 server.xml 文件中使用 ibm:alias 条目时,该条目必须以产品扩展名作为前缀。安装在缺省用户位置中的扩展的产品扩展名是 usr。对于通过使用 wlp/etc/extension 目录中的 extension-name.properties 文件来定义到 Liberty 安装的产品扩展,产品扩展名是为 extension-name 选择的名称。
对于先前示例中所示的元类型,如果将功能部件安装在缺省 usr 位置中,那么以下是有效 server.xml 条目的示例:<usr_properties username="JANE"/>
<com.ibm.ws.jdbc.dataSource.properties username="JANE"/>
- ibm:type
在元类型规范中定义标准属性类型。有数种 IBM® 扩展类型可供使用。有关更多信息,请参阅扩展类型。
- ibm:reference
reference 属性指定 PID 所引用的 OCD 类型。它仅与 ibm:pid 类型一起使用,且支持在 server.xml 文件中嵌套元素;请参阅嵌套配置元素。
以下示例显示了 ibm:reference 扩展:
<AD id="fooRef" type="String" ibm:type="pid" ibm:reference="com.ibm.ws.foo".../>- ibm:final
final 属性指示不能在配置中指定值。相反地,总是使用元类型中的缺省值。使用 name="internal" 来指示工具不显示此属性。
以下示例显示了 ibm:final 扩展:
<AD id="foo" name="internal" ibm:final="true" type="String" default=${someVariable}"/>- ibm:variable
variable 属性用来指定要用于缺省值的变量(如果未指定变量)。行为是以下列顺序选择:
- 在 server.xml 中指定的值
- 指定为系统属性的值(例如,在 bootstrap.properties 中指定)
- 元类型中的缺省值
以下示例显示了 ibm:variable:
<AD id="traceString" ibm:variable="trace.string" default=*.all=enabled".../>- ibm:unique
- unique 属性表明配置值在所有使用同一个唯一属性组的属性定义中必须唯一。下列唯一属性组受支持:
-
jndiName:通过将 osgi.jndi.service.name 属性与 JNDI 名称配合使用来对用于注册服务的属性使用此组。有关更多信息,请参阅 在 Liberty 功能部件中使用 JNDI 缺省名称空间开发。
-
- 缺省值语法
可以在缺省表达式中使用 ${prop-name} 语法,从其他配置属性构造字符串。
以下示例显示了缺省值语法:
<AD id="httpEndpoint.target" name="internal" description="internal use only" ibm:final="true" required="false" type="String" default="(&(virtualHost=${id}) (enabled=true))"/>
扩展类型
- Duration
duration 类型用来表示时间。它以多个时间单位进行描述。例如,“1h30m”将是一个半小时。“1d5h10s”将是 1 天 5 小时 10 秒。
以下列表显示可用单位:
- d - 天
- h - 小时
- m - 分钟
- s - 秒
- ms - 毫秒
缺省情况下,使用 duration 类型时,将以毫秒为单位对用户指定的值进行求值。例如,“10s”将是字典中的长整型值 10000。此外,如果用户指定没有任何单位的值,那么将以毫秒为单位对此值进行求值。例如,值“10”将求值为 10 毫秒。但是,您也可以指定 duration 类型,以便它依照不同的单位进行求值。例如,针对 ibm:type="duration(s)" 指定值“10”将求值为 10 秒,并作为 10 存储在字典中。
以下列表将显示可能类型:
- duration(h)
- duration(m)
- duration(s)
- duration(ms)
- duration
指定 duration 与 duration(ms) 之间没有差别。
注:最佳实践:在值中始终包括单位,并使用最容易阅读的单位来表示值。例如,对 ibm:type="duration(s)" 不指定值“7200”,而是指定值“2h”。
以下示例显示了 duration 类型:
- <AD id="timeout" type="String" ibm:type="duration(s)".../>
- <AD id="timeout" type="String" ibm:type="duration".../>
- Location
location 类型可让 UI 工具以更有帮助的方式来显示属性,而这些属性表示各种文件和目录位置。它不影响运行时环境进行的处理。字典对象总是为字符串。
以下示例显示可能类型:
- location
- 对文件进行引用。引用可以是绝对文件、相对文件,也可以是文件的 URL。
- location(file)
- 通过使用绝对或相对文件路径来引用文件。
- location(dir)
- 通过使用绝对或相对文件路径来引用目录。
- location(url)
- 在 URL 末尾对文件进行引用。
以下示例显示了 location 类型:
<AD id="location" name="%appmgr.location.name" description="%appmgr.location.desc" type="String" required="true" ibm:type="location"/>- Password
这种 password 类型用于密码字段。如果使用,那么字典对象是 com.ibm.wsspi.kernel.service.utils.SerializableProtectedString 的实例。密码字段的值不会记录在跟踪文件中。开发者工具显示可用于密码字段的编码选项。有效编码选项为 xor 和 aes。
以下示例显示了 password 类型:
<AD id="password" type="String" ibm:type="password".../>- Hashed password
此 passwordHash 类型与 password 类型相似,用于散列密码字段。如果使用,那么字典对象是 com.ibm.wsspi.kernel.service.utils.SerializableProtectedString 的实例。散列密码字段的值不会记录在跟踪文件中。开发者工具显示可用于散列密码字段的编码选项。有效的编码选项为 xor、aes 和 hash。
使用 PasswordUtil.encode(String, String, Map) 方法并指定以下参数来对散列密码验证新密码:- 新密码。
- 散列算法,通过调用 PasswordUtil.getCryptoAlgorithm 方法获取。此散列算法必须与该散列密码的算法匹配。
- 属性对象,其中某个属性使用 PasswordUtil.PROPERTY_HASH_ENCODED 来表示密钥,并使用散列密码来表示值。
以下示例显示 passwordHash 类型:
<AD id="hashedPassword" type="String" ibm:type="passwordHash".../>- Pid
pid 类型用来对配置中的另一个对象进行引用。它与 ibm:reference 属性一起使用,且支持在 server.xml 文件中嵌套元素;请参阅嵌套配置元素。
以下示例显示了 pid 类型:
<AD id="fooRef" type="String" ibm:type="pid" ibm:reference="com.ibm.ws.foo".../>- OnError
onError 类型会在字典中产生 onError 枚举类型的实例。可能的值为 WARN、FAIL 和 IGNORE。
以下示例显示了 onError 类型:
<AD id="errorBehavior" type="String" ibm:type="onError".../>- Token
token 类型用于指示对于配置中指定的值,必须将出现在 String 前后的任何空格删除。
以下示例显示一个使用 token 类型定义的属性:
<AD id="name" type="String" ibm:type="token" .../>
用户界面元类型扩展
xmlns:ibmui="http://www.ibm.com/xmlns/appservers/osgi/metatype/ui/v1.0.0"
- ibmui:localization
localization 扩展用来指定元类型本地化文件。元类型本地化文件用来查找其他 UI 扩展的标签和描述的翻译。在大多数情况下,ibmui:localization 扩展的值与 <Metadata> 元素上的 localization 属性匹配。
以下示例显示了 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
extraProperties 扩展用来指示可以在此配置上设置任意的配置属性集。
以下示例显示了 ibmui:extraproperties 扩展:
<OCD id="com.ibm.ws.jdbc.dataSource.properties" name="%properties" description="%properties.desc" ibmui:extraProperties="true"> <AD id="username".../> </OCD>
在元类型本地化文件中查找与扩展相关联的标签和描述(如果已使用 ibmui:localization 扩展来指定了元类型本地化文件)。对于扩展标签,请先检查 extraProperties.<ocd id>.name 键,然后检查 extraProperties.name 键。对于扩展描述,请先检查 extraProperties.<ocd id>.description 键,然后检查 extraProperties.description 键。
- ibmui:group
group 扩展用来指定属性属于组。在用户界面中,注释为同一个组的属性分为一组。
以下示例显示了 ibmui:group 扩展:
- <AD id="username" ibmui:group="userInfo".../>
- <AD id="password" ibmui:group="userInfo".../>
- <AD id="port" ibmui:group="hostInfo".../>
在元类型本地化文件中查找组标签和描述信息(如果已使用 ibmui:localization 扩展来指定了元类型本地化文件)。对于组标签,请先检查 <group>.<ocd id>.name 键,然后检查 <group>.name 键。对于组描述,请先检查 <group>.<ocd id>.description 键,然后检查 <group>.description 键。