application migration tool - public.dhe.ibm.com · • migrating weblogic java, jsp, and class path...

WebSphere Application Server

Application Migration ToolBuilt on Rational Software Analyzer technology

Version 1.2.0July 27, 2010

A combined effort:

IBM Software Group, Application and Integration Middleware SoftwareIBM Software Group, Rational Software

© Copyright IBM Corp. 2009, 2010

2 | Application Migration Tool | Contents

Contents

Overview................................................................................................................................ 3New for this release...............................................................................................................4

Version 1.2............................................................................................................................................... 4Version 1.1............................................................................................................................................... 4

Support...................................................................................................................................7Installing and updating the migration tool.........................................................................8Importing applications....................................................................................................... 11

Shared Java Projects...............................................................................................................................11EAR-Level Library.................................................................................................................... 11WAR-Level Library................................................................................................................... 13

Configuring a Java EE Runtime Library................................................................................................14Configuring the tool for analysis....................................................................................... 17Running analysis................................................................................................................. 22Completing the Process...................................................................................................... 25WebLogic to WebSphere Application Server rules and quick fixes.............................. 26

WebLogic Java code review rules..........................................................................................................26WebLogic JSP code review rules...........................................................................................................30WebLogic XML file review rules.......................................................................................................... 30WebLogic class path review rules..........................................................................................................33

JBoss to WebSphere Application Server rules and quick fixes......................................34JBoss Java code review rules................................................................................................................. 34JBoss XML file review rules..................................................................................................................35JBoss class path review rules................................................................................................................. 36

Troubleshooting.................................................................................................................. 37Software Analyzer options not shown................................................................................................... 37Java EE constructs or JSP not read correctly......................................................................................... 37Logging and trace...................................................................................................................................37Reports and history.................................................................................................................................38Markers...................................................................................................................................................38Known issues..........................................................................................................................................38

Copyright and trademarks.................................................................................................40

Application Migration Tool | Overview | 3

Overview

Converting Java™ Platform, Enterprise Edition (Java EE) applications from one third-party application server to anotherplatform can be costly and time consuming. The conversion process can involve modifying Java source code, JavaServer™

Pages (JSP), and deployment descriptors. The Application Migration Tool can assist you in performing these types ofmigrations.

The Application Migration Tool is part of the IBM® WebSphere® Application Server Migration Toolkit. This toolkit is partof the overall strategy and plan for assisting customers in migrating from one application server to the IBM WebSphereApplication Server.

This document explains how to install, configure, and use the tooling to assist in the conversion process. The toolingis based on IBM Rational® Software Analyzer, which provides a single solution to identify, analyze, and optimize theapplication health. The migration tool uses the scanning capabilities of Rational Software Analyzer to look for specificconstructs unique to the Oracle® WebLogic application server. The tool then provides a way to review and change that dataso that the application can run on IBM WebSphere Application Server.

The tool flags a number of known differences between applications hosted on Oracle WebLogic or JBoss and WebSphereApplication Server. In many cases, the tool can automatically convert these key differences. If the tool is unable to performthe fix, it flags the file in question to provide insight to where design changes are needed. The migration tool supports:

• Migrating applications to WebSphere Application Server Version 7• Migrating WebLogic Java, JSP, and class path artifacts (Java EE 5 and prior versions)• Migrating WebLogic deployment descriptors (Java EE 5 and prior versions)• Migration JBoss Java and class path artifacts (Java EE 5 and prior versions)• Migrating JBoss deployment descriptors (Java EE 5 and prior versions)

4 | Application Migration Tool | New for this release

New for this release

Version 1.2

Application Migration Tool version 1.2 adds support to existing rules and quickfixes for Java EE 5, and it providesadditional rules for JBoss migration.

New JBoss rules and quick fixes:

• Use WebSphere extensions to define CMP mappings• Use WebSphere bindings to define message-driven bean JNDI names

Rules with Java EE 5 support:

• Do not use local JNDI names• Use WebSphere bindings to define EJB JNDI names• Use WebSphere bindings to define EJB reference names• Use WebSphere bindings to define resource reference names• Use WebSphere extensions to define concurrency strategy• Use WebSphere extensions to define transaction timeout seconds• Use WebSphere extensions to define Web module context root• Use WebSphere bindings to define message-driven bean JNDI names

The tool is translated into the following additional languages:

• German (de)• Spanish (es)• French (fr)• Japanese (ja)• Korean (ko)• Brazilian Portuguese (pt_BR)• Simplified Chinese (zh_CN)

Version 1.1

Application Migration Tool version 1.1 adds new rules and quick fixes for WebLogic deployment descriptor migration(J2EE 1.4), additional rules for WebLogic Java code (including Java EE 5, EJB 3, and JPA), and JBoss support.

Also new in this release is the Quick Fix All Category results menu option. Quick Fix All Category has a larger scopethan Quick Fix All and allows you to run all quick fixes for the selected rule provider with one click.

When quick fixes are applied for deployment descriptor rules, the line in the WebLogic or JBoss deployment descriptoris commented with a  comment. This comment prevents therule from triggering again and allows you to review your WebLogic and JBoss deployment descriptors to verify that allinformation was migrated.

WebLogic Java rules and quick fixes:

• Do not use Commons Logging system level property1

• Do not use invalid JPA imports3

Application Migration Tool | New for this release | 5

• Do not use kodo properties that have no openJPA equivalent1

• Use OpenJPA property names instead of Kodo-specific property names when equivalent1

• Do not use non portable JPA imports1

• Do not use subclass of EntityManager or EntityManagerFactory for injected JPA elements1

• Do not use WebLogic log4j logging objects3

• Do not use WebLogic LoggingHelper object to get Logger instance1

• Do not use WebLogic logging objects1

• Do not use WebLogic NonCatalogLogger object1

• Do not use WebLogic servlet attributes for XML parsing1

• Do not use WebLogic-specific JDBC properties or extensions3

• Do not use WebLogic-specific JNDI environment properties for initial context1

• Do not use WebLogic StAX objects3

• Do not use WebLogic TransactionManager object3

• Do not use WebLogic Transaction object3

• Do not use WebLogic TransactionSynchronizationRegistry object3

• Do not use WebLogic RollbackException object3

• Do not use WebLogic WLLevel object1

