Application Edition Manager



Search Tips   |   Advanced Search


The Application Edition Manager for WebSphere Extended Deployment helps us manage interruption-free production application deployments. Loss of service to users means loss of business to you. Using the Application Edition Manager, we can ensure that the users of our application experience no loss of service when we install an application update in our environment.

The Application Edition Manager also provides an application versioning model that supports multiple deployments of the same application in a WebSphere Extended Deployment cell. We can choose which edition to activate on a WebSphere Extended Deployment application server cluster, enabling us to either roll out an application update or revert to a previous level.

The Application Edition Manager interacts with the On Demand Router (ODR), the dynamic workload manager and application placement manager. This integration assures predictable application behavior when we apply application updates, ensuring a smooth transition from one application edition to another while the system continues to manage our application performance goals. The edition control center provides control over the application update and rollout process, including edition activation and deactivation across the application servers to which our application is deployed. Scripting APIs enable the integration of edition management functions with automated application deployment. IBM WebSphere Extended Deployment V6.0.1 will provide additional wsadmin AdminTasks for these edition management functions.

The Application Edition Manager provides advanced application management capabilities that focus on five functional requirements:

  1. Application versioning capability.
  2. Interruption-free application rollout.
  3. Ability to back-out an application update.
  4. A validation mode to check out an application before rolling it out to production.
  5. Ability to host concurrent versions of an application to support needs of more complicated rollout strategies, such as piloting and branch upgrade.


Application edition installation

Companies commonly have a build and deploy process that their application moves through as it goes from development to production. A software library is normally used to store the application source code and related artifacts. These library systems are typically designed to store multiple versions of these parts. The concept of an application version is well established in the context of software libraries and build processes.

With IBM WebSphere Extended Deployment V6.0, it is now possible to store these application versions in the system management repository and deploy them as needed.


Application editions

An application edition represents a unique instance of an application in the WebSphere Extended Deployment environment. An application edition encompasses both application versions and deployment bindings.


Edition names

The Application Edition Manager component enables WebSphere Extended Deployment users to install multiple editions of the same application. Each edition is identified with an application edition name and description. The edition name is a free-form text field in which we can specify a value to uniquely identify one application edition distinctly from other editions of the same application. A version number scheme, such as 1.0, 2.0, and so on, may be a useful approach for naming editions, but we are free to employ whatever scheme is most useful in our environment. An application installed with no edition name given is called a base edition.

When deploying an application we can also specify an edition description next to the edition name which gives we the ability to store additional information.


Non-destructive update

The existing application install and update functions in WebSphere Network Deployment are destructive: they replace the old instance of the application with a new one. Installing an application edition is additive: we may install any number of application editions and keep them in the system management repository.


Split deployment

Split deployment refers to the case when the modules deployed in a single J2EE application archive are divided across two or more deployment targets. For example, an ear file containing a Web application module and an EJB module is installed in the WAS environment; the Web application module is installed on a server and the EJB module is deployed on a cluster. With the Application Edition Manager it is possible to install and activate applications that are splitted as described.


Installing a new application edition

Installing a new application edition is similar to installing a new application in other WebSphere editions such as Network Deployment.

  1. Go to Applications | Install New Application in the Administrative Console. Select our application's ear file and click Next. Make any necessary changes on the Preparing for the application installation panel then click Next again. Click Continue if we receive the Application Security Warnings panel.

  2. This displays the Step 1: Select installation options panel. This panel has changed compared to the traditional application installation procedure. On this panel we can specify the edition name/number and description. If no Application Edition name or number is entered, then this is considered the base edition.

    Verify that we specify the same Application name as for our previous edition plus an Application Edition number and optionally an Edition Description.

    Although possible it is not recommended to enter a space in the application edition name because WebSphere Extended Deployment creates a directory which includes the name of the ear file and the name of the application editor. Values such as 1.0 or 1.1.0 or 1.0.1_FIX are less problematic.

  3. A new step during application edition installation is that we have to specify if we want to clone existing work classes. If we have created work classes for our application, we should clone them to the new application. Otherwise, we have to create them manually again.

  4. Step through all other necessary installation steps to finish the installation of the application edition.

