OSGi バンドル・マニフェスト・ヘッダー

バージョン 3.1 - 最終改訂日 2005 年 6 月 20 日

バンドルは、META-INF/MANIFEST.MF という名前のマニフェスト・ファイルで、それ自体に関する記述情報を伝えることができます。OSGi R4 フレームワーク仕様では、Export-Package や Bundle-Classpath などのマニフェスト・ヘッダーのセットを定義しています。バンドルの開発者は、これを使用して、バンドルに関する記述情報を提供します。Eclipse OSGi フレームワークは、完全な OSGi R4 フレームワーク仕様、およびすべてのコア・フレームワーク・サービスを実装しています。OSGi R4 コア・フレームワーク・サービスには、以下のようなものがあります。

OSGi R4 仕様には、多くのオプションのサービスが定義されています。これらのオプション・サービスは、Eclipse OSGi フレームワークの実装には含まれていません。 FOSGi R4 マニフェスト・ヘッダーおよびサービスについては、OSGi 仕様 を参照してください。

Eclipse バンドル・マニフェスト・ヘッダー

Eclipse OSGi フレームワークは、多くの追加のバンドル・マニフェスト・ヘッダーおよびディレクティブをサポートしています。バンドル開発者は、これらの追加のヘッダーおよびディレクティブを使用して、標準の OSGi R4 フレームワークのパーツとして指定されていない、Eclipse OSGi フレームワークのいくつかの追加フィーチャーを利用することができます。

追加の Export-Package ディレクティブ

Eclipse OSGi フレームワークは、Export-Package ヘッダーで追加のディレクティブをサポートします。これらのディレクティブは、エクスポートされたパッケージのアクセス制限ルールを指定する場合に使用されます。ランタイム時にアクセス制限ルールを実施するように、Eclipse OSGi フレームワークを構成する場合は、『osgi.resolverMode』を参照してください。

x-internal ディレクティブ

x-internal ディレクティブは、パッケージが内部パッケージであるかどうかを指定するために、Export-Package ヘッダーで使用されます。プラグイン開発環境では、他のバンドルが内部パッケージを使用することは推奨されていません。x-internal ディレクティブが指定されていない場合は、デフォルト値である「false」が使用されます。x-internal ディレクティブでは、以下の構文を使用する必要があります。

x-internal ::= ( 'true' | 'false' )

以下に、x-internal ディレクティブの例を示します。

Export-Package: org.eclipse.foo.internal; x-internal:=true

x-friends ディレクティブ

x-friends ディレクティブを Export-Package ヘッダーで使用すると、パッケージへのアクセスを許可されているバンドルのリストを指定することができます。プラグイン開発環境では、他のバンドルがパッケージを使用することは推奨されていません。x-friends ディレクティブでは、以下の構文を使用する必要があります。

x-friends ::= '"' ( target-bundle ) ( ',' target-bundle ) * '"'
target-bundle ::= バンドル・シンボル名

以下に、x-friends ディレクティブの例を示します。

Export-Package: org.eclipse.foo.formyfriends; x-friends:="org.eclipse.foo.friend1, org.eclipse.foo.friend2"

この例では、バンドル org.eclipse.foo.friend1 および org.eclipse.foo.friend2 だけに org.eclipse.foo.formyfriends パッケージの使用が推奨されます。x-internal パッケージは、x-friends ディレクティブよりも優先されます。x-internal ディレクティブが「true」を指定している場合、プラグイン開発環境では、バンドルによるパッケージの使用は (バンドルが friend と指定されている場合であっても) 推奨されていません。

Eclipse-LazyStart ヘッダー

Eclipse-LazyStart ヘッダーは、バンドルが最初のクラスまたはリソースにアクセスする前に、自動的にそのバンドルを開始するかどうかを指定する場合に使用します。このフィーチャーを使用すると、バンドルが最初に必要になったときに、Eclipse がゆるやかに活動化することができます。Eclipse は、このモデルを使用して、できるだけ少ないアクティブ・バンドルを使用して開始することができます。Eclipse-LazyStart ヘッダーでは、以下の構文を使用する必要があります。