• Do not use WebLogic XPath objects3

• Use OpenJPA property names instead of Kodo-specific property names when equivalent1

• Use unitName attribute for injected JPA elements1

WebLogic XML rules and quick fixes:

• Do not use local JNDI names2

• Do not use WebLogic servlet filter for XML parsing1

• Do not use WebLogic-specific EJB Query Language constructs3

• Use WebSphere bindings to define EJB JNDI names2

• Use WebSphere bindings to define EJB reference names2

• Use WebSphere bindings to define message-driven bean JNDI names2

• Use WebSphere bindings to define resource reference names2

• Use WebSphere extensions to define CMP mappings1

• Use WebSphere extensions to define concurrency strategy2

• Use WebSphere extensions to define transaction timeout seconds2

• Use WebSphere extensions to define Web module context root1

• Do not use kodo PersistenceServerServlet in web.xml1

• Do not use kodo properties that have no openJPA equivalent1

• Do not use kodo-specific values for kodo properties and use openJPA equivalent values1

• Use openJPA properties instead of kodo properties when equivalent1

JBoss Java rules and quick fixes:

• Do not use JBoss-specific JNDI name values1

• Do not use JBoss-specific packages3

• Do not use MBeans for JBoss application startup or shutdown logic1

• Use portable JNDI names3

JBoss XML rules and quick fixes:

• Do not use local JNDI names1

• Manually migrate resource references for URLs and resource managers3

• Use WebSphere bindings to define EJB JNDI names1

• Use WebSphere bindings to define EJB reference names1

• Use WebSphere bindings to define resource reference names1

• Use WebSphere extensions to define Web module context root1

• Do not use jboss.xml file3

• Do not use jboss-app.xml file3

• Do not use jboss-client.xml file3

• Do not use jbosscmp-jdbc.xml file3

• Do not use jboss-web.xml file3

• Do not use JBoss Web services deployment descriptor1

JBoss class path rules and quick fixes:

• Use MANIFEST.MF for application class path1

1 This is a new rule with a quick fix that is added in release 1.1.2 This is a new quick fix that is added in release 1.1 to an existing rule.3 This is a new rule that is added in release 1.1 without a quick fix.

Application Migration Tool | Support | 7

Support

The Application Migration Tool scans for a number of known issues in applications being migrated from WebLogic orJBoss to WebSphere Application Server. Where possible, a quick fix is provided to change your code to a more portablesolution. Supported WebLogic rules and quick fixes are documented in WebLogic to WebSphere Application Server rulesand quick fixes on page 26. Supported JBoss rules and quick fixes are documented in JBoss to WebSphere ApplicationServer rules and quick fixes on page 34. The tool will be updated on developerWorks as new rules and quick fixes areavailable.

You can use the quick fix preview support in the migration tool to decide if you want to accept the suggested code change.Also, view the help information provided with the rules to decide if you want to run the quick fix. Always make a backupcopy of your source code before starting a migration.

During the scanning process, the tool detects areas that require design changes and code rewrites. The tool highlights theseproblem areas but does not provide a quick fix.

