Introduction

If you've been using WebSphere® Application Server Version 3.x, you'll find that Version 4 necessitates some major changes in how you install and manage applications. This article identifies important differences in how you work with the two releases, and provides a concise guide to migrating existing Version 3.x applications to Version 4. Additional information is found in the WebSphere Application Server V4.0 Information Center.

While this article focuses on WebSphere Application Server, Advanced Edition, the migration tools discussed will also migrate to WebSphere Application Server, Advanced Single Server Edition.

Back to top

Major changes

WebSphere Application Server V4.0 introduces many new capabilities, the most obvious of which is full support of the J2EE 1.2 specification. One of the biggest changes this brings about is in the packaging of application components. WebSphere Application Server V3.x allowed, but didn't require, you to create enterprise applications to group application components such as EJBs, JSPs, Servlets, HTML pages, and other application resources into single units for ease of management. To manage all of the configuration information for these components, you used the Administrative Console or the WSCP (WebSphere Control Program) or XMLConfig to modify information stored in the WebSphere repository.

J2EE 1.2 requires much of this application configuration information to be stored in deployment descriptor XML files, which are packaged along with your application code and resources into Java Archive (.jar) files and Web Archive (.war) files. These Java^TM archives and Web archives are then packaged in an Enterprise Archive (.ear) file along with an enterprise application deployment descriptor XML file.

Security is another major area of change with the transition from the WebSphere security authorization model to role-based security. In V3.x, users or groups could receive access to specific groups of servlet methods and EJB methods using method groups. J2EE 1.2 uses security roles, whereby the application developer specifies which roles have the authority to access specific methods, and the deployer maps these roles to specific users or user groups. J2EE also provides for role references, which let the deployer use different names for roles than those the developer of a specific module used inside the module.

Back to top

Migration overview

Migration to WebSphere Application Server V4.0, Advanced Edition, from V3.x (Advanced Edition or Standard Edition) involves a number of tasks, such as repackaging the existing applications into J2EE applications, migrating the existing V3.x configuration information, and making any necessary application code changes required by the new level of supported J2EE specifications. Fortunately, V4 includes two migration tools, WASPreUpgrade and WASPostUpgrade, to ease the transition from V3.0 (starting with V3.0.2) or V3.5 (starting with V3.5.1).

You can follow one of three approaches for migrating to WebSphere Application Server V4.0:

1. Manual migration. Manually migrate all of your applications by using the Application Assembly Tool (AAT) to manually create J2EE applications, and manually configure your V4 domain using the WebSphere Administrative Console.
2. Using the upgrade tools. Use the two V4 migration tools, WASPreUpgrade and WASPostUpgrade, from a command window to migrate your applications and domain configuration after V4 is installed.
3. Installation integrated migration. Let the WebSphere Application Server installation program migrate your applications and domain configuration during the installation process. (The installation program will also run WASPreUpgrade and WASPostUpgrade for you.)

Back to top

Approach 1: Manual migration

The manual approach involves the following steps:

1. Back up WebSphere Application Server V3.x administrative configuration.
2. Back up application code and resources.
3. Uninstall WebSphere Application Server V3.x.
4. Install any new prerequisite software and operating system patches required by WebSphere Application Server V4.
5. Install WebSphere Application Server V4.
6. Repackage application code, resources, and deployment information as J2EE applications.
7. Convert security settings to the J2EE roles-based security model.
8. Migrate WebSphere Application Server V3.x administrative configuration into the V4 administrative repository.
9. Upgrade application code to be J2EE 1.2 compliant.

(You may notice that the WebSphere Application Server InfoCenter topic 3.2.2, Migrating from Version 3.x, outlines only six migration steps. I've expanded several of the InfoCenter's steps in the list above to clarify what's involved in a manual approach.)

Regarding these steps, here are some things to be aware of:

• In step 6: WebSphere Application Server V4.0 includes the Application Assembly Tool (AAT) to guide the user through the process of creating a J2EE 1.2-compliant enterprise application and the associated J2EE modules from existing Web application components. The AAT isn't primarily a migration tool, but you can use it (after WebSphere Application Server V4.0 is installed) to manually create J2EE applications from existing V3.x application components or to modify existing J2EE applications. You can start AAT by running the command assembly from a command window or on Windows© systems by selecting Start => Programs => IBM WebSphere => Application Server V4.0 AE => Application Assembly Tool.
• In step 7: You can use the AAT, along with the WebSphere Application Server V4 Administrative Console's Security Center to setup WebSphere Application Server security and to define application roles.
• In step 8: The manual process involves using the WebSphere Application Server V4 Administrative Console to modify the V4 configuration to match the settings you had in your V3.x configuration.

Back to top

Approach 2: Using the upgrade tools

With this approach, you use two tools, WASPreUpgrade and WASPostUpgrade, which automate much of the migration process. This approach involves the following steps:

1. Install any new prerequisite software and operating system patches required by V4.
2. Install WebSphere Application Server V4 to a different directory than your V3.x installation. (This step also installs the WASPreUpgrade and WASPostUpgrade tools.)
3. Start WebSphere Application Server V3.x administrative server.
4. Run WASPreUpgrade.
5. Uninstall V3.x.
6. Run WASPostUpgrade.
7. Upgrade application code to be J2EE V1.2 compliant.

After being installed, the WASPreUpgrade and WASPostUpgrade tools can be run from a command window. Basically, WASPreUpgrade performs steps 1 and 2 of manual Approach 1, and WASPostUpgrade takes the place of steps 6 through 8 of Approach 1. Additionally, WASPostUpgrade will also import the migrated configuration using XMLConfig, but only when it is called from a command window.

WASPreUpgrade: What it does

The WASPreUpgrade tool automates the process of saving the existing V3.x configuration and applications. WASPreUpgrade requires the V3.x administrative server be running and accessible from the node that's being migrated.

The WASPreUpgrade tool exports the V3.x (Advanced Edition or Standard Edition) configuration information to an XML file with the default name of websphere_3x_backup.xml. It then copies additional files and directories into a specific directory structure, which is subsequently used by the WASPostUpgrade tool. The default directory is /was3_backup. The installation GUI will prompt for this directory name, or you can pass it as a parameter to WASPreUpgrade and WASPostUpgrade when you run these tools from a command window.

The directory structure that WASPreUpgrade creates and WASPostUpgrade requires is as follows (directory names are preceeded with a /):

/was3_backup 
    websphere_3x_backup.xml 
    /websphere_3x_backup.userFiles 
        /hosts 
        /servlets 
        /classes 
        /deployableEJBs 
        /deployedEJBs 
    /websphere_3x_backup.programFiles 
        /properties 
        /bin

(The only file needed from the bin directory is admin.config.)

WASPreUpgrade copies the V3.x admin.config file into the bin subdirectory in the directory structure shown above and then copies the other V3.x /WebSphere/AppServer/ directories listed above in their entirety.

Although WASPreUpgrade creates the appropriate directory structure and includes the necessary files, it's also possible to do this manually. You could manually create the websphere_3x_backup.xml file using the XMLConfig tool from V3.0.2.2 or later. You can perform a full or partial export, depending on what you want migrated; however, with a partial export, the security information isn't included. Therefore, it would be better to do a full export and then edit the resulting XML file to remove the applications you don't want to migrate.

The primary difference between the XML file that's created by XMLConfig in V3.x and the one created by WASPreUpgrade is that WASPreUpgrade performs encoding on the passwords before exporting them. XMLConfig in V3.x exports them as clear text or as substitution variables. (The V4.0 XMLConfig encodes passwords on output but can #x201cread#x201d passwords in either encoded or clear text form.)

WASPostUpgrade: What it does

The WASPostUpgrade tool automates the process of repackaging existing enterprise applications and Web applications into J2EE applications, converting security settings to the J2EE roles-based security model, and converting the V3.x configuration information into the V4.0 administrative repository and J2EE deployment descriptors:

• WASPostUpgrade processes the websphere_3x_backup.xml file and outputs the converted file websphere_4x_restore.xml. During this process, WASPostUpgrade also creates Web modules packaged in WAR files and EJB modules packaged in JAR files. Then, WASPostUpgrade creates a J2EE application packaged in an EAR file that contains these Web and EJB modules.
  
  
• WASPostUpgrade also creates deployment descriptor files based on the V3.x configuration. It then inserts the deployment descriptor files along with the corresponding application code and resources into the appropriate modules.
  
  
• For an EJB module to be installed and run in V4, it must have new deployment code generated. WASPostUpgrade calls EJBdeploy to automatically generate the deployment code for Bean Managed Persistence (BMP) entity beans and Container Managed Persistence (CMP) entity beans that were deployed and installed using the V3.x Administrative Console (top-down mapping).
  
  
• When mapping CMP entity beans to database tables, EJBDeploy uses different table/schema rules in V4.0 than it did in V3.5. WASPostUpgrade calls EJBDeploy using the arguments -35 -dbschema EJB to preserve the existing table/schema rules.
  
  
• WASPostUpgrade does not generate WebSphere Application Server v4.0 deployment code for CMP entity beans with bottom-up or meet-in-the-middle mapping. However, if you wish to do this:
  
  
  • Use WebSphere Studio Application Developer or VisualAge for Java Version 4 to create the schema and map files. If you're not using one of these development environments you can edit the schema and map files created by the EJBDeploy tool (top-down mapping) to match your existing database tables. The schema and map files are located inside the EJB .jar file. The META-INF/map.mapxmi file describes the mapping of EJB attributes to database columns and the META-INF/schema/schema.dbxmi file describes the database schema. You can find more information about how to modify schema and map files in InfoCenter topics 6.6.0.15.3 and 6.6.0.15.4.
  • Run the EJBDeploy tool for each EJB .jar file from a command line or select File => Generate code for deployment from the AAT main menu. You can find more information about the EJBDeploy tool and its arguments in InfoCenter topic 6.6.0.15.1.
  • In the enterprise application EAR file, replace the original EJB JAR file with the EJB JAR file created with the EJBDeploy tool.
  • WASPostUpgrade doesn't call the EJBDeploy tool with the -cp argument (to specify a classpath). Therefore, EJB JAR files that have classpath dependencies on other EJB JAR files will cause errors in the WASPostUpgrade log file. However, the rest of the J2EE application will be built. To work around these errors, you can run the EJBDeploy tool with the -cp argument and specify the classpath. In the enterprise application EAR file, replace the original EJB JAR file with the one created with the EJBDeploy tool.

Another requirement for an EJB module to be installed in WebSphere Application Server V4 involves the format of the deployment descriptors. WASPostUpgrade migrates the serializable bean deployment descriptors (EJB 1.0 .ser files) for each EJB into a single XML deployment descriptor file. This XML file will contain the deployment information for all of the EJBs in the EJB module (as required by the EJB 1.1 specification) and is necessary to install the EJB module in WebSphere Application Server V4.0.

In addition to WASPostUpgrade, you can use AAT or EJBDeploy to migrate EJB 1.0 JARs into EJB 1.1-compliant modules. All three tools also log warning messages about EJB 1.0 methods that have been deprecated or changed in EJB 1.1. In most cases, the log entry also references the EJB 1.1 specification for details of the change. Although WebSphere Application Server V4.0 still supports the deprecated EJB 1.0 methods, you should modify your code to use EJB 1.1-supported methods, as deprecated methods will be removed in a future version.

You should also be aware of how WASPostUpgrade handles these additional migration functions:

• Enterprise applications weren't required in V3.x, but if they're in your V3.x configuration, WASPostUpgrade creates an EAR file for each one. All other resources that aren't associated with a V3.x enterprise application are put into a J2EE application named defaultApplication.
  
  
• Unlike previous versions, V4 has a single EJB container per server. If you deployed EJBs to multiple containers in V3.x, WASPostUpgrade deploys all the EJBs to a single container. If your V3.x containers had different data sources specified, WASPostUpgrade sets the V4 data source for each EJB module based on the data source of its V3.x container.
  
  
• WebSphere Application Server V4.0 uses ServerGroups to replace the functionality of application server models and clones in V3.x. WASPostUpgrade will create ServerGroups based on application server models and clones from the V3.x configuration. Models and clones of objects other than application servers are migrated as normal objects.
  
  
• WASPostUpgrade modifies the V4 admin.config file to contain the com.ibm.ejs.sm.adminServer.nodeName and com.ibm.ejs.sm.adminServer.bootstrapPort values from the V3.x configuration. Other V4 property files are not modified.
  
  
• WASPostUpgrade will map any settings that reference directory names for stdin, stdout, stderr, and passivation directories and working directories to the V4.0 directory names. V3.x allowed a datasources.xml file in the properties directory to augment the datasource configuration settings. If the datasources.xml file exists, WASPostUpgrade migrates the properties in the file into the V4 datasource and JDBC driver configuration.
  
  
• WASPostUpgrade automatically converts the Web server-to-application server transport protocol from the Open Servlet Engine (OSE) protocol (which WepSphere Application Server V4 no longer supports) to HTTP. However, it does not change the port number that the Web server and the application server use to communicate. In a DMZ configuration, if you have configured your firewall to allow IP traffic through a specific port for OSE communication, keeping the same port allows the migrated node to run successfully without you having to make any changes to your firewall configuration. After you complete your migration, you may want to consider tightening your firewall configuration to allow only HTTP traffic through that port.
  
  
• Be aware also that the default port for OSE in V3.x is different from the default port for HTTP communication in V4. If you install V4 without migration on some nodes and use WASPostUpgrade (either directly or through the V4 installation program) for other nodes you may end up with different port numbers on each machine, which may cause problems depending on your configuration.
  
  
• When WASPostUpgrade migrates any JDBC driver, warning message MIGR0260W is logged to remind you to check the classpath for the JDBC driver to validate that the classpath is still correct on the V4 system. If you've migrated from DB2 UDB v6.1 to v7.1 on a Windows system the classpath may no longer be valid. The default location for the SQLLIB directory in v6.1 was in the root directory, but in v7.1 it's under the Program Files directory.
  
  
• Large applications may not migrate properly due to a migration limit of 300 files for each document root. If you hit this limit, WASPostUpgrade logs warning message MIGR0250W and ends migration for that Web application but continues to migrate other components of your configuration. This unmigrated Web application may cause additional errors when the migrated configuration is imported into V4.
  
  
• WASPostUpgrade will offer some suggestions about application code changes that may be necessary (in many cases, it will list the sections of the J2EE specification that make the changes necessary), but the migration tools don't modify application code. Therefore, you must perform this step manually with any of the migration approaches.

Security Migration

In addition to creating J2EE 1.2 compliant applications and migrating the domain configuration, WASPostUpgrade also converts the V3.x security configuration to the V4 security model. WebSphere Application Server V3.x secured EJB and Servlet methods by creating method groups for each application, assigning specific methods to each method group, and granting access to these method groups to specific users and groups of users. V4 conforms to the J2EE 1.2 authorization model, which is based on security roles rather than method groups.

WASPostUpgrade creates a security role for each of an application's method groups and grants permission for that role to execute all the methods from that method group. For example, if you migrated an enterprise application in V4.0 named #x201ctestApplication#x201d (with only the default method groups configured), WASPostUpgrade would create the following security roles:

• TestApplication-CreateMethods-Role
• TestApplication-ExecuteMethods-Role
• TestApplication-FinderMethods-Role
• TestApplication-ReadMethods-Role
• TestApplication-RemoveMethods-Role
• TestApplication-WriteMethods-Role

The users and user groups that had permission to access an application/method group pair in V3.x will be assigned to the corresponding role in the V4 configuration. Although this process may create more security roles than are necessary for your environment, this one-to-one mapping of method groups to application security roles lets users execute the same methods they could execute before migration

After migration, you can use the AAT and the Administrative Console's Security Center to view and modify the migrated security configuration and modify it to more closely match the security roles your company requires. To start the Security Center, select the Console => Security Center... menu item from the Administrative Console.

You can use the AAT to delete, rename, or create new security roles that more closely match your organization, and also to create new method permissions for EJB modules and security constraints for Web modules. Method permissions map security roles to specific EJB methods and security constraints map security roles to Web resource collections that are a combination of HTTP methods and URL patterns.

There are some important differences between WebSphere Application Server V4 and V3.x security. The default behavior for EJB security when global security is turned on has changed. In V3.x, access to the any of the EJB methods would be denied; however, in V4, access to the EJB methods is granted unless security is defined for the EJB. Another important difference is that URIs served by external Web servers are no longer secured using WebSphere Application Server security. See Info Center topic 5.3 for more differences between WebSphere Application Server V4 and V3 security.

Back to top

Approach 3: Installation integrated migration

The third approach runs the WASPreUpgrade and WASPostUpgrade tools as part of the WebSphere Application Server V4 installation process. The steps required to complete an installation integrated migration are:

1. Start WebSphere Application Server V3.x administrative server.
2. Run the V4 installation program and select Perform Migration (this runs WASPreUpgrade).
3. Uninstall V3.x.
4. Install any new prerequisite software and operating system patches required by V4.
5. Install WebSphere Application Server V4 (this runs WASPostUpgrade).
6. Upgrade application code to be J2EE 1.2 compliant.
7. Start WebSphere Application Server V4 application server to import the migrated configuration.

The first time the installation program runs, it will detect and list previous installations of WebSphere Application Server and allow you to choose which installation to migrate or backup and uninstall. After you choose a previous WebSphere Application Server installation and select Perform Migration, the installation program prompts for directory locations to be used during migration and then runs WASPreUpgrade to save the existing V3.x configuration, source code, and resource files.

One caution in this step: Even though the dialog in the WebSphere Application Server installation program recommends you exit all Windows programs before running the setup program, the WebSphere Application Server V3.x administrative server must be running for WASPreUpgrade to execute successfully. (In a production environment, this would normally not be a contradiction because the administrative server is typically installed on a different machine than the application servers.)

The status of the WASPreUpgrade execution appears in a window and is saved in the WASPreUpgrade.log.<timestamp> file in the was3_backup directory. (On UNIX installations, this window won't display until WASPreUpgrade has completed.) If the WASPreUpgrade.log file indicates errors, select Cancel on the "Pre-Migration Process status" window, correct the cause of the errors, and run the installation program again.

For both Windows and UNIX installations, when WASPreUpgrade completes successfully, one of the last items in the "Pre-Migration Process status" window instructs you to install any necessary prerequisite software and then run the installation program again to install WebSphere Application Server V4 and complete migration.

After you install any necessary prerequisite software and operating system patches, restart the installation program. The installation program prompts for the information needed to install V4.

After the installation program installs V4, it runs WASPostUpgrade to convert the V3.x configuration to a V4.0 configuration. As discussed earlier, WASPostUpgrade also builds J2EE applications from your existing application components, converts the security configuration to the J2EE roles-based security model, and migrates the V3.x administrative configuration into the V4 domain. The status of the WASPostUpgrade execution appears in a window and is saved in the WASPostUpgrade.log.<timestamp> file in the /WebSphere/AppServer/logs directory. (On UNIX installations, this window will not display until WASPostUpgrade has completed.)

If you want to verify the XML configuration file created by the WASPostUpgrade process before it's loaded into your V4 domain, examine the websphere_4x_restore.xml file (located in the /WebSphere/AppServer/properties directory) before restarting WebSphere Application Server. This XML file will be loaded into the V4.0 repository when WebSphere Application Server is next started. To accomplish this, the installation program alters the /WebSphere/AppServer/properties/initial_setup.config file so that when WebSphere Application Server is restarted, the configuration specified in /WebSphere/AppServer/properties/websphere_4x_restore.xml is loaded into the administrative repository.

If the WASPostUpgrade tool logs errors, you must cancel the installation and - after fixing the problems that caused the errors - either run WASPostUpgrade from a command prompt or run the installation program again.

Back to top

Application code changes

Regardless of which of the three migration approaches you follow, you may still need to make some code changes for applications to run properly under WebSphere Application Server V4 and the J2EE 1.2 specification. You can find a list of J2EE changes in the various API specifications at the Sun Microsystems Web site. Additional information on necessary changes can be found in the V4 InfoCenter topic 3.3 and its subsections.

As WASPostUpgrade redeploys your EJBs, the tool logs some warnings to draw your attention to specific changes in the EJB specification. You should especially examine the items below. (Important: Additional code changes may be necessary beyond those listed here.)

Exception handling. Default exception handling by the EJB container during a transaction has a couple of significant changes between V3.x and V4. Non-application (system-level) exceptions under EJB 1.0 (in WebSphere Application Server V3.x) didn't result in a transaction rollback if the instance threw java.rmi.RemoteException. However, with EJB 1.1 (in WebSphere Application Server V4.x) a non-application exception will automatically cause a transaction rollback. Conversely, application exceptions under EJB 1.0 automatically caused a transaction rollback under certain circumstances. However, with EJB 1.1, an application exception won't cause a transaction rollback unless the setRollbackOnly method has been executed on the instance's EJBContext object. These changes in the processing of exceptions could drastically change the execution of the EJBs causing unanticipated results.

Limited object scoping. Prior to V4, HttpSession objects were scoped at the servlet engine, which allowed multiple applications to share session data. The Servlet 2.2 specification, which is supported in WebSphere Application Server V4, introduced a requirement to limit the scope of an HttpSession object to the application/servlet context level. Any applications that depend on sharing session data with other applications will need to be modified to conform to the tighter scope requirements of the Servlet 2.2 specification.

New connection pooling support. WebSphere Application Server V4 removes support for the IBM connection manager API in favor of JDBC 2.0 connection pooling. Any applications that are still using the connection manager APIs must be changed to use JDBC 2.0 connection pooling.

Back to top

Domain migration

WASPostUpgrade migrates a single node at a time by comparing the local node name to the corresponding node names listed in the websphere_3x_backup.xml file. V4 nodes can't share an administrative domain with previous versions of WebSphere Application Server, so if your migration plan includes having V3.x and V4 nodes in production at the same time during migration, you'll need to use a different name for your V4 administrative domain database or use a different database server. You should also read InfoCenter topic 3.7 to determine if the interoperability required by your migration plan is supported.

In order to migrate a domain while providing the required performance levels for your Web applications during migration, you must be able to remove nodes from the existing domain without an unacceptable decline in response time. You can accomplish this using additional hardware or by migrating during an off-peak period when all of your nodes aren't required to provide the desired level of performance

Ideally, you'd have twice the number of machines necessary to provide an acceptable level of performance during migration. This would let you migrate enough nodes to V4 to provide the desired level of performance and ensure that everything is working properly before switching your production Web servers to use the V4 domain.

After migrating, you should check all of the log files (the migration log files mentioned earlier as well as the standard WebSphere Application Server log files) and run regression testing on your application running in V4 before using the V4 domain in production.

Back to top

Conclusion

You can do it! Migration is never much fun, but with careful planning and the help of the WebSphere Application Server V4 migration aids, you can make a smooth transition from Version 3.x to Version 4.

Top of page

Resources

• WebSphere Application Server Version 4.0, Advanced Edition Information Center
  
  
• Supported hardware, software and APIs for WebSphere Application Server
  
  
• WebSphere Application Server Support
  
  
• J2EE information from Sun Microsystems
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Major changes
• Migration overview
• Approach 1: Manual migration
• Approach 2: Using the upgrade tools
• Approach 3: Installation integrated migration
• Application code changes
• Domain migration
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers