OSGi Metatype Service の拡張
Liberty ランタイム環境と開発者ツールは、より複雑な構成への対応やユーザー・インターフェースでの表示の向上を図るための、 OSGi メタタイプ仕様に対するいくつかの拡張を認識します。
ランタイム・メタタイプの拡張
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 が構成の分かりやすい名前です。 alias は id と異なるものでなければなりません。
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 フィーチャー内の JDNI デフォルト名前空間を使用した開発』を参照してください。
-
- デフォルト値の構文
デフォルトの式で ${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」は、1 時間半になります。 「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 タイプを使用して、ファイルやディレクトリーのさまざまなロケーションを表す属性をより便利に UI ツールで表示できるようになります。 これは、ランタイム環境による処理には影響しません。 ディクショナリー・オブジェクトは常に String です。
以下は、可能なタイプの例です。
- 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 タイプは 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 タイプを使用して、構成に指定された値では 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 のキーが検査されます。