2 Overview of SIP Servlet Application Development

This chapter describes the Session Initiation Protocol (SIP) protocol, and provides a background on SIP application development using the Java programming language.

About the SIP Protocol

SIP is a simple network signalling protocol for creating and terminating sessions with one or more participant. The SIP protocol is designed to be independent of the underlying transport protocol, so SIP applications can run on Transport Control Protocol (TCP), User Datagram Protocol (UDP), or other lower-layer networking protocols.

Typically, the SIP protocol is used for internet telephony and multimedia distribution between two or more endpoints. For example, one person can initiate a telephone call to another person using SIP, or someone may create a conference call with many participants.

The SIP protocol was designed to be very simple, with a limited set of commands. It is also text-based, so humans can read the SIP messages passed between endpoints in a SIP session.

SIP Requests

The SIP protocol defines the following common request types:

Table 2-1 SIP Request Types

SIP Request	Description
INVITE	Initiates a session between two participants.
ACK	The client acknowledges receiving the final message from an INVITE request.
BYE	Terminates a connection.
CANCEL	Cancels any pending actions, but does not terminate any accepted connections.
OPTIONS	Queries the server for a list of capabilities.
REGISTER	Registers the address in the To header with the server.
INFO	Sends a mid-session information that does not modify session state.
UPDATE	Modifies session state without changing the dialog state.
SUBSCRIBE	Subscribes to event notifications from a notifier.
NOTIFY	Notifies a subscriber of a new event.
REFER	As a recipient to issue a SIP call transfer request.
PRACK	A provisional acknowledgement.
PUBLISH	Publishes an event to the server.
MESSAGE	Simple instant message transport.

SIP requests are codes used to indicate the various stages in a connection between SIP-enabled entities.

SIP Responses

The SIP Protocol uses response codes similar to the HTTP protocol. Some of the common response codes are:

100 (Trying)
200 (OK)
404 (Not found)
500 (Server error)
600 (Global failure)

What are SIP Servlets?

A servlet is a Java programming language class used to extend the capabilities of servers that host applications accessed via a request-response programming model. A Servlet is a Java class in Java EE that conforms to the Java Servlet application program interface (API), a protocol by which a Java class may respond to requests. They are not tied to a specific client-server protocol, but are most often used with the HTTP protocol. Therefore, the word ”Servlet” is often used in the meaning of ”HTTP Servlet”.

A SIP servlet is a Java programming language server-side component that performs SIP signalling. SIP servlets are managed by a SIP servlet container, which typically are part of a SIP-enabled application server. SIP servlets interact with clients by responding to incoming SIP requests and returning corresponding SIP responses.

Note:

In this document, the term "SIP Servlet" is used to represent the API, and "SIP servlet" is used to represent an application created with the API.

Figure 2-1 Servlet API and SIP Servlet API

SIP Servlets are similar to HTTP Servlets, and HTTP servlet developers can easily adapt to the programming model. The service level defined by both HTTP and SIP Servlets is very similar, allowing for the design of applications that support both HTTP and SIP.

Developing SIP Servlets

This section describes general techniques for developing SIP servlets using Java Plain Old Java Objects (POJOs) and Java Enterprise Edition (EE) annotations as well as using legacy version 1.x techniques.

Developing SIP Servlets Using POJOs and Annotations

JSR-359 defines a standard method for creating SIP servlets using Java EE annotations in conjunction with POJOs, significantly reducing the amount of code required compared to the earlier 1.x API techniques. In addition, servlet descriptors such as web.xml and sip.xml are optional.

Example 2-1 illustrates a basic annotated SIP servlet POJO that handles a variety of SIP response and request methods.

Example 2-1 SIP Servlet POJO

import javax.inject.Inject;
import javax.servlet.sip.SipFactory;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServletResponse;
import javax.servlet.sip.annotation.Ack;
import javax.servlet.sip.annotation.AnyMethod;
import javax.servlet.sip.annotation.Bye;
import javax.servlet.sip.annotation.ErrorResponse;
import javax.servlet.sip.annotation.Invite;
import javax.servlet.sip.annotation.SipApplication;
import javax.servlet.sip.annotation.SipServlet;
import javax.servlet.sip.annotation.SuccessResponse;
import java.io.IOException;

@SipServlet(loadOnStartup = 1)
public class CallHandler {

