C Porting Existing Applications to Oracle WebLogic Server SIP Container

This chapter describes guidelines and issues related to porting existing applications based on SIP Servlet v1.0 specification to Oracle WebLogic Server SIP Container and the SIP Servlet v1.1 specification. It contains the following sections:

Section C.1, "Application Router and Legacy Application Composition"
Section C.2, "SipSession and SipApplicationSession Not Serializable"
Section C.3, "SipServletResponse.setCharacterEncoding() API Change"
Section C.4, "Transactional Restrictions for SipServletRequest and SipServletResponse"
Section C.5, "Immutable Parameters for New Parameterable Interface"
Section C.6, "Stateless Transaction Proxies Deprecated"
Section C.7, "Backward-Compatibility Mode for v1.0 Deployments"
Section C.8, "Deprecated APIs"
Section C.9, "SNMP MIB Changes"
Section C.10, "Renamed Diagnostic Monitors and Actions"

C.1 Application Router and Legacy Application Composition

The SIP Servlet v1.1 specification describes a formal application selection and composition process, which is fully implemented in Oracle WebLogic Server SIP Container. Use the SIP Servlet v1.1 techniques for all new development. Application composition techniques described in earlier versions are now deprecated.

Oracle WebLogic Server SIP Container provides backwards compatibility for applications using version SIP Servlet 1.0 composition techniques, provided that:

you do not configure a custom Application Router, and
you do not configure Default Application Router properties.

C.2 SipSession and SipApplicationSession Not Serializable

The SipSession and SipApplicationSession interfaces are no longer serializable in the SIP Servlet v1.1 specification. Oracle WebLogic Server SIP Container maintains binary compatibility for the earlier v1.0 specification, to allow any compiled applications that treat these interfaces as serializable objects to work. However, you must modify the source code of such applications before you can recompile them with Oracle WebLogic Server SIP Container.

Version 1.0 Servlets that stored the SipSession as a serializable info object using the TimerService.createTimer API can achieve similar functionality by storing the SipSession ID as the serializable info object. On receiving the timer expiration callback, applications must use the SipApplicationSession and the serialized ID object returned by the ServletTimer to find the SipSession within the SipApplicationSession using the retrieved ID. See the SIP Servlet v1.1 API JavaDoc for more information.

C.3 SipServletResponse.setCharacterEncoding() API Change

SipServletResponse.setCharacterEncoding() no longer throws UnsupportedEncodingException. If you have an application that explicitly catches UnsupportedEncodingException with this method, the existing, compiled application can be deployed to Oracle WebLogic Server SIP Container unchanged. However, the source code must be modified to not catch the exception before you can recompile.

C.4 Transactional Restrictions for SipServletRequest and SipServletResponse

SIP Servlet v1.1 acknowledges that SipServletRequest and SipServletResponse objects always belong to a SIP transaction. The specification further defines the conditions for committing a message, after which no application can modify or re-send the message. See 5.2 Implicit Transaction State in the SIP Servlet Specification v1.1 (http://jcp.org/en/jsr/detail?id=289) for a list of conditions that commit SIP messages.

As a result of this change, any attempt to modify (set, add, or remove a header) or send a committed message now results in an IllegalStateException. Ensure that any existing code checks for the committed status of a message using SipServletMessage.isCommitted() before modifying or sending a message.

C.5 Immutable Parameters for New Parameterable Interface

SIP Servlet v1.1 introduces a new javax.servlet.sip.Parameterable interface for accessing, creating, and modifying parameters in various SIP headers. Note that the system header parameters described in Table C-1 are immutable and cannot be modified using this new interface.

Table C-1 Immutable System Header Parameters

Header	Immutable Parameters
From	tag
To	tag
Via	branch, received, rport, wlsslport, wlssladdr, maddr, ttl
Record-Route	All parameters are immutable.
Route	For initial requests, the application that pushes the Route header can modify any of the header's parameters. In all other cases, the parameters of the Route header are immutable.
Path	For Register requests, the application that pushes the Path header can modify any of the header's parameters.In all other cases, the parameters of the Path header are immutable.

C.6 Stateless Transaction Proxies Deprecated

For applications in Oracle WebLogic Server SIP Container, the Proxy function is always transactionally stateful, and setting the Proxy object to stateless has no effect.

The Proxy.setStateful() and Proxy.getStateful() methods are redundant: Proxy.getStateful() always returns true, and Proxy.setStateful() performs no operation.

C.7 Backward-Compatibility Mode for v1.0 Deployments

Oracle WebLogic Server SIP Container automatically detects precompiled, v1.0 deployments and alters the SIP container behavior to maintain backward compatibility. The sections that follow describe differences in behavior that occur when deploying v1.0 SIP Servlets to Oracle WebLogic Server SIP Container.

C.7.1 Validation Warnings for v1.0 Servlet Deployments

The SIP Servlet v1.1 specification requires more strict validation of Servlet deployments than the previous specification. In the following cases, v1.0 SIP Servlets can be successfully deployed to Oracle WebLogic Server SIP Container, but a warning message is displayed at deployment:

If a listener is declared in the listener-class element of a v1.0 deployment descriptor but the corresponding class does not implement the EventListener interface, a warning is displayed during deployment. (Version 1.1 SIP Servlets that declare a listener must implement EventListener, or the application cannot be deployed).
If a SIP Servlet is declared in the servlet-class element of a v1.0 deployment descriptor, but the corresponding class does extend the SipServlet abstract class, a warning is displayed. (Version 1.1 SIP Servlets must extend SipServlet, or the application cannot be deployed).

C.7.2 Modifying Committed Messages

The SIP Servlet v1.1 specification now recommends that the SIP container throw an IllegalStateException if an application attempts to modify a committed message. To maintain backward compatibility, Oracle WebLogic Server SIP Container throws the IllegalStateException only when a version 1.1 SIP Servlet deployment modifies a committed message.

C.7.3 Path Header as System Header

The SIP Servlet v1.1 specification now defines the Path header as a system header, which cannot be modified by an application. Version 1.0 SIP Servlets can still modify the Path header, but a warning message is generated. Version 1.1 SIP Servlets that attempt to modify the Path header fail with an IllegalArgumentException.

C.7.4 SipServletResponse.createPrack() Exception

In Oracle WebLogic Server SIP Container, SipServletResponse.createPrack() can throw Rel100Exception only for version 1.1 SIP Servlets. createPrack() does not throw the exception for version 1.0 SIP Servlets to maintain backward compatibility.

C.7.5 Proxy.proxyTo() Exceptions

For version 1.1 SIP Servlets, Oracle WebLogic Server SIP Container throws an IllegalStateException if a version 1.1 SIP Servlet specifies a duplicate branch URI with Proxy.proxyTo(uri) or Proxy.proxyTo(uris). To maintain backward compatibility, Oracle WebLogic Server SIP Container ignores the duplicate URIs (and throws no exception) if a version 1.0 SIP Servlet specifies duplicate URIs with these methods.

C.7.6 Changes to Proxy Branch Timers

SIP Servlet v1.1 makes several protocol changes that effect the behavior of proxy branching for both sequential and parallel proxying.

For sequential proxying, the v1.1 specification requires that Oracle WebLogic Server SIP Container start a branch timer using the maximum of the sequential-search-timeout value, which is configured in sip.xml, or SIP protocol Timer C (> 3 minutes). Prior versions of Oracle WebLogic Server SIP Container always set sequential branch proxy timeouts using the value of sequential-search-timeout; this behavior is maintained for v1.0 deployments.

For parallel proxying, the v1.1 specification provides a new proxyTimeout value that controls proxying. The specification requires that Oracle WebLogic Server SIP Container reset a branch timer using the configured proxyTimeout value, rather than using the Timer C value as required in the SIP Servlet v1.0 specification. The Timer C value is still used for v1.0 deployments.

C.8 Deprecated APIs

Earlier versions of WebLogic SIP Server provided proprietary APIs to support functionality and RFCs that were not supported in the SIP Servlet v1.0 specification. The SIP Servlet v1.1 specification adds new RFC support and functionality, making the proprietary APIs redundant. Table C-2 shows newly-available SIP Servlet v1.1 methods that must be used in place of now-deprecated WebLogic SIP Server methods. The deprecated methods are still available in this release to provide backward compatibility for v1.0 applications.

Table C-2 Deprecated APIs

Deprecated Methods (WebLogic SIP Server Proprietary)	Replacement Method (SIP Servlet v1.1)
`WlssSipServlet.doRefer()`, `WlssSipServlet.doUpdate()`, `WlssSipServlet.doPrack()`	`SipServlet.doRefer()`, `SipServlet.doUpdate()`, `SipServlet.doPrack()`
`WlssSipServletResponse.createPrack()`	`SipServletResponse.createPrack()`
`WlssProxy.getAddToPath()`, `WlssProxy.setAddToPath()`	`Proxy.getAddToPath()`, `Proxy.setAddToPath()`
`WlssSipServletMessage.setHeaderForm()`, `WlssSipServletMessage.getHeaderForm()`	`SipServletMessage.setHeaderForm()`, `SipServletMessage.getHeaderForm()`
`com.bea.wcp.util.Sessions`	See Table 6–1, "Sessions in a Converged Application".

C.9 SNMP MIB Changes

Previous versions of the Oracle WebLogic Server SIP Container SNMP MIB definition did not follow the WebLogic MIB naming convention. Specifically, the MIB table column name label did not begin with the table name. Oracle WebLogic Server SIP Container changes the SNMP MIB definition to prepend labels with sipServer in order to comply with the WebLogic naming convention and provide compatibility with WebLogic tools that generate the metadata file.

For example, in version 3.x the SipServerEntry MIB definition was:

SipServerEntry  ::=  SEQUENCE {
  sipServerIndex  DisplayString,
  t1TimeoutInterval  INTEGER,
  t2TimeoutInterval  INTEGER,
  t4TimeoutInterval  INTEGER,
  .... 
  }

In Oracle WebLogic Server SIP Container, the definition is now:

SipServerEntry  ::=  SEQUENCE {
  sipServerIndex  DisplayString,
  sipServerT1TimeoutInterval  Counter64,
  sipServerT2TimeoutInterval  INTEGER,
  sipServerT4TimeoutInterval  INTEGER,
  .....
  }

This change in the MIB may cause backwards compatibility issues if an application or script uses the MIB table column name labels directly. All hard-coded labels, such as iso.org.dod.internet.private.enterprises.bea.wlss.sipServerTable.t1TimeoutInterval must be changed to prepend the table name (iso.org.dod.internet.private.enterprises.bea.wlss.sipServerTable.sipServerT1TimeoutInterval).

Note:

Client-side SNMP tools generally load a MIB and issue commands to retrieve values based on the loaded MIB labels. These tools are unaffected by the above change.

The complete Oracle WebLogic Server SIP Container MIB file is installed as $WLSS_HOME/server/lib/wlss/BEA-WLSS-MIB.asn1.

C.10 Renamed Diagnostic Monitors and Actions

The diagnostic monitors and diagnostic actions provided in Oracle WebLogic Server SIP Container are now prefixed with occas/. For example, the SIP Server 3.1 Sip_Servlet_Before_Service monitor is now named occas/Sip_Servlet_Before_Service. You must update any existing diagnostic configuration files or applications that reference the non-prefixed names before they can work with Oracle WebLogic Server SIP Container.