Liberty プロファイルのマニフェスト・ファイル

Liberty のフィーチャーは、フィーチャー・マニフェスト・ファイルと、Liberty プロファイル・ランタイム環境の特定の機能に対応するクラスおよびサービスを提供する 1 つ以上の OSGi バンドルのコレクションから成ります。 フィーチャー・マニフェストのフォーマットと、マニフェスト・ファイル内の各ヘッダーの意味について概説します。

Liberty プロファイルのフィーチャー・マニフェスト・ファイルでは、OSGi Enterprise R5 仕様の Subsystem Service メタデータ・フォーマットを使用します。 フィーチャーは、lib/features ディレクトリーに保管されているフィーチャー・マニフェスト・ファイル (.mf ファイル) によって定義され、サブシステムのカスタム・タイプ osgi.subsystem.feature を使用する必要があります。 OSGi マニフェスト構文について詳しくは、OSGi コア仕様のセクション 1.3.2 を参照してください。

注: フィーチャー・マニフェスト・ファイルで、属性の形式は name=value ですが、 ディレクティブの形式は name:=value になります。

以下のヘッダーが定義されます。
表 1. フィーチャー・マニフェスト・ファイルのヘッダー.

この表では、Liberty プロファイルのフィーチャー・マニフェスト・ファイルのヘッダーを示します。 1 列目にはヘッダーのリスト、2 列目には各ヘッダーの説明が示されています。3 列目には、当該ヘッダーが必須かどうかが示されています。

ヘッダー 説明 必須
Subsystem-ManifestVersion フィーチャー・マニフェスト・ファイルのバージョン・フォーマット。 1 に設定する必要があります。 いいえ
Subsystem-SymbolicName フィーチャーおよびすべての属性またはディレクティブのシンボル名。 はい
Subsystem-Version フィーチャーのバージョン。これの定義方法について詳しくは、OSGi コア仕様のセクション 3.2.5 を参照してください。 いいえ
Subsystem-Type フィーチャーのサブシステム・タイプ。すべてのフィーチャーは現在、同じサブシステム・タイプの osgi.subsystem.feature です。 はい
Subsystem-Content フィーチャーのサブシステムの内容。これは、このフィーチャーを実行するために必要なバンドルとサブシステムのコンマ区切りリストです。 server.xml ファイルで自動フィーチャーを構成できるようにする場合は、必須フィーチャーが含まれた機能ヘッダーを設定し、さらにそれらをサブシステムの内容で定義する必要があります。 はい
Subsytem-Localization フィーチャーのローカリゼーション・ファイルのロケーション。 いいえ
Subsystem-Name 人間が判読可能な短いフィーチャー名。 この値は、ローカライズ可能です。 いいえ
Subsystem-Description フィーチャーの説明。この値は、ローカライズ可能です。 いいえ
IBM-Feature-Version このサブシステム・タイプのバージョン。2 に設定する必要があります。 はい
IBM-Provision-Capability フィーチャーを自動的にプロビジョンできるかどうかを記述する機能ヘッダー。 いいえ
IBM-API-Package このフィーチャー、他の製品拡張内のフィーチャー、および Liberty カーネルによってアプリケーションに公開される API パッケージ。 いいえ
IBM-API-Service このフィーチャーによって OSGi アプリケーションに公開される OSGi サービス。 いいえ
IBM-SPI-Package このフィーチャーによって他の製品拡張内のフィーチャーおよび Liberty カーネルに公開される SPI パッケージ。 いいえ
IBM-ShortName フィーチャーのショート・ネーム。 いいえ
IBM-AppliesTo このフィーチャーが適用される Liberty バージョン。 いいえ
Subsystem-License このフィーチャーのライセンス・タイプ。 いいえ
IBM-License-Agreement ご使用条件ファイルのロケーションの接頭部。 いいえ
IBM-License-Information ライセンス情報ファイルのロケーションの接頭部。 いいえ
IBM-App-ForceRestart 稼働中のサーバーに対してフィーチャーのインストールまたはアンインストールを行った場合にアプリケーションを再始動することを指定します。 いいえ

Subsystem-SymbolicName

このヘッダーの構文は、バンドルの Bundle-SymbolicName 構文と同じです。パッケージ名スタイル構文の後に、シンボル名が続きます。また、オプションとして、属性およびディレクティブのセットを取ることができます。

以下の属性がサポートされます。
  • superseded。この属性は、このフィーチャーが 1 つ以上のフィーチャーまたは機能項目によって置き換えられているかどうかを示します。 以下のいずれかの値となります。
    • true - フィーチャーは置き換えられています。
    • false - フィーチャーは置き換えられていません。
    この属性はオプションです。デフォルト値は false です。

    詳細については、『置き換えられたフィーチャー』を参照してください。

  • superseded-by。この属性は、このフィーチャーを置き換えるフィーチャーが存在する場合に、そのフィーチャーのコンマ区切りリストを指定します。この属性はオプションです。
以下のディレクティブがサポートされます。
  • visibility。このディレクティブは、以下の値のいずれかを取ります。
    • public - API と見なされるフィーチャー。このフィーチャーは、開発者ツールでサポートされており、server.xml ファイルで使用するためのもので、メッセージで出力されます。
    • protected - SPI と見なされるフィーチャー。このフィーチャーは、開発者ツールでサポートされておらず、server.xml ファイルで使用するためのものではなく、メッセージで出力されることもありません。エクステンダーが使用してより高度なフィーチャーをビルドするために、このフィーチャーは提供されています。
    • private - (デフォルト) このフィーチャーは、製品内部です。 このフィーチャーは、server.xml ファイルで使用するためにサポートされず、またエクステンダー・フィーチャーで参照されることもありません。 フィーチャーはフィックスパック間を含め、いつでも変更できます。
以下に例を示します。
Subsystem-SymbolicName: com.ibm.example.feature-1.0; 
    visibility:=public; superseded=true; superseded-by="com.ibm.example.feature-2.0"
superseded-by リスト内のフィーチャー名が大括弧 ([]) で囲まれている場合、このフィーチャーは置き換えのフィーチャーから切り離されています。次の例では、フィーチャー appSecurity-1.0 (フィーチャー servlet-3.0ldapRegistry-3.0 を含む) が フィーチャー appSecurity-2.0 (servlet-3.0ldapRegistry-3.0 フィーチャーを含まない) によって置き換えられます。
IBM-ShortName: appSecurity-1.0
Subsystem-SymbolicName: com.ibm.websphere.appserver.appSecurity-1.0; visibility:=public;
superseded=true; superseded-by="appSecurity-2.0, [servlet-3.0], [ldapRegistry-3.0]"
詳細については、『置き換えられたフィーチャー』を参照してください。
ベスト・プラクティス: 開発者ツールがフィーチャーを示す必要がある場合は、public でなければなりません。フィーチャーを使用できるのが信頼できるパーティーのみの場合は、protected でなければなりません。 フィーチャーが内部で、任意の時点で変更される場合、private でなければなりません。

Subsystem-Content

このヘッダーでは、ランタイムとインストールの両方に対して、フィーチャーの内容を定義します。 これは、次の構文を持つサブシステム仕様と同じヘッダー構文に従います。
Subsystem-Content ::= content ( ',' content )*
        content ::= unique-name ( ';' parameter )*
        unique-name ::= unique-name        (see OSGi core spec section 1.3.2)
unique-name は、Bundle-SymbolicName または Subsystem-SymbolicName ヘッダーの形式を使用します。 以下の属性がサポートされます。
  • version - バンドルの検索時に突き合わせるバージョンの範囲。この範囲内のバンドルのみが選択されます。バージョン範囲の一般的な例として、[1,1.0.100) が挙げられます。
  • type - プロビジョンする内容のタイプ。 内容のタイプを示す任意の値を指定できます。 タイプによっては、指定すると、そのフィーチャーを使用するサーバーの OSGi フレームワークにバンドルがインストールされて開始されます。 どのタイプでも、そのフィーチャーを含むインストール・パッケージにその内容が組み込まれます。 定義済みの値は、以下のとおりです。
    • osgi.bundle - これはデフォルト値です。 サーバーの OSGi フレームワークとインストール・パッケージの両方にプロビジョンする OSGi バンドルを示します。
    • osgi.subsystem.feature - この値は、サーバーの OSGi フレームワークとインストール・パッケージの両方にフィーチャーをプロビジョンすることを示します。 これらのフィーチャーは、 Subsystem-SymbolicName ヘッダーで指定された名前を使用する必要があります。
    • jar - この値は、JAR ファイルがインストール・パッケージに組み込まれる必要があり、バージョン範囲、ロケーション値、またはその両方の組み合わせを使用して JAR ファイルが選択されることを示します。
    • file - この値は、 location 属性で特定されたファイルがインストール・パッケージに組み込まれることを示します。
以下のディレクティブがサポートされます。
  • location - バンドルのロケーション。バンドルまたは JAR タイプの場合、この値は、dev ディレクトリー内の仕様および API バンドルを識別するために使用されるディレクトリーのコンマ区切りリスト、または JAR ファイルを直接指している単一エントリーにすることができます。typefile の場合は、単一エントリーのみが許可され、そのファイルを直接指していなければなりません。
  • start-phase - システム始動時にバンドルを開始する始動フェーズ。 start-phase ディレクティブは、以下のいずれかの値を取ることができます。
    • SERVICE - この値は、最初期のフェーズを示します。デフォルトでは、始動レベル 9 にマップされます。
    • CONTAINER - これは、start-phase を指定しなかった場合のデフォルト値です。アプリケーション・コンテナーの始動時のコンテナー・フェーズを示します。デフォルトでは、始動レベル 12 にマップされます。
    • APPLICATION - この値は、アプリケーションの始動時の最後のフェーズを示します。
    バンドルをこれらのフェーズの直前または直後に開始するように定義することもできます。キー・フェーズの直後にする場合は _LATE を追加し、直前にする場合は _EARLY を追加します。そのため、コンテナー・フェーズの直後に実行する場合は、CONTAINER_LATE を使用し、APPLICATION フェーズの前に実行する場合は、APPLICATION_EARLY を使用します。
以下に例を示します。
Subsystem-Content: com.ibm.websphere.appserver.api.basics; version="[1,1.0.100)"; type=jar; location:="dev/api/ibm/,lib/",
                   com.ibm.websphere.appserver.spi.application; 
				   location:="dev/spi/ibm/com.ibm.websphere.appserver.spi.application_1.0.0.jar"; type="jar",
                   com.ibm.websphere.appserver.spi.application_1.0.0-javadoc.zip;
				   location:="dev/spi/ibm/javadoc/com.ibm.websphere.appserver.spi.application_1.0.0-javadoc.zip"; type="file"
AIX プラットフォームの場合HP UNIX プラットフォームの場合LINUX プラットフォームの場合Solaris プラットフォームの場合IBM i プラットフォームの場合Liberty リポジトリー[8.5.5.4 以降]バージョン 8.5.5.4 以降では、以下のディレクティブがサポートされます。
  • ibm.executable - 値が「true」に設定されている場合、現在の umask 設定に従って、実行許可を関連ファイルに追加します。それ以外の値の場合、アクションは実行されません。以下の表に現在の umask 設定と、実行許可が付与されるクラスを示します。
    表 2. umask 値と、ibm.executable によって実行許可が設定されるクラスの例
    umask 実行許可が付与されるクラス
    022 所有者、グループ、その他
    023 所有者、グループ
    055 所有者

Subsytem-Localization

このヘッダーは、フィーチャーのローカリゼーション・ファイルのロケーションを指定します。

