Migrating to Liberty

Edit online

Liberty is the WebSphere container-ready runtime available to run everything from your Java™ EE monoliths to your Microprofile microservices to your Spring Boot deployable JAR files. Moving to Liberty modernizes both your runtime and operational environment.

Why move to Liberty from WebSphere Application Server traditional?

Liberty is a container-ready Java EE application server that is perfect for containerized environments.

When you adopt a container strategy, Liberty images are available for both Open Liberty and WebSphere Liberty on Docker Hub and Red Hat certified images.

Liberty has one of the fastest startup times of any Java EE application servers, and it has high server throughput to handle your most important workloads.

Open Liberty is the open source Liberty application server that is developed fully in the open at http://openliberty.io. It supports the Java EE 7 and 8, Jakarta EE 9.1 and 10 full profile programming models as well as Microprofile. It is a fast, composable, production-ready, open source Java EE application server.

WebSphere Liberty is built from Open Liberty and contains more features for Java EE 6 web profile to ease some migration scenarios due to different underlying implementations for Java EE technologies like JPA, JAX-RS, and CDI.

Zero migration

After your initial move to Liberty, the Liberty zero-migration architecture means that you can update the product runtime files and continue to use your existing unmodified applications and configuration with no unwanted or unexpected behavior changes.

If you choose to update your application to a later Java EE level to get the latest capability, the migration tools help you with that as well.

Application modernization assessment and detailed analysis

There are two parts to application modernization: runtime and operations. Runtime modernization refers to moving applications from traditional WebSphere Application Server to Liberty. Operational modernization refers to updating your deployment operations to use container orchestration and with new DevOps and GitOps best practices. Using IBM Enterprise Application Runtimes and Red Hat OpenShift, all your runtimes can be managed with consistency.

The tools described here evaluate your applications to move to Liberty for runtime modernization. There are some differences between traditional WebSphere Application Server and Liberty that takes some migration effort if your application uses older, deprecated technologies or proprietary APIs. For example, WebSphere Liberty supports Java EE 6 web profile (not Java EE 6 full profile). Liberty has Java EE 7 and 8 full profile support, but it does not include optional Java EE technologies such as JAX-RPC and Entity EJB beans. Some of the WebSphere proprietary APIs that were superseded by Java EE APIs were also removed from Liberty. When you have a Java EE application running on Liberty, the zero migration architecture gives you confidence that it is easy to keep it running there.

As described in the Getting Started guide, developing a strategy and plan are an important part of any modernization project. The modernization and migration tools show you the differences and make it easy to understand which applications are affected so that you can plan.

To start your modernization process, there are a number of tools that can help.

Here is a comparison of the capability available in our major tools. In the table, the letter X indicates support by the indicated product or component for the feature listed in the first column.

Features IBM Application Modernization Accelerator Binary Scanner Source Scanner WebSphere Admin Console Mono2Micro
Enterprise scope X
Application detailed migration analysis X X X X
Application inventory report X X X
Application technology report X X X X
Liberty configuration X X X
WebSphere Application Server traditional configuration X X
Graphical user interface X X X X
Command line interface X X X
Complexity rating and development costs X
Shared library analysis X
Container migration artifacts X
Interaction with GitHub repositories X
Cross product analysis - WAS, MQ, IIB X
Business application grouping X
HTML and JSON report formats X X
WebLogic, JBoss, Tomcat application analysis X X X X
WebLogic, JBoss, Tomcat config analysis X X
Containerized implementation X X
Source code analysis and generation X X
Microservice partitioning X

IBM Application Modernization Accelerator

To get the large picture of the migration effort for your application estate, start with IBM Application Modernization Accelerator. The IBM Application Modernization Accelerator data collector scans your entire cell and uploads the results to the IBM Application Modernization Accelerator UI, where you can compare application migration complexities, estimate development costs, and produce migration artifacts for containerized environments. IBM Application Modernization Accelerator reports on runtime modernization for moving from WebSphere Application Server traditional to Liberty, and assists with operational modernization by producing migration artifacts to deploy your workloads in Red Hat OpenShift.

When you cannot move an application to Liberty, IBM Application Modernization Accelerator also gives guidance on moving applications to WebSphere Application Server traditional containers to at least modernize your operations. Remember that Liberty is the preferred container-ready runtime, however.


Transformation Advisor user interface showing analysis of Java applications in a data collection
There are several ways to create your IBM Application Modernization Accelerator data collection.
  • You can download a data collector from IBM Application Modernization Accelerator.
  • You can use the binary scanner to create a data collection by using the --ta parameter. You can get started by downloading the binary scanner before you install IBM Application Modernization Accelerator.
  • Starting with WebSphere Application Server 9.0.5.14, you can use wsadmin to run the data collection that uses the tools that are delivered with WebSphere.

WebSphere admin console

You can analyze applications for their Liberty readiness directly from the WebSphere administrative console when you are running WebSphere Application Server 8.5.5.16 or 9.0.0.11 or higher. Using the Analyze > Run scanner option, you can start the binary scanner to produce a consolidated migration report that can be exported. To learn more, click through this online demo.


Producing a consolidated migration report from the WebSphere administrative console

WebSphere Application Server Migration Toolkit (binary scanner)