  @Inject SipFactory sipFactory;

  @Invite
  public void handleInvite(SipServletRequest request) throws IOException {
    // Handle a SIP invite on an incoming Request...
  }

  @Ack
  public void handleAck(SipServletRequest request) throws IOException {
    // Handle a SIP ACK on an incoming Request...
  }

  @AnyMethod
  public void handleAllRequests(SipServletRequest request) throws IOException {
    // Handle any generic method on an incoming Request...
  }

  @AnyMethod
  public void handleAllResponses(SipServletResponse resp) throws IOException {
    // Handle any other SIP response for any other method...
  }

  @SuccessResponse
  @ErrorResponse
  @Bye
  public void handleByeResponse(SipServletResponse resp) throws IOException {
    // Handle SIP responses in the case of success, error, or BYE...
  }
 
}

In Example 2-1, the class CallHandler imports the necessary SIP annotation libraries, and is itself annotated with @SipServlet indicating that it is a SIP Servlet. CallHandler then exposes the following public methods:

handleInvite(request): Annotated with @Invite, handles any incoming SIP INVITE requests.
handleAck(request): Annotated with @Ack, handles any incoming SIP ACK request.
handleAllRequests(request): Annotated with @AnyMethod, handles any incoming SIP request method that is not an ACK or an INVITE. The methods annotated with @Invite and @Ack are more specific, and thus have higher precedence than @AnyMethod.
handleAllResponses(response): Annotated with @AnyMethod, handles any incoming SIP response. Handles any responses other than success, error, or BYE which are handled by the more specifically annotated handleByeResponse().
handleByeResponse(response): Annotated with @SuccessResponse, @ErrorResponse, and @Bye, and therefore handles any SIP success, error responses, or BYE. Any other SIP responses are handled by general handleAllResponses().

For more information on developing SIP servlet POJOs, see Chapter 3, "SIP Servlet POJOs".

Developing Legacy SIP Servlets

Example 2-2 shows an example of a simple SIP servlet using the legacy 1.x SIP Java API.

Example 2-2 SimpleSIPServlet.java

package oracle.example.simple;
import java.io.IOException;
import javax.servlet.*;
import javax.servlet.sip.*;

public class SimpleSIPServlet extends SipServlet {
    protected void doMessage(SipServletRequest req)
       throws ServletException, IOException
    {
       SipServletResponse res = req.createResponse(200);
       res.send();
    }
}

In Example 2-2 the SIP servlet that sends back a 200 OK response to the SIP MESSAGE request. As you can see from the list, SIP Servlet and HTTP Servlet have many things in common:

Servlets must inherit the base class provided by the API. HTTP servlets must inherit HttpServlet, and SIP servlets must inherit SipServlet.
Methods doXxx must be overridden and implemented. HTTP servlets have doGet/doPost methods corresponding to GET/POST methods. Similarly, SIP servlets have doXxx methods corresponding to the method name (in Example 2-2, the MESSAGE method). Application developers override and implement necessary methods.
The life cycle and management methods (init, destroy) of SIP Servlet are exactly the same as HTTP Servlet. Manipulation of sessions and attributes is also the same.

Overview of the Differences Between HTTP Servlets and SIP Servlets

SIP servlets differ from typical HTTP servlets used in web applications in the following ways:

HTTP servlets have a particular context (called the context-root) in which they run, while SIP servlets have no context.
HTTP servlets typically return HTML pages to the requesting client, while SIP servlets typically connect SIP-enabled clients to enable telecommunications between the client and server.
SIP is a peer-to-peer protocol, unlike HTTP, and SIP servlets can originate SIP requests, unlike HTTP servlets which only send responses to the originating client.
SIP servlets often act as proxies to other SIP endpoints, while HTTP servlets are typically the final endpoint for incoming HTTP requests.
SIP servlets can generate multiple responses for a particular request.
SIP servlets can communicate asynchronously, and are not obligated to respond to incoming requests.
SIP servlets often work in concert with other SIP servlets to respond to particular SIP requests, unlike HTTP servlets which typically are solely responsible for responding to HTTP requests.

Detailed Differences from HTTP Servlets

This section describes detailed differences between SIP Servlets and HTTP Servlets.

Multiple Responses

