Introduction

IBM WebSphere Application Server V6 contains many significant enhancements in system management functionality over the previous release, Version 5. This article series explores the evolution of the product in this area, with each article focusing on the details related to a specific feature. The articles is this series include:

• Part 1: Overview of system management features
• Part 2: Incremental cell upgrade

with additional installments on the way.

Back to top

What is incremental cell upgrade?

Until Version 5.1 of IBM WebSphere Application Server (hereafter referred to as Application Server), upgrading a cell from a previous release to a newer release of Application Server was a time consuming process that could be disruptive to the existing environment. It was possible, for example, for the entire cell to be shut down during the upgrade. Alternatively, if an online upgrade was required, a parallel cell with the new release of Application Server would be created to mirror the existing cell, then the old cell would be taken offline after the new cell was functional.

With WebSphere Application Server V5.1, the deployment manager became able to manage both V5.0.x and V5.1 nodes, which enables the cell to be upgraded to a new release one node at a time -- with minimal impact to the applications that are running within the cell. Such inconveniences associated with upgrading old releases of Application Server to the newer release had been eliminated.

In Version 6.0, many additional enhancements have been introduced. Some of these enhancements, such as the adoption of JMX 1.2, or the introduction of a new messaging implementation, might have made V5 incompatible with V6, if not for measures taken specifically to ensure compatibility. Additional functions in V6, such as displaying the versions of nodes or servers from the console, adapting the console to present only information valid for a particular version node or server, and enhanced validation when modifying the configuration on different version servers or nodes through scripting or JMX APIs, further expand the administrative features that were previously available.

The emphasis in V6 is to facilitate the upgrade of the entire cell in a timely fashion by giving the administrator the ability to perform rolling upgrades of individual nodes. It is still possible for an administrator to choose to not upgrade some nodes, but there are restrictions in V6, documented later in this article, with respect to what can be achieved when running such a mixed release environment for extended periods of time. Administrators are encouraged to assess their intended usage of this type of environment in the context of these restrictions. (It is anticipated that many of these restrictions will be lifted in future versions or maintenance releases of Application Server.)

Figure 1 illustrates a cell in the midst of being upgraded from V5 to V6. Refer to this figure as we go through the features and complexities of this environment

Back to top

Upgrading a cell

The incremental upgrade process begins with the migration of your V5 deployment manager to V6. The deployment manager must always be the first part of the cell migrated to the new release level, and must always be at the highest release and fix level of any node within a cell to enable it to manage all the nodes in the cell, regardless of their individual release levels.

To upgrade the deployment manager:

1. Make a backup of your Application Server V5 configuration.
2. Install Application Server V6 on the same machine where your V5 deployment manager is located.
3. Create a new V6 deployment manager profile. Ensure that the name of the cell and the name of the deployment manager node match your existing cell.
4. Shut down your V5 deployment manager. This should not affect your applications, as the deployment manager is not needed to keep your application servers running.
5. From the bin directory of your V6 deployment manager profile, run the WASPreUpgrade tool. For example, if you are using a Microsoft® Windows® machine, run:

   .\WASPreUpgrade.bat <backupdir> <location_v5>

   where:

   <backupdir> is a temporary directory of your choosing, and

   <location_v5> is where you installed your V5 deployment manager.

   The WASPreUpgrade tool examines the V5 installation, and copies the files that it needs to recreate the V5 environment into <backupdir>.

6. From the bin directory of your V6 deployment manager profile, run the WASPostUpgrade tool. For a Windows machine, this would be:

   .\WASPostUpgrade.bat <backupdir> -profileName <dmgrProfile>

   The WASPostUpgrade tool uses the contents of <backupdir>, created by the WASPreUpgrade tool, to populate the deployment manager profile, whose profile is <dmgrProfile>, so that the configuration of the V6 deployment manager is the same as the V5 deployment manager.