Eclipse-LazyStart ::= ( 'true' | 'false' ) ( ';' 'exceptions' '=' '"' exceptions-list '"' ) ?
exceptions-list ::= コンマ ',' で区切られたパッケージのリスト

'exceptions' 属性は、クラスまたはリソースがパッケージからロードされるときに、バンドルを活動化してはいけないパッケージのリストを指定するために使用されます。 Eclipse-LazyStart ヘッダーがバンドル・マニフェストで定義されていない場合は、デフォルト値である「false」が使用されます。以下に、Eclipse-LazyStart ヘッダーの例を示します。

Eclipse-LazyStart: true; exceptions="org.eclipse.foo1, org.eclipse.foo2"

この例では、パッケージ 'org.eclipse.foo1' および 'org.eclipse.foo2' 内のクラスおよびリソース以外の、このバンドルからロードされるすべてのクラスまたはリソースに対して、このバンドルを活動化する必要があることを指定しています。

Eclipse-AutoStart ヘッダーは、Eclipse 3.2 では推奨されなくなりました。代わりに Eclipse-LazyStart ヘッダーを使用してください。

Eclipse-PlatformFilter ヘッダー

Eclipse-PlatformFilter は、バンドルにプラットフォーム・フィルターを指定する場合に使用されます。バンドルを解決できるようにするためには、稼働中のプラットフォームでプラットフォーム・フィルターが true に評価される必要があります。Eclipse-PlatformFilter ヘッダーでは、以下の構文を使用する必要があります。

Eclipse-PlatformFilter ::= 有効な LDAP フィルター・ストリング

フレームワークは、以下のシステム・プロパティーに対するフィルターをサポートしています。

以下に、Eclipse-PlatformFilter ヘッダーの例を示します。

Eclipse-PlatformFilter: (& (osgi.ws=win32) (osgi.os=win32) (osgi.arch=x86))

この例では、プラットフォームのプロパティーが osgi.ws=win32、osgi.os=win32、および osgi.arch=x86 である場合にのみ、バンドルが解決可能であることを示しています。これはつまり、x86 アーキテクチャーで稼働し、win32 オペレーティング・システムと win32 ウィンドウ操作システムを使用しているプラットフォームを意味します。

Eclipse-BuddyPolicy ヘッダー

Eclipse-BuddyPolicy ヘッダーは、バンドルにバディ・ロード・ポリシーを指定するために使用されます。 Eclipse-BuddyPolicy ヘッダーでは、以下の構文を使用する必要があります。

Eclipse-BuddyPolicy ::= ( policy-name ) ( ',' policy-name ) *
policy-name ::= ( 'dependent' | 'global' | 'registered' | 
                  'app' | 'ext' | 'boot' | 'parent' )

以下に、Eclipse-BuddyPolicy ヘッダーの例を示します。

Eclipse-BuddyPolicy: dependent

Eclipse-RegisterBuddy ヘッダー

Eclipse-RegisterBuddy ヘッダーは、このバンドルが登録済みのバディになっている、バンドルのリストを指定する場合に使用されます。Eclipse-RegisterBuddy ヘッダーでは、以下の構文を使用する必要があります。

Eclipse-RegisterBuddy ::= ( target-bundle ) ( ',' target-bundle ) *
target-bundle ::= バンドル・シンボル名

以下に、Eclipse-RegisterBuddy ヘッダーの例を示します。

Eclipse-RegisterBuddy: org.eclipse.foo.bundle1, org.eclipse.foo.bundle2

Eclipse-ExtensibleAPI ヘッダー

Eclipse-ExtensibleAPI を使用して、フラグメント・バンドルが追加の API をホストに追加することをホスト・バンドルが許可するかどうかを指定します。追加のパッケージをホストの API に追加することをホスト・バンドルからフラグメントに対して許可する場合は、このヘッダーを使用する必要があります。このヘッダーが指定されていない場合は、デフォルト値である「false」が使用されます。Eclipse-ExtensibleAPI ヘッダーでは、以下の構文を使用する必要があります。

Eclipse-ExtensibleAPI ::= ( 'true' | 'false' )

以下に、Eclipse-ExtensibleAPI ヘッダーの例を示します。

Eclipse-ExtensibleAPI: true

Eclipse-GenericCapabilty ヘッダー

