Liberty 特性資訊清單檔
Liberty 特性包含一個特性資訊清單檔與一個含有一或多個 OSGi 軟體組的集合,以提供對應於 Liberty 執行時期環境中之特定功能的類別和服務。 您可以找到特性資訊清單格式以及資訊清單檔內各標頭之意義的簡介。
Liberty 中的特性資訊清單檔使用 OSGi Enterprise R5 規格中的「子系統服務」meta 資料格式。 特性由儲存在 lib/features 目錄中的特性資訊清單檔或 .mf 檔來定義,必須使用自訂類型的子系統:osgi.subsystem.feature。如需 OSGi 資訊清單語法的相關資訊,請參閱 OSGi 核心程式規格的 1.3.2 節。
標頭 | 說明 | 是否需要 |
---|---|---|
Subsystem-ManifestVersion | 特性資訊清單檔的版本格式。必須設為 1。 | 否 |
Subsystem-SymbolicName | 特性的符號名稱,以及任何屬性或指引。 | 是 |
Subsystem-Version | 特性的版本。請參閱 OSGi 核心規格 3.2.5 節,以取得其定義方式的詳細資料。 | 否 |
Subsystem-Type | 特性的子系統類型。 所有特性目前都屬於相同的子系統類型:osgi.subsystem.feature。 | 是 |
Subsystem-Content | 特性的子系統內容。這是一份逗點區隔的清單,其中包含執行這個特性時所需的軟體組和子系統。如果您想要容許在 server.xml 檔中配置自動特性,您必須有包含必要特性的功能標頭,並且將它們定義在子系統內容中。
|
是 |
Subsystem-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 - 不取代特性。
如需相關資訊,請參閱已汰換的 Liberty 特性。
- 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"
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]"
如需相關資訊,請參閱已區隔特性。- singleton。這個指引採用下列值之一:
- True。此特性是單態。
- False。此特性不是單態。
singleton 為選用指引。預設值為 False。
此指引用來宣告特定的特性是單態。單態是指執行時期中一次只能載入給定特性的一個版本。依預設,特性不是單態。如果特性是單態,且伺服器配置需要給定特性的多個版本,則執行時期會嘗試尋找所有必要特性都可容忍的共用版本。如需版本容錯的相關資訊,請參閱 Subsystem-Content 之下的 ibm.tolerates 指引。
當特性是單態時,符號名稱值的格式是 "<singleton feature name >-<singleton version>",其中,name 和 version 之間以連字號區隔。單態特性名稱可以包含連字號,但是會將最後一個連字號之後的字元解譯成單態版本。如果最後一個連字號之後的字元不是有效的版本,則會使用單態版本 0.0.0,並以完整符號名稱作為單態名稱。在您處理 Subsystem-Content 之下的 "ibm.tolerates" 指引時,會使用單態版本;例如:Subsystem-SymbolicName: com.ibm.example.feature-1.0; visibility:=public; singleton:=true
Subsystem-Content
Subsystem-Content ::= content ( ',' content )*
content ::= unique-name ( ';' parameter )*
unique-name ::= unique-name (see OSGi core spec section 1.3.2)
- version - 您尋找軟體組時,所要比對的版本範圍。 只會選取這個範圍的軟體組。 [1,1.0.100) 是版本範圍的典型範例。
- type - 要供應的內容類型。
您可以指定任意值來表示內容類型;某些類型會導致在使用該特性之伺服器的 OSGi 架構中安裝並啟動軟體組,所有類型都會導致將內容併入包含該特性的安裝套件中。
以下是預先定義的值:
- osgi.bundle - 這是預設值,指出必須供應到伺服器的 OSGi 架構以及安裝套件兩者中的 OSGi 軟體組。
- osgi.subsystem.feature - 這個值指出必須將特性供應到伺服器的 OSGi 架構以及安裝套件兩者中。這些特性需要使用 Subsystem-SymbolicName 標頭中指定的名稱。
- jar - 這個值指出必須將 JAR 檔併入安裝套件中,且是利用版本範圍及/或位置值的組合來選取。
- file - 這個值指出在 location 屬性中識別的檔案,必須包含在安裝套件中。
- location - 軟體組的位置。對於軟體組或 JAR 類型,這個值可以是代表搜尋路徑的目錄清單(以逗點區隔)。對於任何類型,此值可以是直接指向資源的單一項目,並且可指定成檔案 URL。路徑可能是絕對或相對。相對路徑會解析成含有該特性之產品延伸的相對位置。若為使用者特性,會使用預設產品延伸位置,亦即 ${wlp.user.dir}/extension。非預設延伸產品的位置是由 ${wlp.install.dir}/etc/extensions 目錄中,其內容檔中的 com.ibm.websphere.productInstall 內容來宣告。例如:
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"
- start-phase - 在系統啟動期間,必須啟動軟體組時的啟動階段。
start-phase 指引可採用下列其中一個值:
- SERVICE - 這個值指出最早的階段。依預設,它會對映至啟動層次 9。
- CONTAINER - 如果未提供 start-phase,這就是預設值。 它指出應用程式儲存器啟動時的儲存器階段。依預設,它會對映至啟動層次 12。
- APPLICATION - 這個值指出應用程式啟動時的最後階段。
- ibm.tolerates - 指定單態特性 type=osgi.subsystem.feature 的一或多個替代單態版本,以便在發生版本衝突時供應給系統。
unique-name 用來針對該單態特性指定您偏好版本的符號名稱。如果已知含括特性會與給定單態特性的其他單態版本搭配運作,則可以使用 ibm.tolerates 指引來指定這些單態版本。一旦其他特性針對給定單態特性所定義的必要版本值發生衝突,這樣做能為正在定義的特性提供更大的相容性。
只有在發生版本衝突時,才會使用 ibm.tolerates 指引中所列出的單態版本。ibm.tolerates 指引所列出版本的排序並不重要 - 可以選取 ibm.tolerates 指引所列出的任何版本,來滿足相依關係需求。
ibm.tolerates 指引中必須明確列出給定單態特性的一或多個容錯版本。請利用逗號來區隔容錯版本清單。不支援指定版本範圍。
例如:Subsystem-Content: com.ibm.websphere.appserver.example.featureA-1.1; ibm.tolerates:="1.2"; type="osgi.subsystem.feature", com.ibm.websphere.appserver.example.featureB-1.1; ibm.tolerates:="1.2, 1.4, 1.6"; type="osgi.subsystem.feature"
註:容錯版本不是過渡的。如此可避免在未經測試下,就自動選擇您特性的相依特性來支援特性的新層次。
例如:使用者特性 featureC-1.1 將 sipServlet-1.1 包含在其資訊清單檔的 Subsystem-Content 標頭中。sipServlet-1.1 包含 servlet-3.0,並容忍 servlet 3.1。如果 featureC-1.1 早在 servlet-3.1 存在之前即已撰寫,則會新增 servlet-3.1,其所用的特性 (sipServlet-1.1) 會容忍它,且 featureC-1.1 應當指出其是否也容忍 servlet-3.1。
如果您將 server.xml 檔配置成具有下列兩項特性:
您會看到類似如下顯示的錯誤訊息:<feature>usr:featureC-1.1</feature> // includes: sipServlet-1.1 <feature>websocket-1.0</feature> // this feature requires servlet-3.1
CWWKF0033E: 單態特性 servlet-3.0 和 servlet-3.1 無法同時載入。所配置的特性 usr:featureC-1.1 和 websocket-1.0 包含一或多項導致衝突的特性。不支援您的配置;請更新 server.xml,以移除不相容的特性。
會報告此錯誤的原因在於,沒有選擇 featureC-1.1 來容忍 servlet-3.1,因此,必須有 servlet-3.0,且 websocket-1.0 不支援 servlet-3.0,因此必須有 servlet-3.1。
針對 featureC-1.1 的解決方案是亦直接相依於 servlet-3.0,並容忍 servlet-3.1。

