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 runtime environment. You 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 Liberty uses the Subsystem Service metadata format in the OSGi Enterprise R5 specification. A feature is defined by a feature manifest file, or .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.

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

The following headers are defined:

Table 1. Headers of a feature manifest file.
This table shows the headers of a feature manifest file in Liberty. The first column shows a list of headers. The second column shows the description of each header, and the third column states whether the header is required.
Header	Description	Required or not
`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 that are required to run this feature. If you want to allow the auto feature to be configured in the server.xml file, you must have the capability header containing the required features, and also define them in the subsystem content. Additionally, you need to specify the OS if the content is not valid for all operating systems. The OS attribute supports the non-case sensitive value of z/OS®. Any other values are ignored and all files are installed on all platforms, but z/OS-marked files are not installed on non-z/OS machines. Any content that is not valid for the installing operating system is skipped.	Yes
`Subsystem-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 that are exposed to applications by this feature, features in other product extensions, and the Liberty kernel.	No
`IBM-API-Service`	The OSGi services that are exposed to OSGi applications by this feature.	No
`IBM-SPI-Package`	The SPI packages that are 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`	Specifies 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; the default value is false.
For more information, see Superseded Liberty features.
superseded-by. This attribute specifies a comma-separated list of the features that supersede this feature, if any, and is optional.

The following directives are 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 the server.xml file, and output in messages.
- protected - Feature considered to be SPI. The feature is not supported by the developer tools, for use in the server.xml file, or output in messages. The feature is provided so extenders can use it to build higher-level features.
- private - (default) The feature is product internals. The feature is not supported for use in the server.xml file 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 is 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 information about separated features.

Best practice: 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.

singleton. This directive takes one of the following values:
- True. The feature is a singleton.
- False. The feature is not a singleton.
The singleton directive is optional. The default value is False.

This directive is used to declare that a particular feature is a singleton. A singleton means that only one version of a given feature can be loaded into the runtime at a time. By default, features are not singletons. If the feature is a singleton and multiple versions of a given feature are required by the server configuration, then the runtime attempts to find a common version that is tolerated by all requiring features. For more information on version toleration, see the ibm.tolerates directive under Subsystem-Content.
When a feature is a singleton, then the symbolic name value is in the form <singleton feature name >-<singleton version>, where the name and version are separated by a hyphen. The singleton feature name can contain hyphens, but the characters that follow the last hyphen are interpreted as the singleton version. If the characters that follow the last hyphen are not a valid version, then a singleton version of 0.0.0 is used and the complete symbolic name is used as the singleton name. The singleton version is used when you process ibm.tolerates directives under Subsystem-Content; for example:
```
Subsystem-SymbolicName: com.ibm.example.feature-1.0; 
    visibility:=public; singleton:=true
```

Subsystem-Content

This header defines the content of the feature, both for runtime and installation. 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 you find 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. You can specify any value to indicate the content type; some types result in bundles being installed and started in the OSGi framework of a server that uses the feature, all types cause the content to be included in an installation package that includes the feature. The following values are predefined:
- osgi.bundle - This is the default value and indicates an OSGi bundle that must be provisioned both into the OSGi framework of the server and an installation package.
- osgi.subsystem.feature - This value indicates that the feature must be provisioned both into the OSGi framework of the server and an installation package. These features need to use the name that is specified in Subsystem-SymbolicName header.
- jar - This value indicates that a JAR file must be included in an installation package and is selected by using a combination of a version range, a location value, or both.
- file - This value indicates that the file that is identified in the location attribute must 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 that represent a search path. For any type, this value might be a single entry that points directly to the resource and might be specified as a file URL. Paths might be absolute or relative. Relative paths are resolved relative to the location of the product extension that contains the feature. For a user feature, the default product extension location is used which is ${wlp.user.dir}/extension. The location of non-default product extensions is declared by the com.ibm.websphere.productInstall property in its properties file in the ${wlp.install.dir}/etc/extensions directory.
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"
```
start-phase - The start phase when the bundle must start during system startup. The start-phase directive can take one of the following values:
- SERVICE - This value indicates the earliest phase. By default it maps to a start level of 9.
- CONTAINER - This is the default value 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 - This value indicates the latest phase when applications are started.
Bundles can also be defined to start before or just after these phases by adding _LATE to be later, or _EARLY to be earlier than the key phase. So if you want to run immediately after the container phase, use CONTAINER_LATE, and if you want to run before the APPLICATION phase then use APPLICATION_EARLY.
ibm.tolerates - Specifies alternative singleton version or versions of a singleton feature,type=osgi.subsystem.feature, to be provisioned into the system if there are version conflicts.
The unique-name specifies the symbolic name of the preferred version of a singleton feature. If the including feature is known to work with other singleton versions of a given singleton feature, then these singleton versions can be specified by using the ibm.tolerates directive. This gives greater compatibility to the defining feature in the case that other features define conflicting required version values of a given singleton feature.

