Product extension

You can expand the capability of Liberty by writing product extensions.

You can write your own Liberty features and install them onto an existing Liberty server, or you can package them for delivery to your users.

Liberty provides various System Programming Interfaces (SPIs) that you can use to extend the runtime environment; you can also use more advanced features such as operating the Liberty server from your Java™ applications programmatically.

Product extension

A product extension is a directory on disk that is structured like the Liberty installation directory, ${wlp.install.dir}. It is defined to the Liberty installation through a file in the ${wlp.install.dir}/etc/extensions directory called extension-name.properties. The contents of the product extension directory are then used to extend Liberty. Multiple product extensions can be installed together but they must have unique names; this is enforced through the naming of the properties files. The default product extension location, ${wlp.user.dir}/extension, does not require a properties file; content under this location is automatically detected and is known to the runtime as the usr product extension.

Product extensions usually contain one or more Liberty features but can have any content that extends the Liberty environment, for example scripts or resources.

Best practice: Install your product extensions into directories that are not affected by updates to the Liberty environment. For more information, see What might be modified by applying service or an upgrade?.
Figure 1.
Diagram showing Liberty installation with two features, "Supergui" and "App Services"

In the previous figure, the Liberty contains two user features and two properties files: supergui.propertiesand appservices.properties. The supergui.properties file is connected to the Supergui installation, which contains the supergui feature. The appservices.properties file is connected to the App Services installation, which contains three appservices features.

The product extension file has the following properties:
com.ibm.websphere.productId=your_product_id
com.ibm.websphere.productInstall=absolute_or_relative_file_path
Note: When a relative file path is used, it must be a peer of the ${wlp.install.dir} value.
For example:
com.ibm.websphere.productId=org.acme.supergui
com.ibm.websphere.productInstall=supergui/wlp-ext

Feature

A Liberty feature consists of a definition file (feature manifest), and a collection of OSGi bundles that provide classes and services corresponding to a particular capability in the Liberty runtime environment.

Scenarios for using a Liberty feature instead of a regular application

Implementing a function as a Liberty feature instead of as an application might be appropriate in a number of scenarios. The following list describes some of the benefits of using a feature:
  • Features are controlled through feature manager configuration, so they are separate from user application management.
  • Feature code has access to the Liberty SPI, which allows deeper integration with the runtime environment.
  • Features can receive user-specified configuration from the server.xml file, and expose their configuration settings in the development tools without the tools having to be changed.
  • Features can easily expose classes and services to each other and to user applications.
  • Features can be extremely lightweight with no application container dependencies.
  • Features can be used to augment a particular programming model. For example, a User Feature can add support for custom Blueprint namespace handlers or Blueprint annotations to the OSGi Application programming model.
Note: Features cannot generally be directly portable to other application servers; if portability is important use specification-compliant applications.

Developing a simple feature

See Developing a Liberty feature manually, Creating a Liberty feature by using developer tools, and Liberty feature manifest files.

Using a feature in the server

To use a user-written feature in the Liberty server, you must install it into a product extension directory. This might be the predefined user product extension location or an extension that is located outside the Liberty installation directory. Then you can add the feature name into the server configuration.

The user product extension is a predefined directory where the server looks for additional features. The feature definition .mf file must be copied into the ${wlp.user.dir}/extension/lib/features directory and the bundle .jar files must be copied into the ${wlp.user.dir}/extension/lib directory.

User-written features are added to the server configuration in the same way as product features. To avoid name clashes with features from different providers, features that are part of a product extension must be prefixed with the extension name. For features in the usr/extension/lib directory, the default prefix is usr:.

For example, if you have installed a feature called simple-1.0 into the ${wlp.user.dir}/extension/lib directory, you must configure that feature into the server.xml as follows:
<featureManager>
    <feature>usr:simple-1.0</feature>
</featureManager>
If you have installed a feature called myFeature into your own location, and defined a product extension in the ${wlp.install.dir}/etc/extensions/myExt.properties file, you must configure that feature into the server.xml file as follows:
<featureManager>
    <feature>myExt:myFeature</feature>
</featureManager>

When you start the server, the feature is detected by the feature manager and the bundles are installed into the OSGi framework and started.

See also Adding and removing Liberty features and Feature management.

Programmatically using a feature from applications

Features can expose classes and services to applications.

To expose Java classes for application use, you must list the class packages in the IBM-API-Package header in the feature manifest. Listing the class packages in the IBM-API-Package header makes the classes visible to the application class loaders. Visibility of API packages can be controlled through the API visibility type. See Specifying API and SPI packages for a Liberty feature project.

To allow services to be used by OSGi applications, you must list them in the IBM-API-Service header in the feature manifest. A feature provides OSGi services so that you can refer to those services programmatically from your applications.

Services must be registered into the OSGi Service Registry (SR) to allow applications (or other features) to locate them. OSGi applications and other features can perform a direct lookup from the SR, or can use capabilities such as Blueprint or OSGi Declarative Services to inject their service dependencies. Java EE applications are more likely to locate services through JNDI; in Liberty there is a federation of the SR and JNDI that allows Java EE applications to use JNDI to locate services in the SR. For more information, see Working with the OSGi service registry.

Exposing a feature as a web application

To expose a Liberty feature as a web application, you can publish the OSGi bundles in the feature as web application bundles (WABs). In addition to the OSGi headers that a bundle requires, you can specify the web application context path by using the Web-ContextPath header.

For example:

Web-ContextPath: myWABapp
Bundle-ClassPath: WEB-INF/classes

Configuration injection and processing

A major benefit of using features is that they can be easily configured by the user in the server.xml file (and included files). The configuration files are monitored and parsed by the Liberty kernel and the resulting sets of properties can be injected into the relevant component each time they change.

Liberty configuration is managed by the OSGi Configuration Admin (CA) service in the kernel and can be accessed according to that specification. Sets of configuration properties are identified by a persisted identity (PID) that is used to associate the element in the server.xml file with the component that registers to receive the properties.

For example, if you register your feature with the CA service using a PID of com.acme.console, a user can specify the following configuration in the server.xml file:
<com.acme.console color="blue" size="17"/>
And your feature will receive the properties:
  • color="blue"
  • size="17"

You can optionally provide metadata that describes your configuration properties by using OSGi Metatype descriptors. The use of descriptors causes your configuration metadata to be included in the configuration schema that is generated by Liberty and is used by the Developer Tools, so your configuration properties are automatically presented to application developers as they configure their server.

For more details on receiving and describing configuration properties, see Enabling a service to receive configuration data.

Declarative Services in Liberty

Larger or more complex features often benefit from the use of OSGi Declarative Services (DS) to enable the feature to be composed of multiple services, and to manage the injection of dependencies and configuration properties. The use of DS allows lazy activation of services, deferring the loading of Java classes until the service is used, and ordering the activation of services based on dependencies. Most of the features in the Liberty product are managed by DS.

See also Composing advanced features by using OSGi Declarative Services .