7. Start the V6 deployment manager.

   After completing the above steps, you will have created a new V6 cell whose deployment manager manages all the pre-existing V5 nodes. All the V5 nodes in the cell remain unchanged and are unaware that they are being managed by a new deployment manager. The WASPostUpgrade tool also disables the old V5 deployment manager. This is to prevent starting two deployment managers that would simultaneously manage the same cell.

   If for some reason you want to immediately undo the upgrade:

   1. Stop the V6 deployment manager.
   2. Restore the backed up V5 deployment manager configuration.
   3. Restart V5 deployment manager.
   4. Remove the V6 deployment manager profile. Again, this is to prevent starting both V5 and V6 deployment managers together.

   It is not advisable to undo the upgrade after you have performed configuration changes through the new deployment manager. These changes are updated in the new deployment manager, which is separate and distinct from the old V5 deployment manager, and cannot be easily re-integrated back into the V5 cell.

   After the deployment manager has been upgraded to V6, the individual nodes in the cell can be upgraded. To upgrade a node:

8. Make a backup of the deployment manager configuration.
9. Make a backup of the V5 node's configuration.
10. Install Application Server V6 on the same machine as your node.
11. Create a custom profile, one that is not pre-federated. This is a profile with minimal configuration that does not contain any server. Ensure the name of the node is the same as the node you are upgrading.
12. Ensure that your new V6 deployment manager is running and can communicate with the V5 node you are upgrading.
13. Stop the V5 node and all its servers. Your application should continue to run as long as each server on the node is a member of a cluster with additional members on other machines.
14. From the bin directory of the new V6 node's profile, run the WASPreUpgrade tool. For a Windows machine:

    .\WASPreUpgrade.bat <backupdir> <version5_node>

    where:

    <backupdir> is the temporary directory for WASPreUpgrade to store information about V5 node.

    <version5_node> is the location where the V5 node is installed.

    WASPreUpgrade examines the V5 node and copies the information it needs to upgrade the node to V6 into <backupdir>.

15. Again from the bin directory, run the WASPostUpgrade tool. For a Windows machine:

    .\WASPostUpgrade.bat <backupdir> -profileName <nodeProfile>

    where:

    <backupdir> is the same directory as the one used for WASPreUpgrade, and

    <nodeProfile> is the name of the profile used to create the node.

16. Start the V6 node and the application servers.

WASPostUpgrade contacts the V6 deployment manager to upgrade the node in the master configuration repository to V6. After upgrading the configuration on the deployment manager, the local repository of the node is synchronized with the master copy from the deployment manager. WASPostUpgrade also disables the old node so that you cannot start both the new and the old node simultaneously.

If for some reason you need to immediately undo the upgrade:

1. Stop the V6 node and application servers.
2. Restore the deployment manager configuration you backed up in Step 8
3. Restore the node configuration you backed up in Step 9.
4. Restart the V6 deployment manager, and the V5 node and servers.
5. Delete the V6 node profile so that you cannot start both V5 and V6 nodes simultaneously.

Back to top

Configuration files

As the incremental upgrade proceeds on each node, the cell's central configuration repository will contain documents for both V5 and V6 nodes. Configuration synchronization will ensure that configuration documents replicated to the V5 nodes are consumable by the V5 runtimes, even if the documents are stored on the deployment manager repository in V6 formats.

Referring back to Figure 1, the deployment manager master repository stores all configuration files at the V6 level, but is designed to also accommodate V5 configuration information. When synchronizing the configuration file between the deployment manager and a V5 node, transformations are applied to the V6 format to make it V5-compatible. Some of these transformations include changing the namespaces in the XML files, removing configuration attributes that are new in V6, and stripping out resources not understood by the V5 runtime.

Back to top

JMX interoperability

WebSphere Application Server V5 supports JMX 1.1, while V6 supports JMX 1.2. Due to the evolution of the JMX specification, the formats of serializables defined by the JMX specification, such as javax.management.ObjectName, are incompatible between Application Server V5 and V6. In order for the V6 deployment manager to manage a V5 node, Application Server V6 has enhanced the SOAP connector to be JMX-version aware. The RMI connector has not been enhanced, thereby restricting the JMX function between the V5 and V6 runtimes to SOAP connectors only.

When sending a JMX-defined serializable to a V5 node, the SOAP connector runtime applies appropriate transformations to the JMX 1.2 serializable classes so that a JMX 1.1 serializable is received by the Application Server V5 runtime. Similarly, when receiving a JMX 1.1 serializable from the V5 runtime, it is transformed to the JMX 1.2 format, so that it is understood by the V6 runtime.

