Liberty 功能部件清单文件
Liberty 功能部件包含一个功能部件清单文件以及一个或多个 OSGi 捆绑软件的集合,这些捆绑软件提供与 Liberty 运行时环境中的特定功能相对应的类和服务。您可以找到有关功能部件清单格式以及清单文件中每个头的含义的简介。
Liberty 中的功能部件清单文件使用 OSGi 企业 R5 规范中的子系统服务元数据格式。功能部件由存储在 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 | 由此功能部件、其他产品扩展中的功能部件和 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。此属性指示此功能部件是否由功能的一个或多个功能部件或项目取代。它接受下列其中一个值:
- 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 文件,并且此 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 在其清单文件的 Subsystem-Content 头中包含 sipServlet-1.1。sipServlet-1.1 包含 servlet-3.0 并容许 servlet 3.1。如果 featureC-1.1 是在 servlet-3.1 存在之前编写的,且它使用的功能部件 (sipServlet-1.1) 添加并容许 servlet-3.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.executable - 根据当前 umask 设置,值设置为“true”时将执行许可权添加至关联文件。任何其他值将导致不执行任何操作。下表显示当前 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 - 指示由标准主体(例如 javax.servlet 或 org.osgi.framework)提供的 API。
- ibm-api - 指示由 IBM® 提供的加值 API。
- api - 指示用户定义的 API。这是缺省值。
- third-party - 指示一个可视但并非由 IBM 控制的 API。通常,这些是开放式源代码包。
- internal - 指示非 API 包,必须向应用程序提供这些非 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 and later]](../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 应用程序希望使用该包,那么它们必须显式导入该包。两个 SPI 包(com.ibm.example.spi.utils 和
com.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