You might notice in Example 2-2 that the doMessage method has only one argument. In HTTP, a transaction consists of a pair of request and response messages, so arguments of a doXxx method specify a request (HttpServletRequest) and its response (HttpServletResponse). An application takes information such as parameters from the request to execute it, and returns its result in the body of the response.

protected void doGet(HttpServletRequest req, HttpServletResponse res)
   throws ServletException, IOException

For SIP, more than one response may be returned to a single request.

Figure 2-2 Example of Request and Response in SIP

The above figure shows an example of a response to the INVITE request. In this example, the server sends back three responses 100, 180, and 200 to the single INVITE request. To implement such sequence, in SIP Servlet, only a request is specified in a doXxx method, and an application generates and returns necessary responses in an overridden method.

The legacy 1.x SIP Servlet API defines the following doXxx methods:

protected void doInvite(SipServletRequest req);
protected void doAck(SipServletRequest req);
protected void doOptions(SipServletRequest req);
protected void doBye(SipServletRequest req);
protected void doCancel(SipServletRequest req);
protected void doRegister(SipServletRequest req);
protected void doSubscribe(SipServletRequest req);
protected void doNotify(SipServletRequest req);
protected void doMessage(SipServletRequest req);
protected void doInfo(SipServletRequest req);
protected void doPrack(SipServletRequest req);
protected void doUpdate(SipServletRequest req);
protected void doRefer(SipServletRequest req);
protected void doPublish(SipServletRequest req);

Likewise, the 2.0 SIP Servlet API defines the following annotations:

@Invite
@Ack
@Options
@Bye
@Cancel
@Register
@Prack
@Subscribe
@Notify
@Message
@Info
@Update
@Refer
@Publish

Receiving Responses

One of the major features of SIP is that roles of a client and server are not fixed. In HTTP, Web browsers always send HTTP requests and receive HTTP responses: They never receive HTTP requests and send HTTP responses. In SIP, however, each terminal needs to have functions of both a client and server.

For example, both of two SIP phones must call to the other and disconnect the call.

Figure 2-3 Relationship between Client and Server in SIP

Figure 2-3 indicates that a calling or disconnecting terminal acts as a client. In SIP, roles of a client and server can be changed in one dialog. This client function is called UAC (User Agent Client) and server function is called UAS (User Agent Server), and the terminal is called UA (User Agent). The legacy 1.x SIP Servlet defines methods to receive responses as well as requests.

protected void doProvisionalResponse(SipServletResponse res);
protected void doSuccessResponse(SipServletResponse res);
protected void doRedirectResponse(SipServletResponse res);
protected void doErrorResponse(SipServletResponse res);

These doXxx response methods are not the method name of the request. They are named by the type of the response as follows:

doProvisionalResponse: A method invoked on the receipt of a provisional response (or 1xx response).
doSuccessResponse: A method invoked on the receipt of a success response.
doRedirectResponse: A method invoked on the receipt of a redirect response.
doErrorResponse: A method invoked on the receipt of an error response (or 4xx, 5xx, 6xx responses).

Likewise the 2.x SIP Servlet API defines the following annotations which behave identically to their 1.x counterparts:

@ProvisionalResponse
@SuccessResponse
@RedirectResponse
@ErrorResponse

The use of methods to receive responses indicates that the SIP Servlet requests and responses are independently transmitted by the application using different threads. Applications must explicitly manage the association of SIP messages. The use of independent requests and responses makes the process more complicated, but enables you to write more flexible processes.

Also, SIP Servlet allows applications to explicitly create requests. Using these functions, SIP servlets not only wait for requests as a server (UAS), but also send requests as a client (UAC).

Proxy Functions

Another function that is different from the HTTP protocol is forking. Forking is a process of proxying one request to multiple servers simultaneously (or sequentially) and used when multiple terminals (operators) are associated with one telephone number (such as in a call center).

Figure 2-4 Proxy Forking

SIP Servlet provides a utility to proxy SIP requests for applications that have proxy functions.

For more information on forking and SIP servlets, see "Forking SIP Requests".

Message Body

As Figure 2-5 illustrates, the contents of SIP messages is the same as the contents of HTTP messages. Both SIP and HTTP messages include:

Starting line: Identifies the message as a request or a response. The starting line is also referred to as the initial request line or the initial response line.
Header field: Provides information about the request or response.
Separator: A blank line separating the header field from the message body.
Message body: A message may have a body of data sent after the header lines. In a response, this is where the requested resource is returned to the client (the most common use of the message body).

Figure 2-5 SIP Message Example

Description of ''Figure 2-5 SIP Message Example''

HTTP is a protocol that transfers HTML files, images, and multimedia data. Contents to be transferred are stored in the message body. HTTP Servlet defines a stream manipulation-based API that enables the sending and receiving of these large-file content types.

Servlet Request

ServletInputStream getInputStream()
BufferedReader     getReader()

Servlet Response

ServletOutputStream getOutputStream()
PrintWriter         getWriter()
int  getBufferSize()
void setBufferSize(int size)
void resetBuffer()
void flushBuffer()

In SIP, however, only low-volume contents are stored in the message body since SIP is intended for real-time communication. Therefore, above methods are provided only for compatibility, and their functions are disabled.

In SIP, contents stored in the body include:

SDP (Session Description Protocol): A protocol to define multimedia sessions used between terminals. This protocol is defined in RFC2373.
Presence Information: A message that describes presence information defined in CPIM.
IM Messages: IM (instant message) body. User-input messages are stored in the message body.

Since the message body is in a small size, processing it in a streaming way increases overhead. SIP Servlet re-defines API to manipulate the message body on memory as follows:

SipServletMessage

void   setContent(Object content, String contentType)
Object getContent()
byte[] getRawContent()

Role of a Servlet Container

The following sections describe major functions provided by Converged Application Server as a SIP servlet container:

Application Management: Describes functions such as application management by servlet context, life cycle management of servlets, application initialization by deployment descriptors.
SIP Messaging: Describes functions of parsing incoming SIP messages and delivering to appropriate SIP servlets, sending messages created by SIP servlets to appropriate UAS, and automatically setting SIP header fields.
Utility Functions: Describes functions such as sessions, factories, and proxying that are available in SIP servlets.

Application Management

Like HTTP servlet containers, SIP servlet containers manage applications by servlet context (see Figure 2-6). Servlet contexts (applications) are normally archived in a WAR format and deployed in each application server.

Note:

The method of deploying in application servers varies depending on your product. Refer to the documentation of your application server.

Figure 2-6 Servlet Container and Servlet Context

A servlet context for a converged SIP and Web application can include multiple SIP servlets, HTTP servlets, and JSPs.

Converged application Server can deploy applications using the same method as the application server you use as the platform. However, if you deploy applications including SIP servlets, you need a SIP specific deployment descriptor (sip.xml) defined by SIP servlets. The table below shows the file structure of a general converged SIP and Web application.

Table 2-2 File Structure Example of Application

File	Description
WEB-INF/	Place your configuration and executable files of your converged SIP and Web application in the directory. You cannot directly refer to files in this directory on Web (servlets can do this).
WEB-INF/web.xml	The Java EE standard configuration file for the Web application. Optional when using SIP servlet POJOs.
WEB-INF/sip.xml	The SIP Servlet-defined configuration files for the SIP application. Optional if a SIP servlet POJO is using the programmatic deployment methods of the SipServletContext interface, addServletPojo(). See the Converged Application Server Java API Reference for more information.
WEB-INF/classes/	Store compiled class files in the directory. You can store both HTTP and SIP servlets in this directory.
WEB-INF/lib/	Store class files archived as Jar files in the directory. You can store both HTTP and SIP servlets in this directory.
.jsp, .jpg	Files comprising the Web application (for example JSP) can be deployed in the same way as Java EE.

Information specified in the sip.xml file is similar to that in the web.xml except servlet-mapping setting that is different from HTTP servlets. In HTTP you specify a servlet associated with the file name portion of URL. But SIP has no concept of the file name. You set filter conditions using URI or the header field of a SIP request. The following example shows that a SIP servlet called registrar is assigned all REGISTER methods.

Example 2-3 Filter Condition Example of sip.xml

 <servlet-mapping>
   <servlet-name>registrar</servlet-name>
   <pattern>
     <equal>
       <var>request.method</var>
       <value>REGISTER</value>
     </equal>
   </pattern>
 </servlet-mapping>

Once deployed, life cycle of the servlet context is maintained by the servlet container. Although the servlet context is normally started and shutdown when the server is started and shutdown, the system administrator can explicitly start, stop, and reload the servlet context.

Note:

The web.xml file is optional for servlets developed as annotated POJOs.

SIP Messaging

SIP messaging functions provided by a SIP servlet container are classified under the following types:

Parsing received SIP messages.
Delivering parsed messages to the appropriate SIP servlet.
Sending SIP servlet-generated messages to the appropriate UA
Automatically generating a response (such as ”100 Trying”).
Automatically managing the SIP header field.

All SIP messages that a SIP servlet handles are represented as a SipServletRequest or SipServletResponse object. A received message is first parsed by the parser and then translated to one of these objects and sent to the SIP servlet container.

A SIP servlet container receives the following three types of SIP messages, for each of which you determine a target servlet.

First SIP Request: When the SIP servlet container received a request that does not belong to any SIP session, it uses filter conditions in the sip.xml file (described in the previous section) to determine the target SIP servlet. Since the container creates a new SIP session when the initial request is delivered, any SIP requests within that SIP session received after that point are considered as subsequent requests.

Note:
Filtering should be done carefully. In Converged Application Server, when the received SIP message matches multiple SIP servlets, it is delivered only to any one SIP servlet.
The use of additional criteria such as request parameters can be used to direct a request to a servlet.
Subsequent SIP Request: When the SIP Servlet container receives a request that belongs to any SIP session, it delivers the request to a SIP Servlet associated with that session. Whether the request belongs to a session or not is determined using the SIP dialog ID.

Each time a SIP Servlet processes messages, a lock is established by the container on the call ID. If a SIP Servlet is currently processing earlier requests for the same call ID when subsequent requests are received, the SIP Servlet container queues the subsequent requests. The queued messages are processed only after the Servlet has finished processing the initial message and has returned control to the SIP Servlet container.

This concurrency control is guaranteed both in a single containers and in clustered environments. Application developers can code applications with the understanding that only one message for any particular call ID gets processed at a given time.
SIP Response: When the received response is to a request that a SIP servlet proxied, the response is automatically delivered to the same servlet since its SIP session had been determined. When a SIP servlet sends its own request, you must first specify a servlet that receives a response in the SIP session. For example, if the SIP servlet sending a request also receives the response, the following handler setting must be specified in the SIP session.
```
SipServletRequest req = getSipFactory().createRequest(appSession, ...);
req.getSession().setHandler(getServletName());
```
Normally, in SIP a session means a real-time session by RTP/RTSP. On the other hand, in HTTP Servlet a session refers to a way of relating multiple HTTP transactions. In this document, session-related terms are defined as follows:

Table 2-3 Session-Related Terminology

Session Name	Description
Realtime Session	A realtime session established by RTP/RTSP.
HTTP Session	A session defined by HTTP Servlet. A means of relating multiple HTTP transactions.
SIP Session	A means of implementing the same concept as in HTTP session in SIP. SIP (RFC3261) has a similar concept of "dialog," but in this document this is treated as a different term because while dialogs and SIP sessions are similar in scope, their exact lifecycles are different.
Application Session	A means for applications using multiple protocols and dialogs to associate multiple HTTP sessions and SIP sessions. Also called "APP session."

Converged Application Server automatically execute the following response and retransmission processes:

Sending ”100 Trying”: When Converged Application Server receives an INVITE request, it automatically creates and sends ”100 Trying.”
Response to CANCEL: When WebLogic Communications Server receives a CANCEL request, it executes the following processes if the request is valid.
1. Sends a 200 response to the CANCEL request.
2. Sends a 487 response to the INVITE request to be cancelled.
3. Invokes a doCancel method on the SIP servlet. This allows the application to abort the process within the doCancel method, eliminating the need for explicitly sending back a response.
Sends ACK to an error response to INVITE: When a 4xx, 5xx, or 6xx response is returned for INVITE that were sent by a SIP servlet, WebLogic Communications Server automatically creates and sends ACK. This is because ACK is required only for a SIP sequence, and the SIP servlet does not require it.

When the SIP servlet sends a 4xx, 5xx, or 6xx response to INVITE, it never receives ACK for the response.
Retransmission process when using UDP: SIP defines that sent messages are retransmitted when low-trust transport including UDP is used. WebLogic Communications Server automatically do the retransmission process according to the specification.

Applications typically do not need to explicitly set and see header fields in HTTP Servlet, as HTTP Servlet containers automatically manage fields such as Content-Length and Content-Type. SIP Servlet provides the same header management functions.

In SIP, however, since important information about message delivery exists in some fields, these headers are not allowed to change by applications. Headers that can not be changed by SIP Servlets are called system headers. Table 2-4 below lists system headers:

Table 2-4 System Headers

Header Name	Description
Call-ID	Contains ID information to associate multiple SIP messages as Call.
Address	Can be modified except for the host/port and scheme part in the Address URI. This restriction does not apply to the To/From headers. Protected parameters and their values cannot be modified.
From, To	Contains Information on the sender and receiver of the SIP request (SIP, URI, etc.). Modifiable except for the tag parameters.
CSeq	Contains sequence numbers and method names.
Via	Contains a list of servers the SIP message passed through. This is used when you want to keep track of the path to send a response to the request. Can only be modified by adding or removing non-protected parameters.
Record-Route, Route	Used when the proxy server mediates subsequent requests.
Contact	Contains network information (such as IP address and port number) that is used for direct communication between terminals. Only the following messages can be modified or set by an application: REGISTER requests and responses 3xx responses 485 responses 200/OPTIONS responses

Utility Functions

JSR-359 defines the following utilities, which are available to SIP servlets:

SIP Session, Application Session
SIP Factory
Proxy
SipSessionsUtil
DnsResolver
TimerService
SipSecurity

SIP Session, Application Session

As stated before, SIP Servlet provides a ”SIP session” whose concept is the same as a HTTP session. In HTTP, multiple transactions are associated using information like Cookie. In SIP, this association is done with header information (Call-ID and tag parameters in From and To). Servlet containers maintain and manage SIP sessions. Messages within the same dialog can refer to the same SIP session. Also, For a method that does not create a dialog (such as MESSAGE), messages can be managed as a session if they have the same header information.

SIP Servlet has a concept of an ”application session,” which does not exist in HTTP Servlet. An application session is an object to associate and manage multiple SIP sessions and HTTP sessions. It is suitable for applications such as B2BUA.

For SIP servlet POJOs, this is handled by the @SipServlet and @SipApplication annotations.

SIP Factory

A SIP factory (SipFactory) is a factory class to create SIP Servlet-specific objects necessary for application execution. You can generate the following objects:

Table 2-5 Objects Generated with SipFactory

Class Name	Description
URI, SipURI, Address	Can generate address information including SIP URI from String.
SipApplicationSession	Creates a new application session. It is invoked when a SIP servlet starts a new SIP signal process.
SipServletRequest	Used when a SIP servlet acts as UAC to create a request. Such requests can not be sent with Proxy.proxyTo. They must be sent with SipServletRequest.send.

SipFactory is located in the servlet context attribute under the default name. You can retrieve it with the following code:

ServletContext context = getServletContext();
SipFactory factory =
    (SipFactory) context.getAttribute("javax.servlet.sip.SipFactory");

For SIP servlet POJOs, this functionality is handled by the @SipFactory annotation. The @SipFactory annotation can be used in place of a ServletContext lookup for the SipFactory from within a Servlet above. The injected SipFactory appears as sip/appname/SipFactory in the application-scoped JNDI tree, where the appname is the name of the application.

Proxy

Proxy is a utility used by a SIP servlet to proxy a request. In SIP, proxying has its own sequences including forking. You can specify the following settings in proxying with Proxy:

Recursive routing (recursive): When the destination of proxying returns a 3xx response, the request is proxied to the specified target.
Record-Route setting: Sets a Record-Route header in the specified request.
Parallel/Sequential (parallel): Determines whether forking is executed in parallel or sequentially.
stateful: Determines whether proxying is transaction stateful. This parameter is not relevant because stateless proxy mode is deprecated in JSR-359.
Supervising mode: In the event of the state change of proxying (response receipts), an application reports this.

For more information, see "Forking SIP Requests".

SipSessionsUtil

A utility class providing additional support for converged HTTP/SIP applications and converged Java EE/SIP applications. This class can be accessed through the ServletContext parameter named javax.servlet.sip.SipSessionsUtil or it can be injected using the @Resource annotation. The injected SipSessionsUtil appears as sip/appname/SipSessionsUtil in the application-scoped JNDI tree, where the appname is the name of the application.

For more information, see the Java SIP Servlet API 2.0.

DnsResolver

For information on the DnsResolver utility, see "Annotation for DnsResolver Injection".

TimerService

The @Resource annotation also can be used to inject an instance of the TimerService for scheduling timers. This annotation can replace the following ServletContext based lookup of the TimerService:

TimerService t = (TimerService) getServletContext().getAttribute(TIMER_SERVICE);

The injected TimerService appears as sip/appname/TimerService in the application-scoped JNDI tree, where the appname is the name of the application.

SipSecurity

This annotation is used on a Servlet implementation class to specify security constraints to be enforced by the container on SIP protocol messages. The SIP servlet container will enforce these constraints on the annotated SIP servlet. The @SipSecurity annotation provides an alternative mechanism for defining access control constraints equivalent to those that could otherwise have been expressed declaratively via security-constraint elements in the portable deployment descriptor.

Note:

If both security-constraint of the deployment descriptor and the @SipSecurity annotation is present for the same servlet, then the configuration in the deployment descriptor will take precedence.

For information on using the @SipSecurity annotation see section 22.3.10.1 in JSR-359, https://jcp.org/en/jsr/detail?id=359.

Internetworking with Third Party Protocols

A Session Initiation Protocol (SIP) application instance may consist of multiple protocol interactions. Each of these protocol interactions may be satisfied by a protocol library, that exposes its own Java API. As with SIP servlets or SIP Plain Old Java Objects (POJOs) acting as protocol listeners for SIP, these other protocol libraries can expose their own protocol listeners. For example, a Diameter library may expose a POJO that listens in on Diameter messages. Those messages may belong to a protocol session maintained by the Diameter protocol library. A SIP application archive, thus, may contain these protocol listeners as well. Furthermore, those protocol listeners can send SIP messages, while SIP POJOs might send other protocol messages as well.

For a detailed example of integrating with the Diameter protocol, see "Working with Diameter Applications Using CDI and POJOs" in Converged Application Server Diameter Application Development Guide.

SIP Servlet Concurrency

Converged Application Server includes concurrency utilities to help you create portable, reliable, thread safe applications. For information on handling SIP servlet concurrency, see Chapter 7, "SIP Servlet Concurrency".

Resolving Telephone Numbers to SipURI

ENUM (E.164 Number Mapping as specified RFC 6116, https://tools.ietf.org/rfc/rfc6116.txt) is a system that uses the Domain Name Service (DNS) to translate telephone numbers, like '+12025552600', into URIs. A TelURL or SipURI with a user=phone parameter constitutes a telephone number. Often, SIP servlet applications need to resolve such telephone numbers using ENUM as specified in RFC 3824, https://tools.ietf.org/html/rfc3284. The SIP servlet API provides a DnsResolver interface to resolve telephone numbers in a TelURL or SipURI that has a user=phone parameter. DnsResolver is implemented by Converged Application Server, and is made available to applications as a ServletContext parameter with the name javax.servlet.sip.DnsResolver. It can also be accessed using resource injection as described in "Annotation for DnsResolver Injection". After a SIP servlet obtains a DnsResolver, it can use the following methods to resolve the telephone numbers to a SipURI:

SipURI resolveToSipURI(URI uri)
List<SipURI> resolveToSipURIs(URI uri)
List<String> resolveToStrings(URI uri, String enumService)

DnsResolver also contains utility methods that help applications while resolving the URIs. The toEnum(URI uri) method helps applications to get the representation of a URI in ENUM format. The resolvesInternally(SipURI uri) method helps applications decide whether the SipURI resolves to the internal container.

Note:

For details on the API described in this section, see the Java SIP Servlet API 2.0 JavaDocs.

Annotation for DnsResolver Injection

The @Resource annotation defined in Common Annotations for the Java Platform (JSR 250, https://jcp.org/en/jsr/detail?id=250) is used to inject an instance of the DnsResolver utility class for DNS Enum lookup of telephone numbers.

This annotation can be used in place of the ServletContext based lookup for the DnsResolver.

The ServletContext lookup in Example 2-4,

Example 2-4 ServletContext Based DnsResolver Lookup

DnsResolver s = (DnsResolver)
  getServletContext().getAttribute("javax.servlet.sip.DnsResolver");

is equivalent to the annotation based implementation in Example 2-5.

Example 2-5 Annotation Based DnsResolver Lookup

@Resource
DnsResolver resolver;