[V5.1 and later]Migrating

Migrating is an activity in which you take advantage of existing materials. Migration tasks and tools help you upgrade the product and its prerequisites, reuse existing application components when feasible, and transfer administrative configurations from your past version to a current one.

Migration of WebSphere Application Server products is about leveraging the existing environment and applications and changing them to be compatible with the current product version.

[V5.1 and later]Product migration functions are provided by the migration tools in IBM WebSphere Application Server Network Deployment, V5.1. The migration tools perform V3.5.x, Version 4.0.x, and V5.0.x migrations. The product installation wizard can call these tools, or you can start these tools directly.

Migration Redbook

Migrating to WebSphere V5: An End-to-End Migration Guide is available from the Redbooks Web site at http://www.ibm.com/redbooks . To locate the Redbook, search for the document number SG24-6910-01. The Redbook provides a broader coverage than the information center articles, including more detailed planning information for application migration and WebSphere Studio Application Developer tooling and samples. Migrating Applications from WebSphere for z/OS V4 and V3.5 to V5 is also available from the Redbooks Web site. Search on document number SG24-7044-00 to locate this book.

Version 5.0.x migration[V5.1 and later]

Migration from V5.0.x to V5.1 involves minimal change because both releases implement the Java 2 Platform, Enterprise Edition (J2EE) 1.3 specification. V5.0.x supports the Java 2 SDK Version 1.3.1. V5.1 supports the Java 2 SDK V1.4.1. V5.0.x applications can run on either release without change. V5.1 applications can run on either release without change if you compile applications on a V5.1 node with the compatibility options. See the "Changes for application developers" section for more information.

There are several considerations. There are new migration tools for V5.1 to help migrate federated nodes and nodes with the embedded messaging feature installed. Use the new tools when uninstalling a node you migrate or when uninstalling the V5.1 node, if you decide to keep using the previous node. One set of tools prevent the deployment manager from removing the node as a member of the cell. The other new set of tools prevents uninstalling the messaging queue manager and deleting the code for embedded messaging feature.

The WASPreUpgrade and the WASPostUpgrade migration tools are also updated for V5.1. Verify that you use the WASPreUpgrade tool from the migration directory on the CD-ROM if you intend to save a configuration from a previous product, install V5.1, and restore the configuration. You must use the V5.1 version of the WASPreUpgrade tool to save a configuration that you intend to add to a V5.1 node.

Version 4.x migration[V5.1 and later]

Migration from V4.x to V5.1 involves minimal change because both releases implement the Java 2 Platform, Enterprise Edition (J2EE) specification. (V4 implements the J2EE 1.2 specification. V5.1 implements the J2EE 1.3 specification.) Most V4.x applications can run without change.

Despite this fact, knowledge of how the migration tools migrate V4.x applications is important. For example, extended messaging support service is now a component of WebSphere Business Integration Server Foundation, V5.1. Applications that use V4.x extended messaging support services require migration to use in an Integration Server system.

V3.5 migration: Moving to the J2EE model

V3.5.x users upgrading to V5 are moving to a platform that is fully compliant with J2EE specifications. J2EE technology clearly separates development and the creation of applications from application administration, deployment and management. Migration from V3.5 involves changes in application structures, development, and deployment.

[V5.1 and later]The migration tools assist in the transition from V3.5.x to V5.1 by migrating system configurations and creating J2EE artifacts, including J2EE security roles mapping. The migration tools create initial J2EE enterprise applications based on V3.5.x configurations. However, because of the significant change in application structures, plan to carefully test and tune migrated applications, using development and deployment tools, to determine exactly how the applications function in the new environment.

The J2EE model enables you to develop applications independently from their final deployment environment. This task separation simplifies the process of promoting an application from initial development through production, or moving an application from one server to another. The intent is to change only the application deployment parameters, and not the application code.

New assembly and deployment user roles and tools

Version 3.5.x and V4.x users perform application tasks through the administrative console.

