Making the move to the Liberty profile, Part 2: Migrating Java EE resources with the Runtime Migration Toolkit

This article series addresses a recent trend among many IT organizations to move their existing Java™ EE applications from Full Platform Java EE servers, such as WebLogic Server, Oracle Application Server, and JBoss Application Server to more lightweight, scalable, and reliable servers, such as the IBM® WebSphere® Application Server Liberty profile. In this three-part series, Part 1 addresses how to evaluate your existing Java EE applications to determine their migration suitability to the Liberty profile. Part 2 shows you how to quickly migrate the Java EE resources that are required for running the applications on the Liberty profile. Part 3 provides step-by-step instructions to quickly migrate your Java EE applications and resources to the Liberty profile.

Sherif Ali (ALYS@ke.ibm.com), IT Specialist , IBM

Sherif Ali is an IBM IT Specialist with over eight years of experience in IT. Sherif has been a member of the World Wide WebSphere Competitive Migration Team since it's creation in 2011. He works with customers to help them realize the value WebSphere Middleware can bring them over other competitive products. In addition, Sherif works with startups on how they can leverage technology to succeed and how IBM can help them get there.



Jagdish Komakula (k.jagdish@in.ibm.com), Certified IT Specialist, IBM

Jagdish Komakula is an IBM Certified IT Specialist, currently working with World-Wide WebSphere Competitive Migrations Team from IBM Software Labs, Hyderabad , India. He has over nine years of IT experience in WebSphere administration, migrations, Java™, J2EE, XML, Service Oriented Architecture, Mobile, Cloud and related technologies. With extensive experience on WebSphere components across various platforms & releases, Jagdish executes WebSphere Competitive Migration Assessments, PoC's and Workshop's worldwide.



Isa Torres (imtorres@us.ibm.com), Application Consultant, IBM

Isa Torres is a member of the WorldWide WebSphere Competitive Migration Team where she currently performs the role of IT Specialist. She has held various roles within IBM in software development and customer support. Her current focus is to enable and assist customers in the process of JEE application migration to WebSphere Application Server by delivering workshops and performing application migrations while developing reusable tools that can assist in future customer engagements.



David Van de Pol (vandepol@ca.ibm.com), IT Specialist, IBM

David Van de Pol is an IBM WebSphere Migration Specialist, currently working with World-Wide WebSphere Competitive Migrations Team from IBM Software Labs, Toronto, Ontario, Canada. He has been a member of the migration team since it's creation in 2011, and has completed many customer migrations from WebLogic, OAS, JBoss, Tomcat, as well as version to version migrations. David came from the WebSphere development team, and now also works on developing and enhancing migration tools used during WebSphere Competitive Migration Assessments and PoC's. David has also worked on creating and performing Migration Workshop's worldwide.



Donald Vines (dhvines@us.ibm.com), Executive IT Architect, IBM

Don Vines is an Executive IT Architect for IBM in the United States. He has been the technical lead of the Worldwide WebSphere Competitive Migration Team since its inception in 2011. In this role, he spends most of his time migrating enterprise applications to the WebSphere V8.x platform for IBM's customers located throughout the world. He is a past representative of the Object Management Group (OMG), where he co-invented the Internet Inter-ORB Protocol (IIOP) that is used throughout the internet. Don is also an IBM Senior Certified IT Specialist, Sun Certified Enterprise Architect, Sun Certified Java Programmer, and OMG Certified UML2 Professional.



23 April 2014

Also available in Chinese

Introduction

The objective of this article is to help you migrate Java EE resources from JBoss and WebLogic Server to the Liberty profile. This enables you to establish the Java EE resources in the Liberty profile that are necessary for running the application. Another article is available on how to migrate Java EE resources from Apache Tomcat to the Liberty profile (see Resources).

In this article, Java EE resources refers to the administrative objects that are created in the Java server via an offline administrative process, and that are accessed by the application at run time. These resources must exist or else the application will not run properly. Examples of these Java EE resources include JMS connection factories, JMS queues, JMS topics, JDBC data sources, JavaMail sessions, and so forth.

To migrate these Java EE resources, you must be able to determine the set of administrative objects that are required by the application. Often the information is not readily available because of a lack of documentation or administrative console access.

Manually inspecting the Java EE server’s XML configuration files, or creating new resources from scratch, is often tedious and error prone especially when dealing with a large number of Java EE resources. Failure to get it right will result in an application that does not run properly.

The Java EE resources for the Liberty profile are defined in a single server.xml file. This is very different than the WebSphere Application Server Full profile, where all of the Java EE resources are created either through the administrative console, or through scripting via the wsadmin tool. In Liberty, these Java EE resources are created manually either through a text editor, or through Eclipse using the WebSphere Application Server Developers Tools plugin (see Resources).

