WebSphere Application Server

Application Migration Tool for WebSphere Version Migration

Built on Rational Software Analyzer technology

Version 3.5.1 December 3, 2012

A combined effort:

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

Copyright IBM Corp. 2009, 2012

2 | Application Migration Tool | Contents

Contents
Overview................................................................................................................................ 3 New for this release...............................................................................................................4
Version 3.5.1............................................................................................................................................ 4

Support...................................................................................................................................5 Installing and updating the migration tools....................................................................... 6 Importing applications....................................................................................................... 10

Shared Java projects............................................................................................................................... 11 EAR-level library....................................................................................................................... 11 Web module library....................................................................................................................11 Configuring a Java EE Runtime Library................................................................................................11

Configuring the migration tool for analysis..................................................................... 14 Analyzing code for migration............................................................................................ 18 Running additional rules to optimize code quality.......................................................... 20 WebSphere Application Developer Tools for Eclipse......................................................21 WebSphere Application Server version migration rules and quick fixes......................22
Java code review.................................................................................................................................... 22 JSP code review..................................................................................................................................... 26 XML code review...................................................................................................................................27 Deprecated features................................................................................................................................ 29

Java SE version migration................................................................................................. 38 Troubleshooting.................................................................................................................. 43

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

Copyright and trademarks.................................................................................................47

Application Migration Tool | Overview | 3

Overview
The Application Migration Tool - WebSphere Version to Version feature is part of the IBM WebSphere Application Server Migration Toolkit. This toolkit is part of the overall strategy and plan for assisting customers in migrating from one application server to the IBM WebSphere Application Server. The Application Migration Tool - WebSphere Version to Version feature provides support for migrating applications from older versions of WebSphere Application Server to WebSphere Application Server Version 7, 8, or 8.5. The overall migration process between versions of WebSphere Application Server involves a series of steps to assess the migration, plan the work involved, migrate and develop the code, manage the runtime configuration, test the results, and roll out the new release. This tool helps migrate and develop the code. There are a number of issues that affect the code migration and development step when moving between WebSphere Application Server releases. These include: Changes to the Java Runtime Environment (JRE) encountered in Java SE 5, 6 and 7 Removal of previously deprecated features Behavior changes in the product APIs Changes resulting from Java Enterprise Edition (Java EE) specification clarifications Deprecated features

The migration process can involve modifying Java source code, JavaServer Pages (JSP), and deployment descriptors. The application migration tool can assist you in performing these types of code changes. This document explains how to install, configure, and use the tool to assist in the conversion process. The migration tool is based on IBM Rational Software Analyzer, which provides a single solution to identify, analyze, and optimize the application health. The migration tool uses the scanning capabilities of Rational Software Analyzer to look for specific constructs that have changed between versions of WebSphere Application Server that can affect compilation and application server runtime behaviors. The tool then provides a way to review problematic code, get help on the issue, and in some cases make automatic fixes to the code so that the application can run on IBM WebSphere Application Server Version 7, 8, or 8.5 For WebSphere Application Server version migration, the tool supports migrating from: WebSphere Application Server Version 5.1 WebSphere Application Server Version 6.0 WebSphere Application Server Version 6.1 WebSphere Application Server Version 7.0 WebSphere Application Server Version 8.0

and migrating to: WebSphere Application Server Version 7.0 WebSphere Application Server Version 8.0 WebSphere Application Server Version 8.5

See the Application Migration Tools for Competitive Migration documentation for information about competitive migration. The WebSphere Application Server V8.5 Migration Guide is now available with comprehensive information on migration topics related to WebSphere Application Server. It uses the Application Migration Toolkit in its examples and provides a wealth of information. See Part 4 for migrating from earlier versions of WebSphere Application Server.

4 | Application Migration Tool | New for this release

New for this release

Version 3.5.1
Application Migration Tool - WebSphere Version to Version V3.5.1 adds the following rules. Detect bad attributes of the global-transaction element Use application version 1.4 or lower when migrating applications from WebSphere V6.1 or prior Avoid using the deprecated Common Event Infrastructure packages

More reports HTML and PDF report capabilities are now available for XML, JSP, and class path rules. In previous releases, these report types were only available for Java rules. JSP Code Review Results JSP Code Review Severity Summary JSP Code Review Severity by Category XML File Review Results XML File Review Ignored Results XML File Review Severity Summary XML File Review Severity by Category

Support Bug and field support fixes have been added to this release. Supports Eclipse 4.2.

Application Migration Tool | Support | 5

Support
The application migration tool scans for a number of known issues in applications being migrated from WebSphere Application Server Version 5.1, 6.0, 6.1, or 7.0 to WebSphere Application Server Version 7.0, 8.0, or 8.5. Where possible, a quick fix is provided to change your code to address the changes between versions. Supported migration rules and quick fixes are documented in the section, WebSphere Application Server version migration rules and quick fixes on page 22. As new rules and quick fixes are available, updates are made on developerWorks. You can use the quick fix preview support in the migration tool to help you 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 backup copy of your source code before starting a migration. For some rules, the scan detects code that requires design changes and code rewrites. The tool highlights these problem areas but does not provide a quick fix. The tool does not identify all problems. As you encounter problems that the tool does not flag, provide that feedback through the Application Migration Tool forum, which 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 problem report. Other users can use the forum to report issues or suggestions and ask questions. The Application Migration Tools are supported on the Windows and Linux operating systems as supported by Eclipse and Rational Application Developer.

6 | Application Migration Tool | Installing and updating the migration tools

Installing and updating the migration tools

The application migration tools are Eclipse features that you install into an existing Eclipse or Rational Application Developer environment. The version migration tool is supported on Eclipse 3.6.2, 3.7.2, and 4.2 available from http:// www.eclipse.org. If using Eclipse, the Eclipse IDE for Java EE Developers is recommended. It contains the required prerequisites and will help when creating your Java projects. Rational Application Developer versions 7.5 to 8.5 are also supported and contain the required prerequisites. If you are using the Liberty Profile Developer Tools, the supported platforms are Eclipse 4.2, 3.7.2, and 3.6.2. Installation for the version migration tool is available through Eclipse Marketplace or by downloading the repository archive, the following steps show you the options: 1. Start the IDE. 2. Uninstall versions 1.0, 1.1, 1.2, 2.0, and 3.5 Beta of the migration tools before installing Version 3.5.1. Versions 2.1, 3.0, 3.1, and 3.5 can be upgraded to Version 3.5.1. 3. If you are using a Rational Application Developer environment, all prerequisite plug-ins are typically installed by default. During installation, verify that the Business Intelligence and Reporting Tools and the Web Development Tools features are selected. If you are not using a Rational Application Developer environment, install the prerequisite plug-ins from either the Juno, Indigo, Helios, or Galileo site depending on your Eclipse version. Eclipse version Eclipse 4.2 Install actions From the Eclipse menu bar, select Help > Install New Software. Using the Juno update site (http://download.eclipse.org/releases/juno) install Business Intelligence, Reporting and Charting and Web, XML and Java EE Development. From the Eclipse menu bar, select Help > Install New Software. Using the Indigo update site (http://download.eclipse.org/releases/indigo) install Business Intelligence, Reporting and Charting and Web, XML and Java EE Development. From the Eclipse menu bar, select Help > Install New Software. Using the Helios update site (http://download.eclipse.org/releases/helios) install Business Intelligence, Reporting and Charting and Web, XML and Java EE Development.

Eclipse 3.7

Eclipse 3.6

Note: The catalog of available plug-ins is large and can require several minutes to download.

Application Migration Tool | Installing and updating the migration tools | 7

Figure 1: Eclipse 4.2 plug-in installation dialog 4. Eclipse Marketplace provides the easiest way to install or update the version migration tool. a) Select Help > Eclipse Marketplace... b) Search for WebSphere migration c) Select the Install button. d) Proceed to the install step.

Figure 2: Eclipse Marketplace dialog 5. If you are using Rational Application Developer or do not have Eclipse Marketplace, proceed with these steps to setup a downloaded repository. a) Download the latest version of the Application Migration Tool - WebSphere Version to Version feature from the developerWorks site http://www.ibm.com/developerworks/websphere/downloads/migration_toolkit.html and save it locally. b) Select Help > Install New Software... to open the installation dialog to install or update the Application Migration Toolkit. c) Click Add to point to your downloaded update site file. d) In the Add Site window, enter the following information, which is shown in Figure 3: Tool installation.

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

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

Figure 3: Tool installation e) Click OK. 6. Complete the following actions in the Install window, which is shown in Figure 4: Select Plug-In. a) Select the check box for Application Migration Tool which selects both the main feature and the other included features. The other included features are the common feature, the JRE feature, and the framework feature. It is particularly important to have the common feature included when upgrading. b) Select the check box to Contact all update sites during install to find required software, and click Next. Note: If you are installing on Rational Application Developer 7.5, it is preferable to not select Uncategorized from the repository site. These plug-ins will be installed automatically regardless of the selection. If Uncategorized is selected, the plug-ins will not be automatically uninstalled if you uninstall the application migration tool. 7. Click Next on the Install Details panel. 8. 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.

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

Figure 4: Select Plug-In 9. Restart the IDE when the Software Updates window is displayed.

Figure 5: Restart dialog

10 | Application Migration Tool | Importing applications

Importing applications
To analyze an application for migration, the application must be imported into your Eclipse based IDE. In order to effectively and completely analyze the application, the application modules must be organized in projects that reflect their structure as EAR, WAR, and EJB files. Specifically, migration rules that analyze web and EJB bindings and extensions only work when analyzing projects created as dynamic web projects and EJB projects. To achieve this, you can either import your existing EAR, web archive (WAR), and Enterprise JavaBeans (EJB) modules or manually create new projects in the workspace for each EAR, WAR module, and EJB module. You can use the Import Eclipse options to create the correct project structure. Rational Application Developer or the Eclipse for Java EE developer tools are needed to create these projects properly. For example, to import an EAR file, select the File > Import... menu option. Select Java EE then EAR to enter the location of your EAR file. The Eclipse import function will create a project for the EAR file and a project for each module in the application.

By importing the application, the proper project structure is created with the deployment descriptor information. If your EAR file contains source code, it will also get imported into the Eclipse project. However, most EAR and module files do not contain the Java source code, and you need to copy the source code to its correct source folders. Again, use the File > Import... options to import the source code from the file system or from an archive (zip) file. Repeat this procedure to import the source code for each module. When creating projects manually, create the EAR file using File > New > Enterprise Application Project option. Create each WAR file using the File > New > Dynamic Web Project option, and create each EJB module using the File > New > EJB Project option. Copy the source files to their correct locations in the project using the File > Import... options. Review the following guidelines for structuring projects: Java source code for a WAR file (for example, servlet, model, or utility classes), belongs in the src folder of the project. The src folder is defined and can be changed in the Java Build Path properties for the project. If the Java source code needs to be referenced by more than one WAR file, 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 path rule and its quick fix to update the class paths correctly. For a more detailed step-by-step description on how to import applications, see the WebSphere Application Server V8.5 Migration Guide (http://www.redbooks.ibm.com/redpieces/pdfs/sg248048.pdf).

Application Migration Tool | Importing applications | 11

Shared Java projects

There are two options for referencing shared Java classes from a web project: 1. Create a single copy of the Java project JAR file in the EAR file. Each WAR file references the JAR file. This approach reduces the size of the EAR file. 2. Create a copy of the JAR file in each WAR file. Use this approach if only one WAR file references the JAR file. For more information on configuring the deployment assembly, refer to Java EE Deployment Assembly.

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 src folder of the project. 2. Right-click the project in the Project view and select Properties. Select the Deployment Assembly item from the left pane. On the right pane, select the Add... button to include the Java projects you want to reference.

Figure 6: Java EE EAR module dependencies

Web module 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. 2. Right-click the project in the Project view and select Properties. Select the Deployment Assembly item from the left pane to view the Web Deployment Assembly. On the right pane, select the Add... button to include the Java projects or archives you want to reference. 3. Select OK to save your changes.

Configuring a Java EE Runtime Library

When using Eclipse with the Java EE tools installed, the Java compiler is not able to resolve references to the Java EE APIs unless a target Java EE 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.

12 | Application Migration Tool | Importing applications

Figure 7: Server Runtime Environments 3. Click Add. Select Basic > J2EE Runtime Library. 4. On the next wizard page, click Browse to choose the library location, locate the dev/JavaEE folder of your WebSphere Application Server installation, and select the appropriate Java EE version. That folder contains the j2ee.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 the project in the Project view, select Properties, and choose the Targeted Runtimes item.

Application Migration Tool | Importing applications | 13

Figure 8: Targeted Runtimes In the Targeted Runtimes window, select the check box next to the recently configured Java EE runtime library, and click OK. You can achieve the same effect by targeting WebSphere Application Servers and the Liberty Profile when you have the WebSphere Application Server Developer Tools installed.

14 | Application Migration Tool | Configuring the migration tool for analysis

Configuring the migration 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 scope can be a project, a working set, or the entire workspace. After you define the scope, you can save the analysis configuration to use or modify later. With a migration tool installed, you have new analysis options to configure and run an analysis. You can access the options in the Eclipse Run menu, in the Launch toolbar, and in the explorer pop-up menus. The following figure demonstrates the different ways you can run the analysis using the application migration tools. From the Eclipse menu: From the Launch Eclipse toolbar:

From the explorer pop-up menu:

Figure 9: Options for running the tool If you do not see Software Analyzer options, see Software Analyzer options not shown on page 43. To configure the analysis using the toolbar, complete the following steps: 1. On the toolbar, select Software Analyzer ( configuration dialog. ) > Software Analyzer Configurations to display the main

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

Application Migration Tool | Configuring the migration tool for analysis | 15

2. In the configurations list, select Software Analyzer. Then, click New the basic configuration interface.

. The right side of the dialog changes to show

3. In the Software Analyzer Configuration dialog, enter a name for the configuration, such as AppMigration. 4. On the Scope tab, select Analyze entire workspace to scan all projects in the workspace.

16 | Application Migration Tool | Configuring the migration tool for analysis

You can limit the scope of an analysis by using the other options on this dialog to analyze a working set or a selection of projects. Tip: When you use the explorer pop-up menu to run your analysis, the scope of the analysis is limited to the node in the project where the menu item 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 using the Rule Sets list. You can also select individual rules to run. Tip: To obtain additional information about a rule, highlight the rule and press F1. Help for the rule is shown in the configuration dialog. The initial help page includes a short description and a link to more information.

There is now one rule set, WebSphere Application Server version migration, for version to vesrion WebSphere Application Server migration. To automatically select all of the rules from one of these rule sets, select it from the list, and click Set. Java Code Review JSP Code Review XML File Review

After the rule set is selected and the Set... button is pressed, the user is presented a dialog allow selection of the needed Java migration rules.

Application Migration Tool | Configuring the migration tool for analysis | 17

Select the target WebSphere Application Server version, either V7, V8, or V8.5. Also, select the source Java version that was being used. If the target WebSphere platform is V8.5, you can also select the target Java version, Java 6 or Java 7. Select the Final target is a Liberty profile server running on Oracle Java check box only if you are not using an IBM supplied Java Runtime Environment with the Liberty profile server. Note: The number of rules in the analysis configuration dialog varies depending on the platform on which the tool is installed. Analysis rules are available in several Rational products such as Rational Application Developer; therefore, the included rule sets might be different. 6. To save the rule configuration, click Apply. 7. You can use the Software Analysis Configurations dialog to select or clear any rule or group of rules to use in the analysis. For example, if you find after analysis that you do not need to make changes pointed out by a particular rule from the selected rule set, you can clear its selection to turn it off. a) To find the rule, the navigation in the configuration dialog is similar to the folders shown in the results tree view. Use the folder names to locate the rule. b) Clear the rule selection. c) Click the Apply button. d) Click the Analyze button. The deselected rule will not be included in the next analysis.

18 | Application Migration Tool | Analyzing code for migration

Analyzing code for migration

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.

Depending on which rules you are running, the content of the results view might vary. The results generated by a migration tool are displayed in one of the following tabs: 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 or correcting the problem with a provided fix.

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

Application Migration Tool | Analyzing code for migration | 19

View Result - Opens an editor showing the source file that triggered the rule. The cause of the 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 that this rule has a quick fix. Selecting this option runs the conversion that modifies the affected Java code, XML file, JSP or manifest file, allowing it to run in WebSphere Application Server. The quick fix might change the code directly or it might present the steps needed to complete the fix. Quick Fix Preview - This option is available for the rules that support showing a side-by-side comparison of the original code and the code after the quick fix is applied. This option allows you to see the changes before they are made. 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 category to which the rule belongs. A rule must have Quick Fix All enabled for the Quick Fix All Category option to run its quick fix. For example, if you choose this option 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. Click Detailed Help to get more information. Press F1 to open the Help view if it is not already displayed.

20 | Application Migration Tool | Running additional rules to optimize code quality

Running additional rules to optimize code quality

After you run quick fixes or make manual code changes, and correct the issues highlighted by a migration tool, additional rules are provided by the Rational Software Analyzer product that can help improve the quality of your code. These rules are not required for conversion. Figure 10: Other architectural and Java rules shows examples of the additional rules.

Figure 10: Other architectural and Java rules Access these rules by creating a new analysis configuration or modifying an existing one. These rules are not automatically selected as part of rule sets for the application migration tools. When the selected rules run and necessary changes are made, the updated application must be exported and tested on WebSphere Application Server. If you use Rational Application Developer, tools are available to create deployments and test the application within the Rational Application Developer environment.

Application Migration Tool | WebSphere Application Developer Tools for Eclipse | 21

WebSphere Application Developer Tools for Eclipse

If you are using the Eclipse IDE for application development, there are a number of tools available that can be used with the migration toolkit that enable you to migrate, develop, deploy, and test within a single lightweight Eclipse IDE. Tools are available for both the traditional WebSphere Application Server and the new Liberty profile server. IBM WebSphere Application Server v8.5 Liberty Profile Developer Tools IBM WebSphere Application Server v8.5 Developer Tools IBM WebSphere Application Server v8.0 Developer Tools IBM WebSphere Application Server v7.0 Developer Tools

These tools are available from the Eclipse Marketplace and can be installed easily from within Eclipse: 1. 2. 3. 4. 5. Start your Eclipse workbench. Click Help > Check for Updates to install the latest updates. Click Help > Eclipse Marketplace. In the Find field, type WebSphere. In the list of results, locate the appropriate WebSphere Application Server Developer Tools and then click Install.

The tools provide function and features for the capabilities of their targeted release of WebSphere. They also contain functionality for managing the server, publishing to a local or remote server, and for controlling incremental publishing. Included is a Rich Page Editor, a WYSIWYG editor that makes it easy to edit HTML files, add Dojo widgets to HTML pages, and create and edit web pages for mobile devices. For general discussion, demos, and information links, go to http://wasdev.net for more information. The Liberty profile provides a simplified application server runtime environment that makes testing web applications much easier for the developer. The corresponding WebSphere Application Server V8.5 Liberty Profile Developer Tools support the development, assembly, and deployment of web applications to servers based on the WebSphere Application Server V8.5 Liberty profile server. To get started with the Liberty profile server, see The Liberty profile. Also see, Liberty profile: Feature management to understand the Liberty profile server supported features and capabilities.

22 | Application Migration Tool | WebSphere Application Server version migration rules and quick fixes

WebSphere Application Server version migration rules and quick fixes

The Application Migration Tool - WebSphere Version to Version feature evaluates Java code, JSP code and deployment descriptors 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:

Java code review

Under the Java Code Review set of rules, the WebSphere version migration category contains rules for migrating from WebSphere Application Server Version 5.1, 6.0, 6.1, and 7.0 to Version 7.0, 8.0, or 8.5. For more information on a rule, press F1 when viewing the rule in the configuration dialog or in the results viewer. Quick fixes are available where possible. Rules without quick fixes flag the rule violations so you can evaluate their usage and migrate the code manually.

Table 1: V5.1 to V6.0 migration Rule Name Check for a behavior change on the ServletResponse default content type Quick Fix No Action Taken

The default content type for HttpServletResponse has changed from "text/html" to "text/plain" for servlets that do not set the content type. This rule flags calls in Java code that create Uniform Resource Locators (URL) that contain a plus ("+") character in the URI that is not part of the query parameters. The plus ("+") is only reserved in the query string portion of the URL. The WebSphere Application Server implementation of the ServletResponse sendRedirect() method omits path information until the last slash. With a new custom property this behavior can be corrected. A restriction was added in WebSphere Application Server V6.0 that code running in the web container is no longer allowed to start threads. Use the work manager to schedule asynchronous beans instead of creating new threads.

Check for behavior change on URLs containing a plus sign

No

Check for expected behavior on ServletResponse sendRedirect() method

No

Do not start threads from code running within the web container

No

Application Migration Tool | WebSphere Application Server version migration rules and quick fixes | 23

Rule Name Use leading slash on ServletContext getResource() and getResourceAsStream() requests

Quick Fix No

Action Taken

This rule flags calls to the ServletContext.getResource() and ServletContext.getResourceAsStream() methods where it cannot easily be determined if the String value passed on the method contains a leading slash (/) as required by the servlet specification. This rule flags the use of the activity component classes and interfaces that were removed in WebSphere Application Server V6.0. This rule flags the use of the Ant task classes and interfaces that were removed in WebSphere Application Server V6.0. This rule flags the use of the asynchronous bean classes and interfaces that were removed in WebSphere Application Server V6.0. This rule flags the use of the object pool classes that were removed in WebSphere Application Server V6.0. This rule flags the use of the RAS classes and interfaces that were removed in WebSphere Application Server V6.0. This rule flags the use of the scheduler classes and interfaces that were removed in WebSphere Application Server V6.0. This rule flags the use of the security classes and interfaces that were removed in WebSphere Application Server V6.0. This rule flags the use of the EarUtils class that was removed in WebSphere Application Server V6.0. This rule flags the use of the method, setJMSPriority, from the interface, com.ibm.websphere.scheduler.MessageTaskInfo. This method was deprecated in the Websphere Application Server V6.0 release and was replaced by the method getJMSPriority. This rule flags the use of the user profile classes and interfaces that were removed in WebSphere Application Server V6.0.

Do not use activity component features that were removed

No

Do not use Ant task features that were removed Do not use asynchronous bean features that were removed

No

No

Do not use object pool features that were removed Do not use RAS features that were removed Do not use scheduler features that were removed Do not use security features that were removed Do not use the EarUtils class that was removed Do not use setJMSPriority() method that was removed

No

No

No

No

No

No

Do not use user profile features that were removed

No

Table 2: V6.0 to V6.1 migration Rule Name Check for behavior change on EJBContext.setRollbackOnly() method Quick Fix No Action Taken

A call to setRollbackOnly under a certain scenario can yield a different result on WebSphere Application Server releases prior to V6.0.2.

24 | Application Migration Tool | WebSphere Application Server version migration rules and quick fixes

Rule Name Do not use Common Connector Framework features that were removed

Quick Fix No

Action Taken

This rule flags the use of the Common Connector Framework API packages that were removed in WebSphere Application Server V6.1. This rule flags the use of the removed method setHost(String s) in the com.ibm.websphere.ant.tasks.StopServer class. This rule flags the use of the JDOM packages that were removed in WebSphere Application Server V6.1. This rule flags the use of the Rhino packages that were removed in WebSphere Application Server V6.1. This rule flags the use of the CustomRegistry interface that was removed in WebSphere Application Server V6.1.

Do not use the WebSphere Ant StopServer.setHost() method that was removed Use the open-source JDOM implementation to replace the JDOM features that were removed Use the open-source Mozilla Rhino implementation to replace the Rhino features that were removed Use the UserRegistry interface to replace the CustomRegistry interface that was removed Table 3: V6.1 to V7.0 migration Rule Name Check the JAXB context factory initialization class

No

No

No

No

Quick Fix No

Action Taken

This rule flags the JAXBContext newInstance() method because the context factory method has changed since earlier versions of JAXB. This rule detects the use of JAX-WS annotations in enterprise projects earlier than Java EE 5. This rule flags the removed com.ibm.websphere.cache.DistributedLockingMap interface. This rule flags the use of the removed constructors in the classes com.ibm.websphere.cache.InvalidationEvent or com.ibm.websphere.cache.ChangeEvent. The new constructor takes an additional field. This rule flags the use of the com.ibm.websphere.rsadapter. SequeLinkDataStoreHelper class. Do not use the com.ibm.websphere.servlet.session. UserTransactionWrapper class because it has been removed. Store a UserTransaction directly into the HTTP session without wrapping it in the removed class. This rule flags the use of the com.ibm.websphere.rsadapter. WSConnectJDBCDataStoreHelper class

Only use JAX-WS annotations in Java EE 5 or later Do not use the DistributedLockingMap interface that was removed Do not use the InvalidationEvent or ChangeEvent constructors that were removed

No

No

No

Do not use the SequeLinkDataStoreHelper class that was removed Do not use the WebSphere UserTransactionWrapper class that was removed

No

No

Do not use the WSConnectJDBCDataStoreHelper class that was removed

No

Application Migration Tool | WebSphere Application Server version migration rules and quick fixes | 25

Rule Name

Quick Fix

Action Taken and the com.ibm.websphere.rsadapter. DataStoreHelper.WSCONNECTJDBC_HELPER field that were removed.

Do not use web services gateway customization APIs that were removed Use Java EE servlet filters instead of WebSphere Servlet filter class that were removed Use the ConnectJDBCDataStoreHelper class instead of DataDirectDataStoreHelper class

No

Do not use web services Customization APIs. The rule flags the use of the package, com.ibm.wsgw.beans.*. Do not use com.ibm.websphere.servlet.filter classes because they were removed. Use javax.servlet.filter classes instead. Do not use the com.ibm.websphere.rsadapter. DataDirectDataStoreHelper object because it was removed. The quick fix changes the code to use com.ibm.websphere.rsadapter. ConnectJDBCDataStoreHelper instead.

No

Yes

Use MicrosoftSQLServerDataStore helper class instead of the MSSQLDataStoreHelper class

Yes

Do not use the com.ibm.websphere.rsadapter. MSSQLDataStoreHelper class because it was removed. The quick fix changes the code to use com.ibm.websphere.rsadapter. MicrosoftSQLServerDataStoreHelper instead.

Table 4: V7.0 to V8.0 migration Rule Name Check for a behavior change for EJB presence in a web module Check for a behavior change in ApplicationException inheritance Quick Fix No Action Taken

This rule flags EJB annotations in Java files if these files are in a web module with version 2.5 or higher. This rule flags the EJB ApplicationException annotation which does not have the attribute inherited set. The inherited attribute was added in EJB 3.1 and changed default behavior of EJB 3.0 applications. This rule flags JAX-WS Dispatch client applications that may experience a behavior change in the SOAP Action setting on outbound messages. This rule flags calls to the SOAPMessage methods getSOAPHeader() and getSOAPBody() that now throw an exception rather than returning null if the respective header or body is not present. This rule flags applications that retrieves JAX-WS and JAXRPC SOAP fault codes and strings because some of the content changed in version 8.0.

No

Check for a behavior change in SOAP Action set on outbound messages

No

Check for a behavior change in SOAPMessage methods

No

Check for a behavior change in web services SOAP fault codes and strings

No

26 | Application Migration Tool | WebSphere Application Server version migration rules and quick fixes

Rule Name Check for a behavior change on EntityManager refresh(Object entity) method Check for a behavior change on OpenJPAEntityManager detach(T pc) method

Quick Fix No

Action Taken

This rule flags the EntityManager.refresh() calls as the behavior of this method has changed. This rule flags the OpenJPAEntityManager detach(T pc) method. The method return type changed to support the 2.0 JPA specification. The quick fix changes the detach() method to detachCopy().

Yes

Check for a behavior change on SipFactory methods

No

This rule flags certain SipFactory methods using a String to, from, or addr parameter for which there is a behavior change. This rule flags the use of changed Server MBean operations getComponentVersion, getEFixVersion, getPTFVersion, getExtensionVersion, getVersionsForAllComponents, and getVersionsForAllEFixesstartTransports. This rule flags the use of the removed classes in the org.apache.soap and com.ibm.soap packages. This rule flags the method getCause() in the class com.ibm.websphere.servlet.error. ServletErrorReport that was removed. This rule flags the use of the Oracle 10g helpers and fields. Version 8.0 only supports the Oracle 11g JDBC driver and helper. The quick fix changes the code to use the Oracle 11g helper after confirming that the runtime configuration was changed.

Check for a behavior change on some Server MBean operations

No

Do not use the removed Apache SOAP API Do not use the removed method getCause() from ServletErrorReport

No

No

Use the Oracle 11g helper instead of earlier versions

Yes

Table 5: V8.0 to V8.5 migration Rule Name Check for a behavior change in JPA cascade strategy Quick Fix No Action Taken

This rule flags projects using JPA entity relationships that use cascade types PERSIST, MERGE, or ALL because there is a potential behavior change in WebSphere Application Server V8.5. There is a corresponding XML rule to detect this behavior change.

JSP code review

Under the JSP code review set, the WebSphere version migration category has rules described in the following table. For more information, press F1 when viewing the rule in the results viewer. Note: JSP pages written in XML syntax (JSP documents) are not supported in this release.

Application Migration Tool | WebSphere Application Server version migration rules and quick fixes | 27

Table 6: Migrating from Version 5.1 Rule Name Check for behavior change for included JSP encoding Quick Fix No Action Taken

In JSP 2.0, page encoding is done on a per-file basis. This rule detects the statically included JSP files that have different page encoding than the parent JSP. This rule flags calls to request.getAttribute() in JSP files that use automatic casting to a String. However in V6, the request.getAttribute() method returns an Object, not a String. This rule flags a URI in a JSP link tag (<a>) or a form action tag (<form action=...) that contain a plus ("+") character in the URI but not a part of the query parameters. The plus ("+") is only reserved in the query string portion of the URL. As of JSP 2.0, you cannot refer to any classes from the unnamed (also known as the default) package. This rule detects JSP Import Directives that contain classes from the default package.

Check for behavior change on the request.getAttribute() method

No

Check for behavior change on URLs containing a plus sign

No

Do not use default packages in JSP import statements

No

Table 7: V6.1 to V7.0 migration Rule Name Check for taglib prefix redefinition Quick Fix No Action Taken

This rule detects the redefinition of a taglib with a different prefix in the same JSP or in the statically included JSP files. If a taglib is defined more than once in a JSP file or a statically included JSP file, it must have the same prefix.

XML code review

The XML file review provides rules to detect deployment descriptors and other XML file issues. Table 8: V6.1 to V7.0 migration Rule Name Detect bad attributes of the globaltransaction element Do not use bean-managed persistence in EJB 3.0 projects Quick Fix No Action Taken This rule flags an invalid transaction timeout attribute of the global-transaction element in the ibm-ejb-jar-ext.xml file. This rule detects the use of bean-managed persistence in EJB 3.0 projects, which is valid in the IBM WebSphere Application Server V6.1 Feature Pack for Enterprise JavaBeans 3.0 but not in WebSphere Application Server V7.0. When migrating from WebSphere Version 6.1 or prior, this rule flags any application with a version higher than 1.4.

No

Use application version 1.4 or lower when migrating applications from WebSphere V6.1 or prior

Yes

28 | Application Migration Tool | WebSphere Application Server version migration rules and quick fixes

Rule Name Use the metadata-complete attribute for Java EE 5 modules without annotations Use web module version 2.4 or lower when migrating applications from WebSphere V6.1 or prior Use unique EJB 3.0 binding names

Quick Fix No

Action Taken

This rule flags Java EE 5 modules that do not have the metadata-complete attribute set. When migrating from WebSphere Version 6.1 or prior, this rule flags any web module with a version 2.5 or higher which can cause migration issues. WebSphere Application Server V6.1 Feature Pack for EJB 3.0 allowed the EJB 3.0 binding file to contain duplicate binding names. The V7.0 server runtime environment added uniqueness checks for names used in the EJB 3.0 bindings file. Applications with uniqueness errors do not start in V7.0 even though the same application worked on the Feature Pack for EJB 3.0. This rule validates the EJB 3.0 bindings file to verify binding name uniqueness. It also validates that class names for session interfaces and interceptors are fully qualified.

Yes

No

Table 9: V7.0 to V8.0 migration Rule Name Check for a behavior change for EJB presence in a web module Quick Fix No Action Taken

This rule flags a web.xml file of a Web Module Version 2.5 or higher if that module contains a .class file which has an EJB annotation. The .class file must be in a library (a .jar file in WEB-INF/lib). This rule flags EJB ApplicationException definitions in ejbjar.xml files which do not have the inherited attribute set. The inherited attribute was added in EJB 3.1 and changed the default behavior of EJB 3.0 applications. This rule flags the Java Server Faces (JSF) application because the default implementation for JSF container has changed in WebSphere V8.0. This rule flags the <is-xml> and <page-encoding> JSP configuration options. The JSP specification was clarified with respect to these configuration options and included JSP files, and the behavior changed in Version 8. This rule flags addressing policy configuration found in the WSDL definition. The addressing policy was ignored in the WSDL definition in previous releases. This behavior change would cause problems only if the the addressing policy in the packaged WSDL differs in a significant way from the active configured addressing policy.

Check for a behavior change in ApplicationException inheritance

No

Check for a behavior change in Java Server Faces (JSF) Applications

No

Check for a behavior change in JSP configuration of <is-xml> and <pageencoding> options

No

Check for a behavior change in web services addressing policy

No

Application Migration Tool | WebSphere Application Server version migration rules and quick fixes | 29

Table 10: V8.0 to V8.5 migration Rule Name Check for a behavior change in JPA cascade strategy Quick Fix No Action Taken

This rule flags projects using JPA entity relationships that use cascade types PERSIST, MERGE, or ALL because there is a potential behavior change in WebSphere Application Server V8.5. There is a corresponding Java rule to detect this behavior change. This rule flags the persistence.xml file for a behavior change in JPA MetaModel code generation concerning ListAttribute in WebSphere V8.5.

Check for a behavior change in JPA MetaModel code generation concerning ListAttribute

No