The tool does not catch all problems. As you encounter patterns that the tool does not flag, we want to hear your feedback.The Application Migration Tool forum is available to provide input and get questions answered. (http://www.ibm.com/developerworks/forums/forum.jspa?forumID=2106).

If you have access to IBM Passport Advantage, you can open a customer defect. Other users can use the forum to reportissues or suggestions and ask questions.

For more information on the Rational Software Analyzer product, go to http://www.ibm.com/developerworks/rational/products/rsar/.

http://www.ibm.com/developerworks/forums/forum.jspa?forumID=2106

http://www.ibm.com/developerworks/forums/forum.jspa?forumID=2106

http://www.ibm.com/developerworks/rational/products/rsar/

http://www.ibm.com/developerworks/rational/products/rsar/

8 | Application Migration Tool | Installing and updating the migration tool

Installing and updating the migration tool

The Application Migration Tool is a plug-in that you install into an existing Eclipse or Rational Application Developerenvironment. The tool is supported on Eclipse version 3.4.2 or higher and Rational Application Developer version 7.5 andhigher. The preferred environments are Rational Application Developer and Rational Application Developer for Assemblyand Deploy since they provide all the tools for application development and deployment. However, the tool works with abasic Eclipse IDE. If an Eclipse IDE is not already installed, then download and install Eclipse 3.4.2 or higher from http://www.eclipse.org.

To install or update the Application Migration Tool, perform the following steps:

1. Download the latest version of the migration tool from developerWorks site http://www.ibm.com/developerworks/websphere/downloads/migration_toolkit.html and save it locally.

2. Start the IDE.3. If this is not a Rational Application Developer environment, install the prerequisite plug-ins from either the Galileo

or Ganymede site depending on your Eclipse version. Rational Application Developer is configured with the requiredplug-ins. Use the appropriate example, depending on your version of Eclipse:

For Eclipse 3.5 and higher For Eclipse 3.4 (3.4.2 and higher)

From the Eclipse menu bar, select Help > InstallNew Software

Using the Galileo update site (http://download.eclipse.org/releases/galileo) onEclipse 3.5 or the Helios update site (http://download.eclipse.org/releases/helios) on Eclipse 3.6install Business Intelligence, Reporting and Chartingand Web, XML, and Java EE Development.

From the Eclipse menu bar, select Help > Softwareupdates

Using the Ganymede update site (http://download.eclipse.org/releases/ganymede), installCharting and Reporting and Web and Java EEDevelopment.

Figure 1: Eclipse plug-in installation4. Use the previous installation dialog to install or update the Application Migration Toolkit. Click Add in Eclipse 3.5 or

click Add Site in Eclipse 3.4. (Rational Application Developer is built on Eclipse 3.4.)5. In the Add Site window, enter the following information: (Figure 2: Tool installation on page 9).

http://www.eclipse.org

http://www.eclipse.org

http://www.ibm.com/developerworks/websphere/downloads/migration_toolkit.html

http://www.ibm.com/developerworks/websphere/downloads/migration_toolkit.html

http://download.eclipse.org/releases/galileo

http://download.eclipse.org/releases/galileo

http://download.eclipse.org/releases/helios

http://download.eclipse.org/releases/helios

http://download.eclipse.org/releases/ganymede

http://download.eclipse.org/releases/ganymede

Application Migration Tool | Installing and updating the migration tool | 9

• Name: Application Migration Tool• Location: Use the Archive button to find the compressed file you downloaded.

Figure 2: Tool installation6. Click OK

7. Complete the following actions in the Install window: (Figure 3: Select Plug-In on page 10).

a) Select the check box for Application Migration Tool.b) Select the check box to Contact all update sites during install to find required software and click Next.

8. Click Next on the Install Details panel.

9. On the Review Licenses panel, read the terms and accept the license agreements, if any are presented. Click Finish.The install status window shows the installation progress.

Figure 3: Select Plug-In10. Restart the IDE when the Software Updates window is displayed.

Figure 4: Restart dialog

Application Migration Tool | Importing applications | 11

Importing applications

If the application to migrate is not already in the IDE, you must import the application enterprise archive (EAR) file ormodules with source code into the IDE before performing analysis. The preferred approach for doing this is to create newprojects in the workspace for each EAR, Web archive (WAR), and Enterprise JavaBeans™ (EJB) module. The EAR fileshould be created as an enterprise application project. Each WAR file within the EAR file should be created as a dynamicWeb project, and each EJB module should be created as an EJB project. You must install Java EE Developer Tools forEclipse to create these projects.

Review the following guidelines for structuring projects:

• Java source code for a WAR file (for example, servlet, model, or utility classes), belong in the src folder of theproject. The src folder is defined and can be changed in the Java Build Path properties for the project. If the Javasource code needs to be referenced by more than one WAR, see the Shared Java Projects section of this document.

• Java source code for an EJB module can be placed in the ejbModule folder of the EJB project.• Precompiled Java archive (JAR) libraries for a WAR file belong in the WebContent/WEB-INF/lib folder.• EAR-level JAR libraries can be placed in the EarContent folder of the enterprise application project. If your project

contains an APP-INF/lib folder, it can be placed in the EarContent folder; however, you must run the class pathrule and its quick fix to update the class paths correctly

Shared Java Projects

There are two options for referencing those Java classes from a Web project:

1. Create a single copy of the Java project's JAR file in the EAR file. Each WAR file references the JAR file. Thisapproach is preferable, since it reduces the size of the EAR file.

2. Create a copy of the JAR file in each WAR file. This approach works well if only one WAR file references the JARfile.

EAR-Level Library

Complete the following steps to place Java source files in a separate project:

1. Create a new Java project and add the Java source into the project's src folder.

2. Go to the Properties dialog of the EAR project (right-click the project in the Project view and select Properties). Selectthe Java EE Module Dependencies item from the left pane, and on the right pane select the check box next to the Javaprojects you want to reference.

12 | Application Migration Tool | Importing applications

Figure 5: Java EE EAR module dependencies3. Open the Properties dialog for each Web project that needs to reference a JAR file. Select the Java EE Module

Dependencies item from the left pane, and ensure that the J2EE Modules tab is selected. Select the check box besidethe JAR files to reference.


Figure 6: Java EE module dependencies

WAR-Level Library

For the second approach, which creates a copy of the JAR file in each WAR file, complete the following steps:

1. Open the Properties dialog of the Web project. Right-click on the project in the Project view and select Properties.Select the Java EE Module Dependencies item from the left pane, and then click on the Web Libraries tab in theright pane. The table contains every Java project available.

14 | Application Migration Tool | Importing applications

Figure 7: Web Libraries Module Dependencies2. Select the check box beside the project to add it to the WAR file.

Configuring a Java EE Runtime Library

When using Eclipse with the Java EE tooling installed, the Java compiler is not able to resolve references to the Java EEAPIs unless a target runtime environment is configured.

Follow these steps to configure the Java EE Runtime Library:

1. Open the Eclipse preferences by choosing Preferences under the Eclipse Window menu.

2. Navigate to the Server > Runtime Environments item on the left pane.


Figure 8: Server Runtime Environments3. Click Add and choose Basic > J2EE Runtime Library.

4. On the next wizard page, click Browse to choose the library location, and locate the dev/JavaEE folder of yourWebSphere Application Server installation and select the appropriate Java EE version. That folder contains thej2ee.jar file with the Java EE APIs.

To use this runtime library in a Web or EJB project, go to the project properties dialog. Right-click on the project in theProject view and select Properties, and choose the Targeted Runtimes item.

Figure 9: Targeted Runtimes

Under the runtime listing, select the check box next to the recently configured Java EE runtime library, and click OK.

Application Migration Tool | Configuring the tool for analysis | 17

Configuring the tool for analysis

You can configure the tool to define a set of rules to run and define the scope of analysis within the workspace. The scopecan be a project, a working set, or the entire workspace. Once defined, you can save the analysis configuration to use ormodify later. With the migration tool installed, you have new analysis options to configure and run an analysis. You canaccess the options in the Eclipse Run menu, in the Launch toolbar, and in the explorer context menus. The followingfigure demonstrates the different ways you can run the analysis using the Application Migration Tool.

From the Launch Eclipse toolbar:

From the Eclipse menu:

From the explorer context menu:

Figure 10: Options for running the tool

If you do not see Software Analyzer options, see Software Analyzer options not shown on page 37.

To configure the analysis using the toolbar, complete the following steps:

1. On the toolbar, select Software Analyzer ( ) > Software Analyzer Configurations to display the mainconfiguration dialog.

You can add or remove analysis configurations by using the icons in the dialog.

18 | Application Migration Tool | Configuring the tool for analysis

Figure 11: Configuration dialog2. In the configurations list, select Software Analyzer then click New . The right side of the dialog changes to show

the basic configuration interface.


Figure 12: Configuration Setup3. In the Software Analyzer Configuration dialog, enter a name for the configuration, such as “AppMigration” as shown

in Figure 12: Configuration Setup on page 19.

4. On the Scope tab, select Analyze entire workspace to scan all projects in the workspace.

You can limit the scope of an analysis by using the other options on this dialog to analyze a working set or a selectionof projects.

Tip: When you use the explorer context menu to run your analysis, the scope of the analysis is limited to the node inthe project where the context menu was selected. This allows you to perform a quick analysis on a limited set of code.

5. On the Rules tab, select the type of analysis to perform (see Figure 13: Rule selection on page 20).

There are two migration related rule sets, WebLogic Application Migration and JBoss Application Migration.

To automatically select all of the rules from one of these rule sets, select it from the list and click Set.

The migration tool has rules under the following analysis providers:

• Class-Path Review• Java Code Review• JSP Code Review• XML File Review

The Rules tab displays a directory tree, where you can select or clear analysis elements. This tab also includesadditional buttons for importing and exporting rule selections. The nodes at the beginning of the domain tree areanalysis providers, which represent the types of analysis tools that are recognized by the analysis framework. Providerscontain categories which organize the rules.

20 | Application Migration Tool | Configuring the tool for analysis

See Figure 13: Rule selection on page 20 for an example of selected rules

Tip: To obtain additional information about a rule, highlight the rule and press F1. Help for the rule is shown in theconfiguration dialog. The initial help page includes a short description and a link to more information.

Note: The number of rules in the analysis configuration dialog varies depending on the platform on which the tool isinstalled. Analysis rules are available in several Rational products such as Rational Application Developer; therefore,the included rule sets might be different.

Figure 13: Rule selection6. To save the rule configuration, click Apply.

Some rules have additional configuration options. When a rule with configuration options is selected, the rule propertiesare shown in the Properties tab under the list of rules. Figure 14: Rule Properties on page 21 shows the rule propertiesfor a Web services rule. If you do not update the properties, the rule uses the default values.


Figure 14: Rule Properties

22 | Application Migration Tool | Running analysis

Running analysis

Run the analysis and display the results.

1. To start the analysis, click Analyze on the Configuration dialog.

2. The results are displayed in the Software Analysis Results view (Figure 15: Java Code Review results view on page22).

Depending on which rules you are running, the results view might vary. The results generated by the migration tool aredisplayed in one of four tabs:

• Class-Path Review• Java Code Review• JSP Code Review• XML File Review

Some results views, such as Java Code Review, support viewing results in more than one format. For example, results canbe viewed in a table or a tree format.

Figure 15: Java Code Review results view

If no results are shown in the panel, no issues were identified while scanning.

Right-clicking on individual results gives access to options such as viewing the source code where the problem occurred orcorrecting the problem with a provided fix.

Application Migration Tool | Running analysis | 23

Figure 16: Result options with Quick Fix Preview and Help

Not all rules have all actions available, but the possible actions include:

• View Result - Opens an editor showing the source file that triggered the rule. The cause ofthe problem is highlighted and a rule violation icon is shown in the left margin of the editor.

•Quick Fix - The light bulb overlay on the result list icon ( ) indicates this rule has a quick fix. Selecting thisoption runs the conversion that modifies the affected Java code, XML file, JSP or manifest file, allowing it to run inWebSphere Application Server. The quick fix might change the code directly or it might present the steps needed tocomplete the fix.

• Quick Fix Preview - This option is available for the rules that support showing a side-by-side comparison of theoriginal code and the code after the quick fix is applied. This option allows you to see the changes before they aremade. Figure 15: Java Code Review results view on page 22 shows an example of the quick fix preview. Somequick fixes modify more than one file. When you select Quick Fix Preview for a fix affecting multiple files, the filesare shown in the Structure Compare portion of the Compare view. Double-click each file to view the differences. Forexample, Figure 17: Quick Fix Preview with multiple files on page 24 shows the changes that will be made to aweb.xml file.

Figure 17: Quick Fix Preview with multiple files• Ignore Result - This option removes the rule from the list without making a code change. For Java files, a comment

annotation is added to the file so that the rule is not triggered on future analysis runs.• Quick Fix All - This option resolves all issues identified for a given rule.• Quick Fix All Category - This option runs all quick fixes identified for the provider type the rule belongs. A rule must

have Quick Fix All enabled in order for Quick Fix All Category to run its quick fix. For example, if you choose thisoption on a Java rule, the quick fixes for all Java rules that have the Quick Fix All option are run.

Context sensitive help is displayed in the Help view as you select each result. The first panel is a short description. ClickDetailed Help to get more information. Press F1 to open the Help view.

Application Migration Tool | Completing the Process | 25

Completing the Process

After correcting the issues highlighted by the migration tool by running quick fixes or by making manual code changes,there are a number of additional rules provided by the Rational Software Analyzer product that can help improve thequality of your code. These rules are not required for conversion. Figure 18: Other architectural and Java rules on page25 shows examples of the additional rules.

Figure 18: Other architectural and Java rules

Access these rules by creating a new analysis configuration or modifying an existing one. These rules are not automaticallyselected as part of the WebLogic Application Migration rule set.

When the selected rules run and necessary changes are made, the updated application must be exported and tested onWebSphere Application Server. If using Rational Application Developer, there are tools available to create deploymentsand test the application within the Rational Application Developer environment.

26 | Application Migration Tool | WebLogic to WebSphere Application Server rules and quick fixes

WebLogic to WebSphere Application Server rules andquick fixes

The Application Migration Tool evaluates Java code, JSP code, deployment descriptors, and Web services deploymentdescriptors as part of its analysis set. This section provides specific details on the rules and quick fixes that are provided.

WebSphere Application Server conversion rules are included in the following analysis domains:

Figure 19: Analysis domains

WebLogic Java code review rules

Under the Java Code Review set of rules, the WebLogic to WebSphere code migration category contains multiple rules.For more information, press F1 when viewing the rule in the configuration dialog or in the results viewer.

Rule Name QuickFix

Action Taken Release

Do not use CommonsLogging system level property

Yes This rule detects setting the commons logging implementationclass using the system property.

The quick fix removes the entry.

1.1

Do not use invalid JPAimports

No This rule detects the use of specific kodo import statements thatdo not have equivalent openJPA imports.

These references are flagged so you can evaluate their usageand migrate manually.

1.1

Do not use kodo propertiesthat have no openJPAequivalent

Yes This rule detects JPA properties that start with kodo.* in javafiles but have no equivalent openJPA values.

The quick fix removes these properties.

1.1

Use OpenJPA propertynames instead of Kodo-specific property names whenequivalent

Yes This rule detects the JPA properties with kodo specific values inJava files.

The quick fix changes these values to valid openJPA values.

1.1

Do not use non-portable JPAimports

Yes This rule detects WebLogic-specific kodo import statements.

The quick fix replaces them with openJPA equivalent importstatements.

1.1

Application Migration Tool | WebLogic to WebSphere Application Server rules and quick fixes | 27

Rule Name QuickFix


Do not use subclassof EntityManager orEntityManagerFactory forinjected JPA elements

Yes This rule detects injected JPA PersistenceContext orPeristenceUnit where the injectable type is a subclass ofEntityManager or EntityManagerFactory.

The quick fix changes the class to use the standard JPA object.

1.1

Do not use UserTransactioninterface from CMT beans

No This rule detects references toctx.lookup('javax.transaction.UserTransaction') within container managed transactionenterprise beans. References to the UserTransactionobject are not allowed from CMT beans.

These references are flagged so that you can remove this JavaEE violation.

1.0

Do not use WebLogic log4jlogging objects

No This rule detects the proprietary WebLogic log4j classes andflags them for manual migration.

1.1

Do not use WebLogicLoggingHelper object to getLogger instance

Yes This rule detects the LoggingHelper object usage.

The quick fix converts the class instance to Java Logger.

1.1

Do not use WebLogic loggingobjects

Yes This rule detects WebLogic logging objects.

The quick fix changes the code to use the Java objects.

1.1

Do not use WebLogicNonCatalogLogger object

Yes This rule detects the NonCatalogLogger usage.

The quick fix converts these objects to Java Logger object.In addition, it converts all the logging method calls to validlogging calls. The level is controlled by the user using ruleproperties.

1.1

Do not use WebLogic RMIAPI calls

Yes This rule detects the use of references to the proprietaryweblogic.rmi packages.

The quick fix changes weblogic.rmi to java.rmi to usethe Java-provided classes.

1.0

Do not use WebLogic servletattributes for XML parsing

Yes This rule detects the use of setAttribute andgetAttribute methods used with specific attributes to parseXML.

The quick fix removes the entries.

1.1

Do not use WebLogic-specificJDBC properties or extensions

No This rule detects the usage of several WebLogic JDBCproperties and extensions that must be manually migrated.

1.1

Do not use WebLogic-specificJNDI environment propertiesfor initial context

Yes This rule detects the usage of theweblogic.jndi.Environment class to set contextproperties.

The quick fix migrates the objects used in the Environmentreferences to a hash table used to initialize theInitialContext object.

1.1


Rule Name QuickFix


Do not use WebLogic-specificJNDI name values

Yes This rule detects the usage of following proprietary JNDI namevalues:

• java.naming.factory.initial = weblogic.jndi.WLInitialContextFactory

• java.naming.provider.url = t3://localhost:7001

If found, users are given the option to change the JNDI namesto default portable JNDI name values:

• java.naming.factory.initial =com.ibm.websphere.naming.WsnInitialContextFactory

• java.naming.provider.url =corbaloc:iiop:localhost:2809

Restriction: The JNDI name values must be in the sameJava source file where the context is initialized with thejavax.naming. InitialContext(Hashtable)constructor.

1.0

Do not use WebLogic startupor shutdown classes

Yes This rule looks for classes that implement the WebLogic startupand shutdown interfaces.

The quick fix converts these classes to use thejavax.servlet.ServletContextListener interfaceand registers it in the web.xml file of the application.

1.0

Do not use WebLogic StAXobjects

No This rule detects the use of WebLogic proprietary XMLStreaming (StAX) objects that must be migrated manually.

1.1

Do not use WebLogicTransactionManager object

No This rule detects the use of the TransactionManagerobject and flags it for manual migration.

1.1

Do not use WebLogicTransaction object

No This rule detects the use of the Transaction object and flagsit for manual migration.

1.1

Do not use WebLogicTransactionSynchronizationRegistryobject

No This rule detects the use of theTransactionSynchronizationRegistry object andflags it for manual migration.

1.1

Do not use WebLogicRollbackException object

No This rule detects the use of theweblogic.transaction.RollbackException objectand flags it for manual migration.

1.1

Do not use WebLogicWLLevel object

Yes This rule detects WLLevel object usage in a setLevel()method.

The quick fix converts the WLLevel to IBM WsLevel. Thelevel is controlled by the user using rule properties.

1.1

Do not use WebLogic XPathobjects

No This rule detects the use of WebLogic proprietary, XML XPathobjects and flags them for manual migration.

1.1


Rule Name QuickFix


Use compliantUserTransaction lookup name

Yes This rule looks for references toctx.lookup("javax.transaction.UserTransaction").

Within bean managed transaction (BMT)beans, the quick fix converts the flagged line toctx.getUserTransaction().

Within servlets, Web applications and client code,the flagged line is converted to the JNDI lookup:ctx.lookup("java:comp/UserTransaction")

1.0

Use matching throws clausein EJB bean class

Yes This rule looks for mismatches between the enterprise beanimplementation and the method definitions in the home andremote interfaces.

The quick fix adds any missing exceptions and removes anyadditional exceptions. The interfaces are not changed.

1.0

Use OpenJPA propertynames instead of Kodo-specific property names whenequivalent

Yes This rule detects the presence of known JPA properties with aname starting with kodo.* in Java files.

The quick fix renames these properties to openjpa.*.

1.1

Use portable JNDI names No This rule detects the usage of the constructor,javax.naming.InitialContext(Hashtable),specifying not to put any proprietary WebLogic JNDI namevalues into the hash table.

1.0

Use unitName attribute forInjected JPA Elements

Yes This rule detects injected JPA PersistenceContext orPersistenceUnit elements without unitName or nameattributes.

The quick fix adds the missing values to offer similar behaviorto WebLogic automated deployment.

1.1

Do not use non-mappingweblogic.apache packages

No This rule flags import and code references to classes where theclass package starts with weblogic.apache and the classdoes not map to an open source Apache class.

You must modify the code to use different classes. See the rulehelp for more information.

1.0

Do not use weblogic.apachepackages

Yes This rule flags import and code references to classes where theclass package starts with weblogic.apache and the classmaps directly to an org.apache class.

The quick fix changes the code to org.apache. Downloadthe appropriate Apache open source .jar file, and include it withyour application.

1.0

Do not use WebLogic-specificpackages

No This rule flags imported classes that begin with weblogic butnot including the weblogic.apache classes. The flaggedserver-specific APIs must be migrated.

1.0


WebLogic JSP code review rules

Under the JSP code review set, the JSP Conversions category has rules described in the following table. For moreinformation, press F1 when viewing the rule in the results viewer.

Rule Name QuickFix


Avoid using a .jsp extensionfor JSP fragments

Yes This rule looks for JSP fragments included in another JSP. Ifthe JSP fragment file has the .jsp extension rather than .jspfextension, it is flagged.

The quick fix takes you to the refactor dialog to change the filename and all of its references.

1.0

Use correct case for tagattribute names

Yes JSP taglib attributes are case-sensitive in WebSphereApplication Server. This rule flags any taglib attribute that isnot case correct.

The quick fix changes the case as it is defined in the tag library.

1.0

WebLogic XML file review rules

The XML file review provides a number of rules to detect deployment descriptors, Web services and other XML fileissues.

Rule Name QuickFix


Do not use local JNDI names Yes This rule detects <local-jndi-name> tags in weblogic-ejb-jar.xml files.

The quick fix scans all the projects associated with theapplication where the local JNDI name is found. If Java codeis found that references the local JNDI name, a <ejb-local-ref> is added to that project. The Web or EJB bindings are alsoupdated.

1.0 rule1.1 fix

Do not use WebLogic servletfilter for XML parsing

Yes This rule detects the use of an internal WebLogic servlet filterin web.xml files.

The quick fix removes the servlet filter entry along with itsfilter mapping entry.

1.1

Do not use WebLogicspecific EJB Query Languageconstructs

No This rule detects query language elements, weblogic-ql,in weblogic-cmp-rdbms-jar.xml files for manualmigration.

1.1

Use WebSphere bindings todefine EJB JNDI names

Previously named: UseWebSphere bindings to defineJNDI names

Yes This rule detects the <jndi-name> tag in weblogic-ejb-jar.xml files for EJB definitions.

The quick fix migrates the value found to the EJB bindings file.

1.0 rule1.1 fix


Rule Name QuickFix


Use WebSphere bindings todefine EJB reference names

Previously named: Usestandard deploymentdescriptors for EJB referencenames

Yes This rule detects <ejb-ref-name> in weblogic.xml orweblogic-ejb-jar.xml files.

The quick fix adds the EJB reference JNDI name to the EJBbindings file.

1.0 rule1.1 fix

Use WebSphere bindings todefine Message-Driven BeanJNDI names

Previously named: UseWebSphere bindings to definemessage driven descriptor

Yes This rule detects <destination-jndi-name> for message-drivenbeans.

The quick fix sets the destination JNDI name in the EJBbindings file.

1.0 rule1.1 fix

Use WebSphere bindingsto define resource referencenames

Previously called: Usestandard deploymentdescriptors for resourcereference names

Yes This rule detects <res-ref-name> elements in weblogic.xmlor weblogic-ejb-jar.xml files.

The quick fix adds the resource reference JNDI name to theEJB bindings file.

1.0 rule1.1 fix

Use WebSphere extensions todefine CMP mappings

Yes This rule detects <weblogic-rdbms-jar> elements inweblogic-cmp-rdbms-jar.xml files.

The quick fix uses the weblogic-cmp-rdbms-jar.xmlfile to generate the EJB to RDB mapping files used byWebSphere Application Server for CMP.

1.1

Use WebSphere extensions todefine concurrency strategy

Yes This rule detects the <concurrency-strategy> element inweblogic-ejb-jar.xml files.

The quick fix moves the Exclusive, ReadOnly, Database, andOptimistic options to the EJB extensions file.

1.0 rule1.1 fix

Use WebSphere extensionsto define transaction timeoutseconds

Yes This rule detect the <trans-timeout-seconds> in weblogic-ejb-jar.xml files.

The quick fix defines the timeout value to the EJB extensionsfile.

1.0 rule1.1 fix

Use WebSphere extensions todefine Web module contextroot

Yes This rule detects the <context-root> element inweblogic.xml files.

The quick fix defines the context root value to the Webextensions file.

1.1

The following rules handle WebLogic JPA persistence XML migration:


Rule Name QuickFix


Do not use kodoPersistenceServerServlet inweb.xml

Yes This rule detects the presence of servlet,kodo.remote.PersistenceServerServlet, inweb.xml files.

The quick fix removes the servlet along with its servletmapping elements.

1.1

Do not use kodo propertiesthat have no openJPAequivalent

Yes This rule detects the use of kodo.* properties that do not haveopenjpa equivalent.

The quick fix deletes the kodo property frompersistence.xml files.

1.1

Do not use kodo specificvalues for kodo propertiesand use openJPA equivalentvalues

Yes This rule detects the JPA properties with kodo-specific valuesin persistence.xml files.

The quick fix changes these values to valid openJPA values.

1.1

Use openJPA propertiesinstead of kodo propertieswhen equivalent

Yes This rule detects the presence of known JPA properties with aname starting with kodo.* in persistence.xml files.

The quick fix renames these properties to openjpa.*.

1.1

The following rules flag any WebLogic unhandled or partially handled XML file:

Rule Name QuickFix


Do not use weblogic.xml file No This rule flags the weblogic.xml file so that you can lookfor any non-migrated elements at the end of the applicationmigration.

1.0

Do not use weblogic-application.xml file

No This rule flags the weblogic-application.xml file sothat you can look for any non-migrated elements at the end ofthe application migration.

1.0

Do not use weblogic-cmp-jar.xml file

No This rule flags the weblogic-cmp-jar.xml file so thatyou can look for any non-migrated elements at the end of theapplication migration.

1.0

Do not use weblogic-cmp-rdbms-jar.xml file

No This rule flags the weblogic-cmp-rdbms-jar.xml fileso that you can look for any non-migrated elements at the endof the application migration.

1.0

Do not use weblogic-diagnostics.xml file

No This rule flags the weblogic-diagnostics.xml file sothat you can look for any non-migrated elements at the end ofthe application migration.

1.0

Do not use weblogic-ejb-jar.xml file

No This rule flags the weblogic-ejb-jar.xml file so thatyou can look for any non-migrated elements at the end of theapplication migration.

1.0


Rule Name QuickFix


Do not use weblogic-ra.xmlfile

No This rule flags the weblogic-ra.xml file so that you canlook for any non-migrated elements at the end of the applicationmigration.

1.0

The following rule migrates Web services within your application:

Rule Name QuickFix


Do not use WebLogicWeb services deploymentdescriptor

Yes This rule flags webservices.xml J2EE deploymentdescriptor files.

The quick fix generates an ANT script that uses IBMWebSphere ANT tasks which generate the appropriate artifactsfor the list of Web services based on the information collectedfrom the deployment descriptors. Depending on the deploymentdescriptor, the fix might also generate the Service EndpointInterface (SEI) for the service and add it to the project classpath. The user can then run the ANT script, copy the generatedartifacts to the project, and possibly add additional targets suchas the endpoint enabler, for example.

1.0

WebLogic class path review rules

The class path review provider verifies that the MANIFEST.MF class path is set up correctly.

Rule Name QuickFix


Use MANIFEST.MF forapplication class path

Yes This rule looks for any classes or libraries contained within anAPP-INF directory of an EAR file.

The quick fix adds an entry to the class path of eachaffected Web module by updating the class path entry of theMANIFEST.MF file of the module.

1.0

34 | Application Migration Tool | JBoss to WebSphere Application Server rules and quick fixes

JBoss to WebSphere Application Server rules and quickfixes

JBoss support is new for this release. The following rules and quick fixes are available to help migrate JBoss applications.

JBoss Java code review rules

Under the Java code review set of rules, the JBoss to WebSphere code migration category contains multiple rules. Formore information, press F1 when viewing the rule in the configuration dialog or in the results viewer.

Rule Name QuickFix


Do not use JBoss-specificJNDI name values

Yes This rule detects the usage of these JNDI name values:

• java.naming.factory.initial = org.jnp.interfaces.NamingContextFactory

• java.naming.provider.url = jnp://localhost:1099

If found, users are given the option to change the JNDI namesto default portable JNDI name values:

• java.naming.factory.initial =com.ibm.websphere.naming.WsnInitialContextFactory

• java.naming.provider.url=corbaloc:iiop:localhost:2809

Restriction: The JNDI name values must be in the sameJava source file where the context is initialized with thejavax.naming. InitialContext(Hashtable)constructor.

1.1

Do not use JBoss-specificpackages

No This rule flags imported classes that begin with org.jbossthat must be manually migrated.

1.1

Do not use MBeans forJBoss application startup orshutdown logic

Yes This rule detects the classes implementing the MBeanregistration interface to run application startup and shutdownlogic.

The quick fix that is provided for this rule converts the classto implement the SessionContextListener interface toperform startup and shutdown logic.

Important: If your code provides MBeans and it implementsMBeanRegistration for its intended purpose, you should turnoff this rule.

1.1

Use portable JNDI names No This rule detects the usage of the constructor,javax.naming.InitialContext(Hashtable),specifying not to put any proprietary JBoss JNDI name valuesinto the hash table.

1.1

Application Migration Tool | JBoss to WebSphere Application Server rules and quick fixes | 35

JBoss XML file review rules

The XML file review provides a number of rules to detect deployment descriptors, Web services, and other XML fileissues.

Rule Name QuickFix


Do not use local JNDI names Yes This rule detects <local-jndi-name> tags in jboss.xml files.

The quick fix scans all the projects associated with theapplication where the local JNDI name is found. If Java codeis found that references the local JNDI name, an <ejb-local-ref> is added to that project. The Web or EJB bindings are alsoupdated.

1.1

Manually migrate resourcereferences for URLs andresource managers

No This rule detects <res-ref-name> elements in jboss-web.xml or jboss.xml files that define URL resources orresource manager resources. These resource references must bemanually migrated.

1.1

Use WebSphere bindings todefine EJB JNDI names

Yes This rule detects the <jndi-name> tag in jboss.xml files forEJB definitions.

The quick fix migrates the value found to the EJB bindings file.

1.1

Use WebSphere bindings todefine EJB reference names

Yes This rule detects <ejb-ref-name> in jboss-web.xml orjboss.xml files.

The quick fix adds the JNDI name of the EJB reference to theEJB bindings file.

1.1

Use WebSphere bindings todefine Message-Driven BeanJNDI names

Yes This rule detects <destination-jndi-name> for message-drivenbeans.

The quick fix sets the destination JNDI name in the EJBbindings file.

1.2

Use WebSphere bindingsto define resource referencenames

Yes This rule detects <res-ref-name> elements in jboss-web.xml or jboss.xml files.

The quick fix adds JNDI name of the resource reference to theEJB bindings file.

1.1

Use WebSphere extensions todefine CMP mappings

Yes This rule detects <jbosscmp-jdbc> elements in jbosscmp-jdbc.xml files.

The quick fix uses the jbosscmp-jdbc.xml file to generatethe EJB to RDB mapping files used by WebSphere ApplicationServer for CMP.

1.2

Use WebSphere extensions todefine Web module contextroot

Yes This rule detects the <context-root> element in jboss-web.xml files.

The quick fix defines the context root value in the Webextensions file.

1.1

The following rule flags any JBoss unhandled or partially handled XML file:

Rule Name QuickFix


Do not use jboss.xml file No This rule flags the jboss.xml file so that you can lookfor any non-migrated elements at the end of the applicationmigration.

1.1

Do not use jboss-app.xml file No This rule flags the jboss-app file so that you can lookfor any non-migrated elements at the end of the applicationmigration.

1.1

Do not use jboss-client.xmlfile

No This rule flags the jboss-client.xml file so that you canlook for any non-migrated elements at the end of the applicationmigration.

1.1

Do not use jbosscmp-jdbc.xmlfile

No This rule flags the jbosscmp-jdbc.xml file so that you canlook for any non-migrated elements at the end of the applicationmigration.

1.1

Do not use jboss-web.xml file No This rule flags the jboss-web.xml file so that you can lookfor any non-migrated elements at the end of the applicationmigration.

1.1

The following rule migrates Web services within your application:

Rule Name QuickFix


Do not use JBoss Webservices deploymentdescriptor

Yes This rule flags webservices.xml J2EE deploymentdescriptor files.

The quick fix generates an ANT script that uses IBMWebSphere ANT tasks which generate the appropriate artifactsfor the list of Web services based on the information collectedfrom the deployment descriptors. Depending on the deploymentdescriptor, the fix might also generate the Service EndpointInterface (SEI) for the service and add it to the project classpath. The user can then run the ANT script, copy the generatedartifacts to the project, and possibly add additional targets suchas the endpoint enabler, for example.

1.1

JBoss class path review rules

The class path review provider verifies the MANIFEST.MF class path is set up correctly.

Rule Name QuickFix


Use MANIFEST.MF forapplication class path

Yes This rule detects jars and classes in the EAR project root folder.

The quick fix adds the jars and the classes to theMANIFEST.MF file so that they are detected by WebSphereApplication Server.

1.1

Application Migration Tool | Troubleshooting | 37

Troubleshooting

Software Analyzer options not shown

After the Application Migration Tool is installed, you have new Software Analyzer menu and toolbar options in the Java,Debug, C++, and Plug-in Development perspectives. When using other perspectives, enable these options manually. Tocustomize other perspectives, complete the following steps:

1. From your perspective, select Window > Customize Perspective from the IDE menu.2. In the Customize Perspective window, click the Commands tab and select the Software Analyzer check box. If you

are running Rational Application Developer, then the Rational Software Analyzer check box might be displayed.3. Click OK

Figure 20: Software Analyzer availability

Java EE constructs or JSP not read correctly

For the tooling to read project files correctly, the projects must be set up with their appropriate project facets. For example,projects that contain enterprise beans must have the EJB Module facet. You can see facets for a project by right-clickingon the project in the project explorer and selecting Properties. Select the Project Facets property. Projects containingWeb modules must be dynamic Web projects. See Importing applications on page 11 for more information.

Logging and trace

The Application Migration Tool writes error information to two log files:

• The workspace log (workspace/.metadata/.log) contains our severe error logs as well as Rational SoftwareAnalyzer logs.

• The Application Migration Tool service logs are located in the workspace/.metadata/.plugins/com.ibm.ws.appconversion.base directory.

This log contains all error information as well as detailed trace information if trace is enabled.

Enable the migration tool's trace by setting the appconversion.trace system variable on the command line to launchthe IDE or in the eclipse.ini property file. For example:

38 | Application Migration Tool | Troubleshooting

• Command line option. Add the system variable to the command line that starts Eclipse.

eclipse.exe -vmargs -Dappconversion.trace=true

• eclipse.ini option. Add the following line to the eclipse.ini file found in the same directory as the eclipse.exe file:

-Dappconversion.trace=true

Reports and history

In the Software Analyzer Results view, the analysis provider tabs have buttons used to export selected analysis history tofile and to generate reports. Java Code Review is the only results view that has support for reports.

For exported history, you can specify the location for the generated result.

For generated reports, the report is displayed when the report is finished. An HTML report is displayed in a Web browser.You can configure the Web browser under the Eclipse properties for General > Web Browser.

PDF reports are displayed in the system's default PDF viewer. The generated files are put in theworkspace/.metadata/.plugins/com.ibm.xtools.analysis.reporting/reports directory.

Markers

Markers appear in the left-hand margin of Eclipse editors and provide information about the content of the editor on theline where the marker appears. Editors for different file types can have different behaviors for the markers, some of whichare described here.

Figure 21: Markers in Java Editor

No popup window displays when clicking on the marker

This issue affects non-Java based rules. For a Java rule, clicking on the marker allows the quickfix to be performed.However, clicking on the marker for the XML rule has no action, and hovering over the marker only displays the help text.Use the Software Analyzer Results view to select the Quick Fix action in non-Java files

Double-clicking on a marker in a manifest file removes the marker

Double-clicking on the marker on the first line removes the marker without applying the quickfix. If this happens, run theclass path rule again to display the marker again.

Cannot select multiple markers on the same line

When there are multiple markers on the same line of text, you cannot toggle between the different markers. You mustcarry out the action of the first marker in order to select successive markers. To apply a quickfix in such a case, use theSoftware Analyzer Results view to select the Quick Fix action you want rather than relying on the marker.

Known issues

Run Quick Fix All Category for one provider at a time.

When you use the Quick Fix All Category option, let it run to completion before running it on another rule provider(category). Also, do not run Quick Fix All Category again on the same provider where it is already running. Wait until itcompletes.

Application Migration Tool | Troubleshooting | 39

Process all rules of a category before running analysis again.

Some rules are interrelated and you might improve results if you run related quick fixes before running analysis again.For example, the trigger for the WebLogic logging rules are related, and you will need to apply all quick fixes related tologging to make sure that the changes can compile successfully.

Multiple rules on the same node

When multiple rules are flagged on the same node, only the first quick fix applied will run correctly. You may need to runthe analysis a few times to make sure that all code is fixed and processed correctly.

40 | Application Migration Tool | Copyright and trademarks

Copyright and trademarks

© Copyright IBM Corporation 2009, 2010.

The information contained in this publication is provided for informational purposes only. While efforts were madeto verify the completeness and accuracy of the information contained in this publication, it is provided AS IS withoutwarranty of any kind, express or implied. In addition, this information is based on IBM's current product plans andstrategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out ofthe use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intendedto, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or alteringthe terms and conditions of the applicable license agreement governing the use of IBM software.

References in this publication to IBM products, programs, or services do not imply that they will be available in allcountries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change atany time at IBM's sole discretion based on market opportunities or other factors, and are not intended to be a commitmentto future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have theeffect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth, savingsor other results.

Performance is based on measurements and projections using standard IBM benchmarks in a controlled environment.The actual throughput or performance that any user will experience will vary depending upon many factors, includingconsiderations such as the amount of multiprogramming in the user's job stream, the I/O configuration, the storageconfiguration, and the workload processed. Therefore, no assurance can be given that an individual user will achieveresults similar to those stated here.

IBM, the IBM logo, developerWorks, Passport Advantage, Rational, and WebSphere are trademarks of InternationalBusiness Machines Corporation in the United States, other countries or both.

Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, othercountries or both.

Other company, product and service names may be trademarks or service marks of others.

application migration tool - public.dhe.ibm.com · • migrating weblogic java, jsp, and class path...

Documents