After the installation completed, the application edition is not yet active. The next section describes how to activate and rollout an application edition.


Application activation and rollout

The Application Edition Manager separates distribution of an application from its activation. Editions are distributed to a target server or cluster in an inactive state and are explicitly activated as a separate step. The first or base edition is however automatically activated.

Only a single edition can be active on a given deployment target at a specific time. Multiple editions can be concurrently active as long as they are on different deployment targets. When multiple editions are active, routing rules can be assigned to the application to instruct the On Demand Router which application requests are to be sent to each edition.

There are four methods for activating an edition:

  1. Simple activation

    Simple activation marks an application edition as available to be started. Once activated, an edition can then be started as a separate step. Before activating an editor, the current activated edition has to be deactivated.

  2. Concurrent activation

    Concurrent activation enables us to activate the same edition on different servers or clusters.

  3. Validation activation

    Validation activation is a special form of concurrent activation. It activates an edition on a clone of its original deployment target. The clone is created on activation. After the validation rollout to the original deployment target, the clone is removed automatically.

  4. Rollout activation

    Rollout activation activates one edition in place of another, ensuring an interruption-free update in the process.

    There are two different types of rollout activation:

    • Group rollout
    • Atomic rollout


Simple edition activation

An application is distributed to the deployment targets at the time of installation. Activation is a configuration change that marks the application to become eligible to be started.

These are the four steps we have to do to simply activate an edition:

  1. Stop the current application.

    We stop an application on the Enterprise Applications panel. Go to Applications | Enterprise Applications, select the application and click Stop.

  2. Deactivate the current edition.

    We deactivate an edition by selecting the edition to be deactivated and clicking the Deactivate button in the application edition control center. Go to Applications | Edition Control Center | application_name.

  3. Activate the new edition.

    We activate an edition by selecting the edition and clicking the Activate button in the application edition control center.

  4. Start the new application.

    We start an application by selecting the application and clicking the Start button on the Enterprise Applications panel.

    Attention: This approach is not interruption-free. If we want an interruption-free activation follow Rollout activation.


Concurrent activation

Multiple editions of the same application can be concurrently activated on different deployment targets. For example, edition 1.0 is deployed on dynamic cluster RedbookCluster10 and edition 2.0 on dynamic cluster RedbookCluster20. Or we have the same application version installed twice in different clusters - for different customers or departments.

In order to use multiple editions concurrently it is necessary that user requests can somehow be distinguished from one another and thus be sent to the application servers hosting the appropriate edition.


Separating user requests among concurrent editions

When multiple editions of the same application are concurrently available to users in the same environment, the On Demand Router needs some kind of information to differentiate between the active editions. Based on that information it will then route the request to the intended edition. This can be accomplished by using either routing rules or unique URIs.


Routing rules

We can assign routing rules to the ODR that instruct it about where to route a request to. Routing rules are new in this WebSphere Extended Deployment release and are the recommended mechanism to separate request traffic among concurrent editions.

The benefit of using routing rules is that they are only visible to the administrator. The application users can access a consistent set of application interfaces, meaning Web application URIs and EJB JNDI names, and still be directed to distinct editions as per the strategy established by the application administrator. For this reason, routing rules are considered administratively directed routing differentiation.

Below we can see two clusters hosting different application editions and the ODR delivers the requests based on the defined routing rules. These routing rules could be based on a unique URI or on client IP addresses.

Figure 13-4 Concurrent activation mode


Unique URIs

For cases where routing rules are insufficient to satisfactorily separate user requests or if we prefer a more familiar mechanism instead of routing rules, we can give each edition its own unique URIs and EJB JNDI names. When doing this, however, the unique interfaces (Web application URIs and EJB JNDI names) for each edition are exposed to the application users and they must choose the right name(s) to use the appropriate edition.

For this reason, unique interfaces are considered client directed routing differentiation.


Activating an edition in concurrent mode

We need to set up routing rules to have multiple editions of the same application running in a WebSphere Extended Deployment environment. We must create the routing rules before we install the new edition. Otherwise the ODR would route all requests to the new edition.

We need to specify different deployment targets for our concurrent editions during installation as we can only have one active editor in a single cluster.


Validation mode

In IBM WebSphere Extended Deployment V6.0, we encountered some problems with the validation mode which have been fixed in IBM WebSphere Extended Deployment V6.0.1. It is therefore recommended to upgrade to V6.0.1 or higher when planning to use the validation mode.

Validation mode is a special case of concurrent activation that enables us to perform final pre-production testing of an application edition in the actual production environment with a selected set of users. This is accomplished by cloning the actual deployment target, including its resource and security definitions, and then activating the target edition on the cloned environment. Routing rules are used to direct the ODR to divert a selected subset of users to the new edition.

Only the application and the resources within WebSphere Extended Deployment are cloned. External components such as third-party software or databases are not cloned!

The On Demand Router delivers the request to the clusters based on the defined routing rules.

Figure 13-5 Validation mode

When the rollout is performed against an edition that is in validation mode, the edition is rolled out on the original deployment target and the cloned environment is deleted.

When our validation mode testing was successful and we want to rollout the application, we can perform the rollout directly against the edition in validation mode. The edition is then rolled out on the original deployment target and the cloned environment is deleted.

Remember that we are not able to roll back any data changes that happened during a test in the production environment. So be very careful when it comes to changing data - it is much better to only read information/ data.


Rollout activation

Interruption-free rollout enables a smooth transition from one edition of an application to another without loss of service. This means that all application requests will be serviced during the rollout - none will be lost. This ensures the perception of continuous application operation from the perspective of the application's customers. To do this, the Application Edition Manager carefully coordinates the activation of the edition and the routing of requests to the application.

Interruption-free rollout is supported only for HTTP and SOAP/HTTP driven application requests.


Application edition compatibility

Replacement of one edition with another in a production environment requires certain discipline in the application's evolution. Because edition replacement happens while application users are potentially accessing the previous application edition, the new edition should be backward compatible with the old edition. This means that the new edition should not add or change any existing application interfaces, including their essential behavior. New interfaces may be added; existing interfaces may be algorithmically corrected, and in some cases, even extended, and still remain compatible with older application users.

A basic requirement for interruption-free rollout is that we use the On Demand Router. In other words, interruption-free rollout is only supported for applications that are accessed through the ODR. This is because the ODR acts as a routing agent so the flow of requests may be controlled during the rollout process, diverting requests away from servers that are transitioning from one active edition to another and queuing requests if there is temporarily no server available to process the application request.


Group rollout strategy

When using the group rollout strategy, the administrator defines the number of servers in the deployment target. That is, how many clustered application servers the Application Edition Manager should update at the same time. This is called the group size. For example, we can specify to rollout a new edition to a server cluster using a group size of two. If we have a four server cluster, this means that the new edition is rolled out in two passes, two servers at a time. The default group size is 1. The group size cannot exceed the number of servers comprising a deployment target.

Naturally, servers that are changed from one edition to another are offline and not processing application requests during the transition. Therefore, we should tailor the group size setting to get the best balance of capacity availability and rollout expedience for our environment. A smaller group size provides greater capacity during rollout; a larger group size updates more servers at a time, thus reducing the total time required to complete the rollout. The group size number always depends on the environment's requirements and therefore we cannot recommend a best or right group size number.

Figure 13-6 Group rollout sequence

At the time of writing this redbook it was not possible to change the group size. This has been changed in IBM WebSphere Extended Deployment V6.0.1.


Atomic rollout strategy

Atomic is a rollout strategy whereby all user requests are served by the same application version. After it is online, the active new edition completely replaces the old edition. For a server cluster, this is done by releasing (rolling out) the new edition to half the cluster at a time. The previous edition is served until the first half of the cluster is available to serve the next edition. At that time, the old edition is taken offline and the remaining half of the cluster is released. So the cluster serves user requests from either edition.

