Liberty zero-migration architecture

With the Liberty zero-migration architecture, you can move to the latest version of Liberty with minimal impact to your current applications and configurations.

Documentation for zero-migration architecture is available on the Open Liberty website.

Zero-migration architecture means that you can use existing, unmodified configuration and application files with an updated version of the Liberty runtime environment without unwanted or unexpected change in behavior. With the following two aspects of architecture, you almost never need to make changes:

Full compatibility between product versions: You can update Liberty without migrating your configuration files.
Pluggable features: Your existing APIs and behaviors are supported in new product versions, and new APIs and behaviors are added in new features.

User configuration files

The Liberty runtime environment never modifies user configuration files, which are fully compatible between versions. You can use a single version of your configuration files across multiple versions. Files that you created for a previous version of Liberty can be used with a later version. Files that you create for later versions can be used with previous versions. As a result, if all configured features are installed, you can use a single set of configuration files across multiple versions without modifications . Any configuration settings that do not apply to a particular version of the Liberty runtime environment are ignored.

User applications

The Liberty runtime environment uses pluggable features to support multiple versions of an API. For example, both the Servlet 3.0 and 3.1 specifications are supported. Changes in API behavior only happen in new feature versions, so you can choose the appropriate feature version for your application. These versioned features continue to be supported across Liberty updates. If you continue to use the same feature version, you never need to migrate your application.

For example, if your application uses Servlet 3.0, the Liberty server that runs the application must have the servlet-3.0 feature. You can update Liberty and continue to use the servlet-3.0 feature indefinitely, regardless of how many other Servlet specification levels are supported. You need to migrate your applications only if you choose to use the servlet-3.1 feature instead.

A diagram that displays how Servlet features are used with previous and recent versions of the product.

The previous diagram shows how different versions of the Servlet feature can be enabled in different versions of the runtime by way of new and existing user configurations and applications. Older versions of the runtime can ignore more recent versions of a feature, while the latest version of the runtime can ignore older versions of the feature.

If you use third-party APIs, be aware that they can be changed or removed when you update Liberty. Third-party APIs are exposed to applications through Liberty features. Compatibility with an earlier version of these APIs is not controlled by Liberty and is not guaranteed. Some APIs that are available to applications are not provided by Liberty features and do not benefit from this design, so you might need to modify your application code. For example, you might need to update the Java™ APIs that are provided by the underlying Java SDK. Occasionally, you might need to update the version of the Java SDK. Rather than manually gathering information and migrating your applications, scan your applications for any required changes by using the Migration Toolkit for Application Binaries and the WebSphere Application Server Migration Toolkit. To download the toolkit and get more information, see the Migration article on WASdev.

Using new features

If you want to use a new feature, consider the following questions:

How does a new feature affect existing applications?: A new version of a feature that you are already using might impact your existing applications. For example, if you currently use Servlet 3.0 and you want to use Servlet 3.1, your existing servlet applications might need to be changed to work correctly with Servlet 3.1. Modify your application to work with the new feature version or keep your applications in a server that is configured with the original feature version, such as Servlet 3.0, and create a server configuration with the new version for new applications.
Is the new feature compatible with existing features?: The product supports mixing some features across different versions of Java EE, but it is simpler to stay within one version of the Java EE specification, if possible. Some features interact closely with other features when they are both configured into the same server, and are sensitive to their versions. For example, many of the Java EE features are closely associated with the features for Contexts and Dependency Injection (CDI) and only work with a specific version of that feature. If you add a feature into your configuration, you might need to change the versions of other features that you are already using. For more information, see Supported Java EE 6 and 7 feature combinations.
Does the new feature require other configuration changes?: Some features require specific versions of prerequisite software, most commonly the Java SDK. Java EE 7 features, for example, require Java version 7 as a minimum. Therefore, adding a Java EE 7 feature to your server configuration might require you to move up to Java SDK 7 or later.

Exceptions to zero-migration

In some rare instances, the zero-migration concept is not followed. In the following scenarios, you might need to modify your application or configuration:

Security fixes: If a security-related fix is required, but cannot be done safely while preserving existing behavior, then you might need to modify your application or configuration.
Third-party API requirements: The product does not control APIs from the third-party class loader configuration. As a result, updates to third-party components have no guarantee of compatibility with an earlier version.
Removal of support: Liberty continues support for parts of the product that affect user data, but it is occasionally necessary to withdraw a feature or supported software product. Usually, users receive removal notifications at least two years in advance. However, notifications are not as practical when other software suppliers remove support for their product earlier than Liberty does. Be aware of the third-party products that you are using with your Liberty installation and of their lifecycle dates. For information about items that are eligible for future removal, see Removal notices.
Undocumented configuration properties: The Liberty code base is common with the WebSphere® Application Server traditional code base. Therefore, some configuration properties in the Liberty code base might not be documented, but when specified might affect the behavior of Liberty. As these configuration properties are not documented for Liberty, they are not supported for Liberty. They were not tested for Liberty and might not work reliably in Liberty now or in the future. As these properties are not documented as a product external, they can be removed at any time.
Incompatible Java changes: Historically new Java SE versions have made few incompatible changes to the language, this changed with Java SE 9. The Liberty runtime will attempt to minimize the impact of these breaking changes on applications, however this may not always be possible.