Liberty 特性資訊清單檔

Liberty 特性包含一個特性資訊清單檔與一個 含有一或多個 OSGi 軟體組的集合,以提供對應於 Liberty 設定檔執行時期環境中之特定功能的類別和服務。 您可以找到特性資訊清單格式以及資訊清單檔內各標頭之意義的簡介。

Liberty 設定檔中的特性資訊清單檔使用 OSGi Enterprise R5 規格中的 Subsystem Service meta 資料格式。 特性由儲存在 lib/features 目錄中的特性資訊清單檔(.mf 檔)來定義,必須使用自訂類型的子系統 (Subsystem):osgi.subsystem.feature。如需 OSGi 資訊清單語法的相關資訊,請參閱 OSGi 核心程式規格的 1.3.2 節。

註: 在特性資訊清單檔中,屬性會取自 name=value,但指引則取自 name:=value

定義的標頭如下:
表 1. 特性資訊清單檔的標頭.

這份表格顯示 Liberty 設定檔中之特性資訊清單檔的標頭。 第一個直欄顯示標頭清單,第二個直欄顯示每個標頭的說明,第三個直欄則指出是否需要這個標頭。

標頭 說明 必要?
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 這個特性向應用程式顯現的 API 套件、其他產品延伸中的特性,以及 Liberty 核心。
IBM-API-Service 這個特性向 OSGi 應用程式顯現的 OSGi 服務。
IBM-SPI-Package 這個特性向其他產品延伸中的特性顯現的 SPI 套件,以及 Liberty 核心。
IBM-ShortName 特性的簡稱。
IBM-AppliesTo 這項特性適用的 Liberty 版本。
Subsystem-License 這項特性的授權類型。
IBM-License-Agreement 授權合約檔的位置字首。
IBM-License-Information 授權資訊檔的位置字首。
IBM-App-ForceRestart 指定在將特性安裝到執行中的伺服器或是從執行中的伺服器解除安裝時,要重新啟動的應用程式。

Subsystem-SymbolicName

這個標頭的語法符合軟體組的 Bundle-SymbolicName 語法。 它有一個遵循套件名稱樣式語法的符號名稱,且可以選擇性地採用一組屬性和指引。

支援的屬性如下:
  • superseded。這個屬性指出,這個特性是否由一或多個特性或功能項目來取代。它採用下列值之一:
    • 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 清單中的特性名稱,則這項特性已與接替的特性分開。在下列範例中,不包含 servlet-3.0ldapRegistry-3.0 特性的 appSecurity-2.0 特性,已取代包含 servlet-3.0ldapRegistry-3.0 特性的 appSecurity-1.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 規格相同的標頭語法,其語法如下:
Subsystem-Content ::= content ( ',' content )*
        content ::= unique-name ( ';' parameter )*
        unique-name ::= unique-name        (see OSGi core spec section 1.3.2)
unique-name 使用 Bundle-SymbolicNameSubsystem-SymbolicName 標頭的形式。 支援的屬性如下:
  • version - 尋找軟體組時,所要比對的版本範圍。 只會選取這個範圍的軟體組。 [1,1.0.100) 是版本範圍的典型範例。
  • type - 要供應的內容類型。 您可以指定任意值來表示內容類型;某些類型會導致在使用該特性之伺服器的 OSGi 架構中安裝並啟動軟體組,所有類型都會導致將內容併入包含該特性的安裝套件中。 以下是預先定義的值:
    • osgi.bundle - 這是預設值,指出應該供應到伺服器的 OSGi 架構以及安裝套件兩者中的 OSGi 軟體組。
    • osgi.subsystem.feature - 這個值指出應該將特性供應到伺服器的 OSGi 架構以及安裝套件兩者中。這些特性需要使用 Subsystem-SymbolicName 標頭中指定的名稱。
    • 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 標頭所指定位置的內容檔中(上述範例中的 loc.properties),格式如下:
name=feature_name

Subsystem-Description

請使用這個標頭來提供特性的說明。您可以指定文字字串或內容名稱。如果您指定內容名稱,該值可以本地化。

比方說,
Subsystem-Description: %desc
其中 desc 的值定義在位於 Subsytem-Localization 標頭所指定位置的內容檔中(上述範例中的 loc.properties),格式如下:
desc=feature_description

IBM-Provision-Capability

自動供應的特性是在資訊清單中有 IBM-Provision-Capability 標頭的特性。 這個標頭說明如果要自動供應這個特性,就必須供應的其他特性。 當列出其他特性時,請使用特性的 Subsystem-SymbolicName 標頭。 當在 server.xml 檔中配置了任何特性時,runtime 會檢查是否有任何自動供應的特性滿足其功能,如果有,就會自動供應它們。

IBM-Provision-Capability 標頭的格式使用標準 OSGi LDAP 過濾器。

IBM-API-Package

這個標頭用來指出應用程式可以看見的 API 套件。 它符合 Export-Package 標頭語法。 這表示它是一份逗點區隔的 API 套件清單,但每個 API 套件都可以有一些屬性。

支援的屬性如下
  • type - API 套件的類型。 type 屬性會採用下列值之一:
    • spec - 指示標準主體所提供的 API,例如 javax.servletorg.osgi.framework
    • 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 介面,或是「宣告式服務」或 Blueprint 之類的任何其他機制,登錄在 OSGi 服務登錄中。 如需相關資訊,請參閱開發含有簡式啟動的 OSGi 軟體組利用 OSGi 宣告式服務來撰寫進階特性

IBM-SPI-Package

當您建立您自己的 Liberty 特性時,您會將它安裝在使用者產品延伸之中。 安裝在使用者產品延伸中的任何其他特性,都能夠存取您的特性中的所有套件。 不過,如果您想要另一項產品延伸中所安裝的某一特性能夠存取您的特性中的某個套件,您必須將套件名稱列在 IBM-SPI-Package 標頭中。

Liberty 特性中的軟體組必須匯出 IBM-SPI-Package 標頭所列出的任何套件,方法為將這些套件列在軟體組資訊清單檔的 Export-Package 標頭中。

IBM-ShortName

這個標頭是一個特性簡稱,在 server.xml 檔中可用來指定特性。 如果資訊清單檔中沒有 IBM-ShortName 標頭,依預設,會使用 Subsystem-SymbolicNameIBM-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-Content 標頭中的相依關係表示有兩個或更多要安裝的特性具有相同的 Subsystem-License 標頭值,在安裝期間,使用者只需要接受授權一次。

例如:
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 屬性允許直接在伺服器配置檔 (server.xml) 中指定這個特性;它也會包含在開發人員工具之伺服器配置視圖顯示的下拉特性清單中,並且可以併入到其他產品延伸的特性中。如果將這個特性安裝到某項執行時期安裝的 usr 產品延伸中,您可以將下列程式碼併到 server.xml 檔內,以將它配置到伺服器中:
<featureManager>
		<feature>usr:example-1.0</feature>
</featureManager>
將這個特性配置在伺服器中,會導致在伺服器執行時期環境的 OSGi 架構中安裝及啟動指定的軟體組 com.ibm.example.bundle1。 這部伺服器中的所有應用程式都能夠看到單一 API 套件 com.ibm.example.publicapi,但配置成無法看到 api 套件類型的 Java EE 應用程式除外。 如果 OSGi 應用程式想要使用這個套件,就必須將它明確匯入。 伺服器中的所有特性碼都將能夠看到 com.ibm.example.spi.utilscom.acme.spi.spiservices 這兩個 SPI 套件,以及 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 月 22 日
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=rwlp_feat_definition
檔名:rwlp_feat_definition.html