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. 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 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.
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 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 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 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 |
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.
For more information, see Superseded features.
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]"
For
more information, see Separated features.Subsystem-Content ::= content ( ',' content )*
content ::= unique-name ( ';' parameter )*
unique-name ::= unique-name (see OSGi core spec section 1.3.2)
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"
This header specifies the location of the localization files for the feature.
Subsystem-Localization: OSGI-INF/l10n/loc
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 a specify a property name, the value can be localized.
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
Use this header to supply a description for the feature. You can specify either a literal string or a property name. If you a specify a property name, the value can be localized.
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
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 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.
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.
IBM-API-Package: javax.servlet; type="spec",
com.ibm.websphere.servlet.session; type="ibm-api",
com.ibm.wsspi.webcontainer.annotation; type="internal"
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.
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.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.
<?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 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.
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 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.
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.
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.
IBM-AppliesTo: com.ibm.websphere.appserver; productVersion=8.5.5; productInstallType=Archive; productEdition="BASE,DEVELOPERS,EXPRESS,ND"
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 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.
Subsystem-License: L-JTHS-93TMHH
Subsystem-License: http://www.apache.org/licenses/LICENSE-2.0.html
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 installing the feature. The license files are copied to the Liberty installation directory.
IBM-License-Agreement: lafiles/LA
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 installing the feature. The license files are copied to the Liberty installation directory.
IBM-License-Information: lafiles/LI
<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 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,
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