OSGi 軟體組 Manifest 標頭

3.1 版 - 前次修訂日期:2005 年 6 月 20 日

軟體組可在名為 META-INF/MANIFEST.MF 的 Manifest 檔中,提供自身的相關敘述性資訊。「OSGi R4 架構」規格定義 一組 Manifest 標頭,例如 Export-Package 和 Bundle-Classpath,軟體組開發人員可以使用這些標頭來提供軟體組的相關敘述性資訊。 「Eclipse OSGi 架構」實作完整的「OSGi R4 架構」規格,以及所有的「核心架構」服務。「OSGi R4 核心架構」服務包含以下各項:

OSGi R4 規格中定義了若干選用服務。 選用服務不包含在「Eclipse OSGi 架構」實作中。如需 OSGi R4 Manifest 標頭和服務的相關資訊,請參閱 OSGi 規格

Eclipse 軟體組 Manifest 標頭

「Eclipse OSGi 架構」支援其他軟體組 Manifest 標頭和指引。軟體組開發人員可用這些其他標頭和指引,來 利用不是指定為標準「OSGi R4 架構」之一部分的「Eclipse OSGi 架構」其他特性。

其他的 Export-Package 指引

「Eclipse OSGi 架構」支援 Export-Package 標頭上的其他指引。這些指引用來指定已匯出套件的存取限制規則。 請參閱 osgi.resolverMode 來配置「Eclipse OSGi 架構」,以在執行時期上實施存取限制規則。

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 ::= a bundle symbolic name

下列是 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 ::= a comma ',' separated list of packages

'exceptions' 屬性用來指定套件清單,該套件在從軟體組載入類別或資源時,不可導致軟體組啟動。 如果軟體組 Manifest 並未定義 Eclipse-LazyStart 標頭,就會使用預設值 'false'。 以下是 Eclipse-LazyStart 標頭的範例:

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

範例指定除了套件 'org.eclipse.foo1' 和 'org.eclipse.foo2' 中的類別和資源之外,必須為從這個軟體組載入的所有類別和資源,啟動此軟體組。

在 Eclipse 3.2 中,Eclipse-AutoStart 標頭已淘汰。 應該改用 Eclipse-LazyStart 標頭。

Eclipse-PlatformFilter 標頭

Eclipse-PlatformFilter 用來指定軟體組的平台過濾器。平台過濾器在執行中的平台上必須評估為 true,以允許解析某一軟體組。Eclipse-PlatformFilter 標頭必須使用下列語法:

Eclipse-PlatformFilter ::= a valid LDAP filter string

架構支援過濾下列系統內容:

下列是 Eclipse-PlatformFilter 標頭的範例:

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

這個範例指定只有在平台內容為 osgi.ws=win32、osgi.os=win32 和 osgi.arch=x86 時,才可以解析此軟體組。換句話說, 即為在使用 win32 作業系統和 win32 Windows 系統的 x86 架構上執行的平台。

Eclipse-BuddyPolicy 標頭

Eclipse-BuddyPolicy 標頭用來指定軟體組的 buddy 類別載入原則。 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 標頭用來指定此軟體組為登錄 buddy 的軟體組清單。 Eclipse-RegisterBuddy 標頭必須使用下列語法:

Eclipse-RegisterBuddy ::= ( target-bundle ) ( ',' target-bundle ) *
target-bundle ::= a bundle symbolic name

下列是 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] )

Eclipse-GenericCapabilty 標頭可用來指定含 OSGi 服務 org.acme.stuff.SomeService 實作的軟體組,以下是它的範例:

  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 )

Eclipse-GenericRequire 標頭可用來指定相依於 OSGi 服務 org.acme.stuff.SomeService 實作的軟體組,以下是它的範例:

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

一般的別名

osgi.genericAliases 選項可用來將現有的 OSGi Manifest 標頭對映至 Eclipse-GenericCapability 和 Eclipse-GenericRequire Manifest 標頭。比方說,我們設想下列 Manifest 標頭

  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