[V5.1 and later]V5 application settings are defined in J2EE deployment descriptors, by application assemblers using the assembly toolkit, which is available on the IBM WebSphere Application Server Toolkit (ASTK) CD-ROM. A deployer follows the instructions in the deployment descriptor to install the application into a particular server environment. (See Deploying).

V5 administration

V5 administrators can install a Version 5 application onto the server and bind it to an environment. This capability enables administration at the application and module level. Administrators no longer must manage individual servlets, JSP files, or enterprise beans.

The relationship between applications and Application Servers has changed in the move to a J2EE base. After creating a J2EE application, deploy it by installing the application onto Application Servers through the administrative console. Through the administrative console, you can view, start, or stop deployed modules by the application to which they belong or by the Application Server on which they are deployed.

Support for J2EE resources. In addition to JDBC drivers and data sources, several resource types are added as the product transitioned to a J2EE base. Administrators now can configure URLs, the Java Message Service (JMS), and the JavaMail API. In each case, you can create a resource provider (such as a JMS provider) and then create resource factories for each provider (such as JMS destinations and JMS connections). The default JavaMail API provider does not appear in the administrative console because it is not configurable. You cannot create additional JavaMail API providers.

More information about the J2EE standard is available from the links in Installation: Resources for learning.

Role based security. V5 security is consistent with J2EE role-based security specifications. Deployment descriptors specify roles for an application. As the administrator installs the application, these roles are bound to users or to groups.

In the administrative console, a Security Center lets you perform all security tasks from a single location. Such tasks include everything from changing the binding information for roles in an application to setting Secure Sockets Layer (SSL) properties to enabling security. Application-specific security tasks are also supported, through the property sheets for each application.

Changes for application developers

V3.5.x and V4.x developers use the administrative console to create, edit, and view application configurations.

[V5.1 and later]V5.1 developers use the assembly toolkit, which is available on the IBM WebSphere Application Server Toolkit (ASTK) CD-ROM to package, edit, and view J2EE applications.

Packaging J2EE applications includes:

[V5.1 and later]In V5.1, the assembly toolkit is available on the IBM WebSphere Application Server Toolkit (ASTK) CD-ROM. The assembly toolkit lets you copy files with appropriate relative paths into the archive and provides a GUI method for defining deployment descriptors. Also, developers can set environment-specific binding information through the assembly toolkit. These bindings are defaults for the administrator to use when installing the application through the administrative console.

You can define IBM extensions to the J2EE specification, for example supporting servlets to be served by class name. These extensions are saved in an XML file that is separate from the standard J2EE deployment descriptor to ensure portability to other Application Servers.

[V5.1 and later]If your existing applications use IBM extensions from earlier product versions, it might be necessary for you to perform mandatory or optional migration to use the same kinds of extensions in V5.1.

V5.1 supports the Java 2 SDK V1.4.1. There are several implications for migration and coexistence. The V5.1 Network Deployment cell is a mixed node environment, where some Application Server nodes might be V5.0.x running Java 2 SDK 1.3.1 and some nodes might be V5.1 nodes running Java 2 SDK 1.4.1.

Applications compiled on V5.0.x nodes can also run on V5.1 nodes. The IBM SDK 1.4.1 in V5.1 provides this backward compatibility.

There is also a cross compiler option for the IBM SDK 1.4.1 that supports compiling code against a bootstrap and extension classes of a previous IBM SDK version. By default, the javac compiler compiles against the bootstrap and extension classes on its platform: the IBM SDK 1.4.1 compiles for 1.4 by default. You can use the IBM SDK 1.4.1 to compile for IBM SDK 1.3.1 compatible output. For example, a developer can issue this command on a V5.1 node to compile against a 1.3 target: 

/ javac -target 1.3 -bootclasspath jdk1.3\lib\classes.zip \ -extdirs "" OldCode.java

The compiled code runs on a 1.3 Java virtual machine (JVM). The -target 1.3 parameter generates class files that are compatible with 1.3 JVMs. If you do not specify the -target option, the -bootclasspath option and the -extdirs option, the compiled code runs on 1.4 JVMs only. You must specifically compile for 1.3 JVMs on a V5.1 node, to avoid compiling against a Java 2 Platform API that is not present on a 1.3 JVM. A 1.4 application fails at run time on a V5.0.x node.

Migrating APIs and specifications

[V5.1 and later]Migrating APIs and specifications means moving to the current Java component level and to other technologies that IBM WebSphere Application Server, V5.1 supports.

Migrating APIs and specifications also includes moving to the most contemporary open specification levels. If your existing applications currently support different specification levels than those supported by this product version, updating at least some aspects of the applications to comply with the new specifications is probable.

[V5.1 and later]From V3.5.x to V5.1, the main migration areas include IBM extensions and the Java 2 SDK. In contrast, little migration is necessary to move from Version 4.x to V5.1.

[V5.1 and later]The following table summarizes potential migration areas.

Functional area Support in V3.5.x or V4.x Must migrate from V3.5.x? Must migrate from V4.x? Must migrate from V5.0.x? Details
Enterprise beans EJB 1.0 Yes Not applicable Not applicable Many EJB 1.0 applications can run unchanged in V5.1 although some changes might be required or recommended. See Migrating enterprise bean code to the supported specification.
EJB 1.1 Not applicable No No Full support for EJB 1.1 is provided. See Migrating enterprise bean code to the supported specification.
Java 2 Connectors Java 2 Connectors Not applicable Yes No The preliminary Java 2 Connector support in V4.x is completed in V5.1. Some changes might be necessary to take full advantage of this support. See J2EE Connector Architecture migration tips.
JDBC API JDBC API Yes Not applicable No Many applications can run unchanged in V5.1 although some changes might be required or recommended. See Migrating a version 4.0 data access application to version 5.1.
JavaServer Pages (JSP) files JSP 1.0 Specification No No No JSP 1.0 APIs are a pure subset of JSP 1.2. See Developing JavaServer Pages files with WebSphere extensions.
JSP 1.1 Specification Not applicable No No JSP 1.1 APIs are a pure subset of JSP 1.2. See Developing JavaServer Pages files with WebSphere extensions.
Security IBM security Yes Yes No Changes might be required due to J2EE security. See Migrating security configurations from previous releases.
Servlets Servlet 2.1 Specification and IBM extensions Yes Yes No Many Servlet 2.1 applications can run unchanged in V5.1 although changes might be required or recommended. See Developing servlets with WebSphere Application Server extensions.
Servlets Servlet 2.2 Specification No No No Servlet 2.2 APIs are a pure subset of Servlet 2.3. See Developing servlets with WebSphere Application Server extensions.
Sessions IBM sessions Yes Yes No Many applications can run unchanged in V5.1 although changes might be required or recommended. See Developing session management in servlets and Migrating HTTP sessions.
Transactions IBM transactions Yes No No A change in the import statement. Also, one datasource connection cannot be used across multiple user transactions. See Using the transaction service.
Web services Apache (SOAP) 2.2 Not applicable Yes No WSIF API
XML parser XML 2.0.x supported Yes Not applicable Not applicable Changes to move to the supported API XML4J V4.2.2 level are required. See TITLE NOT DEFINED and TARGET NOT FOUND FOR LOOKUP.
XML parser XML4J V3.1 Not applicable Yes Not applicable Recompilation is required to convert to XML4J V4.2.2. See TARGET NOT FOUND FOR LOOKUP.
XML parser XML4J V4.0.6 Not applicable Not applicable Yes Recompilation is required to convert to XML4J 4.2.2. See XML parser for Java code.
XML configuration tool XMLConfig Yes Yes No Use the JMX support provided by wsadmin. See Migrating from wscp V4.0 to wsadmin V5.x.
WebSphere Control Program (WSCP) WSCP Yes Yes No Use the JMX support provided by wsadmin. See Migrating from wscp V4.0 to wsadmin V5.x.


Related tasks
Migrating a JMS listener application to use message-driven beans