Deprecated features
There are deprecation rules under the Java Code Review, JSP Code Review, and XML File Review categories. The rules are organized by target release: Migration to V7.0 - currently deprecated in V7 and removed in V8 Migration to V7.0 and V8.0 - currently deprecated in V7.0 and in V8.0 Migration to V8.0 - newly deprecated in V8.0 Migration to V8.5 - newly deprecated in V8.5 Table 11: Java deprecated features - Migration to V7.0 Rule Name Avoid using the deprecated Apache SOAP API Avoid using the deprecated OracleDataStoreHelper class Quick Fix No Action Taken

This rule flags references to the org.apache.soap and com.ibm.soap packages. This rule flags the use of the deprecated Oracle data store helper and field. The quick fix changes the code to use the Oracle 11g helper after confirming that the server runtime configuration was changed.

Yes

Table 12: Java deprecated features - Migration to V7.0 and V8.0 Rule Name Avoid using the deprecated analyzer logging system classes Avoid using the deprecated Ant setCompileWithAssert method Quick Fix No Action Taken

This rule flags the use of the deprecated com.ibm.websphere.als classes. This rule flags the use of the deprecated Ant method setCompileWithAssert. The quick fix replaces the method with setJdkSourceLevel.

Yes

Avoid using the deprecated AppDeploymentController methods Avoid using the deprecated AppDeploymentTask methods

No

This rule flags the use of the application deployment controller getTaskInfo methods. This rule flags the use of the deprecated methods from the com.ibm.websphere.management.application. client.AppDeploymentTask class.

Yes

30 | Application Migration Tool | WebSphere Application Server version migration rules and quick fixes

Rule Name

Quick Fix

Action Taken The quick fix changes the methods to the recommended replacements.

Avoid using the deprecated application management installStandaloneRAR method Avoid using the deprecated application management moveModule method Avoid using the deprecated application profile access intent methods Avoid using the deprecated Cache interface Avoid using the deprecated com.ibm.etools.logging utilities Avoid using the deprecated command manager methods

No

This rule flags the use of the application management installStandaloneRAR method. This rule flags the use of the application management moveModule method. This rule flags the use of deprecated application profile access intent methods. This rule flags the use of the com.ibm.websphere.Cache interface. This rule detects and flags references to com.ibm.etools.logging packages that are deprecated. This rule flags the use of the deprecated methods in com.ibm.websphere.management.cmdframework. CommandMgrInitializer class. The quick fix changes the methods to the recommended replacements.

No

No

No

No

Yes

Avoid using the deprecated ConnectionFactory MBean methods

No

This rule flags the deprecated ConnectionFactory MBean operations getPoolContents, getAllPoolContents, and showAllocationHandleList. This rule flags the deprecated methods from the com.ibm.websphere.ola.ConnectionSpecImpl class. The quick fix changes the parameter to the appropriate boolean value.

Avoid using the deprecated ConnectionSpecImpl methods

Yes

Avoid using the deprecated Connector Architecture interfaces

No

This rule flags the deprecated Connector Architecture interfaces com.ibm.websphere.j2c. ConnectionEventListener and com.ibm.websphere.j2c.ConnectionManager. This rule flags the deprecated com.ibm.websphere.cache. DistributedObjectCache. TYPE_DISTRIBUTED_LOCKING_MAP field and the removed com.ibm.websphere.cache. DistributedLockingMap interface. This rule flags the use of the deprecated constructor and fields from the com.ibm.websphere.naming.DumpNameSpace class.

Do not used the deprecated distributed locking map field and removed interface

No

Avoid using the deprecated DumpNameSpace constructor and fields

No

Application Migration Tool | WebSphere Application Server version migration rules and quick fixes | 31

Rule Name Avoid using the deprecated DynamicCacheAccessor methods

Quick Fix No

Action Taken

This rule flags the use of the deprecated methods from the com.ibm.websphere.cache.DynamicCacheAccessor class. This rule flags the use of the deprecated methods and fields from the com.ibm.websphere.cache.CacheEntry and the com.ibm.websphere.cache.EntryInfo interfaces. This rule flags the use of the com.ibm.websphere.ejbpersistence. EJBToRAAdapter.createInteraction (javax.resource.cci.Connection conn) method. This rule detects and flags the method registerSynchronizationCallbackFor CurrentTran from the class ExtendedJTATransaction. This rule flags the use of the HttpServletRequestProxy and HttpServletResponseProxy classes. This rule flags the use of the com.ibm.websphere.sib.admin. SIBTransmitMessageRequest interface. The quick fix replaces the interface with the com.ibm.websphere.sib.admin. SIBMessageRequest interface.

Avoid using the deprecated dynamic cache methods and fields

No

Avoid using the deprecated EJB persistence createInteraction method

No

Avoid using the deprecated ExtendedJTATransaction method registerSynchronizationCallbackFor CurrentTran Avoid using the deprecated HttpServlet request/response proxy classes Avoid using the deprecated interface SIBTransmitMessageRequest

No

No

Yes

Avoid using the deprecated JRas extension APIs Avoid using the deprecated LocalHomeAccessor class

No

This rule flags deprecated Java reliability, availability, and serviceability APIs. This rule flags the use of the com.ibm.websphere.ejbcontainer. LocalHomeAccessor class. This rule flags the use of the com.ibm.websphere.management.exception. InvalidDocumentURIException class. The quick fix changes the code to use DocumentNotFoundException.

No

Avoid using the deprecated management InvalidDocumentURIException class

Yes

Avoid using the deprecated management NestedAdminException class Avoid using the deprecated management NotificationConstants TYPE_AGENT_DISCOVERED field

No

This rule flags the use of the com.ibm.websphere.management.exception. NestedAdminException class. This rule flags the use of the NotificationConstants.TYPE_AGENT_DISCOVERED field.

Yes

32 | Application Migration Tool | WebSphere Application Server version migration rules and quick fixes

Rule Name

Quick Fix

Action Taken The quick fix replaces references to this field with the NotificationConstants.TYPE_DISCOVERY_AGENT_FOUND field.

Avoid using the deprecated management removeNotificationListenerExtended methods

No

This rule flags the use of the deprecated removeNotificationListenerExtended methods from the com.ibm.websphere.management.AdminService and com.ibm.websphere.management.AdminClient classes. This rule flags the use of the com.ibm.websphere.management.statistics package. The quick fix changes all references of com.ibm.websphere.management.statistics to javax.management.j2ee.statistics and all reference of MessageBeanStats to MessageDrivenBeanStats.

Avoid using the deprecated management statistics interfaces

Yes

Avoid using the deprecated methods from WebSphere SIB MQ classes

Yes

This rule flags the use of the getNpmSpeed() and getStatus() methods from SIB MQ classes. The quick fix changes the methods to the recommended replacements.

Avoid using the deprecated naming properties INITIAL_CONTEXT_ FACTORY_LEGACY field

Yes

This rule flags the use of the com.ibm.websphere.naming. PROPS.INITIAL_CONTEXT_FACTORY_LEGACY field. The quick fix changes all references to this field to com.ibm.websphere.naming. PROPS.INITIAL_CONTEXT_FACTORY.

Avoid using the deprecated PMI Client API Avoid using the deprecated PmiConstants fields Avoid using the deprecated PmiDataInfo getParticipation method

No No No

This rule flags the use of PMI Client API classes. This rule flags the use of deprecated PmiConstants fields. This rule flags the use of the com.ibm.websphere.pmi.PmiDataInfo. getParticipation() method. This rule flags the use of the deprecated com.ibm.websphere.pmi.stat. WSDynamicCacheStats.OBJECT_CACHE_GROUP field. The quick fix changes OBJECT_CACHE_GROUP to OBJECT_GROUP.

Avoid using the deprecated PMI dynamic cache OBJECT_CACHE_GROUP field

Yes

Avoid using the deprecated PMI dynamic cache SERVLET_CACHE_GROUP field Avoid using the deprecated PmiJmxTest methods

No

This rule flags the use of the deprecated com.ibm.websphere.pmi.stat. WSDynamicCacheStats.SERVLET_CACHE_GROUP field. This rule flags the use of the deprecated methods from the com.ibm.websphere.pmi.PmiJmxTest class.

No

Application Migration Tool | WebSphere Application Server version migration rules and quick fixes | 33

Rule Name Avoid using the deprecated PMI MBeanLevelSpec methods

Quick Fix No

Action Taken