This article introduces a new Eclipse plug-in, the Runtime Migration Toolkit, that assists enterprises in quickly and cost effectively migrating Java EE resources from WebLogic Server or JBoss to the Liberty profile.

Although the focus on this article is on the Liberty profile, this tool also supports the migration of Java EE resources from WebLogic Server and JBoss AS to the WebSphere Application Server Full profile.

The purpose of this tool is primarily to help you quickly set up your Liberty profile server with the Java EE resources necessary to run the ported application. This tool can also be used by administrators to provision testing and production environments. Some manual intervention might be required for these more complex environments.

As of the date of publication, this tool supports runtime migrations from these Java EE servers:

  • JBoss 4.x - 5.x
  • WebLogic Server 6.x – 11.x

How the Runtime Migration Toolkit works

The Runtime Migration Toolkit is packaged as an Eclipse plug-in.

The tool scans the existing Java EE server’s XML configuration files looking for Java EE resources. The user is then presented with a list of Java EE resources that the tool finds.

Next, the tool lets the user provide additional information, such as new passwords, JNDI names, and so on. Finally, the tool generates a server.xml file for the Liberty profile with the Java EE resources that were discovered and any changes that were made.

Table 1 shows what Java EE resources are supported by the tool for different migration scenarios, such as migrations to the Liberty profile and migrations to the WebSphere Application Server Full profile.

Table 1. Java resources supported by the tool, by migration scenario
Java EE resourcesJBoss to LibertyWebLogic to LibertyJBoss to WebSphere Full profileWebLogic to WebSphere Full profileNotes
JDBC providersYesYesYesYes
Data sourcesYes1Yes1Yes2Yes2
JMS providerN/AN/AYesYes
Foreign JMS providerN/AN/ANoYes
JMS destinationN/AN/ANoYes
JMS topicYesYesYesYes
JMS queueYesYesYesYes
Activation specificationYesYesYesYes
Queue activation specificationYesYesYesYes
Topic activation specificationYesYesYesYes
JMS connection factoryYesYesYesYes
JMS topic connection factoryYesYesYesYes
JMS queue connection factoryYesYesYesYes
Mail sessionNoNoNoYes
Mail providerNoNoNoYes
JCA authentication aliasYesYesYesYes
Service Integration Bus3YesYesYesYes
Configures global security and an LDAP user registry YesYesYesYes

Notes:

1 Supports Oracle JDBC Driver, DB2 Universal JDBC Driver, and User-Defined JDBC Provider.
2 Supports all listed above plus Derby JDBC Driver, Informix JDBC Driver, Sybase JDBC Driver, and Microsoft SQL Server JDBC Driver.
3 Creates the Service Integration Bus, but does not create messaging engines or data stores associated with the Service integration Bus. You will need to create them after the tool runs to have a fully functional JMS messaging engine.

Figure 1 shows how the Runtime Migration Toolkit works.

Figure 1. Runtime Migration Toolkit overview
Runtime Migration Toolkit overview

Installing the Runtime Migration Toolkit

The Runtime Migration Tool is an Eclipse plugin you can download free of charge. To install the plugin, follow the standard plugin installation instructions:

  1. Download the Runtime Migration Toolkit.
  2. Start your Eclipse-based IDE.
  3. From the Eclipse menu bar, select Help > Install New Software.
  4. In the Available Software window, click Add.
  5. In the Add Repository popup, enter the following:
    • Name: Enter a name for the tool; for example, WebSphere Runtime Migration Toolkit.
    • Location: Enter the location of the downloaded zip file; for example, C:\RuntimeMigrationToolkit\Runtime_Migration_Toolkit_v2.0.0.0.zip.
  6. In the Available Software window, select Runtime Migration Tool and click Next.
  7. Accept the license and any warning on installing unsigned content.
  8. Click Finish to begin the installation.
  9. Restart Eclipse when prompted.

Using the Runtime Migration Toolkit

Once the Runtime Migration Toolkit is installed you should see a new menu option at the top of the Eclipse window called Migration Tools (Figure 2). You must be in the Java or Java EE perspective in order to access this menu option.

Figure 2. Runtime Migration Toolkit overview
Runtime Migration Toolkit overview

In order to run the runtime migration toolkit you will need a copy of the existing Java EE server’s XML configuration file:

  1. Get the correct XML configuration files for the environment that you want to migrate. If you are migrating from a development environment, for example, then retrieve the XML configuration files from that environment. If you are migrating a test environment, then retrieve the correct XML configuration files for that test environment, and so forth.
  2. Get the entire directory; not just a single XML configuration file. For JBoss, that directory is typically a subdirectory of <JBoss_Home>/server; for example, minimal, default/conf, all/conf, standard/conf, and web/conf. For WebLogic that directory is <WebLogic_Home>/config. You need to copy the entire directory because the tool needs all of these files so that it can find all of the resources that have been defined.

