Upgrading Deployed SIP Applications

The following sections describe how to upgrade deployed SIP applications to a newer version of the same application without losing active calls:

Overview of SIP Application Upgrades

With WebLogic SIP Server 2.2, you can upgrade a deployed SIP application to a newer version without losing existing calls being processed by the application. This type of application upgrade is accomplished by deploying the newer application version alongside the older version. WebLogic SIP Server automatically manages the SIP Servlet mapping so that new requests are directed to the new version. Subsequent messages for older, established dialogs are directed to the older application version until the calls complete. After all of the older dialogs have completed and the earlier version of the application is no longer processing calls, you can safely undeploy it.

WebLogic SIP Server's upgrade feature ensures that no calls are dropped while during the upgrade of a production application. The upgrade process also enables you to revert or rollback the process of upgrading an application. If, for example, you determine that there is a problem with the newer version of the deployed application, you can simply undeploy the newer version. WebLogic SIP Server then automatically directs all new requests to the older application version.

Requirements and Restrictions for Upgrading Deployed Applications

You must assign version information to your updated application in order to distinguish it from the older application version. Note that only the newer version of a deployed application requires version information; if the currently-deployed application contains no version designation, WebLogic SIP Server automatically treats this application as the "older" version. See Assign a Version Identifier.
Both the deployed application and the updated application must provide only SIP protocol functionality. You cannot upgrade converged HTTP/SIP applications using these procedures. See Upgrading Software and Converged Applications instead.
A maximum of two different versions of the same application can be deployed at one time.
If your application hard-codes the use of an application name (for example, in composed applications where multiple SIP Servlets process a given call), you must replace the application name with calls to a helper method that obtains the base application name. WebLogic SIP Server provides SipApplicationRuntimeMBean methods for obtaining the base application name and version identifier, as well as determining whether the current application version is active or retiring. See Accessing the Application Name and Version Identifier.
When applications take part in a composed application (using application composition techniques), WebLogic SIP Server always uses the latest version of an application when only the base name is supplied.

Steps for Upgrading a Deployed SIP Application

Assign a Version Identifier—Package the updated version of the application with a version identifier.
Deploy the Updated Application Version—Deploy the updated version of the application alongside the previous version to initiate the upgrade process.
Undeploy the Older Application Version—After the older application has finished processing all SIP messages for its established calls, you can safely undeploy that version. This leaves the newly-deployed application version responsible for processing all current and future calls.

Each procedure is described in the sections that follow. You can also Roll Back the Upgrade Process if you discover a problem with the newly-deployed application. Applications that are composed of multiple SIP Servlets may also need to use the SipApplicationRuntimeMBean for Accessing the Application Name and Version Identifier.

Assign a Version Identifier

WebLogic SIP Server uses a version identifier—a string value—appended to the application name to distinguish between multiple versions of a given application. The version string can be a maximum of 215 characters long, and must consist of valid characters as identified in Table A-1.

Table A-1 Valid and Invalid Characters
Valid ASCII Characters	Invalid Version Constructs
a-z	..
A-Z	.
0-9
period ("."), underscore ("_"), or hyphen ("-") in combination with other characters

For deployable SIP Servlet WAR files, you must define the version identifier in the MANIFEST.MF file of the application, and you must append the version identifier to the WAR filename. EAR deployments must additionally append the version identifier to the application name in the context-root specified in application.xml.

Defining the Version in the Manifest

Both WAR and EAR deployments must specify a version identifier in the MANIFEST.MF file. Listing A-1 shows an application with the version identifier "v2":

WebLogic SIP Server strips the version string specified in the manifest from the application's deployment name, so that it can recognize when multiple versions of the same application are deployed.

If you deploy an application without a version identifier, and later deploy with a version identifier, WebLogic SIP Server recognizes the deployments as separate versions of the same application.

Appending the Version to the Archive Name

In the name of the SIP application WAR or EAR file, you must append the same version identifier that you defined in the manifest. Continuing with the example shown in Listing A-1, if the application is named mySIPApplication, you would package the deployment as mySIPApplicationv2.war (or mySIPApplicationv2.ear for an Enterprise Application).

Appending the Version to the context-root (Enterprise Applications)

If you are deploying an EAR file, the context-root element in the application.xml deployment descriptor must match the full application name and version string used in the archive name. For example:

This context root requirement exists because you cannot deploy two different applications having the same context root. If your Enterprise Application must obtain a simple application name (without a version string) programmatically, you can use SipApplicationRuntimeMBean to retrieve the application name without the appended version string. See Accessing the Application Name and Version Identifier.

Deploy the Updated Application Version

To begin the upgrade process, simply deploy the updated application archive using either the Administration Console or weblogic.Deployer utility. WebLogic SIP Server examines the version identifier in the manifest file, and strips the string value from the end of the deployment name to determine if another version of the application is currently deployed. If two versions are deployed, the server automatically begins routing new requests to the most recently-deployed application. The server allows the other deployed application to complete in-flight calls, directs no new calls to it. This process is referred to as "retiring" the older application, because eventually the older application version will process no SIP messages.

Note that WebLogic SIP Server does not compare the actual version strings of two deployed applications to determine which is the higher version. New calls are always routed to the most recently-deployed version of an application.

WebLogic SIP Server also distinguishes between a deployment that has no version identifier (no version string in the manifest) and a subsequent version that does specify a version identifier. This enables you to easily upgrade applications that were packaged before you began including version information as described in Assign a Version Identifier.

Undeploy the Older Application Version

After deploying a new version of an existing application, the original deployment process messages only for in-flight calls (calls that were initiated with the original deployment). After those in-flight calls complete, the original deployment no longer processes any SIP messages. In most production environments, you will want to ensure that the original deployment is no longer processing messages before you undeploy the application.

To determine whether a deployed application is processing messages, you can obtain the active session count from the application's SipApplicationRuntimeMBean instance. Listing A-2 shows the sample WLST commands for viewing the active session count for the findme sample application on the default single-server domain.

Based on the active session count value, you can undeploy the application safely (without losing any in-flight calls) or abruptly (losing the active session counts displayed at the time of undeployment).

Use either the Administration Console or weblogic.Deployer utility to undeploy the correct deployment name.

cd ('examples:Location=myserver,Name=myserver_myserver_findme_findme,ServerRuntime=myserver,Type=SipApplicationRuntime')

Roll Back the Upgrade Process

If you deploy a new version of an application and discover a problem with it, simply undeploying that version reverts the update process. WebLogic SIP Server automatically routes all requests to the earlier version of the application.

Accessing the Application Name and Version Identifier

If you intend to use WebLogic SIP Server's production upgrade feature, applications that are composed of multiple SIP Servlets should not hard-code the application name. This is because the deployment name and context-root of the application must change from version to version in order to support side-by-side deployment. Instead of hard-coding the application name, your application can dynamically access the base application name (without version identifier), the deployment name, or just the version identifier by using helper methods in SipApplicationRuntimeMBean. Table A-2 describes the methods as they would apply to an application deployed as "myApplicationv2.war" with the version identifier "v2" defined in the manifest.

Table A-2 SipApplicationRuntimeMBean Methods for Returning Name and Version Information
Method Signature	Description
`getApplicationVersion()`	Returns only the version string assigned to the application (for example, "v2".
`getActiveVersionState()`	Returns an int value that describes the state of the selected application version: 0 indicates that this version of the application is INACTIVE. This means that the application is either still in the process of being deployed and has not yet been activated, or that WebLogic SIP Server is currently retiring the application. 2 indicates that this version of the application is ACTIVE. The application is currently processing all new requests for the application.
`getApplicationName()`	Returns the base application name without the version identifier (for example, "myApplication").

Configuring and Managing WebLogic SIP Server