This rule flags the use of the deprecated constructors and methods from the com.ibm.websphere.pmi.stat.MBeanLevelSpec class. This rule flags the use of the deprecated com.ibm.websphere.pmi.PmiModuleConfig. print(PrintWriter) method. This rule flags the use of the deprecated constructor and methods from the com.ibm.websphere.pmi.stat.StatDescriptor class. This rule flags the use of the deprecated classes from the com.ibm.websphere.pmi.stat package. This rule flags the use of the deprecated methods from the com.ibm.websphere.pmi.stat.WSStats interface. This rule flags the deprecated RemoteCommandMgr MBean. This rule flags the use of the deprecated resource adapter classes and interfaces. This rule flags the use of the deprecated resource adapter fields. This rule flags the use of the deprecated resource adapter methods. This rule flags the use of methods deprecated from the com.ibm.websphere.runtime.ServerName class. This rule flags the use of the deprecated methods from the com.ibm.websphere.scheduler.MessageTaskInfo class. This rule flags the use of the deprecated createBeanTaskInfo() and createMessageTaskInfo() methods from the com.ibm.websphere.scheduler.Scheduler class. This rule flags the use of the deprecated exception classes com.ibm.websphere.security.auth. MapCredentialFailedException and com.ibm.websphere.security.auth. MapCredentialNotSupportedException. This rule flags the use of the deprecated getCredential() method from the com.ibm.websphere.security.auth.WSPrincipal class.

Avoid using the deprecated PmiModuleConfig print method

No

Avoid using the deprecated PMI StatDescriptor methods

No

Avoid using the deprecated PMI statistic classes Avoid using the deprecated PMI WSStats methods Avoid using the deprecated RemoteCommandMgr MBean Avoid using the deprecated resource adapter classes and interfaces Avoid using the deprecated resource adapter fields Avoid using the deprecated resource adapter methods Avoid using the deprecated runtime ServerName methods Avoid using the deprecated scheduler MessageTaskInfo methods

No

No

No No

No No No

No

Avoid using the deprecated Scheduler methods

No

Avoid using the deprecated security authentication exception classes

No

Avoid using the deprecated security authentication WSPrincipal getCredential method

No

34 | Application Migration Tool | WebSphere Application Server version migration rules and quick fixes

Rule Name Avoid using the deprecated security printStackTrace() methods

Quick Fix No

Action Taken

This rule flags the use of the deprecated printStackTrace() methods from the com.ibm.websphere.security. WSSecurityException and com.ibm.websphere.security.auth. WSLoginFailedException classes. This rule flags the use of the deprecated com.ibm.ws.security.util.LoginHelper class. This rule flags the use of the deprecated servlet cache classes. This rule flags the use of the deprecated methods initialize() and getSharingPolicy() from the com.ibm.websphere.servlet.cache.IdGenerator class. This rule flags the use of the deprecated initialize() method from the com.ibm.websphere.servlet.cache. MetaDataGenerator class. This rule flags the use of the deprecated com.ibm.websphere.sib.mediation. messagecontext.SIMediationBeanMessageContext interface. This rule flags the use of the deprecated com.ibm.websphere.sib.mediation.handler. SIMessageContextException class. The quick fix changes the code to use MessageContextException instead.

Avoid using the deprecated security LoginHelper class Avoid using the deprecated servlet cache classes Avoid using the deprecated servlet cache IdGenerator methods

No

No No

Avoid using the deprecated servlet cache MetaDataGenerator initialize method Avoid using the deprecated SIMediationBeanMessageContext interface

No

No

Avoid using the deprecated SIMessageContextException class

Yes

Avoid using the deprecated TransactionControl interface

No

This rule flags the use of the deprecated com.ibm.ws.extensionhelper. TransactionControl interface. This rule flags the use of UDDI Version 2 related packages. This rule flags the use of the deprecated methods from the com.ibm.websphere.wssecurity. callbackhandler.UNTGenerateCallback class. The quick fix changes the methods to the recommended replacements.

Avoid using the deprecated UDDI Version 2 interfaces Avoid using the deprecated UNTGenerateCallback methods

No Yes

Avoid using the deprecated WASProduct class

No

This rule flags the deprecated com.ibm.websphere.product.WASProduct class was used to get installed product information and history. This rule flags the deprecated web container custom extension classes from the com.ibm.servlet package.

Avoid using the deprecated web container custom extension classes

No

Application Migration Tool | WebSphere Application Server version migration rules and quick fixes | 35

Rule Name Avoid using the deprecated WebContainer MBean operations

Quick Fix No

Action Taken

This rule flags references to the deprecated WebContainer MBean operations startTransports, stopTransports, and restartWebApplication. This rule flags the use of the deprecated WebSphere Ant class com.ibm.websphere.ant.tasks. ModuleValidator. This rule flags the use of the deprecated WebSphere Studio tools runtime classes from the com.ibm.webtools.runtime package. This rule flags the deprecated WSAddressing for JAXWS 2.0 classes from the com.ibm.websphere.wsaddressing.jaxws package. This rule flags use of deprecated fields from the com.ibm.websphere.naming.WsnBatchResult class. The quick fix changes the fields to the recommended replacements.

Avoid using the deprecated WebSphere Ant class ModuleValidator Avoid using the deprecated WebSphere Studio tools runtime classes Avoid using the deprecated WSAddressing for JAXWS 2.0 classes Avoid using the deprecated WsnBatchResult fields

No

No

No

Yes

Table 13: Java deprecated features - Migration to V8.0 Rule Name Avoid extending the AppDeploymentTask class Quick Fix No Action Taken

This rule flags any class that extends com.ibm.websphere.management.application. client.AppDeploymentTask. This rule flags the use of the deprecated fields from the com.ibm.websphere.management.application. AppConstants class. This rule flags the use of the deprecated methods from the com.ibm.websphere.management.application. AppManagementBaseFactory class. This rule flags the deprecated classes from the com.ibm.websphere.product packages. This rule flags the use of the deprecated elements from the com.ibm.websphere.management.application. EditionInfo class. This rule flags the use of the deprecated elements from the com.ibm.websphere.servlet.filter. IFilterConfig interface. This rule flags the use of the deprecated field taskHelperSuffix from the class com.ibm.websphere.management.application. client.AppDeploymentController.

Avoid using the deprecated AppConstants fields

No

Avoid using the deprecated AppManagementBaseFactory methods Avoid using the deprecated com.ibm.websphere.product classes Avoid using the deprecated elements in the EditionInfo class

No

No

No

Avoid using the deprecated elements in the IFilterConfig interface

No

Avoid using the deprecated field in the AppDeploymentController class

No

36 | Application Migration Tool | WebSphere Application Server version migration rules and quick fixes

Rule Name Avoid using the deprecated IRequest isStartAsync() method

Quick Fix No

Action Taken

This rule flags the use of the deprecated method isStartAsync() from the interface com.ibm.websphere.servlet.request.IRequest. This rule flags the deprecated com.ibm.websphere.product.WASDirectory methods and related fields. This rule flags the use of the deprecated WebSphere Studio Application Developer Integration Edition libraries.

Avoid using the deprecated WASDirectory methods and fields

No

Avoid using the deprecated WebSphere Studio Application Developer Integration Edition libraries

No

Table 14: Java deprecated features - Migration to V8.5 Rule Name Avoid using the deprecated Common Event Infrastructure packages Avoid using the deprecated WSSecurityHelper getLTPACookieFromSSOToken method Avoid using the deprecated WSSecurityHelper revokeSSOCookies method Quick Fix No Action Taken

This rule flags APIS from the deprecated com.ibm.events packages. This rule flags the deprecated com.ibm.websphere.security.WSSecurityHelper getLTPACookieFromSSOToken method. This rule flags the deprecated com.ibm.websphere.security.WSSecurityHelper revokeSSOCookies method.

Yes

Yes

Table 15: JSP file deprecated features - Migration to V7.0 and V8.0 Rule Name Avoid using the deprecated JSP <tsx> tags Quick Fix No Action Taken

This rule flags the use of the deprecated <tsx> tags in JSP files.

Table 16: XML file deprecated features - Migration to V7.0 and V8.0 Rule Name Avoid using the deprecated methodlevel access intent for entity beans Avoid using the deprecated reload attributes of the IBM deployment descriptor extensions Quick Fix No No Action Taken

This rule flags the use of method-level access intent on entity beans. This rule flags the deprecated reloadInterval and reloadingEnabled attributes of the IBM deployment descriptor extensions, including both the WAR file extension (WEB-INF/

Application Migration Tool | WebSphere Application Server version migration rules and quick fixes | 37

Rule Name

Quick Fix

Action Taken ibm-web-ext.xmi) and the application extension (META-INF/ibmapplication-ext.xmi).

38 | Application Migration Tool | Java SE version migration

Java SE version migration

Under the Java Code Review set of rules, Java SE Migration category contains rules for migrating from J2SE 1.4, J2SE 5.0, or Java SE 6. Java migration targets are Java SE 6 and Java SE 7. These rules were previously in the WebSphere Version to Version migration tool and are now available for the competitive tools. The Sun to IBM Java compatibility impacts category provides a set of rules to migrate Sun APIs that are not available on the IBM Java Runtime Environment. Where possible, the rules migrate the code to use javax.net or com.ibm.net.ssl classes. The specific rules selected depends on your selection of the source Java Runtime Environment that your application previously used and the version of WebSphere you are migrating to. For WebSphere Application Server V8.5, you can choose either Java SE 6 or Java SE 7 as your target. Quick fixes are available where possible. Rules without quick fixes flag the rule violations so you can evaluate their usage and migrate the code manually if needed. Table 17: J2SE 5.0 compatibility impacts Rule Name Check for JAXP API usage compatibility Quick Fix No Action Taken

