Operations Guide

Upgrading Deployed SIP Applications

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

Overview of SIP Application Upgrades

With WebLogic SIP Server, 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 undeploy the newer version and activate the older version.

Note:

When you undeploy an active version of an application, the previous application version remains in administration mode. You must explicitly activate the older version in order to direct new requests to the application.

You can also use the upgrade functionality with a SIP administration channel to deploy a new application version with restricted access for final testing. After performing final testing using the administration channel, you can open the application to general SIP traffic.

WebLogic SIP Server application upgrades provide the same functionality as WebLogic Server 9.2 application upgrades, with the following exceptions:

WebLogic SIP Server does not support “graceful” retirement of old application versions. Instead, only timeout-based undeployment is supported using the -retiretimeout option to weblogic.Deployer.
If you want to use administration mode with SIP Servlets or converged applications, you must configure a sips-admin channel that uses TLS transport.
WebLogic SIP Server handles application upgrades differently in replicated and non-replicated environments. In replicated environments, the server behaves as if the save-sessions-enabled element was set to “true” in the weblogic.xml configuration file. This preserves sessions across a redeployment operation.

For non-replicated environments, sessions are destroyed immediately upon redeployment.

See Redeploying Applications in a Production Environment in the WebLogic Server 9.2 documentation for general information and instructions regarding production application redeployment.

Requirements and Restrictions for Upgrading Deployed Applications

To use the application upgrade functionality of WebLogic SIP Server:

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.
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 Server provides ApplicationRuntimeMBean 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.
If you want to deploy an application in administration mode, you must configure a sips-admin channel that uses TLS transport. See Managing WebLogic SIP Server Network Resources in Configuring Network Resources.

Steps for Upgrading a Deployed SIP Application

Follow these steps to upgrade a deployed SIP application to a newer version:

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 ApplicationRuntimeMBean 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 0-1.

Table 0-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 or specify it on the command line at deployment time. See Specifying an Application Version Identifier in the WebLogic Server 9.2 documentation for more information.

Defining the Version in the Manifest

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

Listing 0-1 Version Identifier in Manifest

Manifest-Version: 1.0

Created-By: 1.4.1_05-b01 (Sun Microsystems Inc.)

Weblogic-Application-Version: v2

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.

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. Use the -retiretimeout option to the weblogic.Deployer utility if you want to automatically undeploy the older application version after a fixed amount of time. For example:

java weblogic.Deployer -name MyApp -version v2 -deploy -retiretimeout 7

WebLogic SIP Server examines the version identifier in the manifest file 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 0-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.

Listing 0-2 Sample WLST Session for Examining Session Count

connect()

custom()

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

ls()

-rw-   ActiveAppSessionCount                        0

-rw-   ActiveSipSessionCount                        0

-rw-   AppSessionCount                              0

-rw-   CachingDisabled                              true

-rw-   MBeanInfo                                    weblogic.management.tools.In

fo@5ae636

-rw-   Name                                         myserver_myserver_findme_fin

dme

-rw-   ObjectName                                   examples:Location=myserver,N

ame=myserver_myserver_findme_findme,ServerRuntime=myserver,Type=SipApplicationRu

ntime

-rw-   Parent                                       examples:Location=myserver,N

ame=myserver,Type=ServerRuntime

-rw-   Registered                                   false

-rw-   SipSessionCount                              0

-rw-   Type                                         SipApplicationRuntime

-rwx   preDeregister                                void :

Roll Back the Upgrade Process

If you deploy a new version of an application and discover a problem with it, you can roll back the upgrade process by:

Undeploying the active version of the application.
Activating the older version of the application. For example:

java weblogic.Deployer -name MyApp -appversion v1 -start

Note:

Alternately, you can use simply use the -start option to start the older application version, which causes the older version of the application to process new requests and retire the newer version.

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. Instead of hard-coding the application name, your application can dynamically access the deployment name or version identifier by using helper methods in ApplicationRuntimeMBean. See ApplicationRuntimeMBean in the WebLogic Server 9.2 documentation for more information.

Using Administration Mode

You can optionally use the -adminmode option with weblogic.Deployer to deploy a new version of an application in administration mode. While in administration mode, SIP traffic is accepted only via a configured network channel named sips-admin having the TLS transport. If no sips-admin channel is configured, or if a request is received using a different channel, the server rejects the request with a 503 message.

To transition the application from administration mode to a generally-available mode, use the -start option with weblogic.Deployer.

Note:

If using TLS is not feasible with your application, you can alternately change the Servlet role mapping rules to allow only 1 user on the newer version of the application. This enables you to deploy the newer version alongside the older version, while restricting access to the newer version.