WebSphere Application Server & Liberty

 View Only

Migrate JAX-RPC applications to Liberty using our new Maven/Gradle Conversion Tool

By David Shi posted Tue January 18, 2022 12:36 PM


Migrate JAX-RPC applications to Liberty using our new Maven/Gradle Conversion Tool


Are you ready to move your traditional WebSphere applications to Liberty, and take advantage of the platform's modern cloud-ready runtime, but find those same applications are held back by older JAX-RPC code that isn't supported in Liberty?  The migration effort can be daunting. Do you go the "easy" route and migrate from JAX-RPC to its successor JAX-WS, or do you re-architect your Web Services with modern technologies like REST or gRPC? When the "easy" route still requires a migration effort that includes the analysis of the application structure, regeneration of stubs and data objects, and carrying forward your business logic - all while trying to maintain the existing functionality of the application, things can get overwhelming quickly.

With our new JAX-RPC conversion tool, we aim to simplify the migration from JAX-RPC to JAX-WS. To start, you can quickly validate your application's WSDL files for their compatibility with JAX-WS. When validation passes, you can then trigger a hands-free migration of your JAX-RPC application. The JAX-RPC conversion tool we bring to you today is the culmination of harnessing our JAX-RPC and JAX-WS knowledge base.

Validation Process

The validation goal/task serves as a quick entry check for clients to investigate and weigh their options for their apps. Validation is run first to identify JAX-RPC structures that are not supported in JAX-WS or Liberty. For example, some namespaces are not supported in JAX-WS including those used by RPC/Encoding style WSDLs. Other types of checks, such as a valid mapping of MIME parts to WSDL parts, exist to ensure our tool can properly convert the code during the migration process. After the validation scan completes, relevant warnings and errors pinpoint the line and file that requires attention. If no warnings or errors are identified, chances are good that the application can be converted automatically.

Conversion Process

The replace JAX-RPC goal/task starts by using wsimport to generate the JAX-WS stubs and data objects. Then our tool does the heavy lifting by migrating various aspects of the application from JAX-RPC to JAX-WS, greatly reducing labor costs and saving significant time. Here's an overall breakdown of the conversion steps.

  • Generate JAX-WS stubs

  • Migrate JAX-RPC client to use JAX-WS stubs

  • Migrate JAX-RPC business logic

  • Migrate JAX-RPC Data Objects to JAX-B Data Objects

  • Migrate JAX-RPC EJB 2.x bean to JAX-WS EJB 3.x bean

  • Migrate handlers

  • Migrate deployment descriptors

  • Remove orphaned JAX-RPC references and artifacts

DevOps Pipeline Integration

You can integrate the use of our conversion tool into your Maven or Gradle build pipeline. After installing the plug-in locally for your chosen build tool, simply configure the plug-in in your project and start the validation and conversion process. You can make use of our Liberty Maven Plugin or Liberty Gradle Plugin to deploy and test the converted application on Liberty also.

If you don't currently use Maven or Gradle to build your applications, either are easy to install and configure. Once installed, just create a project and point to the already built archive (.ear or .war) that you want to convert. 

Source Free Migration

Another significant feature of our conversion tool is that it works on the binary application (.ear or .war) and manipulates the bytecode directly. So if you have a legacy application where the source code has been misplaced, no problem!


We strive to automate the conversion of most major functions from JAX-RPC to JAX-WS where possible. However, there are some restrictions and limitations. For example, the tool does not handle conversion of web services security, or applications that use the dynamic invocation interface (DII). While the tool can't migrate WS-Security configuration for you, WS-Security can still be manually configured on Liberty with your migrated application. Finally, the converted applications must run on a minimum Liberty version of or later.

Version 1.1 of the JAX-RPC conversion tool adds support for Windows.

In Conclusion:

Depending on the complexity of your application, this tool could be your simple ticket to running on Liberty in a matter of minutes. We are very interested to hear about customer experiences with the tool, both success stories as well as issues that prevented conversion, so that we can prioritize any additional necessary functionality. 

Are you ready to migrate your JAX-RPC applications to Liberty now? Get started by visiting our support page to download the tool. Note: You will need entitlement to WebSphere Liberty in order to have access to the tool.

Helpful Resources

Migrating JAX-RPC applications to Liberty

WebSphere Migration Knowledge Collection: Migrating to Liberty

WebSphere Application Server Migration Toolkit

IBM OpenLiberty/developer-experience gitter