- ibm.zos.extended.attributes - 將相關聯檔案的延伸屬性設為指定值。值可以是
a'、'l'、'p' 和 's' 的組合。值選項的摘要:
- a = 具備 APF 權限
- p = 由程式控制
- s = 共用位址空間
- l = 共用程式庫
- ibm.file.encoding - 將相關聯的檔案從 ASCII 編碼轉換成指定的編碼類型。ibm.file.encoding 指引的值可以是 "ebcdic",表示將以 ASCII 編碼的檔案轉換成 EBCDIC 編碼。






- ibm.executable - 當值設為 "true" 時,會根據現行 umask 設定,新增相關聯檔案的執行權。其他任何的值都會造成不採取動作。下表顯示現行 umask,以及哪些類別會取得執行權。
表 2. umask 值與具備 ibm.executable 設定之執行權的類別範例 Umask 授與類別的執行權 022 擁有者、群組、其他 023 擁有者、群組 055 擁有者
Subsystem-Localization
這個標頭指定特性的本土化檔案的位置。
Subsystem-Localization: OSGI-INF/l10n/loc
Subsystem-Name
請使用這個標頭來提供特性的可讀簡稱。您可以指定文字字串或內容名稱。如果您指定內容名稱,該值可以本地化。
Subsystem-Name: %name
其中 name 的值定義在位於 Subsystem-Localization
標頭所指定位置的內容檔中(上述範例中的 loc.properties),格式如下:name=feature_name
Subsystem-Description
請使用這個標頭來提供特性的說明。您可以指定文字字串或內容名稱。如果您指定內容名稱,該值可以本地化。
Subsystem-Description: %desc
其中 desc 的值定義在位於 Subsystem-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.servlet 或 org.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 標頭所提供的服務,應用程式必須包含指向這個服務的藍圖參照,才會向應用程式供應這個服務。
<?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 介面,或是「宣告式服務」或藍圖之類的任何其他機制,登錄在 OSGi 服務登錄中。 如需相關資訊,請參閱開發含有簡式啟動的 OSGi 軟體組和利用 OSGi 宣告式服務來撰寫進階特性。
IBM-SPI-Package
當您建立您自己的 Liberty 特性時,您會將它安裝在使用者產品延伸之中。 安裝在使用者產品延伸中的任何其他特性,都能夠存取您的特性中的所有套件。 不過,如果您想要另一項產品延伸中所安裝的某一特性能夠存取您的特性中的某個套件,您必須將套件名稱列在 IBM-SPI-Package 標頭中。
IBM-SPI-Package 標頭所列出的任何套件,必須由 Liberty 特性中的軟體組匯出,其作法是將這些套件列在軟體組資訊清單檔的 Export-Package 標頭中。
IBM-ShortName
這個標頭是一個特性簡稱,在 server.xml 檔中可用來指定特性。 如果資訊清單檔中沒有 IBM-ShortName 標頭,依預設,會使用 Subsystem-SymbolicName。 IBM-ShortName 標頭只適用於公用特性。
IBM-AppliesTo
product_id; productVersion=product_version; productInstallType=product_install_type; productEdition=product_editions
如果您提供多個項目,每一個項目的 product_id 值必須不同。
productVersion 的值可以是確切版本(例如 8.5.5.7),或是最低版本(以結尾為加號 + 的版本來表示),例如 8.5.5.7+。
productEdition 的值可以是單一版本,或是以逗點區隔的版本清單(以引號括住)。
IBM-AppliesTo: com.ibm.websphere.appserver; productVersion=8.5.5.6; productInstallType=Archive; productEdition="BASE,DEVELOPERS,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
![[18.0.0.1 以及更新版本]](../ng_v18001plus.gif)
IBM-Maven-Dependency
IBM-Maven-Dependency: javax.servlet:javax.servlet-api:3.1.0
IBM-App-ForceRestart
- install - 安裝特性時重新啟動應用程式。
- uninstall - 解除安裝特性時重新啟動應用程式。
- install,uninstall - 安裝或解除安裝特性時重新啟動應用程式。
特性資訊清單檔範例
<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.utils 和 com.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