Making the move to the Liberty profile, Part 2: Migrating Java EE resources with the Configuration 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.

Share:

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 with IBM Software Services for WebSphere (ISSW) 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.



19 February 2015 (First published 23 April 2014)

Also available in Chinese Russian Portuguese

Introduction

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 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 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 Resources 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 resourcesJBoss to LibertyWebLogic to LibertyWebSphere V7+ Full to LibertyJBoss to WebSphere Full profileWebLogic to WebSphere Full profileWebSphere V7+ Full to WebSphere V8.5 Full
JDBC providersYesYesYesYesYesYes
Data sourcesYes1Yes1Yes1Yes2Yes2Yes2
JMS providerN/AN/AN/AYesYesYes
Foreign JMS providerN/AN/AN/ANoYesNo
JMS destinationN/AN/AN/ANoYesYes
JMS topicYesYesYesYesYesYes
JMS queueYesYesYesYesYesYes
Activation specificationYesYesYesYesYesYes
Queue activation specificationYesYesYesYesYesYes
Topic activation specificationYesYesYesYesYesYes
JMS connection factoryYesYesYesYesYesYes
JMS topic connection factoryYesYesYesYesYesYes
JMS queue connection factoryYesYesYesYesYesYes
Mail sessionNoNoNoNoYesNo
Mail providerNoNoNoNoYesNo
JCA authentication aliasYesYesYesYesYesYes
Service Integration Bus3YesYesYesYesYesYes
Configures global security and an LDAP user registry YesYesYesYesYesNo

Notes:

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
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
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:

  1. 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.
  2. 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
    or
  • Migration Tools > WebSphere Application Server Migration > Configuration Migration > WebSphere Configuration Migration Toolkit for JBoss
    or
  • Migration Tools > WebSphere Application Server Migration > Configuration Migration > WebSphere Configuration Migration Toolkit for WebSphere

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 Configuration Migration Toolkit to search for resources in WebLogic.

Figure 3. Configuration Migration Toolkit overview
Configuration Migration Toolkit overview

Click to see larger image

Figure 3. Configuration Migration Toolkit overview

Configuration Migration Toolkit overview

JBoss

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
Specify target environment

Click to see larger image

Figure 4. Specify target environment

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
    Specify target environment

    Click to see larger image

    Figure 5. Specify target environment

    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 Resources)

    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.

    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
    Cell setting for default scope

    Click to see larger image

    Figure 6. Cell setting for default scope

    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
Review Resources Found

Click to see larger image

Figure 7. Review Resources Found

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
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
Liberty profile preview page

Click to see larger image

Figure 9. Liberty profile preview page

Liberty profile preview page
Figure 10. WebSphere Full profile Jython script
WebSphere Full profile Jython script

Click to see larger image

Figure 10. WebSphere Full profile Jython script

WebSphere Full profile Jython script

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. 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 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 <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 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 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.


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 Configuration Migration Toolkit
publish-date=02192015