以下に例を示します。
Subsystem-Localization: OSGI-INF/l10n/loc

Subsystem-Name

このヘッダーを使用して、人間が判読可能な短いフィーチャー名を指定します。 リテラル・ストリングまたはプロパティー名のいずれかを指定することができます。 プロパティー名を指定する場合、値はローカライズ可能です。

例:
Subsystem-Name: %name
ここで、name の値は、 Subsytem-Localization ヘッダーで指定されたロケーションにある properties ファイル (上記の例では loc.properties) において次の形式で定義されています。
name=feature_name

Subsystem-Description

このヘッダーを使用して、フィーチャーの説明を指定します。 リテラル・ストリングまたはプロパティー名のいずれかを指定することができます。 プロパティー名を指定する場合、値はローカライズ可能です。

例:
Subsystem-Description: %desc
ここで、desc の値は、 Subsytem-Localization ヘッダーで指定されたロケーションにある properties ファイル (上記の例では loc.properties) において次の形式で定義されています。
desc=feature_description

IBM-Provision-Capability

自動的にプロビジョンされるフィーチャーは、マニフェスト内に IBM-Provision-Capability ヘッダーがあるフィーチャーです。このヘッダーに、このフィーチャーを自動的にプロビジョンするためにプロビジョンされる必要がある他のフィーチャーを記述します。他のフィーチャーをリストする場合は、そのフィーチャーの Subsystem-SymbolicName ヘッダーを使用します。server.xml ファイル内にフィーチャーが構成されている場合、ランタイムによって、自動的にプロビジョンされるフィーチャーの機能が満たされているかどうかがチェックされ、満たされているフィーチャーが存在する場合は、それらのフィーチャーが自動的にプロビジョンされます。

IBM-Provision-Capability ヘッダーのフォーマットは、標準 OSGi LDAP フィルターを使用します。

IBM-API-Package

このヘッダーを使用して、アプリケーションから可視の API パッケージを示します。Export-Package ヘッダー構文と同じです。つまり、API パッケージのコンマ区切りリストです。ただし、各 API パッケージに属性を設定できます。

以下の属性がサポートされます。
  • type - API パッケージのタイプ。type 属性は、以下のいずれかの値を取ります。
    • spec - javax.servletorg.osgi.framework など、標準化団体によって提供される API を示します。
    • ibm-api - IBM® によって提供される、価値が付加された API を示します。
    • api - ユーザー定義の API を示します。これはデフォルト値です。
    • third-party - 可視であるが、IBM によって制御されない API を示します。 オープン・ソースのパッケージが典型的です。
    • internal - アプリケーション が機能するためにアプリケーションに対して公開される必要のある 非 API パッケージを示します。これは、 実行時に内部コードへの参照を追加するために Java™ コード がバイトコード拡張 (ウィーブ ) されている場合に 使用される可能性があります。
以下に例を示します。
IBM-API-Package: javax.servlet; type="spec",
                 com.ibm.websphere.servlet.session; type="ibm-api",
                 com.ibm.wsspi.webcontainer.annotation; type="internal"

IBM-API-Service

このヘッダーを使用して、OSGi アプリケーションから可視のフィーチャーのサービスを示します。 フィーチャーは、サービスを OSGi サービス・レジストリーに登録する必要もあります。

構文は以下のとおりです。
IBM-API-Service ::= service ( ',' service )*
                    service ::= service-name ( ';' attribute )*
                    service-name ::= unique-name
service-name は、サービスの Java クラスまたはインターフェース名です。属性は、サービスのサービス・プロパティーとして解釈されます。
以下に例を示します。
IBM-API-Service: com.ibm.example.service.FeatureServiceOne; 
                 myServiceAttribute=myAttributeValue,
                 com.ibm.example.service.FeatureServiceTwo

OSGi アプリケーションが、IBM-API-Service ヘッダーによって提供されるサービスを使用する必要がある場合、サービスをアプリケーションにプロビジョンするために、サービスへの Blueprint 参照をアプリケーションに組み込む必要があります。