The transformation framework employed by the SOAP connector uses special class loaders to perform these transformations. All classes defined by the JMX specification are currently being transformed. However, user-defined classes that refer to a JMX-defined class cannot be transformed correctly, and are not supported when passed between the V5 and V6 runtimes.

For example, say you implemented a JMX MBean and wanted to pass a class you created as a parameter to one of its methods. This user-defined class is passed correctly, as long as it does not contain a reference to one of the serializables defined by JMX, such as ObjectName. Note that passing ObjectName by itself works, but passing some class "A" that refers to ObjectName will not work.

Expect to see few (if any) user defined classes fall into this category. If you need to define a new MBean method that works with both V5 and V6 releases, then pass any classes belonging to the javax.management package as separate parameters.

Most of the internal classes within Application Server V6 that contain references to the javax.management package and are used as MBean method parameters have been transformed so that they work in the mixed release environment. The only exceptions are PMI-related classes. Users of PMI will have to wait for a maintenance release of Application Server V6 before they can receive PMI data correctly from V5 nodes to a V6 environment.

The JMX 1.2 specification also disallows the use of ":" as a valid property value within an ObjectName. The V5 ObjectName contained ":" when it was used to store configuration IDs, but this has been changed in V6 to "|". The SOAP connector will automatically transform between these two characters, so that a configuration ID is transparently usable by both runtime versions.

When using JMX from within an Application Server V5 runtime to call into V6, classes newly defined in V6 can not be deserialized in the V5 runtime, since these classes are not available in the V5 runtime CLASSPATH. This situation rarely occurs. But when it does, it is usually caused by a new exception introduced in V6.

Back to top

Adapt-A-View administration

The Application Server V6 deployment manager is aware of information about the nodes it manages, including Application Server product version, operating system, and other product features. As a node is upgraded to a new version, or as product features are added, the node information is also updated. The deployment manager uses this node information to determine which administrative functions are actually valid for a given node. For example, new V6 features are not displayed on the console for a V5 node, since those new features are not valid for V5. When displaying a node or a server, a new column containing the node version is also displayed. This ability to adapt to different node information is called Adapt-A-View.

For scripting users, the scripting runtime has also been enhanced with Adapt-A-View capabilities. Unlike the console, which can select what information to present to the user, the scripting runtime implements configuration validation. For example, if the user tries to configure a V5 node by creating a new instance of a configuration type, or by setting a new V6 configuration attribute, an exception will be raised. If the user tries to access types or attributes that are deprecated, a warning is logged, but the operation is allowed to proceed.

One exception concerns the preexisting AdminConfig attributes <type> command. Since the command itself does not take a version parameter, it will list all attributes that are valid for the <type> irrespective of the version.

For those who want to write their own Adapt-A-View code, the node information can be accessed through a new set of Java APIs, documented in the WebSphere Application Server Information Center, and are also available through new wsadmin tasks. Here are some examples of the tasks:

• $AdminTask getNodeBaseProductVersion { -nodeName <nodeName> }
  returns WebSphere base product version, such as "6.0.0.0"
• $AdminTask getNodeMajorVersion { -nodeName <nodeName> }
  returns the WebSphphere base product major version, such as "6"
• $AdminTask getNodeMinorVersion { -nodeName <nodeName> }
  returns the WebSphere base product minor version, such as "0"
• $AdminTask getNodePlatformOS { -nodeName <nodeName>}
  returns the operating system of the node, such as "windows"

Back to top

Runtime interoperation

In addition to JMX interoperability, other parts of the Application Server runtime have also been enhanced to ensure they work in a mixed environment. If you have a mixed cluster containing both old version and new version nodes, the workload management runtime will still route requests to all members of the cluster. However, in order for this mixed environment to work, certain V6 performance enhancements are not turned on by default. When all the members are upgraded to V6, the user is encouraged to set the com.ibm.websphere.ObjectIDVersionCompatibility ORB property to enable these performance enhancements.

