Skip Headers
Oracle® Communications Converged Application Server Developer's Guide
Release 5.1

Part Number E27707-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

6 Porting Existing Applications to Oracle Communications Converged Application Server

This chapter describes guidelines and issues related to porting existing applications based on the SIP Servlet v1.0 specification to Oracle Communications Converged Application Server and the SIP Servlet v1.1 specification.

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 Converged Application Server. Use the SIP Servlet v1.1 techniques for all new development. Application composition techniques described in earlier versions of WebLogic SIP Server are now deprecated.

Converged Application Server provides backwards compatibility for applications using version SIP Servlet 1.0 composition techniques, provided that:

SipSession and SipApplicationSession Not Serializable

The SipSession and SipApplicationSession interfaces are no longer serializable in the SIP Servlet v1.1 specification. Converged Application Server 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 Converged Application Server.

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 at the Java Community Process web site (JSR 289: SIP Servlet v1.1 at jcp.org) for more information.

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 Converged Application Server unchanged. However, the source code must be modified to not catch the exception before you can recompile.

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.

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 6-1 are immutable and cannot be modified using this new interface.

Table 6-1 Immutable System Header Parameters

Parameter Description

Header

Immutable Parameters

Contact

 

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.


Stateless Transaction Proxies Deprecated

For applications in Converged Application Server, 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.

Backward-Compatibility Mode for v1.0 Deployments

Converged Application Server 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 Converged Application Server.

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 Converged Application Server, 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).

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, Converged Application Server throws the IllegalStateException only when a version 1.1 SIP Servlet deployment modifies a committed message.

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.

SipServletResponse.createPrack() Exception

In Converged Application Server, 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.

Proxy.proxyTo() Exceptions

For version 1.1 SIP Servlets, Converged Application Server 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, Converged Application Server ignores the duplicate URIs (and throws no exception) if a version 1.0 SIP Servlet specifies duplicate URIs with these methods.

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 Converged Application Server 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 Converged Application Server always set sequential branch proxy time-outs 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 Converged Application Server 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.

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 6-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 6-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 9-1, "Deprecated com.bea.wcp.util.Sessions Methods" to learn more.


SNMP MIB Changes

Previous versions of the Converged Application Server 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. Converged Application Server 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 Converged Application Server, 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 Converged Application Server MIB file is installed as $WLSS_HOME/server/lib/WLSS-MIB.asn1.

Renamed Diagnostic Monitors and Actions

The diagnostic monitors and diagnostic actions provided in Converged Application Server 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 Converged Application Server.

See the discussion on using the WebLogic Server Diagnostic Framework (WLDF) in the Converged Application Server Administrator's Guide for more information.