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 resources||JBoss to Liberty||WebLogic to Liberty||JBoss to WebSphere Full profile||WebLogic to WebSphere Full profile||Notes|
|Foreign JMS provider||N/A||N/A||No||Yes|
|Queue activation specification||Yes||Yes||Yes||Yes|
|Topic activation specification||Yes||Yes||Yes||Yes|
|JMS connection factory||Yes||Yes||Yes||Yes|
|JMS topic connection factory||Yes||Yes||Yes||Yes|
|JMS queue connection factory||Yes||Yes||Yes||Yes|
|JCA authentication alias||Yes||Yes||Yes||Yes|
|Service Integration Bus3||Yes||Yes||Yes||Yes|
|Configures global security and an LDAP user registry||Yes||Yes||Yes||Yes|
1 Supports Oracle JDBC Driver, DB2 Universal JDBC Driver, and User-Defined
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
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:
- Download the Runtime Migration Toolkit.
- Start your Eclipse-based IDE.
- From the Eclipse menu bar, select Help > Install New Software.
- In the Available Software window, click Add.
- 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,
- Name: Enter a name for the tool; for example,
- In the Available Software window, select Runtime Migration Tool and click Next.
- Accept the license and any warning on installing unsigned content.
- Click Finish to begin the installation.
- 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
In order to run the runtime migration toolkit you will need a copy of the existing Java EE server’s XML configuration file:
- 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.
- 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
- Migration Tools > WebSphere Application Server Migration > Configuration Migration > WebSphere Runtime Migration Toolkit for JBoss
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
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
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).
- 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
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
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
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
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
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> -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
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)
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.
The authors thank Frank Golazeski for his valuable input and assistance.
- Making the move to the Liberty profile, Part 1: Determining migration suitability using the Liberty Technology Preview
- Migrating from Apache to WebSphere Application Server Liberty Profile
- IBM WebSphere Application Server V8.5 Concepts, Planning, and Design Guide, pp. 414-416. (PDF)
- IBM WebSphere Application Server V8.5 Administration and Configuration Guide for the Full Profile, pp. 324-325 (PDF)
- WebSphere Application Server Liberty Profile Guide for Developers
- Migration Apache Tomcat configuration to WebSphere Application Server Liberty Tech Preview
- IBM developerWorks WebSphere
Get products and technologies
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.