以下に例を示します。
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
	<reference id="FeatureServiceOneRef"
			interface="com.ibm.example.service.FeatureServiceOne" />
</blueprint>

OSGi アプリケーション内のバンドルでサービスを使用可能にするためには、そのバンドルでインターフェース・パッケージを使用できるようにしなければなりません。すなわち、コンシュームするバンドルのマニフェスト・ファイル内の Import-Package ヘッダーでインターフェース・パッケージを指定する必要があります。インターフェース・パッケージは、フィーチャー・バンドルの Export-Package ヘッダーでも指定される必要があるほか、フィーチャー・マニフェスト・ファイルの IBM-API-Package ヘッダー内にも指定する必要があります。フィーチャーによって提供されるサービスは、OSGi BundleContext インターフェースまたは Declarative Services や Blueprint などの他のメカニズムを使用して、OSGi サービス・レジストリーに登録する必要があります。詳細については、『単純なアクティベーションを使用した OSGi バンドルの開発』および『OSGi Declarative Services を使用した拡張フィーチャーの構成』を参照してください。

IBM-SPI-Package

独自の Liberty フィーチャーを作成した場合は、そのフィーチャーをユーザー製品拡張にインストールします。ユーザー製品拡張にインストールされている他のすべてのフィーチャーが、フィーチャー内のすべてのパッケージにアクセスできます。ただし、別の製品拡張にインストールされているフィーチャーからフィーチャー内のパッケージにアクセスするには、IBM-SPI-Package ヘッダーにパッケージ名をリストする必要があります。

IBM-SPI-Package ヘッダーにリストされたすべてのパッケージは、バンドル・マニフェスト・ファイルの Export-Package ヘッダーにリストすることで、Liberty フィーチャー内のバンドルによってエクスポートする必要があります。

IBM-ShortName

このヘッダーは、server.xml ファイルでのフィーチャーの指定に使用できる、フィーチャーのショート・ネームです。 マニフェスト・ファイルに IBM-ShortName ヘッダーがない場合は、 Subsystem-SymbolicName がデフォルトで使用されます。IBM-ShortName ヘッダーはパブリックのフィーチャーの場合にのみ有効です。

IBM-AppliesTo

このヘッダーは、このフィーチャーが適用される Liberty バージョンを指定します。 以下の形式の各項目をコンマ区切りリストで指定します。
product_id; productVersion=product_version; productInstallType=product_install_type; productEdition=product_editions

複数の項目を指定する場合は、各項目の product_id の値を異なるものにする必要があります。

product_editions の値には、単一のエディションを指定することも、 エディションのコンマ区切りリストを引用符で囲んで指定することもできます。

以下に例を示します。
IBM-AppliesTo: com.ibm.websphere.appserver; productVersion=8.5.5; productInstallType=Archive; productEdition="BASE,DEVELOPERS,EXPRESS,ND"

Subsystem-License

このヘッダーは、このフィーチャーのライセンス・タイプを定義します。 Subsystem-License ヘッダーに値を指定して IBM-License-Agreement ヘッダーと IBM-License-Information ヘッダーに値を指定しないと、Subsystem-License ヘッダーの値がインストール中に同意のためにユーザーに表示されます。

同じ Subsystem-License ヘッダー値で既にインストールされているフィーチャーがある場合、 インストール中に、そのライセンスは表示されず、ライセンスの承認は求められません。 Subsystem-License ヘッダー値が同じ 2 つ以上のフィーチャーがインストールされることが、Subsystem-Content ヘッダーの依存関係によって示されている場合、 インストール中にライセンスを受諾する必要があるのは一度のみです。

以下に例を示します。
Subsystem-License: L-JTHS-93TMHH
Subsystem-License: http://www.apache.org/licenses/LICENSE-2.0.html

IBM-License-Agreement

このヘッダーは、ご使用条件ファイルのロケーションの接頭部を指定します。 サブシステム・アーカイブ内での LA_language ファイルへのファイル・パスを、 「_」という文字の前まで指定します (言語コードはインストール・ツールによって付加されます)。 このライセンスが受諾されていない場合、 ユーザーはフィーチャーのインストール時にライセンスを受諾する必要があります。 ライセンス・ファイルは、Liberty のインストール・ディレクトリーにコピーされます。

以下に例を示します。
IBM-License-Agreement: lafiles/LA

IBM-License-Information

このヘッダーは、ライセンス情報ファイルのロケーションの接頭部を指定します。 サブシステム・アーカイブ内での LI_language ファイルへのファイル・パスを、 「_」という文字の前まで指定します (言語コードはインストール・ツールによって付加されます)。 このライセンスが受諾されていない場合、 ユーザーはフィーチャーのインストール時にライセンスを受諾する必要があります。 ライセンス・ファイルは、Liberty のインストール・ディレクトリーにコピーされます。

以下に例を示します。
IBM-License-Information: lafiles/LI

IBM-App-ForceRestart

このヘッダーを指定すると、稼働中のサーバーにフィーチャーがインストールされたり、そこからフィーチャーが削除されたりした場合に、アプリケーションが再始動されます。このヘッダーには、以下のいずれかの値を指定することができます。
  • install - フィーチャーがインストールされた場合にアプリケーションを再始動します。
  • uninstall - フィーチャーがアンインストールされた場合にアプリケーションを再始動します。
  • install,uninstall - フィーチャーがインストールまたはアンインストールされた場合にアプリケーションを再始動します。

フィーチャー・マニフェスト・ファイルの例

以下の例は、 example-1.0 フィーチャーの定義を示しています。 visibility 属性を public に設定することで、このフィーチャーが、サーバー構成 (server.xml) ファイルで直接指定可能になります。 また、これは、開発者ツールの「サーバー構成」ビューで表示されるフィーチャーのドロップダウン・リストにも組み込まれ、他の製品拡張内のフィーチャーに組み込むために選択可能になります。 このフィーチャーがランタイム・インストールの usr 製品拡張にインストールされた場合、 server.xml ファイルに以下のコードを組み込むことによって、サーバーに構成することができます。
<featureManager>
	<feature>usr:example-1.0</feature>
</featureManager>
サーバーでこのフィーチャーを構成すると、 指定されたバンドル com.ibm.example.bundle1 が サーバー・ランタイム環境の OSGi フレームワークにインストールされて開始されます。単一の API パッケージ com.ibm.example.publicapi は、api パッケージ・タイプが可視でないように構成された Java EE アプリケーション以外の、そのサーバー内のすべてのアプリケーションから可視になります。 OSGi アプリケーションがこのパッケージを使用する場合は、明示的にそれをインポートする必要があります。 2 つの SPI パッケージ com.ibm.example.spi.utilscom.acme.spi.spiservices は、API パッケージと同様に、サーバー内のすべてのフィーチャー・コードから可視になります。
IBM-Feature-Version: 2
Subsystem-ManifestVersion: 1.0
Subsystem-SymbolicName: com.ibm.example-1.0; visibility:=public
Subsystem-Version: 1.0.0.qualifier
Subsystem-Type: osgi.subsystem.feature
Subsystem-Content: com.ibm.example.bundle1; version="1.0.0"
Subsystem-Localization: OSGI-INF/l10n/loc
Manifest-Version: 1.0
Subsystem-Name: %name
Subsystem-Description: %desc
IBM-API-Package: com.ibm.example.publicapi; type="api"
IBM-SPI-Package: com.ibm.example.spi.utils, com.ibm.example.spi.spiservices
IBM-ShortName: example-1.0

トピックのタイプを示すアイコン 参照トピック

インフォメーション・センターに関するご使用条件 | フィードバック


タイム・スタンプ・アイコン 最終更新: 2015 年 6 月 17日
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=rwlp_feat_definition
ファイル名: rwlp_feat_definition.html