IBM Application Modernization Accelerator and the WebSphere admin console use the same binary scanner tool that you can also download and run easily from the command line, so all of these tools produce migration reports that include: You can run the binary scanner to produce all four of the reports by default: 
java -jar binaryAppScanner.jar MyApplication.ear
This command creates an Application Migration Report in HTML format. Use the --help option to learn the other options including the JSON format option. The various reports are described in the following list.
Application Technology Evaluation Report

The Technology Evaluation Report shows the editions of WebSphere Application Server that are best suited to run the application. The report provides a list of Java EE programming models that are used by the application, and it indicates whether the application can be supported by Liberty or WebSphere Application Server traditional.


Example application technology evaluation report
Application inventory report

The Inventory Report helps you understand your application contents including the number of modules and the Java EE technologies used by those modules. It also gives you a view of all the utility JAR files in the application that tend to accumulate over time. Potential deployment problems and performance considerations are also included.


Example application inventory report

As of version 20.0.0.2, the Inventory Report includes new insights on how to migrate WebSphere Application Server Network Deployment qualities of service to a Kubernetes environment.


Example operational considerations section of the application inventory report
Detailed Migration Analysis Report

The Migration Analysis Report gives insights to dive in deeper to understand the details of the migration effort. Based on your source and target application server, Java EE levels, and Java SE levels, a set of analysis rules are run against your application binary files. The detailed analysis results give you insight to application issues such as those in the following list.

  • Java EE differences going back as far as Java EE 6
  • Changes to the Java Runtime Environment (JRE) encountered in going back as far as Java SE 5
  • Removal of previously deprecated features
  • Behavior changes in product APIs
  • Changes resulting from Java EE specification clarifications
  • Deprecated features
  • WebSphere APIs not available on Liberty
  • Optional Java EE technologies not available on Liberty
  • Differences in technology implementations
  • Cloud connectivity considerations
  • Deployment descriptor differences for third-party application servers.

Every issue flagged has a detailed help with useful links to help you mitigate migration issues.


Example detailed migration analysis report
Liberty or WebSphere Application Server traditional configuration

When the application is scanned from a deployed environment or from backup configuration, the tools also produce configuration for deploying to Liberty or WebSphere Application Server traditional containerized environments. At a minimum for Liberty, a feature list is created which provides you the set of features needed to run the application. By adding only the features you need, you create a server that is right-sized for the application needs.


Example Liberty configuration server.xml file
IBM Application Modernization Accelerator

The binary scanner can be used to create a data collection archive. You can manually upload the data collection into your running IBM Application Modernization Accelerator installation. Using the binary scanner gives you a jump on data collection when you do not have IBM Application Modernization Accelerator already installed. Use the java -jar binaryAppScanner.jar --help --ta command to get started with data collection.

WebSphere Application Server Migration Toolkit (source scanner)

After you complete the initial analysis by using IBM Application Modernization Accelerator, the admin console, or the binary scanner, the WebSphere Application Server Migration Toolkit Eclipse plug-in helps developers make the source code changes easier. You run the same set of rules based on your source and target application server, Java EE levels, and Java SE levels against your application source files including Java, JSP, XML, XMI, and properties files. Where possible, the Eclipse-based tool has quick fixes that you can optionally use to make changes to your code. When a quick fix is provided, you can use a side-by-side compare tool to see and understand the changes being recommended before you apply the fix.

Configure the analysis tool by selecting the Run > Analysis menu. Create a Software Analyzer configuration. Choose the scope of the analysis and select the rules to run. Select the WebSphere Application Server Version Migration Rule Set and click Set to configure the migration rules for your scenario.

The Software Analyzer Results view show the issues found in your code. From the result, you can double-click to open the source code in the editor and view the rule help in the Eclipse Help view.


Example Eclipse user interface with software analyzer results view

Mono2Micro

When you want to do more than get your monolith application running on the most modern runtime, IBM Mono2Micro helps you analyze your application gain insights on how to break your monolith into microservices. IBM Mono2Micro uses machine learning to analyze your Java application at the class level based on runtime calls and detected data dependencies (specifically, containment and inheritance relationships). The analysis produces application refactoring options that can be explored and modified through graphs and reports. Mono2Micro has code generation capability to help the initial steps of breaking the monolith apart.

WebSphere Liberty JAX-RPC Conversion Tool for Maven and Gradle

Since Liberty does not support JAX-RPC services or clients, the WebSphere Liberty JAX-RPC Conversion Tool is available to convert JAX-RPC applications to JAX-WS applications that can run on Liberty. This tool runs in Maven or Gradle as part of your build process. There is a validation task and a conversion task. As part of the binary scanner and IBM Application Modernization Accelerator data collection, applications are validated to see whether they are candidates to use this tool. See your analysis reports or IBM Application Modernization Accelerator output to understand whether your applications can take advantage of this tool.

Eclipse Transformer

The Eclipse Transformer helps you modernize applications to use the Jakarta EE programming model. Before Jakarta 9, the Java EE programming model uses javax in their package naming. Starting with Jakarta 9, the Jakarta programming model moved to jakarta package naming. The Eclipse Transformer helps you modify either your application source code or your binary archives to use the new package naming. It takes the guess work out of the package rename since some Java SE classes still use javax.