Skip Headers
Oracle® Communications Converged Application Server Technical Product Description
Release 5.0

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

Go to previous page
Go to next page
View PDF

A SIP Servlet API Service Invocation

This appendix describes the Service invocation method of the SIP Servlet API (JSR 116).

SIP Servlet API Overview

The SIP Servlet API provides a model for application composition and interaction Service Interaction which is analogous with a simplistic implementation of the Service Capability Interaction Manager (SCIM) alluded to by the 3GPP. Handling of all incoming requests is governed by the Converged Application Server SIP Servlet Container in accordance with the SIP Servlet API specification.

The Oracle communications Converged Application Server SIP Servlet Container filters received Initial SIP requests and applies a set of defined rules (Servlet Mapping Rules) to determine which SIP Servlets within the deployed applications shall be invoked to service that particular request. This order is always sequential and is defined in a configuration file built up through successive deployments of SIP applications.

Within the deployment descriptor for each SIP Application that is deployed, a sequence of conditions, called Servlet Mapping Rules, is defined. These rules determine which Servlets will handle any initial request. As the request object is “routed” between Servlets, the path from Servlet to Servlet is recorded in a fashion equivalent to the “record-route” and “via” headers in SIP requests. This route is stored as part of the SIP application session and is appended to subsequent requests within the same dialogue in either “forward” or “reverse” order depending on the orientation of the “From” and “To” tags for the request. This internal “route” is stripped from the request object before a SIP request leaves Converged Application Server and is not visible to external SIP servers. It is again added whenever a new request within an existing dialog is received.

The SIP Servlets (SIP/HTTP application) that are invoked in this manner are unaware that any other SIP/HTTP application exists. This is one of the fundamental characteristics of the SIP Servlet programming model. Making maximal use of this model requires that the Servlet container be treated by the developer as if it is a logical sub-network, with the container effectively acting as an intermediary proxy. In many ways, the SIP Servlet Container may be compared with the Serving CSCF function in an IMS architecture.

Servlet Mapping Rules: Objects, Properties and Conditions

Servlet mapping rules are defined by the service developer and are detailed in the Deployment Descriptor for the application. The deployment descriptor is a document that is contained within the SAR archive file that is deployed on Converged Application Server. There may be more than one Servlet mapping rule defined within the Deployment Descriptor for the application (SIP/HTTP application). In this case, these rules must be applied in the order in which they are defined in the Deployment Descriptor.

The following figure provides an example of a simple Servlet mapping rule found in a typical Deployment Descriptor.


Servlet mapping rules are entirely concerned with the content of the SIP message being processed. It is not possible to use information regarding the actual IP address and port number on which the request was received as service trigger points unless this information matches the request URI of the Sip message.

The Servlet mapping rule shown in Example A-1 illustrates the following Boolean expression:

(Method=”INVITE” OR Method = “MESSAGE” OR Method=”SUBSCRIBE”) AND

(Method=”INVITE” OR Method = “MESSAGE” OR (NOT Header = “from” Match = “Bob”))


This is the same logical condition used in the Initial filter Criteria example provided in 3GPP TS 29.228 Annex C expressed as a Servlet Mapping Rule.

Example A-1 Example Servlet Mapping Rule


Supported Service Trigger Points

Service Point Triggers are the attributes of a SIP request that may be evaluated by Servlet Mapping Rules. See "Section 11.1: Triggering Rules" in the JSR 116 specification for more information.

Request Object

The Request Object is a Java representation of a SIP request.

  • method: the request method, a string

  • uri: the request URI; for example a SipURI or a TelURL

  • from: an Address representing the value of the From header

  • to: an Address representing the value of the To header


  • scheme: the URI scheme

SipURI (extends URI)

  • scheme: a literal string – either “sip” or “sips”

  • user: the “user” part of the SIP/SIPS URI

  • host: the “host” part of the SIP/SIPS URI. This may be a domain name or a dotted decimal IP address.

  • port: the URI port number in decimal format; if absent the default value is used (5060 for UDP and TCP, 5061 for TLS).

  • tel: if the “user” parameter is not “phone”, this variable is undefined. Otherwise, its value is the telephone number contained in the “user” part of the SIP/SIPS URI with visual separators stripped. This variable is always matched case insensitively (the telephone numbers may contain the symbols 'A', 'B', 'C' and 'D').

  • value of the named parameter within a SIP/SIPS URI; name must be a valid SIP/SIPS URI parameter name.

TelURL (extends URI)

  • scheme: always the literal string “tel”

  • tel: the tel URL subscriber name with visual separators stripped off

  • value of the named parameter within a tel URL; name must be a valid tel URL parameter name


  • uri: the URI object; see URI, SipURI, TelURL types above

  • display-name: the display-name portion of the From or To header

Conditions and Logical Connectors

  • 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 defined, and false otherwise.

  • contains: evaluates to true if the value of the variable specified as the first argument contains the literal string specified as the second argument.

  • subdomain-of: given a variable denoting a domain name (SIP/SIPS URI host) or telephone subscriber (tel property of SIP or Tel URLs), and a literal value, this operator returns true if the variable denotes a subdomain of the domain given by the literal value. Domain names are matched according to the DNS definition of what constitutes a subdomain; for example, the domain names “” and ““are both subdomains of “”. IP addresses may be given as arguments to this operator; however, they only match exactly. In the case of the tel variables, the subdomain-of operator evaluates to true if the telephone number denoted by the first argument has a prefix that matches the literal value given in the second argument; for example, the telephone number “1 212 555 1212" would be considered a subdomain of “1212555”.

  • and: contains a number of conditions and evaluates to true if and only if all contained conditions evaluate to true

  • or: contains a number of conditions and evaluates to true if and only if at least one contained condition evaluates to true

  • not: negates the value of the contained condition.

The equal and contains operators optionally ignore character case when making comparisons. The default is case-sensitive matching.