Migrating Java EE resources with the Configuration Migration Toolkit
This content is part # of # in the series: Making the move to the Liberty profile, Part 2
This content is part of the series:Making the move to the Liberty profile, Part 2
Stay tuned for additional content in this series.
The objective of this article is to help you migrate Java EE resources from JBoss and WebLogic Server to the Liberty profile. This tool also supports migrating Java EE resources from the WebSphere Application Server full profile 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 Related topics).
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 Related topics).
This article introduces a new Eclipse plug-in, the WebSphere Configuration Migration Toolkit, that assists enterprises in quickly and cost effectively migrating Java EE resources from WebLogic Server, JBoss Server, or WebSphere Application Server V7.0 (and later) Full profile 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, JBoss AS, and WebSphere Application Server V7.0 (and later) to the WebSphere Application Server V8.5 Full profile. This article will also, therefore, include instructions for these use cases as well. The download and forum links in the Related topics section also cover these usage scenarios.
As of the date of publication, this tool supports runtime migrations from these Java EE servers:
- JBoss 4.x - 5.x to Liberty or Full profile
- WebLogic Server 6.x – 11.x to Liberty or Full profile
- WebSphere Application Server V7.0 (and later) to Liberty or Full profile
The purpose of this tool is primarily to help developers quickly set up their Liberty or Full profile server with the Java EE resources necessary to run the ported application. This tool can also be used by administrators to provision system test and production environments. Some manual intervention might be required for more complex environments; for example, setting database passwords configuring persistent messaging, and so on.
How the Configuration Migration Toolkit works
The Configuration 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||WebSphere V7+ Full to Liberty||JBoss to WebSphere Full profile||WebLogic to WebSphere Full profile||WebSphere V7+ Full to WebSphere V8.5 Full|
|Foreign JMS provider||N/A||N/A||N/A||No||Yes||No|
|Queue activation specification||Yes||Yes||Yes||Yes||Yes||Yes|
|Topic activation specification||Yes||Yes||Yes||Yes||Yes||Yes|
|JMS connection factory||Yes||Yes||Yes||Yes||Yes||Yes|
|JMS topic connection factory||Yes||Yes||Yes||Yes||Yes||Yes|
|JMS queue connection factory||Yes||Yes||Yes||Yes||Yes||Yes|
|JCA authentication alias||Yes||Yes||Yes||Yes||Yes||Yes|
|Service Integration Bus3||Yes||Yes||Yes||Yes||Yes||Yes|
|Configures global security and an LDAP user registry||Yes||Yes||Yes||Yes||Yes||No|
1 Supports Oracle JDBC Driver, DB2 Universal JDBC Driver, DB2
Using IBM JCC Drive, Derby, Derby Network Server Using Derby Client,
Microsoft SQL Server JDBC Driver and User-Defined JDBC Provider.
2 Supports all listed above plus Informix JDBC Driver and Sybase 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 Configuration Migration Toolkit works.
Figure 1. Configuration Migration Toolkit overview
Installing the Configuration Migration Toolkit
The WebSphere Configuration Migration Toolkit is an Eclipse plugin you can download free of charge. To install the plugin, follow the standard plugin installation instructions.
Using the Configuration Migration Toolkit
Once the WebSphere Configuration 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. WebSphere Configuration Migration Toolkit overview
In order to run the WebSphere Configuration Migration Toolkit you will need a copy of the existing Java EE server’s configuration file:
- Collect the correct 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.
- Collect 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. For WebSphere Application Server, you will need to generate a configuration properties file. See the WebSphere Application Server V7.0 (and later) section for instructions.
To launch the tool select either:
- Migration Tools > WebSphere Application Server Migration
> Configuration Migration > WebSphere Configuration
Migration Toolkit for WebLogic
- Migration Tools > WebSphere Application Server Migration
> Configuration Migration > WebSphere Configuration
Migration Toolkit for JBoss
- Migration Tools > WebSphere Application Server Migration > Configuration Migration > WebSphere Configuration Migration Toolkit for WebSphere
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 Configuration Migration Toolkit to search for resources in WebLogic.
Figure 3. Configuration Migration Toolkit overview
For JBoss you will need to enter the location of the JBoss configuration directory rather than a single XML configuration file. The panel looks very similar to Figure 3. 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. You will therefore need to enter the root folder of the JBoss configuration so that the tool can search all of the files below this directory.
WebSphere Application Server V7.0 (and later)
For WebSphere Application Server V7.0 and later, you must first extract the configuration from WebSphere Application Server into a properties file. To do this, you must start the source application server and then run this following command from the <Profile_Home>\bin directory:
wsadmin(.sh/.bat) –lang jython –c “AdminTask.extractConfigProperties(['-propertiesFileName my.props'])”
After that, enter the location of the resulting file into the tool; the panel looks similar to Figure 3.
Specify target environment
Once you have selected your WebLogic config.xml, JBoss conf directory, or WebSphere properties file, you will be asked to specify the target environment (Figure 4).
Migrating to Liberty profile only
For migrations to the Liberty profile, there are no additional options (Figure 4).
Figure 4. Specify target environment
Migrating to WebSphere Application Server Full profile only
When migrating to the WebSphere Full profile, you have the option to select the default scope for your resources:
- Default option: Single server environment
By default these options are Cell, Node and Server (Figure 5).
Figure 5. Specify target environment
- Advanced option: Clustered environment
If you have a more complex environment and want to specify resources at specific scopes, such as at the cluster level, you can select the advanced option. You can then provide the location of the Deployment Manager cell.xml file, and the tool will determine the available scopes in that environment:
<DMGR Profile Home>\config\cells\<cellName>\cell.xml
Proper assignment of the resource scope will ultimately save you time and cost in maintaining those resources after they have been created. If you are not sure, then generally speaking you will want to assign at the cluster scope. In this case, all applications within the same cluster will have access to those resources. This makes it easier to support dynamic provisioning of cluster members and their Java EE resources.
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 Related topics)
- 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.
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 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 6. Cell setting for default scope
Once you have selected your options, click Next. The plugin will scan the configuration files from the source environment you specified in Figures 3 through 5, and then list the Java EE resources that it finds from those source environments. It shows those Java EE resources that need to be migrated in a tree view on the Review Resources Found page (Figure 7). This figure will also show you the resource as well as the scope that it is assigned.
Figure 7. Review Resources Found
You will notice that there is a checkbox beside each resource. You can select the resources that you want to migrate to the target environment. The tool will find all Java EE resources that were defined in your source environment. We have discovered that many times there are Java EE resources that are no longer used in the source environment. This is a good time to go through the Java EE resources that were discovered by the tool to make sure they all apply so you can avoid defining unnecessary resources in your target environment. 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 simply have those unnecessary resources created in the target environment also.
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 Configuration Migration Toolkit 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; this has the functionality to encrypt the password within the server.xml. For WebSphere Application Server Full profile the password will be in clear text, but it will be encrypted once the script has been executed.
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. This option will only appear if you select the WebSphere Application Server Full Profile as the target environment.
Figure 8. Assign resources to scope
Once you have made the necessary changes to your resources, click Next.
Preview and Save your configuration files
On the next page you will be able to view the resulting server.xml for Liberty profile, or Jython script for WebSphere Full profile. Here you can copy and paste the file contexts or save the file to your file system.
Figure 9. Liberty profile preview page
Figure 10. WebSphere Full profile Jython script
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. 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.
Figure 11. WebSphere Full profile Jython script
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.
WASX7017E: Exception received while running file "C:\jython.py";
exception information: com.ibm.websphere.management.exception.ConfigServiceException:
ADMG0032E: An existing JAASAuthData entry matches alias <Alias>, so a JAASAuthData entry cannot be created for user ID <userID>.
Note: The server must be running in order to execute the wsadmin command.
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.
If you need any additional assistance with the tool or its usage then you can also post questions to the WebSphere Configuration Migration Forum. It is moderated by the developers of the tool. (See Related topics)
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 a path for moving resources between the Liberty profile and the WebSphere Application Server Full profile. You might want to do this in cases where you use Liberty profile on the desktop and Full profile for system test and production.
At present, this tool also supports the migration of Java EE resources from WebLogic and JBoss to the Liberty or Full profile servers. We are investigating extending the tool to migrate Java EE resources from 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. The tools does not create the target standalone servers or the clustered topologies in which the applications are deployed. Instead, the developers create the target standalone server, or the administrators set up the target topology, and once that is done they use this tool to create all of the Java EE resources required for these applications to run in those standalone servers or clustered topologies
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
- WebSphere Configuration Migration Toolkit