Simplify feature selection with versionless features

Versionless features provide a generic way to specify Open Liberty features without having to specify a feature version. These features automate version selection, so you can focus on application development without worrying about feature compatibility issues.

Versionless features are available for the MicroProfile, Jakarta EE, and Java EE platforms. They are supported only in server environments, not in client environments.

Enabling versionless features

To enable versionless features, you must declare a corresponding versioned platform. You have three options to declare a platform:

Specify a platform element inside the featureManager element of your server.xml file

You can declare a platform version by specifying a platform element inside the featureManager element of your server.xml file. This method is the simplest way to configure and manage your versionless features.

For example, the following server.xml file configuration specifies a Jakarta EE platform of jakartaee-9.1, with associated versionless features for servlet, persistence, and restfulWS:

<featureManager>
    <platform>jakartaee-9.1</platform>
    <feature>servlet</feature>
    <feature>jpa</feature>
    <feature>jaxrs</feature>
</featureManager>

With this configuration, Open Liberty automatically resolves each feature to the version that is included in the Jakarta EE 9.1 platform.

Similarly, the following example enables versionless MicroProfile features that are included in the MicroProfile 5.0 platform:

<featureManager>
  <platform>microProfile-5.0</platform>
  <feature>mpHealth</feature>
  <feature>mpMetrics</feature>
</featureManager>

Specify the PREFFERED_PLATFORM_VERSIONS environment variable

Alternatively, you can declare platforms for versionless features by defining the PREFERRED_PLATFORM_VERSIONS environment variable in your server.env file, as shown in the following example:

PREFERRED_PLATFORM_VERSIONS=microProfile-5.0,jakartaee-9.1

When this environment variable is set, you can specify versionless features in your server.xml file and Open Liberty automatically resolves them to the correct version. In this server.xml file example, the mpHealth and mpMetrics features resolve to versions that are included in MicroProfile 5.0:

<featureManager>
    <feature>mpHealth</feature>
    <feature>mpMetrics</feature>
</featureManager>

You can also set the PREFERRED_PLATFORM_VERSIONS environment variable from the environment shell. However, this method might cause problems if you need to package the server by running the server package command. When you set PREFERRED_PLATFORM_VERSIONS in the server.env file, server packaging retains the setting is retained when you run the server package command. When the server image is unpacked, the server.env file still has the PREFERRED_PLATFORM_VERSIONS setting.

If you set the PREFERRED_PLATFORM_VERSIONS environment variable in the environment shell, the variable is not retained when the server is packaged. If this scenario occurs, the server package command issues the following warning:

CWWKE0969W: A manual PREFERRED_PLATFORM_VERSION environment variable was specified during server packaging.

After you unpack the server image, you must provide a definition of the PREFERRED_PLATFORM_VERSIONS variable to the server.

Enable a versioned feature from a supported platform in your server.xml file

You can declare a platform implicitly by enabling at least one versioned feature that is included in only one supported platform version. Open Liberty then automatically resolves versionless features from that platform to their corresponding versions.

In the following server.xml example, the mpHealth-3.0 feature is part of the MicroProfile 4.0 platform, and no other MicroProfile platform. Open Liberty automatically resolves the versionless mpMetrics and mpConfig features to the versions that are included in MicroProfile 4.0:

<featureManager>
  <feature>mpHealth-3.0</feature>
  <feature>mpMetrics</feature>
  <feature>mpConfig</feature>
</featureManager>

However, this strategy does not work if you declare a feature version that is part of more than one platform, such as mpConfig-2.0, which is included in both MicroProfile 4.0 and MicroProfile 4.1. This strategy is useful primarily for simple configurations, where only a few features are enabled. If you specify multiple versioned features that are part of the same platform, but different platform versions, versionless features might not resolve correctly. For more complex configurations, declare a platform explicitly in a platform element.

Available platforms and versionless features

The currently available MicroProfile, Jakarta EE, and Java EE platform versions and their corresponding versionless features are documented on the following pages:

You can declare up to 2 platform elements, one for MicroProfile and another for either Jakarta EE or Java EE.

Only features that are included in the supported platforms are available in versionless format. For example, because the springBoot-3.0 feature is not specifically included in the MicroProfile, Jakarta EE, or JavaEE platforms, no springBoot versionless feature is available.