OSGi meta 類型服務延伸
Liberty 執行時期環境和開發人員工具可辨識一些適用於較複雜的配置,且在使用者介面中會呈現得更好的 OSGi meta 類型規格延伸。
執行時期 meta 類型延伸
xmlns:ibm="http://www.ibm.com/xmlns/appservers/osgi/metatype/v1.0.0"
- ibm:alias
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 是使用者易懂的配置名稱。 別名必須有別於 ID。
當在 server.xml 檔中使用 ibm:alias 項目時,它的字首必須是產品延伸名稱。 安裝在預設使用者位置中的各項延伸,其產品延伸名稱是 usr。 利用 wlp/etc/extension 目錄中的 extension-name.properties 檔定義給 Liberty 設定檔安裝架構中的產品延伸,其產品延伸名稱是針對 extension-name 所選擇的名稱。
對於上述範例所顯示的 meta 類型,如果特性安裝在預設 usr 位置中,有效的 server.xml 項目範例如下:<usr_properties username="JANE"/>
<com.ibm.ws.jdbc.dataSource.properties username="JANE"/>
- ibm:type
標準屬性類型定義在 meta 類型規格中。 提供了若干 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 屬性指出無法在配置中指定值。 相反地,一律會使用 meta 類型中的預設值。 請利用 name="internal" 來指示工具不會顯示這個內容。
下列範例顯示 ibm:final 延伸:
<AD id="foo" name="internal" ibm:final="true" type="String" default=${someVariable}"/>- ibm:variable
variable 屬性用來指定要用作預設值的變數(如果未指定的話)。 這個行為有待選擇,順序如下:
- server.xml 中所指定的值
- 指定為系統內容的值,例如,在 bootstrap.properties 中
- meta 類型的預設值
下列範例顯示 ibm:variable:
<AD id="traceString" ibm:variable="trace.string" default=*.all=enabled".../>- ibm:unique
- unique 屬性指出配置值在使用相同唯一屬性群組的所有屬性定義中,必須是唯一的。支援的唯一屬性群組如下:
-
jndiName:使用這個屬性群組,以使用含有 JNDI 名稱的 osgi.jndi.service.name 內容來登錄服務。如需相關資訊,請參閱在 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" 是指一小時又 30 分鐘。 "1d5h10s" 是指 1 天又 5 小時 10 秒。 單位已全球化,因此使用者可以利用當地語言的縮寫來輸入值。
針對英文,下列清單顯示可用的單位:
- d - 日
- h - 時
- m - 分
- s - 秒
- ms - 毫秒
依預設,當使用 duration 類型時,會以毫秒求出使用者指定的值。例如,在字典中,"10s" 是 long 值 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
- 參照檔案。參照可能是絕對檔案、相對檔案,也可能是檔案的 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".../>- 雜湊式密碼
passwordHash 類型類似於密碼類型,用於雜湊式密碼欄位。 當使用時,字典物件是 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".../>
使用者介面 meta 類型延伸
xmlns:ibmui="http://www.ibm.com/xmlns/appservers/osgi/metatype/ui/v1.0.0"
- ibmui:localization
localization 延伸用來指定 meta 類型本地化檔案。 meta 類型本地化檔案用來查閱其他使用者介面延伸的標籤和說明的翻譯。 在大部分情況下,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>
會在 meta 類型本地化檔案(如果有利用 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".../>
會在 meta 類型本地化檔案(如果有利用 ibmui:localization 延伸指定的話)中,查閱 group 標籤和說明資訊。 對於群組標籤,會先檢查 <group>.<ocd id>.name 索引鍵,再檢查 <group>.name 索引鍵。 對於群組說明,會先檢查 <group>.<ocd id>.description 索引鍵,再檢查 <group>.description 索引鍵。