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 文件中配置自动功能部件,那么必须具有包含所需功能部件的功能头,并且也必须在子系统内容中定义所需功能部件。 | 是 |
Subsytem-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 - 不取代此功能部件。
有关更多信息,请参阅取代的功能部件。
- 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]"
有关更多信息,请参阅分隔开的功能部件。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 类型,此值可以是目录的逗号分隔列表(用于标识 dev 目录中的规范和 API 捆绑软件),也可以是直接指向 JAR 文件的单个条目。如果 type 为 file,那么仅允许此值为单个条目,并且它必须直接指向该文件。
- start-phase - 在系统启动期间捆绑软件应该启动的开始阶段。start-phase 伪指令可采用下列其中一个值:
- SERVICE - 此值指示最早阶段。缺省情况下,它映射到开始阶段 9。
- CONTAINER - 如果未提供任何 start-phase,那么这是缺省值。启动应用程序容器时,它指示容器阶段。缺省情况下,它映射到开始阶段 12。
- APPLICATION - 启动应用程序时,此值指示最晚的阶段。
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"






![[8.5.5.4 或更高版本]](../ng_v8554.gif)
- ibm.executable - 根据当前 umask 设置,值设置为“true”时将执行许可权添加至关联文件。任何其他值将导致不执行任何操作。下表显示当前 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 - 指示由标准主体(例如 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 头提供的服务,那么应用程序必须包括对该服务的 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 头中列出该包的名称。
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 的值必须是唯一的。
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 - 安装或卸载功能部件后重新启动应用程序。
示例功能部件清单文件
<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