Liberty feature manifest files

A Liberty feature consists of a feature manifest file and a collection of one or more OSGi bundles that provide classes and services corresponding to a particular capability in the Liberty profile runtime environment. We can find the introduction of the format of a feature manifest and the meaning of each header in the manifest file.

The feature manifest file in the Liberty profile uses the Subsystem Service metadata format in the OSGi Enterprise R5 specification. A feature is defined by a feature manifest file (.mf file) that is stored in the lib/features directory, and must use a custom type of Subsystem: osgi.subsystem.feature. For more information on OSGi manifest syntax, see section 1.3.2 of the OSGi core specification.

In the feature manifest file, the attributes take the form name=value, but directives take the form name:=value.

The following headers are defined:

Header	Description	Required?
Subsystem-ManifestVersion	The version format for the feature manifest file. Must be set to 1.	No
Subsystem-SymbolicName	The symbolic name of the feature and any attributes or directives.	Yes
Subsystem-Version	The version of the feature. See the OSGi core specification section 3.2.5 for the details of how this is defined.	No
Subsystem-Type	The subsystem type for the feature. All features are currently of the same subsystem type: osgi.subsystem.feature.	Yes
Subsystem-Content	The subsystem content of the feature. This is a comma separated list of bundles and subsystems required to run this feature. To allow the auto feature to be configured in server.xml, have the capability header containing the required features, and also have them defined in the subsystem content.	Yes
Subsytem-Localization	The location of the localization files for the feature.	No
Subsystem-Name	A short, human readable name for the feature. This value can be localized.	No
Subsystem-Description	A description of the feature. This value can be localized.	No
IBM-Feature-Version	The version of this subsystem type. Must be set to 2.	Yes
IBM-Provision-Capability	The capability header that describes whether a feature can be provisioned automatically.	No
IBM-API-Package	The API packages exposed to applications by this feature, features in other product extensions, and the Liberty kernel.	No
IBM-API-Service	The OSGi services exposed to OSGi applications by this feature.	No
IBM-SPI-Package	The SPI packages exposed by this feature to features in other product extensions, and the Liberty kernel.	No
IBM-ShortName	The short name of the feature.	No
IBM-AppliesTo	The Liberty version that this feature applies to.	No
Subsystem-License	The license type for this feature.	No
IBM-License-Agreement	The prefix of the location of the license agreement files.	No
IBM-License-Information	The prefix of the location of the license information files.	No
IBM-App-ForceRestart	That applications are to be restarted when the feature is installed to, or uninstalled from, a running server.	No

Subsystem-SymbolicName

The syntax for this header matches the Bundle-SymbolicName syntax for a bundle. It has a symbolic name that follows the package names style syntax, and can optionally take a set of attributes and directives.

The following attributes are supported:

• superseded. This attribute indicates whether this feature is superseded by one or more features or items of functionality. It takes one of the following values:

  • true - The feature is superseded.

  • false -

    The feature is not superseded.

  This attribute is optional. Default is false.

  See Superseded features.

• superseded-by. This attribute specifies a comma-separated list of the features that supersede this feature, if any, and is optional.

The following directive is supported:

• visibility. This directive takes one of the following values:

  • public - Feature considered to be API. The feature is supported by the developer tools, for use in server.xml, and output in messages.

  • protected - Feature considered to be SPI.

    The feature is not supported by the developer tools, for use in server.xml, or output in messages. The feature is provided so extenders can make use of it to build higher level features.

  • private - (default) The feature is product internals.

    The feature is not supported for use in server.xml or to be referenced by extender features. The feature can be changed at any time, including between fix packs.

For example:

Subsystem-SymbolicName: com.ibm.example.feature-1.0; 
    visibility:=public; superseded=true; superseded-by="com.ibm.example.feature-2.0"

If a feature name in the superseded-by list is surrounded by brackets, [], this feature has been separated from the superseding feature. In the following example, feature appSecurity-1.0, which contains features servlet-3.0 and ldapRegistry-3.0, is superseded by feature appSecurity-2.0, which does not contain servlet-3.0 and ldapRegistry-3.0 features:

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]"

See Separated features.

Best practise: If the developer tools must show the feature, it must be public. If the feature is available only to trusted parties, it must be protected. If the feature is internal and subject to change at any time, it must be private.

Subsystem-Content

Content of the feature, both for run time and install. It follows the same header syntax as the Subsystem specification with the following syntax:

Subsystem-Content ::= content ( ',' content )*
        content ::= unique-name ( ';' parameter )*
        unique-name ::= unique-name        

See OSGi core spec section 1.3.2.

The unique-name uses the form of the Bundle-SymbolicName or Subsystem-SymbolicName headers. The following attributes are supported:

version

The range of versions to be matched when finding a bundle. Only bundles in this range are selected. A typical example of the version range is [1,1.0.100).

type

The type of content to be provisioned. We can specify any value to indicate the content type; some types will result in bundles being installed and started in the OSGi framework of a server that uses the feature, all types will cause the content to be included in an installation package that includes the feature. The following values are predefined: osgi.bundle Default. Indicates an OSGi bundle that should be provisioned both into the OSGi framework of the server and an installation package. osgi.subsystem.feature The feature should be provisioned both into the OSGi framework of the server and an installation package. These features need to use the name specified in Subsystem-SymbolicName header. jar A JAR file should be included in an installation package and is selected using a combination of a version range, a location value, or both. file The file identified in the location attribute should be included in an installation package.

The following directives are supported:

• location - The location of the bundle. For a bundle or JAR type, this value can be a comma separated list of directories used to identify spec and API bundles in the dev directory, or a single entry pointing directly to the JAR file. When the type is file, only a single entry is allowed and it must point directly to that file.

• start-phase - The start phase when the bundle should start during system startup. The start-phase directive can take one of the following values:

  • SERVICE - Earliest phase. By default it maps to a start level of 9.

  • CONTAINER - Default if no start-phase is provided. It indicates the container phase when application containers are started. By default it maps to a start level of 12.

  • APPLICATION - Latest phase when applications are started.

  Bundles can also be defined to start just before or just after these phases by adding _LATE to be later, or _EARLY to be earlier than the key phase. So to run immediately after the container phase, use CONTAINER_LATE, and to run before the APPLICATION phase then use APPLICATION_EARLY.

For example:

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"

The following directive is supported in version 8.5.5.4 and later:

• ibm.executable - Adds the execute permission to the associated file, according to the current umask setting, when the value is set to "true". Any other value will result in no action taken. The following table shows the current umask and which class gets the execute permission.

  Umask	Execute permissions granted to class
  022	owner, group, other
  023	owner, group
  055	owner

Subsytem-Localization

Location of the localization files for the feature.

For example:

Subsystem-Localization: OSGI-INF/l10n/loc

Subsystem-Name

Use this header to supply a short, human readable name for the feature. We can specify either a literal string or a property name. If you a specify a property name, the value can be localized.

For example

Subsystem-Name: %name

where the value of name is defined in a properties file at the location specified by the Subsytem-Localization header (loc.properties in the previous example), in the following format:

name=feature_name

Subsystem-Description

Use this header to supply a description for the feature. We can specify either a literal string or a property name. If you a specify a property name, the value can be localized.

For example

Subsystem-Description: %desc

where the value of desc is defined in a properties file at the location specified by the Subsytem-Localization header (loc.properties in the previous example), in the following format:

desc=feature_description

IBM-Provision-Capability

Automatically provisioned features are features that have the IBM-Provision-Capability header in the manifest. This header describes other features that must be provisioned for this feature to be automatically provisioned. When listing the other features, use the Subsystem-SymbolicName header of the feature. When any features are configured in server.xml, the runtime checks to see whether any automatically provisioned features have had their capabilities satisfied, and if any have, they are automatically provisioned.

The format of the IBM-Provision-Capability header uses standard OSGi LDAP filters.

IBM-API-Package

Which API packages are visible to applications. It matches the Export-Package header syntax. This means it is a comma separated list of API packages, but each API package can have some attributes.

The following attribute is supported:

• type - The type of API package. The type attribute takes one of the following values:

  spec	API provided by a standard body, such as javax.servlet or org.osgi.framework.
  ibm-api	Value-add API provided by IBM.
  api	User-defined API. Default.
  third-party	API tht is visible, but not controlled by IBM. Typically, these are open source packages.
  internal	Non-API packages that must be exposed to applications for them to function. This might be used if Java code is bytecode enhanced, or weaved, to add references to internal code at run time.

For example:

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

Which services from the feature are visible to OSGi applications. The feature must also register the service in the OSGi service registry.

It has the following syntax

IBM-API-Service ::= service ( ',' service )*
                    service ::= service-name ( ';' attribute )*
                    service-name ::= unique-name

The service-name is the Java class or interface name of the service. The attributes are interpreted as the service properties for the services.

For example:

IBM-API-Service: com.ibm.example.service.FeatureServiceOne; 
                 myServiceAttribute=myAttributeValue, com.ibm.example.service.FeatureServiceTwo

If an OSGi application want to use the services provided by the IBM-API-Service header, the application must include a blueprint reference to the service in order for the service to be provisioned into the application.

For example:

<?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>

In order for a service to be usable by a bundle in an OSGi application, the interface package must be available to that bundle, which means the interface package must be specified by an Import-Package header in the manifest file of the consuming bundle. The interface package must also be specified by an Export-Package header in a feature bundle and specified in the IBM-API-Package header of the feature manifest file. The service provided by a feature must be registered in the OSGi service registry using the OSGi BundleContext interface or any other mechanism such as Declarative Services or Blueprint.

See Develop an OSGi bundle with simple activation and Composing advanced features using OSGi Declarative Services.

IBM-SPI-Package

When we create our own Liberty feature, you install it into the user product extension. All the packages in the feature can be accessed by any other feature installed into the user product extension. However, if we want a package in the feature to be accessed by a feature installed into another product extension, we must list the package name in the IBM-SPI-Package header.

Any package listed in the IBM-SPI-Package header must be exported by a bundle in the Liberty feature, by being listed in the Export-Package header of the bundle manifest file.

IBM-ShortName

Short name for a feature we can leverage to specify a feature in server.xml. If there is no IBM-ShortName header in the manifest file, then the Subsystem-SymbolicName is used by default. The IBM-ShortName header is only valid for public features.

IBM-AppliesTo

Liberty version that this feature applies to. Supply a comma separated list of items, each in the following form:

product_id; productVersion=product_version; productInstallType=product_install_type; productEdition=product_editions

If you supply more than one item, the value of product_id must be different for each one.

The value of product_editions can be either a single edition or a comma-separated list of editions enclosed in quotation marks.

For example:

IBM-AppliesTo: com.ibm.websphere.appserver; productVersion=8.5.5; productInstallType=Archive; productEdition="BASE,DEVELOPERS,EXPRESS,ND"

Subsystem-License

License type for this feature. If you supply a value for the Subsystem-License header, and do not supply values for the IBM-License-Agreement and IBM-License-Information headers, then the Subsystem-License header value is displayed to the user for acceptance during installation.

If there is a feature already installed with the same Subsystem-License header value, then the license is not displayed, and license approval is not sought, during the installation. If dependencies in the Subsystem-Content header mean that there are two or more features being installed that have the same Subsystem-License header value, the user has only to accept the license once during installation.

For example:

Subsystem-License: L-JTHS-93TMHH

Subsystem-License: http://www.apache.org/licenses/LICENSE-2.0.html

IBM-License-Agreement

Prefix of the location of the license agreement files. Supply the file path in the subsystem archive to the LA_language files, up to, but not including, the "_" character (the language code is appended by the installation tool). If this license has not been accepted, the user must accept the license when installing the feature. The license files are copied to the Liberty installation directory.

For example:

IBM-License-Agreement: lafiles/LA

IBM-License-Information

Prefix of the location of the license information files. Supply the file path in the subsystem archive to the LI_language files, up to, but not including, the "_" character (the language code is appended by the installation tool). If this license has not been accepted, the user must accept the license when installing the feature. The license files are copied to the Liberty installation directory.

For example:

IBM-License-Information: lafiles/LI

IBM-App-ForceRestart

Causes applications to be restarted when the feature is installed to, or removed from, a running server. This header can take one of the following values:

install	restart applications when the feature is installed.
uninstall	restart applications when the feature is uninstalled.
install,uninstall	restart applications when the feature is installed or uninstalled.

Example feature manifest file

The following example shows the definition for the example-1.0 feature. The public visibility attribute allows this feature to be directly specified in server configuration (server.xml) files; it will also be included in the drop down list of features that are displayed in Server Configuration view of the developer tools and will be available for inclusion in features that are in other product extensions. If this feature is installed into the usr product extension of a runtime install, it can be configured into a server by including the following code in server.xml:

<featureManager>
 <feature>usr:example-1.0</feature>
</featureManager>

Configuration of this feature in a server will result in the specified bundle, com.ibm.example.bundle1, being installed and started in the OSGi framework of the server runtime environment. The single API package, com.ibm.example.publicapi, will be visible to all applications in that server, except for Java EE applications configured to not have visibility to the api package type. OSGi applications must explicitly import the package if they wish to use it. The two SPI packages, com.ibm.example.spi.utils and com.acme.spi.spiservices, will be visible to all feature code in the server, as will the API package.

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

Parent topic: Develop a Liberty feature manually

Tasks:
Develop a custom TAI as a Liberty profile feature
Auto-provisioning a feature
Develop a custom user registry
Develop a custom thread identity service