The JAXP APIs used in JRE 1.4.2 might have compatibility issues when used in JRE 5. This rule detects the import of any JAXP-related packages so that you can check the usage. JAXP EntityResolver.resolveEntity(String, String) now throws the exception, IOException, in addition to SAXException. This rule detects the missing IOException. New JAXP DOM APIs where added to the following interfaces: org.w3c.dom.Attr org.w3c.dom.Document org.w3c.dom.DOMImplementation org.w3c.dom.Element org.w3c.dom.Entity org.w3c.dom.Node org.w3c.dom.Text

Check for JAXP EntityResolver.resolveEntity() exception compatibility Check for new JAXP DOM APIs

No

No

This rule detects classes that implement any of these interfaces and flags them so that the new interfaces can be added. Check Java Object Serialization compatibility No Serialization in not consistent between Java 1.4 and Java 5.0. This rule detects the classes that implement java.io.Serializable without a serialVersionUID field. The IBMJSSEFIPS provider has been included in the IBMJSSE2 support. References to the classes of the previous provider, com.ibm.fips.*, must be removed. This rule detects the use of any reference to com.ibm.fips packages.

Do not make direct references to IBMJSSEFIPS provider classes

No

Application Migration Tool | Java SE version migration | 39

Rule Name Do not use APIs from com.ibm.net.ssl packages

Quick Fix Yes

Action Taken

The classes and interfaces in the com.ibm.net.ssl package have been replaced by classes and interfaces in the javax.net.ssl package. This rule detects the use of any reference to com.ibm.net.ssl packages. The quick fix changes package names com.ibm.net.ssl to javax.net.ssl.

Do not use APIs from sun.* packages

No

Some APIs in the sun.* packages changed in JRE 5 and have compatibility issues with JRE 1.4.2. These APIs are not intended for use by developers. This rule detects the use of any reference to sun.* packages. Internal JAXP classes changed. Do not use these internal classes in these packages: 1. 2. 3. 4. 5. org.apache.crimson.* org.apache.xml.* org.apache.xalan.* org.apache.xpath.* org.apache.xalan.xsltc.*

Do not use JAXP 1.1 internal classes

No

This rule detects the use of these packages and flags them. Do not use JAXP 1.1 package names in string literals No Some of the implementation package names changed between JAXP 1.1 and JAXP 1.3. This rule detects JAXP 1.1 package names used in string literals. In the conversion from IBMJSSE to IBMJSSE2 two of the JSSE classes were removed. This rule detects the use of any reference to com.ibm.jsse. KeyManagerFactoryParametersSpec and com.ibm.jsse.SSLContext. Since com.ibm.net.ssl. KeyManagerFactoryParametersSpec was migrated to com.ibm.jsse. KeyManagerFactoryParametersSpec and then removed from use, com.ibm.net.ssl. KeyManagerFactoryParametersSpec is also detected with this rule. Beginning in Java 5.0, enum is a reserved Java type and cannot be used as a variable name any longer. If your code uses variables named enum, they must be renamed. This rule detects variables and arguments named enum. The BigDecimal toString() method behaves differently than in earlier versions. J2SE 5.0 added toPlainString() to BigDecimal, which behaves like the toString() method in earlier versions. This rule detects the implicit use of the toString() method in a class.

Do not use removed IBMJSSE APIs

No

Do not use the Java reserved word enum

No

Use the BigDecimal toPlainString() method explicitly when deriving a string value

No

40 | Application Migration Tool | Java SE version migration

Rule Name Use the BigDecimal toPlainString() method instead of the toString() method

Quick Fix Yes

Action Taken

The BigDecimal toString() method behaves differently than in earlier versions. J2SE 5.0 added toPlainString() to BigDecimal, which behaves like the toString() method in earlier versions. The quick fix changes toString to toPlainString.

Use the IBMJSSE2 Provider

Yes

In the conversion from IBMJSSE to IBMJSSE2, the providers, IBMJSSEProvider and JSSEProvider, are replaced by IBMJSSEProvider2. This rule detects the use of any reference to com.ibm.jsse.IBMJSSEProvider and com.ibm.jsse.JSSEProvider classes. The quick fix changes the reference to com.ibm.jsse2.IBMJSSEProvider2.

Table 18: Java SE 6 compatibility impacts Rule Name Check exception logic for calls to EventHandler Quick Fix No Action Taken

In Java SE 6, the EventHandler constructor and create() methods require non-null parameters to be passed. This rule flags the constructor and create() method calls so that you can verify your logic handles a NullPointerException properly. Detect the use of Duration and XMLGregorianCalendar equals() method. Java 6 now returns false if the parameter passed is null. The exception, NullPointerException, was thrown previously. In Java SE 6, the FileChannel.lock() method now throws OverlappingFileLockException. This rule flags the lock() method calls without a catch block for OverlappingFileLockException or without a throws declaration for OverlappingFileLockException on the method. Detect the use of the double-slash character string ("//") in JMX ObjectNames.

Check for Duration and XMLGregorianCalendar equals() compatibility

No

Check for the OverlappingFileLockException for the FileChannel lock() method

No

Remove use of double slashes in JMX ObjectName elements

No

Table 19: Java SE 7 compatibility impacts Rule Name Check for a behavior change for an empty TreeSet add and TreeMap put methods Check for a behavior change for AWT Exception Handler Quick Fix No Action Taken This rule flags the use of java.util.TreeSet or java.util.TreeMap. Depending on the configuration of the rule, either the constructor or the add()/put() methods of these classes will get flagged. A new behavior is added in Java 7 for these methods. This rule flags the string literal sun.awt.exception.handler. A new exception handling mechanism is added in Java 7.

No

Application Migration Tool | Java SE version migration | 41

Rule Name Check for a behavior change for File setReadOnly, setWritable and canWrite methods Check for a behavior change for URLConnection, HttpURLConnection getInputStream method Check for a behavior change on DatagramChannel send, receive, and connect methods Check for a behavior change on the isLowerCase and isUpperCase methods Check for a behavior change on Locale getDefault method Check for a behavior change on MouseEvent getButton method Check for a behavior change on ThreadGroup setMaxPriority method Check for a behavior change on Toolkit getPrintJob method Check for a behavior change on Window setBackground method Check for classes implementing the TypeVisitor interface Check for new methods on JDBC interfaces

Quick Fix No

Action Taken This rule flags the methods java.io.File setReadOnly(), setWritable(boolean arg) and setWritable(boolean arg, boolean user). A new behavior is added in Java 7 for these methods. This rule flags the getInputStream() method on URLConnection or HttpURLConnection. This method has a new behavior in Java 7. This rule flags calls to the java.nio.channels.DatagramChannel send, receive, and connect methods that have a new behavior in Java 7. This rule flags the isLowerCase and isUpperCase methods. There is a very slight chance that a behavior change in these methods could affect your application. This rule flags calls to the java.util.Locale getDefault() method as it has a new behavior. This rule flags instances of the java.awt.event.MouseEvent getButton() method as it has a new behavior. This rule flags the method setMaxPriority on a ThreadGroup object. The method behavior has changed in JDK 7. This rule flags instances of the java.awt.Toolkit getPrintJob(...) method as it has a new behavior. This rule flags calls to the java.awt.Window setBackground() method because its behavior changed by throwing a new exception. This rule flags classes implementing the javax.lang.model.type.TypeVisitor interface. In Java SE 7, a new method was added to this interface. This rule detects classes that implement the JDBC interfaces that added new methods. The interfaces include java.sql.Connection, java.sql.Driver, java.sql.Statement, and javax.sql.CommonDataSource. This rule detects class that extend java.lang.Throwable that implement methods addSuppressed and getSuppressed which were added as new final methods in Java 7. This rule flags the Path2D getPathIterator methods. These methods are now marked final in Java 7. This rule detects the use of the class org.apache.xalan.client.XSLTProcessorApplet. This class has been removed from JDK 7 release.

No

No

No

No No

No

No No

No

No

Do not define methods declared as final in java.lang.Throwable

No

Do not override the Path2D getPathIterator methods Do not use removed class XSLTProcessorApplet

No No

