This appendix describes the Service invocation method of the SIP Servlet API (JSR 116).
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.
Oracle Communications Converged Application Server's 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 that of the Record-Route and Via headers used 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 are defined by the service developer and are detailed in the application's deployment descriptor. A deployment descriptor is an XML-based text file whose elements describe how to assemble and deploy the unit into a specific environment. Each element consists of a tag and a value expressed in the following syntax: <tag>value</tag>. Usually deployment descriptors are automatically generated by deployment tools, so you will not have to manage them directly. Deployment descriptor elements contain behavioral information about components not included directly in code. Their purpose is to tell the Deployer how to deploy an application, not tell the server how to manage components at runtime.
In the context of SIP applications, the deployment descriptor is contained within the Servlet archive (SAR) 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.
Example A-1 provides an example of a simple Servlet mapping rule found in a typical deployment descriptor.
Note:
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”))
Note:
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
<servlet-mapping>
<servlet-name>servlet1</servlet-name>
<pattern>
<and>
<or>
<equal>
<var>request.method</var>
<value>INVITE</value>
</equal>
<equal>
<var>request.method</var>
<value>MESSAGE</value>
</equal>
<equal>
<var>request.method</var>
<value>SUBSCRIBE</value>
</equal>
</or>
<or>
<equal>
<var>request.method</var>
<value>INVITE</value>
</equal>
<equal>
<var>request.method</var>
<value>MESSAGE</value>
</equal>
<not>
<equal>
<var>request.from.display-name</var>
<value>Bob</value>
</equal>
</not>
</or>
</and>
</pattern>
</servlet-mapping>
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.
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: 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').
param.name: value of the named parameter within a SIP/SIPS URI; name must be a valid SIP/SIPS URI parameter name.
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 ”example.com” and ”research.example.com”are both subdomains of ”example.com”. 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.