Eclipse-GenericCapability ヘッダーは、バンドルの汎用機能を指定するために使用されます。汎用機能は、(Eclipse-GenericRequire ヘッダーを使用して) システム内の他のバンドルによって必要とされる可能性のあるバンドルの機能の説明に使用される場合があります。汎用機能には名前および機能タイプがあります。機能タイプは、その機能を提供するバンドルによって定義されます。機能には、Eclipse-GenericRequire ヘッダーの解決時のマッチングに使用される、型付きマッチング属性セットもあります。マッチング属性は、[string | version | uri | long | double | set] のタイプのいずれかです。set タイプは、コンマで区切られたストリングのリストとしてストリングのセットを定義するために使用されます。 Eclipse-GenericCapability ヘッダーでは、以下の構文を使用する必要があります。

  Eclipse-GenericCapability ::= capability ( ',' capability ) *
  capability                ::= typed-name ( ';' typed-name ) *
                                ( ';' typed-param ) *
  typed-name                ::= name ( ':' capability-type )
  typed-param               ::= typed-key '=' quouted-string
  typed-key                 ::= name ( ':'
                                [string | version | uri | long | double | set] )

以下は、OSGi サービス org.acme.stuff.SomeService インプリメンテーションとのバンドルを指定するために使用可能な Eclipse-GenericCapabilty ヘッダーの例です。

  Eclipse-GenericCapability:
   org.acme.stuff.SomeService:osgi.service;
   version:version="1.0.1"

Eclipse-GenericRequire ヘッダー

Eclipse-GenericRequire ヘッダーは、別のバンドルによって (Eclipse-GenericCapability ヘッダーを使用して) 提案される汎用機能への要求を指定するために使用されます。汎用要求には名前および機能タイプがあります。機能タイプは、その機能を提供するバンドルによって定義されます。汎用要求は、汎用機能とのマッチングを解決するための選択フィルターとして使用される LDAP フィルター・ストリングを指定することができます。 Eclipse-GenericRequire ヘッダーでは、以下の構文を使用する必要があります。

  Eclipse-GenericRequire   ::= generic-require ( ',' generic-require ) *
  generic-require          ::= typed-name ( ';' typed-name ) *
                               ( ';' selection-filter '=' quoated-ldapFilter )
                               ( ';' optional '=' [true|false] )
                               ( ';' multiple '=' [true|false] )
  typed-name                ::= name ( ':' capability-type )

以下は、OSGi サービス org.acme.stuff.SomeService インプリメンテーションに依存するバンドルを指定するために使用可能な Eclipse-GenericRequire ヘッダーの例です。

  Eclipse-GenericRequire:
   org.acme.stuff.SomeService:osgi.service;
   selection-filter="(version>=1.0.1)"

汎用別名

osgi.genericAliases オプションは、既存の OSGi マニフェスト・ヘッダーを Eclipse-GenericCapability および Eclipse-GenericRequire マニフェスト・ヘッダーにマッピングするために使用することができます。例えば、以下のマニフェスト・ヘッダーについて考えてみます。

  Export-Service: org.acme.stuff.SomeService
  Import-Service: org.acme.stuff.SomeService

これらのヘッダーは、以下のプロパティーを使用して Eclipse-GenericCapability ヘッダーおよび Eclipse-GenericRequire ヘッダーにマッピングすることができます。

  osgi.genericAliases=Export-Service:Import-Service:osgi.service

具体的には、これは以下の汎用ヘッダーに変換されます。

  Eclipse-GenericRequire: org.acme.stuff.SomeService:osgi.service
  Eclipse-GenericCapability: org.acme.stuff.SomeService:osgi.service

Plugin-Class ヘッダー

Plugin-Class ヘッダーは、Eclipse 2.1 プラットフォーム用に開発されたプラグインをサポートする場合にのみ使用されます。このヘッダーは、古い Eclipse 2.1 活動化モデルを用いてプラグインを活動化する場合に使われるクラス名を指定する際に使用します。Eclipse 3.0 以上用に開発された新規のバンドルでは、このヘッダーを使用しないでください。以下に、Plugin-Class ヘッダーの例を示します。

Plugin-Class: org.eclipse.foo.FooPlugin