Run the following rules when you are migrating your application from an Oracle Java Runtime Environment to an IBM Java Runtime Environment. If you are running Liberty profile server using an Oracle Java Runtime, do not run the quick fixes for these rules. Table 20: Oracle to IBM compatibility impacts Rule Name Detect com.sun.net.ssl.internal packages Quick Fix No Action Taken This rule flags import statements of certain com.sun.net.ssl.internal packages in Java files that are not available and should not be used. This rule detects the classes and interfaces in the >com.sun.net.ssl package have been replaced by classes and interfaces in the javax.net.ssl package. This rule flags internal Sun JAXP classes are not available in the IBM Java Runtime Environment. This rule detects com.sun.org.apache JAXP 1.3 package names that are used in string literals. This rule flags the class com.sun.net.ssl.internal.ssl.Provider should be replaced by com.ibm.jsse.IBMJSSEProvider. This rule flags the com.sun.net.ssl.internal.www.protocol. https.Handler class that should be replaced by com.ibm.net.ssl.www2.protocol.https.Handler. This rule flags the com.sun.net.ssl.internal.www.protocol package references that should be replaced by com.ibm.net.ssl.www2.protocol.

Do not use APIs from com.sun.net.ssl packages Do not use com.sun.org.apache JAXP internal classes Do not use com.sun.org.apache JAXP package names in string literals Do not use the com.sun.net.ssl.internal.ssl.Provider Do not use the com.sun.net.ssl.internal. www.protocol.https.Handler class

Yes

No No Yes

Yes

Do not use the com.sun.net.ssl.internal.www.protocol package

Yes

Only run the following rules when you are migrating your application from an Oracle Java Runtime Environment to an IBM Java Runtime that contains the IBM class. For example, the HP-UX and Solaris Java Runtime Environment that ships with WebSphere application server does not contain the class. This rule is not selected automatically by any rule set. Table 21: Sun internal APIs Rule Name Do not use APIs from the sun.security.x509 package Quick Fix Yes Action Taken The classes and interfaces in the sun.security.x509 package are replaced by classes and interfaces in the com.ibm.security.x509 package on some operating systems.

Application Migration Tool | Troubleshooting | 43

Troubleshooting

Software Analyzer options not shown

After an 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. To customize 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 11: Software Analyzer availability

Java EE constructs or JSP not read correctly

For the tools 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-clicking on the project in the project explorer and selecting Properties. Select the Project Facets property. Projects containing web modules must be dynamic web projects. See Importing applications on page 10 for more information.

Logging and trace

The application migration tools write error information to two log files: The workspace log (workspace/.metadata/.log) contains messages logged by the application migration tools as well as messages logged by Rational Software Analyzer. The service logs for the application migration tools 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 trace in the migration tools by setting the appconversion.trace system variable on the command line to launch the IDE or in the eclipse.ini property file; for example:

44 | 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 option 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 that are used to export selected analysis history to file and to generate 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 default PDF viewer. The generated files are put in the workspace/.metadata/.plugins/com.ibm.xtools.analysis.reporting/reports directory.

Markers
Markers are displayed in the left margin of Eclipse editors and provide information about the content of the editor on the line where the marker is displayed. Editors for different file types can have different behaviors for the markers, some of which are described here.

Figure 12: Analysis rule markers in a Java editor No pop-up window displays when clicking on the marker This issue affects non-Java based rules. For a Java rule, clicking on the marker allows the quick fix 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 a marker removes the marker Double-clicking the marker in the file editor removes the marker without applying the quick fix. If this happens, run the analysis again to flag the problem 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 must carry out the action of the first marker to select successive markers. To apply a quick fix in such a case, use the Software Analyzer Results view to select the Quick Fix action you want, rather than relying on the marker.

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

Application Migration Tool | Troubleshooting | 45

If you notice errors being logged when running the Quick Fix All Category option, there are a few things you can do in Eclipse to mitigate issues: In the Window > Preferences > General > Editors, select Close editors automatically and limit the Number of open editors before closing to a reasonable number. The default value is 8 which should be OK, but you can limit it further. You can also choose Run in Background to prevent all the editors from opening and possibly running out of window handles. Disable the automatic build feature of Eclipse (Project > Build Automatically) while running Quick Fix All Category. Manually build the projects and enable the option again after running Quick Fix All Category.

Multiple rules on the same node When multiple rules are flagged on the same node, only the first quick fix applied runs correctly. You might need to run the analysis multiple times to make sure that all code is fixed and processed correctly. Viewing external links from help in Linux Many detailed help pages have external references to information applicable to the specific rule. This information is generally viewed better from an external browser than the Eclipse help view. On Windows platforms, help automatically launches these external references in the default browser. On Linux operating systems, it displays the information in the Eclipse help view. To manually open help in an external browser, use the Show in external window icon ( detailed help page. Java Architectural Discovery rules The Java Architectural Discovery rules are not supported in Rational Application Developer 7.5.x. These rules depend on APIs in Eclipse 3.5 and higher. Do not select the Java Architectural Discovery rules if your development environment is based on Eclipse 3.4.x. Ignore Results If you select Ignore Results on a line of code that is the beginning of a block of Java code with nested results being flagged for the same rule, the nested results line numbers will be set to zero. You can rerun analysis to see the proper line numbers. Examples of statements that cause this issue are method declarations and if statements. View Results for .xmi files If you select View Results for an .xmi file and get an error opening the file, add an .xmi file association. Go to Window > Preferences > General > Editors > File Associations, and click Add... to enter *.xmi. Select either XML Editor or Text Editor, and click the Default button. Click OK to save. Uncategorized plug-ins If you are installing the tools on Rational Application Developer 7.5, it is preferable to not select Uncategorized from the repository site. If you do select Uncategorized, and you want to uninstall the tool, you must manually uninstall these plugins: Analysis Reporting nl1 version Analysis Reporting nl2 version Command Line Analysis Command Line Analysis nl1 version Command Line Analysis nl2 version Compatibility feature Core_feature Feature JEE Code Review JEE Code Review nl1 version JEE Code Review nl2 version ) on the

J2SE Code Review J2SE Code Review nl1 version J2SE Code Review nl2 version Java Architectural Discovery Java Code Review Feature Translations Java Globalization Code Review Java Globalization Code Review nl1 version Java Globalization Code Review nl2 version Java Security Code Review Java Security Code Review nl1 version Java Security Code Review nl2 version ODA Compatability Feature Rational Code Analyst Core Services Feature Rational Software Analyzer Architecture Core Rational Software Analyzer Code Review Core Rational Software Analyzer Java Code Review Rational Software Analyzer Reporting Rational Software Analyzer Reporting ODA RCA Analysis Feature Translations

This problem does not occur in Eclipse 3.5 and higher. Rational Application Developer install dependency conflicts If an application migration tool installation fails with a conflicting dependency error, you may need to remove the Rational Application Developer Code Analysis or Code Review feature. Here is an example of the error: Cannot complete the install because of a conflicting dependency. Software being installed: Application Migration Tool - WebSphere Version to Version 3.0.1.201111170830 (com.ibm.ws.appconversion_feature.was2was.feature.group 3.0.1.201111170830) Software currently installed: Shared profile 1.0.0.1322626949228 (SharedProfile_bootProfile 1.0.0.1322626949228) Only one of the following plugins can be installed at once: Analysis History Data Source ODA Runtime Driver 7.0.100.v20100517_2203 (com.ibm.rsar.analysis.reporting.oda 7.0.100.v20100517_2203) Analysis History Data Source ODA Runtime Driver 7.0.100.201111170830 (com.ibm.rsar.analysis.reporting.oda 7.0.100.201111170830) The solution is to uninstall the Rational Application Developer Code Analysis or Code Review feature. The name used depends on your Rational product version. To do this, start the IBM Installation Manager, and select the Modify option. Select your Rational Application Developer installation from the Modify Packages list. Select next, and clear Code Analysis selection from the list of features. Click Next, and verify that Code Analysis is in the list of features to be be removed. Proceed with the removal of the feature. After Installation Manager completes, try the toolkit installation again. Java Code Review Severity Summary HTML report in Windows fails to display The Java Code Review Severity Summary HTML report in Windows does not display in the Eclipse HTML viewer unless you are using Internet Explorer 9 which supports SGV image files. There are two ways to work around the issue. You can choose to produce a PDF file instead of HTML. Alternatively, you can produce the HTML file, right click on the view to Create Shortcut, then open the short cut using a browser, such as FireFox, that supports SVG files on Windows.

Application Migration Tool | Copyright and trademarks | 47

Copyright and trademarks

Copyright IBM Corporation 2009, 2012.

The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM's current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the 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 all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM's sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth, savings or 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, including considerations such as the amount of multiprogramming in the user's job stream, the I/O configuration, the storage configuration, and the workload processed. Therefore, no assurance can be given that an individual user will achieve results similar to those stated here. IBM, the IBM logo, developerWorks, Passport Advantage, Rational, and WebSphere are trademarks of International Business Machines Corporation in the United States, other countries or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Other product and service names might be trademarks of IBM or other companies.