If you are working with JMS, interoperability between the old and new runtimes are preserved as well. You will, however, need to change your topic connection factory port settings from DIRECT to QUEUED prior to migrating your node. During migration, the jmsserver from V5 is converted to a regular application server, with appropriate message engine settings to perform the functions of the original JMS server. This happens because Application Server V6 contains a brand new JMS implementation using message engines. Similarly, the V5 WebSphere Default Messaging Provider has been renamed the V5 Default Provider to make room for the message engine based default provider.

If you are using Data Replication Service (DRS), your existing configurations should continue to work. After migrating all the nodes, customers are encouraged to move to the new DataReplication domain, a new implementation in Application Server V6.

Back to top

Using resources

Resources that are defined in Application Server V5 will continue to work after migrating to V6, including:

• JDBC provider
• Generic JMS provider
• WebSphere MQ JMS provider
• Mail provider
• Resource environment provider
• URL providers
• JCA 1.0 resource adapters JDBC provider.

Of course, any resources new to V6 may not be created on V5 nodes or servers. These include:

• WebSphere default messaging provider
• JCA 1.5 resource adapters.

Back to top

Working with applications

In Application Server V6, all applications are classified as either V5- or V6-compatible, based on the Application Server features they use:

• V5-compatible applications are those that deploy and run within a V5 environment. These include J2EE 1.3 applications and JCA 1.0 adapters, and do not call any new V6 APIs.
• V6-compatible applications are those applications that only run within a V6 environment, and include J2EE 1.4 applications, JCA 1.5 adapters, and any applications that call new APIs introduced in V6.

A V5-compatible application may be installed on any V5 or V6 server, or on any cluster containing V5 or V6 servers. When updating an application for re-installation, or for editing or remapping modules to new targets, the target of the V5-compatible application is not restricted. By contrast, the target of a V6-compatible application may only be a V6 server, or a cluster containing only V6 members.

Application Server checks for version compatibility based on the J2EE or JCA version of the application; it does not check any of the APIs that the application is using. What this means is that Application Server will let a J2EE 1.3 application that calls new V6 APIs -- though it is not V5-compatible -- deploy to a V5 server or cluster. Enforcing lower-level checks would be too costly during application installation or updates, for the very few cases that may occur.

When installing a V5-compatible application to a V5 target, the deployejb, deployws, and precompileJSP options are not supported. The deployment tool in V6 is currently not aware of the target environment in which the applications are deployed, so these applications need to be pre-deployed before installation. The useMetadataFromBinary option is also not supported when installing to a V5 target. This option is turned off by default since it is rarely used. The reason for this restriction is that the metadata in the application binaries have been enhanced in V6; the version in the deployed applications is for the V6 runtime and cannot be consumed by the V5 runtime.

Administrators are encouraged to deploy, edit, or update their applications from a V6 environment. If initiated from a V5 environment (for example, by starting wsadmin from a V5 node to point to the V6 deployment manager), only those tasks available in V5 are supported. For example, the following V6 application deployment tasks are not supported:

• Mapping message destination reference to EJB
• Binding J2CObject to JNDI name
• Binding J2CActivation to destination JNDI name

Back to top

Capacity planning: Working with nodes, servers and clusters

There are restrictions with regard to what can be done with V5 nodes. These restrictions have to do with the inability to expand the capacity of a mixed release cell by adding additional nodes, servers, or cluster members. These restrictions will be lifted in future maintenance releases for V5 or V6 where appropriate. In the meantime, the workaround is to preplan the post-migration capacity by creating additional nodes and servers prior to upgrading the cell from V5 to V6. These additional nodes and servers do not have to be started until needed.

Workarounds for other specific situations are presented below:

• A V5 node may not be added to a V6 cell.
  One workaround is to first upgrade the node to V6, then add the node to the V6 cell.
• A V5 node may not be removed from a V6 cell.
  There are two workarounds. First, you can uninstall the V5 node, then run the cleanupNode command to delete the node from the V6 deployment manager. Second, you can upgrade the V5 node, then run the removeNode command.
• A new V5 server may not be created after the deployment manager is upgraded to V6.
  A future release of Application Server will enable this function by supplying the required V5 templates and runtime changes.
