Comment lines by Donald Vines & Andy Hoyt: How the Application Migration tool makes it easy to move to WebSphere Application Server

The IBM® WebSphere® Application Server Migration Toolkit contains an Application Migration tool that you can use to easily move applications from a source application server to IBM WebSphere Application Server V7.0. This article introduces the capabilities of this new tool and provides resources to help you start using it. This content is part of the IBM WebSphere Developer Technical Journal.


Donald Vines (, Executive IT Architect, IBM

Author photoDonald Vines is currently an Executive IT Architect at IBM responsible for the WebSphere migration practice within North America.

developerWorks Contributing author

Andy Hoyt, WebSphere Development Manager, IBM

Author photoAndy Hoyt is currently a Development Manager at IBM responsible for the Application Migration Tool for WebSphere.

27 January 2010

Also available in Chinese Russian Japanese

Application analysis and migration made easy

The Application Migration tool in the IBM WebSphere Application Server Migration Toolkit helps you easily move applications from a source application server to WebSphere Application Server V7.0. Source application servers currently supported include WebLogic Server 8.1 and WebLogic Server 9.2. The Application Migration plug-in works on an imported EAR file. The tool scans the JSPs, Java™ source code, and deployment descriptors for porting issues and reports these issues in the Problems view in your Eclipse IDE. Most of the porting issues that you could encounter will be identified by the tool and, in many cases, the tool will offer a quick fix to resolve them.

In case you’re not familiar with it, here is a look at the capabilities of the Application Migration tool, along with some pointers to the download and other material to get you started.

What the tool is

The Application Migration tool is the result of an effort to enable IBM Rational® Software Analyzer V7.1 to assist in migrating applications from a supported source application server to WebSphere Application Server. Rational Software Analyzer is a simple and powerful tool for automating software analysis and delivering better quality software. To do its job, Rational Software Analyzer uses a vast set of rules, plus it enables the creation custom of rules to suit specific environments and purposes.

To that end, custom rules for discovering code migration problems were created and provide the tool with quick fixes for resolving many of these issues. All of these custom rules are bundled in an Eclipse 3.4.2 plug-in that you can download at no cost (and no additional licenses).

The plug-in works on an imported EAR file. It parses the Java source code, JSPs, and deployment descriptors in the Eclipse workspace and reports migration issues in the Problems view. Because the tool works on the source and not the class files, you do not need to get a clean compile of the application under WebSphere Application Server before running the tool.

When the analysis is complete, right-clicking on an individual result in the Problems view provides you with options for addressing problems:

  • View Result opens an editor that shows the source file that triggered the rule. The line where that problem occurred is highlighted and a rule violation icon is shown beside that line.
  • Quick Fix will perform the migration that will modify the affected Java code, JSP page, or deployment descriptor. The quick fix might change the file directly or it might present the steps necessary to fix it.
  • Quick Fix Preview enables you to compare the original code with the proposed changed code side-by-side before any updates are actually made.
  • Ignore Result will remove the rule from the list without making a file change.
  • Quick Fix All resolves all issues for a given rule.

You have complete control over whether to accept a quick fix or enter your own. There is also an option for you to accept all changes if you prefer not to go through them one-by-one. When you have completed reviewing the changes, you can then export the EAR file from Eclipse and deploy it to WebSphere Application Server.

This plug-in is a knowledge-based migration assistant. This means that developers without extensive knowledge of the source application server or of WebSphere Application Server should still be able to perform a successful migration.

How the tool works

If the application to be migrated isn’t already in Eclipse then you must import the EAR file into Eclipse prior to performing the migration. If the Java source files and the JSP source files are not available in the EAR, then the tool will only run the rules to migrate the deployment descriptor files. If the source files are available in the EAR file then the tool will run the rules to migrate the:

  • Java source files
  • JSP source files
  • Deployment descriptor files
  • Class path review

The plug-in includes a parser for Java source files, JSP source files, and deployment descriptor files, plus a set of rules that detect the use of proprietary classes, APIs, constants, and any differences in product conformance to the Java EE specification. These rules have been effective in finding the major sources of portability problems in these files.

The next sections list some of the rules and quick fixes for the file types listed above. See Resources for complete details.

Java source files

The plug-in detects Java source files based on the .java extension. This includes servlets, EJB components, and Java classes. The tool parses all of the Java files in the workspace, applies the rules to find any portability issues, and displays the issues with their quick fix.

Table 1. Java source files
RuleQuick fix
Do not use WebLogic RMI API calls.
Detects the references to WebLogic proprietary RMI classes and APIs.
Changes the code to use the Java standard RMI classes and APIs.
Do not use WebLogic specific JNDI names.
Scans Java files detecting the usage of WebLogic proprietary JNDI name values:
  • java.naming.factory.initial = weblogic.jndi.WLInitialContextFactory
  • java.naming.provider.url = t3://localhost:7001
Changes the code to use WebSphere Application Server JNDI names, or to use the portable JNDI lookup:
  • java.naming.factory.initial =
  • java.naming.provider.url = corbaloc:iiop:localhost:2809
Do not use WebLogic proprietary startup or shutdown classes.
Looks for classes that implement WebLogic startup and shutdown interfaces.
Converts these classes to use the standard javax.servlet.ServletContextListener interface and registers it in the application's web.xml file.
Do not use non-compliant UserTransaction lookup name.
Finds references to ctx.lookup(“javax.transaction.UserTransaction”) in BMT beans and servlets. (WebLogic permits this non-compliant lookup, WebSphere Application Server does not.)
If the problem occurs in a BMT bean, then the quick fix converts the bean to use ctx.getUserTransaction(). If the problem occurs in a servlet or client code, then the quick fix converts it to use JNDI lookup: ctx.lookup(“java:comp/UserTransaction”)
Do not use mismatching throws clauses.
Finds mismatches between throws clause in the EJB bean’s methods, and the home and remote interfaces. (WebLogic permits this non-compliant mismatch, WebSphere Application Server does not.)
Adds any missing exceptions and remove any extra exceptions to the EJB bean. The home and remote interfaces are not changed.
Do not use WebLogic proprietary Apache packages.
Flags references to proprietary WebLogic Apache classes and APIs that can map to the open source Apache classes and APIs.
Changes the code to use the open source Apache classes and APIs. You will need to download the appropriate Apache Xerces .jar file and include it with your application.

JSP source files

The plug-in detects JSP source files with the .jsp extension, parses all of these files in the workspace, and applies the rules to find portability problems and to offer quick fixes. Be aware that JSP source files can invoke non-portable classes, APIs, and constants, just as Java source files can. The plug-in detects these portability issues and handles them in the same manner described earlier.

Table 2. JSP source files
RuleQuick fix
Avoid using a .jsp extension for JSP fragments.
Finds JSP fragments. Fragment files with a .jsp extension rather than .jspf are flagged. According to the Java EE specification, all JSPs must compile; JSP fragments do not.
Changes the file name and all of its references using the refactor dialog.
Use correct case for tag/attribute names.
Flags any tag/attribute name in the JSP that is not case correct. According to the XML specification, tag/attribute names are case sensitive; WebSphere Application Server enforces this, WebLogic does not.
Changes the case in the affected JSP source files to match the case as defined in the tag library.

Deployment descriptor files

The plug-in detects vendor-specific deployment descriptor files by their file name (for example, weblogic.xml, weblogic-ebj-jar.xml, weblogic-webservices.xml, and so on). As with the other files, the plug-in parses the deployment descriptors, applies the rules to find porting issues, and offers quick fixes.

Table 3. Deployment descriptor files
RuleQuick fix
Use standard deployment descriptors for EJB references.
The WebLogic deployment descriptor (weblogic.xml) can contain EJB references to map session beans to their JNDI name.
Moves all EJB references defined in the weblogic.xml file to the standard web.xml deployment descriptor.
Use standard deployment descriptors for resource reference names.
The WebLogic-specific deployment descriptors (weblogic.xml) can contain resource references to map data sources to their JNDI names.
Moves all resource references defined in WebLogic-specific deployment descriptors to standard deployment descriptors.
Do not use WebLogic Web services deployment descriptor.
Looks for the Web services deployment descriptor, specifically looks for the presence of either:
  • web-services.xml
  • weblogic-webservices.xml and the Java EE deployment descriptor (webservices.xml) in the same folder.
Generates an ANT script that uses WebSphere Application Server ANT tasks to generate the appropriate artifacts for the Web services, based on information collected from the deployment descriptors. The fix also generates the Service Endpoint Interface (SEI), if required for the service, and adds it to the project classpath. You can then run the ANT script to migrate the Web service.

Class path review

The class path review verifies that the class path is set up properly.

Table 4. Class path review
RuleQuick fix
Use MANIFEST.MF for application class path.
Looks for classes and libraries in the APP-INF folder of the EAR file. This WebLogic extension to the EAR file implicitly adds those classes and libraries to the class path.
Adds an entry to the class path of each affected module by updating the class path entry of the module's MANIFEST.MF file. This is the industry standard way to add classes and libraries to the class path.

Using the tool

Detailed steps on using the Application Migration tool is beyond the scope of this article, but to get you started, Figure 1 shows some key features of the tool, followed by Resources that should provide all the details you need. The figure shows a screen capture of the Application Migration tool while migrating a WebLogic Startup class to WebSphere Application Server. In the figure:

  • The Java Source Compare panel shows an example of the quick fix review feature. The left half of that panel shows the code if the quick fix were applied and the right half shows the original code without applying the fix.
  • The Help tab in the right column explains the rule and the quick fix to be applied.
  • The Java Source Compare panel shows the available options you can select to migrate the code. The options include:
    • View the scanned file.
    • Change the file with the quick fix.
    • Preview the quick fix with quick fix review.
    • Ignore the result.
    • Fix all occurrences of that rule.
Figure 1. Application Migration tool analysis results
Figure 1. Application Migration tool analysis results

If you are working on migrating applications to WebSphere Application Server, of if there is application migration in your future, download and try the Application Migration Tool. A Getting Started guide is available (see Resources) to help you out, and a forum is available to share your stories and collect your feedback.



Get products and technologies



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

ArticleTitle=Comment lines by Donald Vines & Andy Hoyt: How the Application Migration tool makes it easy to move to WebSphere Application Server