Oracle E10293-02 User Manual

Oracle® Communication and Mobility Server

Developer’s Guide

Release 10.1.3

E10293-02

August 2007

Oracle Communication and Mobility Server Developer’s Guide Release 10.1.3

E10293-02

Copyright © 2006, 2007, Oracle. All rights reserved.

The Programs (which include both the software and documentation) contain proprietary information; they
are provided under a license agreement containing restrictions on use and disclosure and are also protected
by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly,
or decompilation of the Programs, except to the extent required to obtain interoperability with other
independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in
the documentation, please report them to us in writing. This document is not warranted to be error-free.
Except as may be expressly permitted in your license agreement for these Programs, no part of these
Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any
purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs
on behalf of the United States Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data
delivered to U.S. Government customers are
data

" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental

regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including
documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable
Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19,
Commercial Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway,
Redwood City, CA 94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently
dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup,
redundancy and other measures to ensure the safe use of such applications if the Programs are used for such
purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third
parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites.
You bear all risks associated with the use of such content. If you choose to purchase any products or services
from a third party, the relationship is directly between you and the third party. Oracle is not responsible for:
(a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the
third party, including delivery of products or services and warranty obligations related to purchased
products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from
dealing with any third party.

"commercial computer software" or "commercial technical

Contents

Preface ................................................................................................................................................................. ix

Audience....................................................................................................................................................... ix

Documentation Accessibility..................................................................................................................... ix

Related Documents ..................................................................................................................................... x

Conventions ................................................................................................................................................. x

1 Overview

Introduction to Oracle Communication and Mobility Server......................................................... 1-1

New in this Release............................................................................................................................ 1-1

Application Development in OCMS.................................................................................................... 1-2

SIP Servlet API.................................................................................................................................... 1-2

Parlay X Web Service Interface ................................................................................................. 1-2

Presence Web Services ............................................................................................................... 1-2

Oracle Communication and Mobility Server Development Tools ............................................. 1-2

2 SIP Servlets

Introduction to SIP Servlets ................................................................................................................... 2-1

The SIP Container .................................................................................................................................... 2-2

Servlet Context ................................................................................................................................... 2-2

SIP Application Sessions................................................................................................................... 2-3

Protocol Sessions................................................................................................................................ 2-3

Transactions ........................................................................................................................................ 2-3

Servlets................................................................................................................................................. 2-4

Increased Servlet Modularity.................................................................................................... 2-4

Renaming SAR Files for the JBoss Application Server.......................................................... 2-4

Listeners............................................................................................................................................... 2-4

SIP Servlets and SIP Applications........................................................................................................ 2-5

SIP Servlet Environment......................................................................................................................... 2-5

Servlet Mapping ................................................................................................................................. 2-7

Classes and Methods ............................................................................................................................ 2-7

Request and Response Handling Methods .................................................................................... 2-7

Messages....................................................................................................................................... 2-8

Requests........................................................................................................................................ 2-8

Responses..................................................................................................................................... 2-9

Content ......................................................................................................................................... 2-9

Manipulating SIP headers ......................................................................................................... 2-9

SipURI........................................................................................................................................ 2-10

Address...................................................................................................................................... 2-11

SIP Details ................................................................................................................................. 2-11

Storing Data as Session Attributes................................................................................................ 2-12

Adding Configuration Parameters............................................................................................... 2-12

Configuring SIP Applications in sip.xml......................................................................................... 2-13

iii

Setting and Accessing Global Init Parameters............................................................................ 2-13

Configuring Application Sessions ................................................................................................ 2-13

Defining a Servlet............................................................................................................................ 2-14

Defining the Servlet Mapping....................................................................................................... 2-14

Creating Rules Using the Request Object Structure ........................................................... 2-15

Conditions................................................................................................................................. 2-16

Examples ................................................................................................................................... 2-16

SIP Servlets in OCMS .......................................................................................................................... 2-18

Handling Initial Requests .............................................................................................................. 2-18

Implementation Decisions ............................................................................................................. 2-19

Protocol Sessions...................................................................................................................... 2-20

Extended doRequest Methods ............................................................................................... 2-20

Asynchronous Send................................................................................................................. 2-20

Multi-Threading.............................................................................................................................. 2-20

Sip Servlet API Javadoc.................................................................................................................. 2-20

External Access to SIP Servlets...................................................................................................... 2-20

OCMS Authentication and Login Modules ................................................................................ 2-21

3 Advanced SIP Servlet Configuration

Using the appId Parameter to Set Addresses for SIP Applications ............................................... 3-1

Configuring the appId Parameter.................................................................................................... 3-2

Adding Deployed Applications to the SipUriList Attribute................................................ 3-3

Configuring Application Security ........................................................................................................ 3-4

4 Programming Guidelines

Introduction............................................................................................................................................... 4-1

Marking Applications as Distributable............................................................................................... 4-1

Storing Data in Application Sessions .................................................................................................. 4-2

Avoiding Static Data................................................................................................................................ 4-2

Avoiding Blocking Calls ......................................................................................................................... 4-2

Invalidating the SipApplicationSession and SIPSession................................................................ 4-2

Monitoring the Memory Usage ............................................................................................................. 4-2

Avoiding Storing Shared Resources in Sessions ............................................................................... 4-2

Avoiding Creating Threads .................................................................................................................... 4-2

Creating B2BUA Applications ............................................................................................................... 4-2

5 Building a SIP Servlet Application

Prerequisites.............................................................................................................................................. 5-1

SIP Application Development Process ................................................................................................ 5-2

Creating a New Dynamic Web Project with SIP Support ................................................................ 5-3

Importing an Existing Project ................................................................................................................ 5-3

Importing Example Projects ................................................................................................................... 5-4

Importing the Basic Response SIP Application Example Project................................................ 5-5

Importing the Call Forward SIP Application Example Project................................................... 5-5

Importing the Message Sender SIP/Web Converged Application Example Project............... 5-6

Importing the Proxy/Registrar Example Project .......................................................................... 5-6

iv

Importing the Third Party Call Control Example Project............................................................ 5-6

Deploying a SIP Application to OCMS............................................................................................... 5-7

Testing an Application ............................................................................................................................ 5-8

Changing the Logging Level ............................................................................................................ 5-8

Viewing the System Log File............................................................................................................ 5-8

Starting the OCMS Server in Eclipse............................................................................................... 5-8

Testing a Third Party Call Control Servlet..................................................................................... 5-9

6 OCMS Parlay X Web Services

Introduction............................................................................................................................................... 6-1

Installing the Web Services .................................................................................................................... 6-2

Installing the Aggregation Proxy.......................................................................................................... 6-2

Configuring Web Services with the Aggregation Proxy................................................................... 6-2

Presence Web Services Interface Descriptions ................................................................................... 6-2

Using the Presence Web Services Interfaces ....................................................................................... 6-3

Interface: PresenceConsumer, Operation: subscribePresence..................................................... 6-3

Code Example.............................................................................................................................. 6-3

Interface: PresenceConsumer, Operation: getUserPresence........................................................ 6-4

Code Example.............................................................................................................................. 6-4

Interface PresenceSupplier, Operation: publish and Oracle Specific "Unpublish" .................. 6-5

Code Example.............................................................................................................................. 6-5

Interface: PresenceSupplier, Operation: getOpenSubscriptions................................................. 6-6

Code Example.............................................................................................................................. 6-6

Interface: PresenceSupplier, Operation: updateSubscriptionAuthorization............................. 6-6

Code Example.............................................................................................................................. 6-6

Interface: PresenceSupplier, Operation: getMyWatchers ............................................................ 6-6

Code Example.............................................................................................................................. 6-6

Interface: PresenceSupplier, Operation: getSubscribedAttributes ............................................. 6-7

Code Example.............................................................................................................................. 6-7

Interface: PresenceSupplier, Operation: blockSubscription......................................................... 6-7

Code Example.............................................................................................................................. 6-7

OCMS Parlay X Presence Custom Error Codes .................................................................................. 6-7

A Oracle Diameter Java APIs

Diameter Java Base Protocol API ......................................................................................................... A-2

Base Protocol Diameter Java Interface ........................................................................................... A-3

Diameter Factory........................................................................................................................ A-3

Diameter Stack............................................................................................................................ A-3

Diameter Application................................................................................................................ A-3

Diameter Transport ................................................................................................................... A-3

Diameter AVPs........................................................................................................................... A-3

Diameter Session........................................................................................................................ A-4

Diameter Event........................................................................................................................... A-4

Diameter Exception ................................................................................................................... A-4

3GPP/Rf Diameter Java API .................................................................................................................. A-5

3GPP/Rf Diameter Java Interface................................................................................................... A-5

v

Rf Provider.................................................................................................................................. A-5

Rf Listener ................................................................................................................................... A-5

Rf Message Factory.................................................................................................................... A-5

Rf Events...................................................................................................................................... A-6

Rf Application Options ............................................................................................................. A-7

Rf Application FSM ................................................................................................................... A-8

3GPP/Ro DIAMETER JAVA API.......................................................................................................... A-9

3GPP/Ro DIAMETER JAVA INTERFACE................................................................................... A-9

Ro Provider................................................................................................................................. A-9

Ro Listener ................................................................................................................................ A-10

Ro Message Factory................................................................................................................. A-10

3GPP/Ro Dictionary ............................................................................................................... A-11

Ro Events................................................................................................................................... A-11

Ro Application Options .......................................................................................................... A-12

Ro Application FSM................................................................................................................. A-13

3GPP/Sh Diameter Java API................................................................................................................ A-14

3GPP/Sh Diameter Java Interface ................................................................................................ A-14

Sh Provider................................................................................................................................ A-14

Sh Listener................................................................................................................................. A-15

Sh Message Factory.................................................................................................................. A-15

3GPP/Sh Dictionary ....................................................................................................................... A-16

Sh Events .......................................................................................................................................... A-16

Sh Application Options.................................................................................................................. A-17

Diameter Application Example .......................................................................................................... A-17

Accounting Call Flow..................................................................................................................... A-17

Application initialization........................................................................................................ A-18

Accounting Diameter message exchange............................................................................. A-20

Cleaning..................................................................................................................................... A-22

B Programming Oracle Diameter Applications

IP and Routes Configuration ................................................................................................................ B-1

Creating a Diameter Stack ............................................................................................................... B-1

Binding to Local Transport Addresses .......................................................................................... B-1

Configuring Routes and Binding to Diameter Peers................................................................... B-2

Realm State Availability................................................................................................................... B-2

Counters Management ........................................................................................................................... B-3

MBeans Management Interface....................................................................................................... B-3

Managing a Diameter Application with MBeans......................................................................... B-4

Registering the Diameter MBeans........................................................................................... B-4

Using jconsole to Monitor Diameter Applications................................................................ B-4

Dictionary ................................................................................................................................................. B-5

Dictionary Composition................................................................................................................... B-5

dictionary Element..................................................................................................................... B-5

vendor Element .......................................................................................................................... B-5

application Element................................................................................................................... B-5

command Element..................................................................................................................... B-6

returnCode Element .................................................................................................................. B-6

vi

avp Element ................................................................................................................................ B-7

type Element............................................................................................................................... B-7

enum Element............................................................................................................................. B-8

grouped Element........................................................................................................................ B-9

Dictionary Extension ........................................................................................................................ B-9

Tracing and Logging Mechanism....................................................................................................... B-10

C Accounting Event API

Introduction.............................................................................................................................................. C-1

logEvent(SipServletRequest req, Map<Object, Object> additional) Method ............................ C-2

logEvent(SipServletResponse resp, Map<Object, Object> additional) Method ....................... C-3

logEvent(Map <Object, Object> event, String category) Method ................................................. C-3

Event Processing in Log4j...................................................................................................................... C-4

Index

vii

viii

This preface contains the following topics:

■ Audience

■ Documentation Accessibility

■ Related Documents

■ Conventions

Audience

This guide is intended for developers and programmers who want to use Oracle
Communication and Mobility Server to create custom applications.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation
accessible, with good usability, to the disabled community. To that end, our
documentation includes features that make information available to users of assistive
technology. This documentation is available in HTML format, and contains markup to
facilitate access by the disabled community. Accessibility standards will continue to
evolve over time, and Oracle is actively engaged with other market-leading
technology vendors to address technical obstacles so that our documentation can be
accessible to all of our customers. For more information, visit the Oracle Accessibility
Program Web site at

Preface

http://www.oracle.com/accessibility/

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The
conventions for writing code require that closing braces should appear on an
otherwise empty line; however, some screen readers may not always read a line of text
that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or
organizations that Oracle does not own or control. Oracle neither evaluates nor makes
any representations regarding the accessibility of these Web sites.

ix

TTY Access to Oracle Support Services

Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services
within the United States of America 24 hours a day, seven days a week. For TTY
support, call 800.446.2398.

Related Documents

For more information, see the following documents:

■ Oracle Communication and Mobility Server Installation Guide

■ Oracle Communication and Mobility Server Administrator’s Guide

■ Oracle Communication and Mobility Server sample documentation (available at

Oracle Technology Network at http://www.oracle.com/technology/index.html)

■ A. Kristensen, "SIP Servlet API Version 1.0", February 4, 2003. Available in the

OCMS SCE installation at C:\Program Files\Oracle\OCMS SCE\doc

■ G. Murray, et al., "Java Servlet Specification, Version 2.5", May 11, 2006

Conventions

The following text conventions are used in this document:

Convention Meaning

boldface Boldface type indicates graphical user interface elements associated

italic Italic type indicates book titles, emphasis, or placeholder variables for

monospace Monospace type indicates commands within a paragraph, URLs, code

with an action, or terms defined in text or the glossary.

which you supply particular values.

in examples, text that appears on the screen, or text that you enter.

x

This chapter describes application development for the Oracle Communication and
Mobility Server (OCMS) in the following sections:

■ "Introduction to Oracle Communication and Mobility Server"

■ "Application Development in OCMS"

Introduction to Oracle Communication and Mobility Server

Oracle Communication and Mobile Server (OCMS) is a carrier-grade SIP application
environment for the development, deployment, and management of SIP applications.
Built on a standard Java2 Enterprise Edition (J2EE) platform, OCMS is a flexible,
scalable environment enabling easy integration of SIP applications and services.

Among the applications that may be developed and deployed on SIP platforms:

■ Voice and video telephony, including call management services such as call

forwarding and call barring

1

Overview

■ Publication of and subscription to user presence information, such as online or

■ Instant messaging

■ Push-to-Talk applications, including Push-to-Talk over Cellular (PoC)

OCMS provides standard SIP applications out-of-the-box, including Presence, a
combination Proxy and Registrar (Proxy/Registrar), and a SIP message routing
application, the Application Router. An integral part of any SIP platform, these
applications are automatically installed to the OCMS platform, reducing development
resources and deployment time.

OCMS is distinguished by its standards-based, high performance Presence application
which is built according to the OMA/Simple Presence Enabler 1.0. The OCMS
Presence application is robust enough to support a significant amount of users, while
still being a viable solution for ISVs, system integrators, and enterprises requiring an
integration platform and an enterprise Presence Server.

New in this Release

This release of Oracle Communication and Mobility Server includes enhancements
and new features. To read about new and improved features, see
http://www.oracle.com/technology/products/ocms/otn_front.htm.

offline status, notifications, permission to access a user’s status

Overview 1-1

Application Development in OCMS

Application Development in OCMS

The OCMS environment enables you to develop JSR-116-compliant applications
through its support of the following:

■ SIP Servlet API

■ Parlay X Web Service Interface

SIP Servlet API

OCMS supports development of SIP servlets using the JSR-116 SIP Servlet API. Using
these interfaces, you can build a SIP Servlet to create customized SIP-based
components that terminate SIP messages, send SIP responses, and proxy SIP messages.
For an overview of SIP servlets and the OCMS extensions to the SIP Servlet API, see

Chapter 2, "SIP Servlets". For an overall view of developing applications in OCMS, see
Chapter 5, "Building a SIP Servlet Application".

Parlay X Web Service Interface

OCMS supports application development using the Parlay X Presence Web Service
interface as defined in Open Service Access, Parlay X Web Services, Part 14, Presence ETSI
ES 202 391-14. Using Parlay X interface, you can build a Web Service that acts as a
client for many users by providing them functions for publishing, subscribing and
listening to notifies. For more information on OCMS support of the Parlay X Web
Service interfaces and developing a Web Service using OCMS SCE as the IDE, see

Chapter 6, "OCMS Parlay X Web Services". For examples of building a Parlay X Web

Service for the Oracle WebCenter 10.1.3.3 platform, see the Oracle Communication and
Mobility Server documents on Oracle Technology Network
(http://www.oracle.com/technology/index.html).

Presence Web Services

You can use the Oracle JDeveloper 10g to test Presence Web Services. Oracle
JDeveloper Release 10.1.3.3 or higher is the preferred development tool for customers
creating applications for the WebCenter 10.1.3.3 platform. For more information on
using Oracle JDeveloper 10g within OCMS, refer to Oracle Communication and
Mobility Server documents on Oracle Technology Network
(http://www.oracle.com/technology/index.html).

Oracle Communication and Mobility Server Development Tools

OCMS provides OCMS Service Creation Environment (OCMS SCE) as the primary
development tool. Oracle JDeveloper is a secondary tool which is used to test Presence
Web Se rvices.

OCMS SCE

OCMS provides the OCMS Service Creation Environment (OCMS SCE), a
development tool for SIP servlets and server-side applications. OCMS SCE (SCE),
intended for developers on the Windows operating systems, provides tools and APIs
for creating services using the OCMS platform. OCMS SCE, which runs on Eclipse,
supports your development effort through the Code, Build, Deploy and Debug phases of
the development cycle (

For information on building applications with OCMS SCE, see Chapter 5, "Building a

SIP Servlet Application".

Figure 1–1).

1-2 Oracle Communication and Mobility Server Developer’s Guide

Figure 1–1 OCMS SCE Application Development Support

Application Development in OCMS

Overview 1-3

Application Development in OCMS

1-4 Oracle Communication and Mobility Server Developer’s Guide

This chapter provides an overview of SIP Servlets and the SIP Servlet API (as
described in JSR-116) in the following sections:

■ "Introduction to SIP Servlets"

■ "The SIP Container"

■ "SIP Servlets and SIP Applications"

■ "SIP Servlet Environment"

■ "Classes and Methods"

■ "Configuring SIP Applications in sip.xml"

■ "SIP Servlets in OCMS"

Introduction to SIP Servlets

This chapter provides an overview the SIP Servlet API, the SIP container, the SIP
servlet environment, SIP classes and methods, and SIP application configuration.

2

SIP Servlets

The SIP Servlet API is defined in JSR 116, and describes a standard interface for
programming SIP services and applications. A SIP servlet can be compared with a Java
HTTP servlet but with SIP protocol-related methods. In fact, the SIP Servlet API builds
on the general Servlet API in the same way as the HTTP Servlet API

SIP Servlets are grouped into four categories:

■ User Agent Server: A servlet that acts as a User Agent Server (UAS) receives

incoming requests and sends responses.

■ User Agent Client: A servlet that acts as a User Agent Client (UAC) initiates

outgoing requests and receives responses to these requests.

■ Proxy: A servlet that acts as a proxy receives incoming requests and proxies them

to other end-points (other proxies or a UAS). A proxy servlet will manipulate the
request URI and proxy the request to that destination.

■ Back to Back User Agent: A servlet that acts as a Back to Back User Agent (B2BUA)

acts as both a UAS and UAC on a request. It receives and answers back to one
request (first session) and initiates and receives responses on another request
(second session).

SIP Servlets 2-1

The SIP Container

The SIP Container

This section describes the SIP Container (Figure 2–1) by discussing the following
components:

■ Servlet Context

■ SIP Application Sessions

■ Protocol Sessions

■ Tra ns ac ti on s

■ Servlets

■ Listeners

Figure 2–1 The SIP Container Object Model

Servlet Context

The Servlet Context is a servlet view of the SIP application to which it belongs. Using
the Servlet Context, the servlet can access such global application services as listeners
and context init parameters.

The application global init parameters are set in the deployment descriptor, the
sip.xml file, and are marked with the <context-param> marker. Examples of
global application parameters are common resource addresses, like addresses to a
database and backend applications.

The Servlet Context also holds all references to any implemented and configured
listeners. Session and proxy timeouts are held by the Servlet Context. These are
configured in the sip.xml file and the session timeout is found within the
<session-config> and marked in the <session-timeout> section. The proxy
timeout is found within the <proxy-config> and marked in the
<sequential-search-timeout> section.

The Servlet Context is retrieved by calling the getServletContext method from the
servlet. For example:

ServletContext servletContext = getServletContext();

2-2 Oracle Communication and Mobility Server Developer’s Guide

SIP Application Sessions

While an application may involve several types of servlet sessions (for example, SIP
and HTTP), these sessions must be related to the same application. This is done
through a SIP Application Session. The SIP Application Session can hold multiple
protocol sessions; the protocol sessions can be of the same type or different types (SIP,
HTTP).

A SIP Application Session can hold attributes available to all protocol sessions related
to that application session. A SIP Application Session can hold multiple protocol
sessions. For example, B2BUA creates two sessions that are located in the same SIP
Application Session.

A SIP Application Session exists until it times out or when the application explicitly
calls the invalidate method. A well-behaved application should always invalidate a
session when it does not need it anymore. If the SIP Application Session is invalidated,
all Protocol Session objects are invalidated together with it. The timeout value of a
session is set with the <session-timeout> parameter in the sip.xml file. If no
timeout value is defined within this element, then the default value for the container is
used (the default is 15 minutes).

If a subsequent request arrives after a session has been invalidated, then the server will
respond with a 481 "Call transaction does not exist" message. Requests and responses
that correspond to a SIP application session can be retrieved with the
getApplicationSession() method on the request (SipServletRequest) or the
response (SipServletResponse) object.

The SIP Container

Protocol Sessions

A Protocol Session is a session for a certain protocol. If an application involves several
protocols, the SIP application session would then hold several protocol sessions.

A SipSession object can represent a point-to-point SIP relationship, an established
SIP dialog, or an initial state SIP dialog. The initial state is described as a request that
has been received or created with the createRequest method in the sipFactory
class. The SIP session object is created by the container when an initial request has
invoked one servlet.

A request or a response corresponding a SIP session can be retrieved with the
getSession() method on the request (SipServletRequest) or the response
(SipServletResponse) object. All of the protocol sessions in an application session
can be retrieved with the getSessions() method on the
SipApplicationSession object.

Transactions

A SIP transaction consists of a single SIP request and all responses to that request,
including the provisional responses and a final response.

A SipServletRequest and a SipServletResponse always belong to a SIP
transaction. If a servlet tries to send a message that violates the SIP transaction state
model, the container throws an IllegalStateException. The SIP Servlet API is
designed in such a way that a developer does not need to consider transactions, only
requests and responses.

SIP Servlets 2-3

The SIP Container

Servlets

Each servlet defined in the deployment descriptor has one instantiation. Because
servlets are run in a multi-threaded environment, only data that is common to all
requests and responses, such as init parameters, are stored as member variables.

Increased Servlet Modularity

Each servlet, which includes a <servlet> and a <servlet-mapping> section in
the deployment descriptor file (sip.xml) also has a <security-constraint>
section. OCMS makes these servlets reusable through the Servlet Creation wizard in
OCMS SCE, because these sections are created together with the servlet.

Renaming SAR Files for the JBoss Application Server

In OCMS, the Servlet archive format (SAR) file is renamed to a Sip Servlet aRchive
(SSR). The format of the two files are the same, the difference in naming is because of
the requirement for a third-party application server for OCMS. Because the application
server cannot process SAR files, the SIP AS checks for SSR files instead. This name
change enables portability between different SIP application servers.

Note: When you deploy a SIP application through Oracle 10g

Application Server Control or through the admin_client.jar
command-line tool you must rename the Servlet archive file (SAR file)
to WAR and list the WAR file in the application.xml just like a WAR
archive. Also the WAR must contain a web.xml file, so that you can
deploy it on OC4J.

Listeners

For more information on packaging SAR files and deploying EAR
files, see Oracle Communication and Mobility Server Administrator’s
Guide.

Listeners can be registered to listen on events and invoke a method. Each deployment
descriptor can only have one defined listener of each type. Each of these listeners must
be implemented by the developer. The different types of listeners are as follows:

■ SipApplicationSessionListener: The listener for

SipApplicationSession creation and invalidation. It can be used to ask for a
session extension. The SipApplicationSessionListener interface must be
implemented and the sip.xml updated.

■ SipSessionListener: The listener for changes in active SipSessions in the SIP

servlet application. The SipSessionListener interface must be implemented
and configured in the sip.xml file.

■ SipSessionAttributeListener: The listener for SipSession attribute

changes. The SipSessionAttributeListener interface must be implemented.

■ TimerListener: The timer service enables delayed actions for a servlet if the

TimerListener interface has been implemented. Only one timer listener exists
per application (sip.xml).

■ SipSessionActivationListener: Objects that depend on a session can listen

on their status about being active or passive if the
SipSessionActivationListener interface is implemented.

2-4 Oracle Communication and Mobility Server Developer’s Guide

SIP Servlets and SIP Applications

A SIP application is a J2EE-compliant application accessed over the SIP protocol.
Applications are triggered by an inbound SIP protocol request, just as Web
applications are triggered by an inbound HTTP protocol request.

An application has a protocol interface such as SIP or HTTP (presentation tier) that
reaches servlets and other business objects (logic tier) which in turn are managed and
have resource connections to the database (data tier). User and application data are
accessed through the data tier which is represented by applicable parts from the J2EE
specification. Applications are delimited by the scope of the deployment descriptor,
the sip.xml file.

SIP Servlet Environment

This section describes the environment of a SIP servlet and what occurs during both
the startup of the application server (AS) and when a request enters the SIP Container.

Figure 2–2 The SIP Container at Startup

SIP Servlet Environment

1. The following occurs at startup:
a. The container reads the deployment descriptor (sip.xml).
b. A Servlet Context is created.

– The global init parameters are set. These are marked with

<context-param> in the sip.xml file.

– Session Configuration values are set. These are marked with

<session-config> in the sip.xml file.

– Proxy Configuration values are set. These are marked with

<proxy-config> in the sip.xml file.

– The container instantiates the TimerListener,

SipApplicationSessionListener,
SipSessionActivationListener,
SipSessionAttributeListener, and the SipSessionListener.

Each listener has one instantiation (if defined).

c. A Servlet Config object is created. The Servlet Config holds all init parameters

per servlet. These are marked with <init-param> and are set per servlet in
the sip.xml file. It also includes the global init parameters
(context-param).

SIP Servlets 2-5

SIP Servlet Environment

Figure 2–3 Initial Requests Processed by the SIP Container

d. The servlets are created and initiated with the init parameters prepared by the

Servlet Config. Each servlet is run as one instance. The init method in the
servlets is executed.

e. A SIP Application Manager, which contains a reference to

SipApplicationSessions and the SipFactory, is created.

2. The container distinguishes between initial requests and subsequent requests,

where initial requests invoke a servlet depending on the invoke conditions (or
rules) of the servlet and subsequent requests get forwarded directly to the same
servlet as invoked for the initial request. At an Initial Request, the following steps
occur:

a. The container chooses a specific application based on the handling described

in "Handling Initial Requests".

b. Which servlet to invoke is decided by evaluating the rules of each servlet in

the servlet invocation order (

Figure 2–3). The rule execution order is decided

by the order of the <servlet-mapping> order for each servlet in the
sip.xml file. The servlet with the top-most servlet mapping is the one that
get the rules checked first. For more information, see the following section,

"Servlet Mapping".

c. A SIP Application Session is created together with a SIP Session.
d. A transaction and a request are created and associated with the SIP session

object just created.

3. For a subsequent request, one for which the container already holds a dialog (a

dialog is defined by the Local-tag + Remote-tag + CallId), the request is forwarded
to the same servlet executed at the initial request. The request works with the
same Message Context (SIP-Application Session + SIP-Session) as it had in the
initial request.

2-6 Oracle Communication and Mobility Server Developer’s Guide

Servlet Mapping

Classes and Methods

A SIP application can contain one or more SIP Servlets. When the SIP container
receives SIP requests, the container selects a SIP application to serve the request. The
SIP application then evaluates its rules (that is, the servlet-mapping defined in the
sip.xml file) to find the appropriate SIP servlet that responds to the request. The SIP
application then uses the first SIP servlet that matches the request.

Note: SIP servlets can forward the request to another SIP servlet by

using javax.servlet.ServletRequest.getRequestDispatcher()
Additionally, you can chain applications using the Application

Router. Refer to the Oracle Communication and Mobility Server
Administrator’s Guide.

For example, if the SIP container receives an INVITE request, the container selects a
SIP application containing the following SIP Servlets to match the request:

■ Servlet 1 - Invoked for INVITE requests.

■ Servlet 2 - Invoke for MESSAGE requests.

■ Servlet 3 - Invoked for all requests.

The SIP application then attempts to find a match by evaluating its rules from the top
to the bottom. In this case, Servlet 1 and Servlet 3 both match the INVITE request.
Since only one of these servlets can serve the request and since the application reviews
the rules sequentially, the application selects Servlet 1. Servlet 1 starves out Servlet 3. If
the SIP container receives a MESSAGE request, then the application invokes Servlet 2.
For REGISTER requests, the application invokes Servlet 3, the only servlet able to
serve this type of request. If the application does not include Servlet 3, the
application’s match method will return null for the REGISTER request and the SIP
container will issue a 403 response, Application choose not to service the request, which
will be written to the log file.

Note: While a SIP application can invoke only one SIP Servlet for a

request, the SIP container can invoke more than one SIP application
for an incoming request using the Application Router.

Classes and Methods

This section introduces the classes and methods in the SIP servlet API.
A SIP Servlet is a class that extends the javax.servlet.sip.SipServlet class

and thereby interacts with a SIP application server to send and receive SIP messages.

Request and Response Handling Methods

The servlet overrides the methods needed for the particular service. The two main
methods that the SIP Servlet uses to perform overrides are:

■ protected void doRequest(SipServletRequest req)

■ protected void doResponse(SipServletResponse resp)

The doRequest() method handles all of the requests and the doResponse()method
handles all of the responses.

SIP Servlets 2-7

Classes and Methods

Outside of the service method, the doRequest() and doResponse() are the
broadest methods provided by the SipServlet class. These methods enable tasks
that are independent of the received method or response. You can extend methods to
perform specific request and response handling tasks.

Extend the following methods for request handling:

■ doInvite – for SIP INVITE requests

■ doAck – for SIP ACK requests

■ doCancel – for SIP CANCEL requests

■ doBye – for SIP BYE requests

■ doOptions – for SIP OPTIONS requests

■ doRegister – for SIP REGISTER requests

■ doSubscribe – for SIP SUBSCRIBE requests

■ doNotify – for SIP NOTIFY requests

■ doMessage – for SIP MESSAGE requests

■ doInfo – for SIP INFO requests

■ doPrack – for SIP PRACK requests

For response handling, extend the following:

■ doProvisionalResponse – for SIP 1xx informational responses

■ doSuccessResponse – for SIP 2xx responses

■ doRedirectResponses – for SIP 3xx responses

■ doErrorResponse – for SIP 4xx, 5xx, and 6xx responses

Note: All of these response handling methods, as well as the doAck

and doCancel request handling methods, are empty. The remaining
request handling methods respond to a request with a 500 Response
(Internal Server Error).

Messages

SIP Messages follow the RFC 822 standard. Headers, values and content can be
accessed through the methods in the javax.servlet.sip.SipServletMessage
interface.

Both the SipServletRequest and SipServletResponse classes extend the
SipServletMessage interfaces:

■ public interface SipServletRequest extends

javax.servlet.ServletRequest,SipServletMessage

■ public interface SipServletResponse extends

javax.servlet.ServletResponse, SipServletMessage

Requests

SipServletRequest and SipServletResponse objects in the SIP servlet methods
doRequest and doResponse are implementations of the SipServletRequest
interface and the SipServletResponse interface which both extend the
SipServletMessage interface from the javax.servlet.sip package.

2-8 Oracle Communication and Mobility Server Developer’s Guide

Classes and Methods

A SIP request consists of the following:

■ Request line

■ Headers

■ Empty line

■ Message body

All parts of the SIP request for instance request URI, headers and parameters are
accessible through these interfaces. The SIP container handles many of these system
headers. Applications must not add, delete, or modify the following system headers:

■ From

■ To

■ Call ID

■ CSeq

■ Via

■ Route (except through pushRoute)

■ Record Route

■ Contact (Contact is a system header field in messages other than REGISTER

requests and responses, as well as 3xx and 485 responses)

Responses

Responses to incoming requests are created using the createResponse method on
the request object. It will automatically create a response with all SIP headers set
according to the request. A SIP response has the same structure as a SIP request,
except for a Status line instead of a request line. When receiving responses through, for
instance the doResponse method, methods like getStatus() can be used on the
response object to decide what action to take.

Content

The content in a request or a response can be set with the setContent() method as
illustrated in

Example 2–1 Setting the Content of a Request with the setConent Method

// Copy of the content from request A to request B
requestB.setContent(requestA.getContent(),
requestA.getContentType());
// Create new content
{
try
req.setContent("Hello!", "text/plain");
}
catch (UnsupportedEncodingException e)
{
// Handle the exception
}

Example 2–1.

Manipulating SIP headers

The javax.servlet.sip.SipServletMessage includes methods for
manipulating SIP headers. The getHeaderNames() method is the most general

SIP Servlets 2-9

Classes and Methods

method that returns an iterator of the SIP headers of the message. The setHeader
method sets or adds an address for a header. Specifying the name of the header in
getHeaders(name) method returns another iterator of String objects containing all
of the values for that header.

For those headers that conform to AddressHeader, the getAddressHeader(name)
method will return the header parsed as an Address object.

Addresses can be added or set for a header by using setAddressHeader(name,
address), addAddressHeader(name, address, first), where name is the
name of the header, the address to add, and first is a Boolean. If first is set to true, then
the address will be added first, otherwise it will be added last.

Example 2–2 shows how to manipulate SIP headers:

Example 2–2 Manipulating SIP Headers

javax.servlet.sip.SipServletRequest req;

// Set a header with the given name and value.
// Overwrites any previous header values.
req.setHeader("Accept", "application/sdp");

// Add a header value to the end of a header
req.addHeader("Accept", "text/html");

// Clear all header values
req.removeHeader("Accept");

// Add a Route header value ahead of the existing Route header
// values.
req.pushRoute(sipURI);

// Get the first route as an Address object
Address first route = req.getAddressHeader("Route");

// Get all address header fields for a header
Iterator addrIter = req.getAddressHeaders("Route");
while (addrIter.hasNext())
{
Address addr = (Address) addrIter.next();
// ...
}

SipURI

A base class javax.servlet.sip.URI exists with two sub classes,
javax.servlet.sip.SipURI and javax.servlet.sip.TelURL which

represents SIP URIs and TEL URLs according to RFC 3261, and URLs defined by
RFC 2806. The Address class stores a SipURI or a TelURL as the address of the user.

URIs can be described as user@host, where the user part is either a user name or a
telephone number, and the host is a domain name or an IP address.

Parameters can be accessed with getters and setters. The getParameterNames
method will return an iterator with the names of the parameters. A parameter can be
accessed either with the general getParameter method or with specific parameter
methods like getUser, getHost and getLrParam, which returns the user, the host,
and true if the loose route, lr is set. Parameters can be set with its corresponding
setMethod() as shown in

2-10 Oracle Communication and Mobility Server Developer’s Guide

Example 2–3.

Classes and Methods

Example 2–3 Accessing Parameters in SipURI

// Create a SipURI, set the port, the lr, and the transport
// protocol parameter
SipURI myURI;
myURI = sipFactory.createSipURI("bob", "10.0.0.10");
myURI.setPort(5072);
myURI.setLrParam(true);
myURI.setTransportParam("udp");

Address

SIP addresses found in headers, such as the From, To , and Contact headers, are stored
as javax.servlet.sip Address objects. As shown in
holds, beside the URI, an optional display name and a set of name-value parameters.

Example 2–4 SIP Addresses Stored in java.servlet.sip Address Objects

Address contactAddress;
String displayName;
try
{
// Get the contact address
contactAdress = req.getAddressHeader("Contact");
displayName = contactAdress.getDisplayName();
}
catch (ServletParseException spe)
{
// Handle exception
}
// Create a new address
Address myNewAddress;
myNewAddress = sipFactory.createAddress(URI, "Bob's display name");
myNewAddress.setParameter("myparameter","42");

Example 2–4, the object

The content of myNewAddress in the preceding example is as follows:
DisplayName: "Bob’s display name"
URI: <sip:[e-mail];lr>;
parameter myparameter: 42

The Address class offers the following methods:

■ getDisplayName()

■ setDisplayName()

■ getURI()

■ setURI()

■ clone()

■ toString()

SIP Details

When working with the SIP Servlet API, many SIP details are hidden and performed
automatically by the OCMS SIP Application Server.

■ When the transport protocol is UDP, retransmissions are handled automatically.

SIP Servlets 2-11

Classes and Methods

■ Dialog-related information such as tags, contacts, and CSeq in the SIP messages

are handled automatically.

■ On outgoing requests, OCMS performs DNS lookups and supports NAPTR-,

SRV-, and A-records (according to RFC 3263).

Storing Data as Session Attributes

The SIP Servlet API enables data to be stored as session attributes. Session attributes
can be used to store session specific data to be used in responses and subsequent
requests or from a listener class. The attributes are stored and accessed through setters
and getters directly on the session object. The session can be either a SipSession or a
SipApplicationSession. An attribute can only be retrieved from the same session
it was set. For example:

session.setAttribute("key", "value");
session.getAttribute("key"); // Will return "value"
session.removeAttribute("key");

Although the session attributes can store any object, the attributes and their keys must
be serializable for applications that are distributable (for High Availability). Use the

getAttributeNames method to retrieve all of the set attributes. For example:

Enumeration attributes = session.getAttributeNames();
String attributeName = null;
while (attributes.hasMoreElements())
{
attributeName = (String) attributes.nextElement();
Object attribute = session.getAttribute(attributeName);
log (attribute.toString());
}

Adding Configuration Parameters

A servlet can be configured by adding parameters to the <servlet> section in the SIP
Servlet application descriptor (sip.xml). The servlet can then access these parameters
through the getInitParameter method.
the response code.

Example 2–5 Configuring Servlet Parameters

package com.mydomain.test;
import javax.servlet.sip.SipServlet;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServletResponse;
import java.io.IOException;
public class MySipServlet extends SipServlet
{
protected void doRequest(SipServletRequest req) throws IOException
{
int responseCode = Integer.parseInt(getInitParameter("responseCode"));
SipServletResponse resp = req.createResponse(responseCode);
resp.send();
}
}

Example 2–5 illustrates how to configure

2-12 Oracle Communication and Mobility Server Developer’s Guide

Configuring SIP Applications in sip.xml

SIP servlets must be declared in the application’s deployment descriptor, the sip.xml
file. The sip.xml file enables you to configure the init parameters and the rules that
match initial requests with SIP servlets.

The deployment descriptor is divided into the following sections:

■ Global init parameters (ServletContext init parameters)

<context-param>

■ Session configurations

<session-config>

■ Servlet definitions

<servlet>

■ Servlet mappings, contains the invocation rules

<servlet-mapping>

■ Listeners

<listener>

Configuring SIP Applications in sip.xml

– Application life cycle listener classes
– Error handler

■ Security

Setting and Accessing Global Init Parameters

The <context-param> and the <env-entry> elements provide the means to set
and access the application’s global parameters, such as the database used with an
application or other resources that are common to the entire application. These
elements differ in how the global parameters are accessed.

The <context-param> element declares the servlet’s init parameters that are global to
the entire

Servlet Context. Example 2–6 illustrates setting the database for an

application within the <context-param> element.

Example 2–6 Setting a Database Name within the <context-param>

<context-param>
<param-name>Database</param-name>
<param-value>10.0.0.100</param-value>
<description>The database to be used with this application.</description>
</context-param>

Configuring Application Sessions

SIP Application Sessions are configured within the <session-config> clause. The

session configuration can configure a session timeout value, which is done within the
<session-timeout> clause as shown in the following example. The timeout is set in
minutes; if it set to 0 or below, an application session will never timeout and must be
invalidated explicitly. If no value is set within <session-timeout>, the default
timeout session set for the SIP Servlet Container is used instead (15 minutes).

<session-config>
<session-timeout>10</session-timeout>
</session-config>

SIP Servlets 2-13

Configuring SIP Applications in sip.xml

Defining a Servlet

The <servlet> element defines the SIP container’s servlets. A servlet requires a
servlet name <servlet-name>, and a servlet class, <servlet-class>. The name
must be unique within the application and the class must be the fully qualified name
of the servlet class, as illustrated in

Example 2–7 Servlet Name and Servlet Class

<servlet>
<servlet-name>MyServlet</servlet-name>
<servlet-class>com.company.example.MyServlet</servlet-class>
</servlet>

A servlet can also have its own init parameters, <init-param> and a description
<description>. When the container starts, it only instantiates and calls the init()

method for the servlets which have set the <load-on-startup> element, as shown
in

Example 2–8.

Example 2–8 Defining a Servlet

<servlet>
<servlet-name>MyServlet</servlet-name>
<servlet-class>com.mydomain.test.MySipServlet</servlet-class>
<init-param>
<param-name>logging</param-name>
<param-value>true</param-value>
<description>
Set if logging should be switched on (true) or not (false).
</description>
</init-param>
<init-param>
<param-name>infotainment</param-name>
<param-value>http://www.infotainmentsite.com</param-value>
<description>
The site to use as the infotainment content provider.
</description>
</init-param>
<load-on-startup/>
</servlet>

Example 2–7.

Defining the Servlet Mapping

The <servletmapping> element of the SIP servlet application deployment
descriptor defines the conditions for invoking a servlet.
servlet named MySipServlet can only be invoked for incoming MESSAGE requests. For
more information, see

Example 2–9 Servlet Mapping

<!-- Servlet Mappings for incoming requests-->
<servlet-mapping>
<servlet-name>My Sip Servlet</servlet-name>
<pattern>
<equal>
<var>request.method</var>
<value>MESSAGE</value>
</equal>
</pattern>
</servlet-mapping>

2-14 Oracle Communication and Mobility Server Developer’s Guide

"Servlet Mapping".

Example 2–9 illustrates how a

Configuring SIP Applications in sip.xml

Creating Rules Using the Request Object Structure

The request object model enables you to define rules for processing SIP requests. This
section describes the object model and the predicates for building the rules.

The Request object contains many sub objects, for example SipURI which extends the
URI object.

The request object contains the following elements:

■ method: The method of the request is represented as String.

■ uri: The URI object of the request object, such as SipURI or a TelURI.

■ from: The From header address represented as Address.

■ to: The To header address represented as Address.

The URI object consists of the URI scheme.
The SipURI object consists of the following elements:

■ scheme: The string sip or sips (where sips indicates that TLS should be used).

■ user: The user part of the SIP or SIPS URI. If the SIP address is

sip:[e-mail], then request.uri.user will return alice.

■ host: The host part of the SIP or SIPS URI. If the SIP address is

sip:[e-mail], then request.uri.host will return
example.com.

■ port: The SIP URI port. If it is not present, then the default value for UDP and TCP

is 5060 and TLS is 5061.

■ tel: Returns the user part of the SIP or SIPS URI if the parameter user is set to

phone for the URI. The initial visual separators as + and - are stripped away. For
example, if the SIP URI is sip:[e-mail];user=phone, then the
request.uri.tel would return 12345.

■ param.name: The value of the SipURI parameter with the name name. For example,

given the following request URI: INVITE
sip:[e-mail];user=phone SIP/2.0, the

request.uri.param.user will return phone.

The TelURL consists of the following elements:

■ scheme: The string, tel.

■ tel: The tel URL subscriber name.

■ param.name: the value of the SipURI parameter with the name name.

Address consists of the following elements:

■ uri: The URI object

■ display-name: The To or From display name of the header.

SIP Servlets 2-15

Configuring SIP Applications in sip.xml

Conditions

Tab le 2–1 lists the operators.

Table 2–1 Operators

Condition Name Description

equal Compares the value of a variable with a literal value and

evaluates to true if the variable is defined and its value equals
that of the literal. Otherwise, the result is false.

exists Takes a variable name and evaluates to true if the variable is

contains Returns true if the first argument, a variable, contains the literal

subdomain of If given a variable denoting a domain name (SIP/SIPS URI host)

defined, or to false if the variable has not been defined.

string specified as the second argument.

or telephone subscriber (tel property of SIP or Tel URLs), and a
literal value, this operator returns true if the variable denotes a
sub domain of the domain given by the literal value.

Tab le 2–2 lists the logical connectors.

Table 2–2 Logical Connectors

Logic Description

and Contains a number of conditions and evaluates to true if all of

or Contains a number of conditions and evaluates to true if and

not Negates the value of the contained condition.

the contained conditions evaluate to true.

only if at least one contained condition evaluates to true.

Examples

Example 2–10 describes the parts of a request which are referenced with the different

types of variables.

Example 2–10 Referencing Request Elements

MESSAGE sip:[e-mail] SIP/2.0
Call-ID: a2412d22-161b-4cff-b4a5-a4c6c1f70f18
To: <sip:[e-mail]>
From: "Alice" <sip:[e-mail]>;tag=1234
Max-Forwards: 70
User-Agent: Oracle-CallTron/4.5.7.1445
Accept: text/plain
CSeq: 2 MESSAGE
Content-Type: text/plain; charset=UTF-8
Content-Length: 13
Via: SIP/2.0/TCP 10.0.0.20:3094;branch=z9hG4bK-477709c9-c064-4b95-

90bc-7391d0154368.1;rport

Route: <sip:[e-mail];lr>
Proxy-Authorization: Digest username="alice", realm="example.com",

nonce="MTEzNDQwMzkwMDc3NDJiM2JkY2E1ZmRiY2M4YzBjYzQ2M2VhMTM2NWFlM2Fm",
uri="sip:[e-mail]", qop=auth, nc=00000001, cnonce="443857DE",
response="e5c48d5d2982cf3974260511218a246a",
opaque="4a94690f435b9049b896dce0b6ddb8fe"

The message!

2-16 Oracle Communication and Mobility Server Developer’s Guide