There might be a window in which there are temporarily no servers available to process requests for the application. During this time, requests are queued in the ODR until the servers are brought back online. This rollout strategy also ensures no loss of service for single server deployment targets.

Figure 13-7 Atomic rollout sequence

Use the atomic rollout option if it is important for us to serve all user requests with a consistent edition of the application. However, this means that our cluster runs at half capacity. If our cluster is very large, group rollout might be the better option for you.

Attention: A basic requirement for the atomic rollout is that all application servers are started. WebSphere Extended Deployment does not verify which servers are currently up and which are down. As a worst case scenario, imagine that only half of our application servers are running and these are shut down for the update first!


Activating an edition using group or atomic rollout

To rollout a new edition, we need to install the application.

In the application edition control center (Applications | Edition Control Center | application_name) select our new edition and click either Group Rollout or Atomic Rollout.

The SystemOut.log of the Deployment Manager will contain detailed logging information about the rollout process. The Administrative Console will also display some information.

WPVR0010I: Rollout started for XDStockTradeEdition-editionNew_2.0. 
WPVR0014I: XDStockTradeEdition-edition1.0 deactivated. XDStockTradeEdition-editionNew_2.0 activated. 
WPVR0015I: Processing node1/RedbookCluster11_node1. 
WPVR0016I: Quiescing node1/RedbookCluster11_node1/XDStockTradeEdition-edition1.0. 
WPVR0018I: Stopping node1/RedbookCluster11_node1/XDStockTradeEdition-edition1.0. 
WPVR0025I: Draining node1/RedbookCluster11_node1/XDStockTradeEdition-edition1.0 (30 sec). 
WPVR0025I: Draining node1/RedbookCluster11_node1. 
WPVR0020I: Synchronizing node1. 
WPVR0022I: Starting node1/RedbookCluster11_node1/XDStockTradeEdition-editionNew_2.0. 
WPVR0015I: Processing node2/RedbookCluster11_node2. 
WPVR0016I: Quiescing node2/RedbookCluster11_node2/XDStockTradeEdition-edition1.0. 
PVR0018I: Stopping node2/RedbookCluster11_node2/XDStockTradeEdition-edition1.0. 
WPVR0025I: Draining node2/RedbookCluster11_node2/XDStockTradeEdition-edition1.0 (30 sec). 
WPVR0025I: Draining node2/RedbookCluster11_node2. 
WPVR0020I: Synchronizing node2. 
WPVR0022I: Starting node2/RedbookCluster11_node2/XDStockTradeEdition-editionNew_2.0. 
WPVR0012I: Rollout completed for XDStockTradeEdition-editionNew_2.0. 
Manage Editions: XDStockTradeEdition

After activating an edition either through atomic or group rollout, the new edition was not shown as the active edition in the application edition center during our tests.

We then tried to activate this edition again by clicking the Activate button and received an error message stating that one cannot activate an active edition. After that, the application edition control center showed the correct status.

This GUI related problem has been fixed in IBM WebSphere Extended Deployment V6.0.1.

We can also see, which applications are active in this file:


#File contains metadata for all editions of the application
#Wed Nov 09 16:39:32 EST 2005
edition.desc-edition2.0=Version 2
edition.desc-editionNew_2.0=New 2.0
edition.desc-edition1.0=Initial Edition2


Reset strategy: New in V6.0.1

A reset strategy instructs the Application Edition Manager in how each of the deployment targets will load the new edition into the server run time. Reset is accomplished by recycling either the application in each affected server or by recycling the entire server itself. Recycling is the combined action of stopping, then restarting the affected object.

The reset strategy is not executed until there are no active requests in the server. Client affinities to the server are allowed to complete according to the drainage interval.

There are two different reset strategies available:

  1. Soft reset
  2. Hard reset


Soft reset

A soft reset attempts to minimize the impact of edition transition in a server by recycling the affected application. This allows the server to continue serving requests for other applications if there are any. It also avoids the system impact of restarting the entire server.

Certain supporting elements in the environment do not benefit from a soft reset. Specifically, certain native resources do not get cleaned up. In particular, process storage containing JITed code is not cleaned up; furthermore, native libraries are not unloaded from memory. Soft reset is generally safe for applications that use no native libraries. When soft reset is used in a production environment, it is recommended to monitor the application server process(es) to ensure there is sufficient virtual memory.


Hard reset

A hard reset recycles the entire application server. This impacts all applications running on that server, since they will all go offline while the server is recycled. Hard reset ensures that both process memory and any native libraries used by the application are refreshed. This prevents virtual storage exhaustion and allows for new versions of native libraries to be loaded. When rolling out an application edition that is accompanied by new versions of native libraries upon which it depends, we must select hard reset as our reset strategy for rollout.


Drainage interval

As the rollout process is initiated in a particular application server, the server is removed as a candidate for new requests for the application being updated. The drainage interval specifies the amount of time an application server is allowed to serve clients with affinity to that server after the rollout process has begun and before the reset strategy is executed.

In addition, certain types of affinities, such as transaction, activity, and compensation-scope will lengthen the effective drainage interval, since the server will not actually stop until these units of work complete.

The default drainage interval is 30 seconds.


Recovery from failure during a rollout

There is no provision for automatic rollback for recovery. If a failure takes place during rollout, then the rollout fails. The administrator needs to rollout the previous edition manually using the backout process described in the next section.


Application back-out

After an edition rollout is complete, we might find that there is a problem with this application edition and we want to revert back to the previously active edition. This is called back-out. Back-out is accomplished by simply rolling out the previous edition.

Back-out is not a routine action. It is an action taken to recover from unexpected application results that are serious enough to require reverting back to a prior edition.

Reverting to an older edition might cause some compatibility disruption to new clients that are expecting access to the new edition.


Application activation and rollout with scripting: New in V6.0.1

It is possible to use wsadmin scripts for application activation and rollout. These are AdminTasks which are build into wsadmin.



Batch mode example usage using Jacl:

$AdminTask activateEdition {-appName BeenThere -edition 1.0}

Using Jython:

AdminTask.activateEdition('[-appName BeenThere -edition 1.0] ' )

Interactive mode example usage using Jacl:

$AdminTask activateEdition {-interactive}Using Jython:AdminTask.activateEdition('[-interactive] ' )



Batch mode example usage using Jacl:

$AdminTask deactivateEdition {-appName BeenThere -edition 1.0}

Using Jython:

AdminTask.deactivateEdition('[-appName BeenThere -edition 1.0]')

Interactive mode example usage: Using Jacl:

$AdminTask deactivateEdition {-interactive}Using Jython:AdminTask.deactivateEdition('[-interactive]')



Batch mode example usage: Using Jacl:

$AdminTask rolloutEdition {-appName BeenThere -edition 1.0 -params "{rolloutStrategy [grouped|atomic]}{resetStrategy [soft|hard]}{groupSize [int]}{drainageInterval [int]}"}

Using Jython:

AdminTask.rolloutEdition('[-appName BeenThere -edition 1.0 -params "{rolloutStrategy [grouped|atomic]}{resetStrategy [soft|hard]}{groupSize [int]}{drainageInterval [int]]')

Interactive mode example usage using Jacl:

$AdminTask rolloutEdition {-interactive}Using Jython:AdminTask.rolloutEdition('[-interactive]')



Batch mode example usage using Jacl:

$AdminTask validateEdition {-appName BeenThere -edition 1.0 -params "{dynClusterMaxSize [int]}{dynClusterMinSize [int]}{staticClusterSize [int]}"}

Using Jython:

AdminTask.validateEdition('[-appName BeenThere -edition 1.0 -params "{dynClusterMaxSize [int]}{dynClusterMinSize [int]}{staticClusterSize [int]]')

Interactive mode example usage:

Using Jacl:

$AdminTask validateEdition {-interactive}

Using Jython:



Logging and tracing

We can activate logging and tracing for the Application Edition Manager using this setting:* = debug

We can either change the trace level through the Administrative Console or using a wsadmin script.




WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.


IBM is a trademark of the IBM Corporation in the United States, other countries, or both.