• A V5 server cannot be converted to a cluster, nor can a new V5 member be added to a cluster.
  A workaround is to first upgrade the node to V6 before the conversion or expansion. Once a cluster contains a V6 member, it becomes a mixed cluster. Adding new V6 members to a mixed cluster is supported.

Back to top

Scripting compatibility

In Application Server V6, changes were made to some configurations that rendered them incompatible with V5. Although efforts were made to maintain strict compatibility, there are a few areas in which it is better to make a clean break early so that future configuration tasks will be easier. Where an incompatibility exists in V6, the runtime can nevertheless run in "compatibility" mode, meaning that the V6 runtime can tolerate both the old and new configuration settings. Scripts developed in V5 may also be used to configure both V5 and V6 nodes/servers. V6 nodes and servers that are migrated from V5 are done so with compatibility mode turned on, the migration tool default.

Compatibility mode is good for the initial upgrade of the cell, when all the members of the cell started from V5. Compatibility mode is not applicable to new V6 nodes that are added to the cell, since these brand new nodes and servers are created with the new configurations. Therefore, the recommendations are:

• If no new V6 node is to be added to the cell after migrating the deployment manager, the entire cell may be run in compatibility mode.
• If the entire cell is to be upgraded before any new V6 nodes are added, modify your existing scripts as soon as possible after migration to use the new configuration. After the script is modified, run the convertScriptCompatibility tool to move from the old to the new configuration. Another alternative is to modify the existing scripts prior to migration and run the migration tool with compatibility mode off.
• If a mixed environment consisting of mixed version nodes from a V5 cell and new V6 nodes is needed, then the existing scripts must be written to be version aware (see Adapt-A-View section on the node information APIs):
  • Use the old format when operating on the V5 node.
  • Use the new format when operating on the V6 node.

Nodes can be migrated from V5 to V6 with compatibility mode off. Alternatively, if they are migrated with compatibility mode on, the convertScriptCompatibility tool can then be used to move to the new configuration.

One incompatible change between releases is in the HTTPTransport used to specify the Web container port. In V6, this has been replaced by a channel framework based configuration, which is a much more flexible mechanism for supporting the input and output of transport end points. However, moving to the channel framework necessitates that the host and port settings for the Web container be changed to conform to channel definitions.

A second incompatible change is in the use of processDefinitions rather than processDefinition. This is a result of the integration with WebSphere Application Server for z/OS® to support a single cell consisting of both workstation and Z nodes. On workstation, there is only one processDefinition per server; on Z, there can be multiple. Therefore, processDefinitions is used to accommodate both.

Another incompatible change is in the location of the transaction log. In Application Server V5, this was specified via TransactionService. For Application Server V6, this is specified as an attribute on ServerEntry. This change was introduced to enable peer recovery of transaction log to complete in-doubt transactions when the machine hosting the transaction log crashes.

One reason that compatibility cannot always be strictly preserved is that the configuration model currently made available to end users is specified at a very low level, which in turn triggers changes in the implementation. In future versions of Application Server, more high level wsadmin tasks will be introduced so that administrators can work with a higher level conceptual model that more closely relate to the tasks at hand, and that are less susceptible to changes in the underlying implementation. Continuous enhancements in usability will be characteristic of forthcoming versions of WebSphere Application Server.

Back to top

Conclusion

This article described the incremental cell upgrade process, with its nuances, complexities, restrictions, and implications for the administrator. Administrators who wish to upgrade an entire cell quickly will find that upgrading the cell one node at a time is a significant improvement over having to either shut down the entire cell, or create a parallel cell. Administrators with the additional requirement of running V5 nodes in a mixed cell environment for extended periods of time will have to work around certain restrictions, the most serious being the capacity planning issues. Many of these temporary restrictions will be removed with future versions or maintenances releases of WebSphere Application Server.

Resources

• System Management for WebSphere Application Server V6 -- Part 1: Overview of system management enhancements
  
  
• WebSphere Application Server V6 Migration Guide
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Browse for books on these and other technical topics.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• What is incremental cell upgrade?
• Upgrading a cell
• Configuration files
• JMX interoperability
• Adapt-A-View administration
• Runtime interoperation
• Using resources
• Working with applications
• Capacity planning: Working with nodes, servers and clusters
• Scripting compatibility
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers