Liberty 功能部件清单文件

Liberty 功能部件包含一个功能部件清单文件以及一个或多个 OSGi 捆绑软件的集合,这些捆绑软件提供与 Liberty 运行时环境中的特定功能相对应的类和服务。您可以找到有关功能部件清单格式以及清单文件中每个头的含义的简介。

Liberty 中的功能部件清单文件使用 OSGi 企业 R5 规范中的子系统服务元数据格式。功能部件由存储在 lib/features 目录中的功能部件清单文件(.mf 文件)定义,并且必须使用定制类型的子系统: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 文件中配置自动功能部件,那么必须具有包含所需功能部件的功能头,并且也必须在子系统内容中定义所需功能部件。
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 - 不取代此功能部件。
    此属性是可选的;缺省值为 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"
如果 superseded-by 列表中的功能部件名称用方括号 [] 括起来,那么此功能部件已经与取代功能部件分隔开。在以下示例中,功能部件 appSecurity-1.0(此功能部件包含功能部件 servlet-3.0ldapRegistry-3.0)被功能部件 appSecurity-2.0(此功能部件未包含功能部件 servlet-3.0ldapRegistry-3.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
  • 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)
unique-name 使用 Bundle-SymbolicNameSubsystem-SymbolicName 头格式。支持下列属性:
  • 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 文件的单个条目。如果 typefile,那么仅允许此值为单个条目,并且它必须直接指向该文件。
    例如:
    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 - 启动应用程序时,此值指示最晚的阶段。
    捆绑软件也可以定义为刚好在这些阶段之前或之后启动,方法是添加晚于关键阶段的 _LATE 或者添加早于关键阶段的 _EARLY。因此,如果要在容器阶段之后立即运行,请使用 CONTAINER_LATE;如果要在 APPLICATION 阶段之前运行,那么使用 APPLICATION_EARLY
  • 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.1sipServlet-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

适用于 AIX 平台适用于 HP UNIX 平台适用于 LINUX 平台适用于 Solaris 平台适用于 IBM i 平台支持以下伪指令:
  • 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.servletorg.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-SymbolicNameIBM-ShortName 头仅对公共功能部件有效。

IBM-AppliesTo

此头指定此功能部件适用于的 Liberty 版本。提供以逗号分隔的项目列表,每个项目的格式如下所示:
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

IBM-App-ForceRestart

对运行中服务器安装或移除功能部件后,此头会导致应用程序重新启动。此头可以采用下列其中一个值:
  • install - 安装功能部件后重新启动应用程序。
  • uninstall - 卸载功能部件后重新启动应用程序。
  • install,uninstall - 安装或卸载功能部件后重新启动应用程序。

示例功能部件清单文件

以下示例显示了 example-1.0 功能部件的定义。公共可视性属性允许直接在服务器配置 (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 应用程序希望使用该包,那么它们必须显式导入该包。两个 SPI 包(com.ibm.example.spi.utilscom.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

用于指示主题类型的图标 参考主题



时间戳记图标 最近一次更新时间: Tuesday, 6 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwlp_feat_definition
文件名:rwlp_feat_definition.html