Singleton versions that are listed in the ibm.tolerates directive are only used if a version conflict. The ordering of versions that are listed in the ibm.tolerates directive is not significant - any version that is listed in the ibm.tolerates directive can be selected to satisfy dependency requirements.

The tolerated version or versions of a given singleton feature must be explicitly listed in the ibm.tolerates directive. Use commas to separate a list of tolerated versions. Specifying a version range is not supported.
For example:
```
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"
```
Note:
Tolerated versions are not transitive. This prevents a feature that your feature depends on from being automatically opted in to supporting a later level of a feature, without testing it.

For example: User feature featureC-1.1 includes sipServlet-1.1 in the Subsystem-Content header of its manifest file. sipServlet-1.1 includes servlet-3.0 and tolerates servlet 3.1. If featureC-1.1 was written before servlet-3.1 existed, and then servlet-3.1 was added and tolerated by the feature that is used by it (sipServlet-1.1), featureC-1.1 should have a say on whether it also tolerated servlet-3.1.
If you configure the server.xml file to have the following two features:
```
<feature>usr:featureC-1.1</feature> // includes: sipServlet-1.1
<feature>websocket-1.0</feature> // this feature requires servlet-3.1
```
You see an error message that resembles the following displayed:
```
CWWKF0033E: The singleton features servlet-3.0 and servlet-3.1 cannot be loaded at the same time. 
The configured features usr:featureC-1.1 and websocket-1.0 include one or more features that cause the conflict. 
Your configuration is not supported; update server.xml to remove incompatible features."
```
This error is reported because featureC-1.1 is not opted in to tolerating servlet-3.1, and so has to have servlet-3.0, and websocket-1.0 does not support servlet-3.0 and so has to have servlet-3.1.

The solution is for featureC-1.1 to also directly depend on servlet-3.0 and tolerate servlet-3.1.

The following directive is supported:

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 results in no action taken. The following table shows the current umask and which class gets the execute permission.

Table 2. Examples of umask values and classes with execute permissions set by ibm.executable
Umask	Execute permissions granted to class
022	owner, group, other
023	owner, group
055	owner

Subsystem-Localization

This header specifies the 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. You can specify either a literal string or a property name. If you 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 that is specified by the Subsystem-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. You can specify either a literal string or a property name. If you 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 that is specified by the Subsystem-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 you list the other features, use the Subsystem-SymbolicName header of the feature. When any features are configured in the server.xml file, 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

This header is used to indicate 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 - Indicates an API provided by a standard body, such as javax.servlet or org.osgi.framework.
- ibm-api - Indicates a value-add API provided by IBM®.
- api - Indicates a user-defined API. This is the default value.
- third-party - Indicates an API that is visible, but not controlled by IBM. Typically, these are open source packages.
- internal - Indicates 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

This header is used to indicate 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 wants to use the services that are 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 that is provided by a feature must be registered in the OSGi service registry by using the OSGi BundleContext interface or any other mechanism such as Declarative Services or Blueprint. For more information, see Developing an OSGi bundle with simple activation and Composing advanced features by using OSGi Declarative Services.

IBM-SPI-Package

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

Any package that is 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

This header is a short name for a feature that you can use to specify a feature in the server.xml file. 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

This header specifies the 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 productVersion can be either an exact version, such as 8.5.5.7, or a minimum version, denoted by the version that ends with a plus sign, +, such as 8.5.5.7+.

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

For example:

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

Subsystem-License

This header defines the 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 that is 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

This header specifies the 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 you install the feature. The license files are copied to the Liberty installation directory.

For example:

IBM-License-Agreement: lafiles/LA

IBM-License-Information

This header specifies the 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 you install the feature. The license files are copied to the Liberty installation directory.

For example:

IBM-License-Information: lafiles/LI

IBM-App-ForceRestart

This header 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 is also included in the drop-down list of features that are displayed in Server Configuration view of the developer tools and is 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 the server.xml file:

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

Configuration of this feature in a server results 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, is visible to all applications in that server, except for Java EE applications that are 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, is visible to all feature code in the server, as is 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