To launch the tool select either:

  • Migration Tools > WebSphere Application Server Migration > Configuration Migration > WebSphere Runtime Migration Toolkit for WebLogic
    or
  • Migration Tools > WebSphere Application Server Migration > Configuration Migration > WebSphere Runtime Migration Toolkit for JBoss

WebLogic

For WebLogic (Figure 3), you will enter the WebLogic config.xml file. This is the main XML configuration file for the WebLogic Server. Depending on the version of WebLogic, this file might be the only file in the folder, or it might have references to other files relative to that folder. In either case, this file is the starting point for the runtime migration tool to search for resources in WebLogic.

Figure 3. Runtime Migration Toolkit overview
Runtime Migration Toolkit overview

JBoss

For JBoss you will need to enter the location of the JBoss configuration directory (Figure 4) rather than a single XML configuration file. JBoss does not have a single XML configuration file that references all of the other configuration files. Instead, it is a collection of independent XML configuration files. Therefore, you will need to enter the root folder of the JBoss configuration so that the tool can search all of the files below this directory.

Figure 4. Runtime Migration Toolkit overview
Runtime Migration Toolkit overview

Select options

Once you have selected your WebLogic config.xml or JBoss conf directory, you will be presented with the migration options page. There is only one option that applies to the migrating to the Liberty profile: Create Liberty Server XML. All the other options apply only to migrations to the WebSphere Application Server Full profile.

Liberty profile options:

  • Create Liberty Server XML: Specify whether or not to create the Liberty server.xml, followed by an option for where to save the server.xml.

WebSphere Application Server Full profile options:

  • Create Jython Script: Specify whether or not to create the Jython script, followed by an option for where to save the Jython script. The Jython script will be used in a later step to create the resources on a WebSphere Application Server Full profile.
  • Get Scopes from WAS: If your WebSphere Application Server topology has already been created and you have multiple nodes or clusters, you can define your resources on those specific scopes. You can get the resource scopes from that topology and create your resources at specific scopes. Proper assignment of the resource scope will ultimately save you time and cost in maintaining those resources after they have been created.

    The resource scope is a powerful concept in WebSphere Application Server that prevents the duplication of resources across lower-level scopes. For example, if a data source can be used by multiple servers in a node, then you can assign the node scope to that data source. This will make the data source visible to all servers on that node. Later, if you need to change that data source definition, you can make that change once at the node level rather than making that change on all servers within the node. (See Resources)

    To get the resource scopes from your WebSphere Application Server topology, you must input the location of the deployment manager's cell.xml file into the Get Scopes from WAS text box (Figure 5). This file is located at <DMGR Profile Home>\config\cells\<cellName>\cell.xml. You will see the list of Scopes. You can then assign a single scope that applies to all of these Java EE resources. If you want to assign different scopes per resource then you can do that in the Assign resources to scope screen (Figure 6).

    Some tips:

    • If you are running this tool on a separate machine from the location of the WebSphere Application Server profile that you wish to configure, you can copy the <DMGR>/config directory to the local machine, and input the location of the cell.xml in the Get Scopes from WAS text box to get the same affect.
    • Assignment of scopes to Java EE resources is not required for single server environments, such as development or integration testing environments; it would only be required for more complex testing or production environments.

    The Default Scope is the scope that you select from a drop down list. The tool will then assign the scope that you selected to all of the resources. If you don’t use the Get Scopes from WAS option, the scopes available are Cell, Node, and Server. If you do provide the topology information in the Get Scopes from WAS, then the default scope options will be replaced with the specific scopes defined in your environment. Whatever value you select for the default scope will be assigned to all of the Java EE resources. You can later change the scope for specific Java EE resources, as explained below.

    Be aware that for standalone servers, such as development machines or continuous integration servers, you can select the Cell setting (Figure 5) for the Default Scope. For more complex testing and production environments, you might want to limit the visibility of the Java EE resources between clusters so that applications in one cluster do not have access to the resources of applications in another cluster.

    Figure 5. WebSphere Configuration Migration
    WebSphere Configuration Migration

    Click to see larger image

    Figure 5. WebSphere Configuration Migration

    WebSphere Configuration Migration

Once you have selected your options, click Next. The plugin will scan your configuration files and then list the Java EE resources it finds in a tree view on the Assign resources to scope page (Figure 6).

Figure 6. Assign resources to scope
Assign resources to scope

You will notice that there is a checkbox beside each resource. You can select the resources that you want to migrate to your new server configuration. The tool might find sample configurations that were defined in your previous environment; this is a good time to go through the resources to determine which ones actually apply so that you can avoid defining unnecessary resources. If you don’t know what resources are used by your application, then creating these unused resources will not hurt your migrated application.

You will also notice that some icons have a red X. This means there is some property value that is unknown and requires user input. The value is usually a “?” which signifies that you must provide a value. Be aware that you must provide a value, or deselect the resource to continue.

For each of the resources, the options are modifiable. For example, Figure 7 shows the definition of the Authentication Alias, which stores username and passwords. Since the password is encrypted, the migration tool cannot supply that value so, as indicated in the figure, it permits you to enter it. Be aware that the password will not be encrypted in the server.xml. You may choose to input a fake password and then change the password via the Eclipse UI for security reasons. Of course, WebSphere Application Server will encrypt the password in its XML configuration files.

Figure 7. Assign resources to scope
Assign resources to scope

Full profile only:

You can change the scope for the JMS provider and the JDBC provider. These are "top-level" Java EE resources that contain other resources. Therefore, assigning a new scope to one of these "top-level" resources assigns that same scope to all resources it contains. For example, if you have a JDBC provider at server scope, you cannot have the corresponding JDBC data source at cell scope. Similarly, if you change the scope for a JMS provider, that scope will be assigned to all JMS queues, topics, and so forth, that are connected to that JMS provider.

Figure 8. Assign resources to scope
Assign resources to scope

Once you have made the necessary changes to your resources, click Finish.

An Eclipse project called Migration Configuration Files will be created in your Eclipse workspace. It will contain the server.xml file you created. These files are links to the file locations you selected through the wizard. Here you can review the server.xml file (or you can review the jython.py file if you are moving your Java EE resources to the WebSphere Application Server Full profile).


Setting up the Java EE resources

Liberty profile

The easiest way to verify the Liberty server.xml is to create a new Liberty server and replace the server.xml with the newly created server.xml. If the server.xml that the tool created contains a time stamp in the name, you should rename it to server.xml. Eclipse will then verify the contents of the server.xml file conform to the XSD.

Once this verification is complete, you can review the resources that were created either by opening the server.xml in Eclipse Design view or by inspecting the server.xml manually. (See Resources)

WebSphere Application Server Full profile

This tool also supports creating a Jython script for use in migrating resources to the WebSphere Application Server Full profile. To run the Jython script, open a command prompt and go to the bin directory of the profile. If in a federated environment (one managed by a deployment manager), then go to the deployment manager in the bin directory.

To run the command:

<Profile Home>/bin/wsadmin.(bat/sh) –lang jython –f <Location of Jython script>

If you have security enabled, then you might need to include –username <username> -password <password> options to the command as well.

If there were any errors in running the script, then you might need to make some changes to the script. For example, the script does not check for duplicate Java EE resources, so if some of the resources have been created already, or if you’re running the script a second time, you might get some errors.

Note: The server must be running in order to execute the wsadmin command. (See Resources)

Once the Jython script completes successfully, you can log into the WebSphere Application Server Full profile administration console to view the newly created resources.


Troubleshooting problems and getting help

There are some resources the tool cannot create. This can be due to factors such as the mapping from JBoss or WebLogic Server to the Liberty profile is not clear and more information is required. This could also be a Java EE resource that the tool hasn’t implemented yet.

All errors and warnings will be displayed in Migration Log view of your Eclipse IDE, as shown in Figure 9. You should carefully review this log to verify if additional steps are required to fix the errors, or address the warnings.

Figure 9. Assign resources to scope
Assign resources to scope

If you need any additional assistance with the tool or its usage then you can also post questions to the WebSphere Runtime Migration Forum. It is moderated by the developers of the tool. (See Resources)


Conclusion

This article presented a new tool for migrating your Java EE resources from WebLogic Server or JBoss Server to the Liberty profile. This tool can also migrate your Java EE resources to the WebSphere Application Server Full profile. This provides an upgrade path between the Liberty profile and the WebSphere Application Server Full profile.

At present, this tool supports the migration of Java EE resources from WebLogic and JBoss. We are investigating extending the tool to other Java EE application servers. If you are interested in other application servers, please post to the forum so that we can prioritize enhancements accordingly.

In addition, this tool supports the migration of Java EE resources that are most frequently used by Java EE applications. If you encounter other resources that the tool does not support then post that new feature request to the forum as well.

When used in conjunction with the WebSphere Application Migration Toolkit that was discussed in Part 1, this tool enables you to quickly move a Java EE application and its associated Java EE resources to the Liberty profile. Part 3 of this article series will provide some examples and step-by-step instructions for migrating your Java EE applications and their resources to the Liberty profile.


Acknowledgements

The authors thank Frank Golazeski for his valuable input and assistance.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Cloud computing
ArticleID=968851
ArticleTitle=Making the move to the Liberty profile, Part 2: Migrating Java EE resources with the Runtime Migration Toolkit
publish-date=04232014