The SipServlet class extends the GenericServlet class in the servlet base package. The service method dispatches the SIP message to either doRequest() or doResponse(), and in turn the requests are directed to the doXXX methods for Requests such as doInvite, doSubscribe, and so forth, or to doXXX methods for Responses such as doSuccessResponse and doErrorResponse.

If you are creating a SIP Servlet using POJOs and annotations, you can use the @SipServlet annotation in conjunction with the following method specific annotations:

• @Invite

• @Ack

• @Options

• @Bye

• @Cancel

• @Register

• @Prack

• @Subscribe

• @Notify

• @Message

• @Info

• @Update

• @Refer

• @Publish

The servlet-mapping element defined in the deployment descriptor can define the rule that MUST be satisfied before invoking a particular Servlet. The mapping rules have a well-defined grammar in JSR 116. Example 2-1 shows a mapping that invokes a Servlet only if the Request is an INVITE and the host part of the Request-URI contains the string “example.com". See "SIP Servlet API Service Invocation" for more information on servlet mapping rules.

pattern
  <and>
    <equal>
      <var>request.method</var>
      <value>INVITE</value>
    </equal>
    <contains ignore-case="true">
      <var>request.from.uri.host</var>
      <value>example.com</value>
    </contains>
  </and>
</pattern>

There is normally only one SipServlet object accessed by concurrent Requests, so it is not a place to define any call- or session- specific data structure. The doXXX methods in the application generally implement the business logic for a given request. Consider Example 2-2.

1: package test;
2: import javax.servlet.sip.SipServlet;
3: import javax.servlet.sip.SipServletRequest;
4: import java.io.IOException;
5: public class SimpleUasServlet extends SipServlet {
6:   protected void doInvite(SipServletRequest req) 
7:      throws IOException {
8:     req.createResponse(180).send();
9:     req.createResponse(200).send();
10:  }
11:  protected void doBye(SipServletRequest req) throws IOException {
12:    req.createResponse(200).send();
13:    req.getApplicationSession().invalidate();
14:  }
15: }

Example 2-2 shows a simple UAS Servlet that is invoked on an incoming INVITE Request (triggered by a rule similar to the one defined in Example 2-1). The container invokes the application by invoking the doInvite method. The application chooses to send a 180 Response (line 8) followed by a 200 Response (line 9). The application does nothing with the ACK, which would be sent by the UAC. In this case the container receives the ACK and silently ignores it. If it were a stateful proxy it would have proxied it.

Example 2-3 shows how the same class could be written using an annotated POJO.

package test;
import javax.inject.Inject;
import javax.servlet.sip.SipFactory;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.annotation.Bye;
import javax.servlet.sip.annotation.Invite;
import javax.servlet.sip.annotation.SipServlet;
 
@SipServlet(loadOnStartup = 1)
public class SimpleUasServlet {
  @Inject SipFactory sipFactory;
  @Invite
  public void handleInviteRequest(SipServletRequest req) throws IOException {
    req.createResponse(180).send();
    req.createResponse(200).send();
  }
  @Bye
  public void handleByeRequest(SipServletRequest req) throws IOException {
    req.createResponse(200).send();
    req.getApplicationSession().invalidate();
  }
}

As its name suggests, this class is used to create various SIP Servlet API objects such as Request, SipApplicationSession, Addresses, and so forth. An application acting as a UA can use it to create a new Request. Requests created through the factory have a new Call-ID (with the exception of a particular method for B2BUAs in which the application can chose to re-use the existing Call-ID on the upstream leg) and do not have a tag in the To header. The Factory object can be retrieved using the javax.servlet.sip.SipFactory attribute on the ServletContext.

See the "findme" example installed with Converged Application Server for an example of obtaining a factory object using SipFactory.

If you are using annotated POJOs, you can use the CDI @Inject annotation to inject the SipFactory into your servlet class:

@Inject SipFactory sipFactory;

There are two classes of SIP messages: SipServletRequest and SipServletResponse. These classes respectively represent SIP Requests (INVITE, ACK, INFO, and so forth) and Responses (1xx, 2xx, and so forth). Messages are delivered to the application through various doXXX methods defined in the SipServlet class.

SIP is an asynchronous protocol and therefore it is not obligatory for an application to respond to a Request when the doRequest(doXXX) method is invoked. The application may respond to the Request at a later stage, because they have access to the original Request object.

Both the SipServletRequest and SipServletResponse objects are derived from the base SipServletMessage object, which provides some common accessor/mutator methods such as getHeader(), getContent(), and setContent(). The SipServletRequest defines many useful methods for Request processing:

• SipServletRequest.createResponse() creates an instance of the SipServletResponse object. This represents the Response to the Request that created it. Similarly, SipServletRequest.createCancel() creates a CANCEL Request to a previously sent Request.

  Note:

  The CANCEL is sent if the UAC decides to not proceed with the call if it has not received a response to the original request. Sending a CANCEL if you have received a 200 response or not received a 100 response would be wrong protocol behavior, luckily the SIP Servlet API steps up to rescue here too. The UAC application can create and send a CANCEL oblivious to these details. The container ensures that a CANCEL is sent out only if a 1xx response code is received, and any response >200 is not received.

• SipServletRequest.getProxy() returns the associated Proxy object to enable an application to perform proxy operations.

• SipServletRequest.pushRoute(SipURI) enables a UAC or a proxy to route the request through a server identified by the SipURI. The effect of this method is to add a Route header to the request at the top of the Route header list.

Another method of interest is SipServletRequest.isInitial(). It is important to understand the concept of initial and subsequent requests, because an application may treat each one differently. For example, if an application receives a Re-INVITE request, it is delivered to the Servlet's doInvite() method, but the isInitial() method returns false.

Initial requests are usually requests outside of an established dialog, of which the container has no information. Upon receiving an initial Request, the container determines which application should be invoked; this may involve looking up the Servlet-mapping rules. Some Requests create dialogs, so any Request received after a dialog is established falls into the category of a "subsequent" Request. Closely-linked with the dialog construct in SIP is the SipSession object (see "SipSession").

In the SipServletResponse object, one particular method of interest is createAck(). createAck() creates an ACK Request on a 2xx Response received for the INVITE transaction. ACKs for non-2xx responses of the INVITE transaction are created by the container itself.

The SipSession roughly corresponds to a SIP dialog. For UAs the session maintains the dialog state as specified by the RFC, in order to correctly create a subsequent request in a dialog. If an application is acting as a UA (a UAC or a B2BUA), and after having processed an initial request wants to send out a subsequent request in a dialog (such as a Re-INVITE or BYE), it must use SipSession.createRequest() rather than one of SipFactory methods. Using a factory method would result in requests being created “out of dialog".

The SipSession is also a place for an application to store any session-specific state that it requires. An application can set or unset attributes on the SipSession object, and these attributes are made available to the application over multiple invocations.

SipSession also provides the SipSession.setHandler(String nameOfAServlet) method, which assigns a particular Servlet in the application to receive subsequent Requests for that SipSession.

The SipApplicationSession logically represents an instance of the application itself. An application may have one or more protocol sessions associated with it, and these protocol sessions may be of type SipSession or HttpSession as of JSR 116. Applications can also store application-wide data as an attribute of the SipApplicationSession.

Any attribute set on a SipApplicationSession object or its associated SipSession is visible only to that particular application. The SIP Servlet API defines a mechanism by which more than one application can be invoked on the same call. This feature is known as application composition. SipApplicationSession provides a getSessions() method that returns the protocol sessions associated with the application session. The image below shows the containment hierarchy of the different sessions in the SIP Servlet API.

Figure 2-3 Relationship Between Session Object Types

The encodeUri(URI) method in the SipApplicationSession interface is of particular interest. This method encodes the SipApplication identifier with the URI specified in the argument. If the container receives a new request with this encoded URI, even if on a different call, it associates the encoded SipApplicationSession with this Request. This method can link two disparate calls, and it can be used in a variety of other ways. SipApplicationSession is also associated with application session timers (see Application Timers).

The SIP Servlet API provides a timer service that applications can use. The TimerService interface can be retrieved using a ServletContext attribute, and it defines a createTimer(SipApplicationSession appSession, long delay, boolean isPersistent, java.io.Serializable info) method to start an application-level timer.

The SipApplicationSession is implicitly associated with application-level timers. When a timer fires, the container invokes an application-defined TimerListener and passes it the ServletTimer object. The listener can use the ServletTimer object to retrieve the SipApplicationSession, which provides the correct context for the timer's expiry.

In terms of the SIP Servlet API, a converged application is one that involves more than one protocol, in this case SIP and HTTP. The example below presents an example of a simple JSP page which can be accessed through an HTTP URL.

Example JSP Showing HTTP and SIP Servlet Interaction

1:<html>
2:<body>
3: <%
4:  if (request.getMethod().equals("POST")) {
5:   javax.servlet.sip.SipFactory factory = 
6:     (javax.servlet.sip.SipFactory) application.getAttribute(javax.servlet.sip.SipServlet.SIP_FACTORY); 
7:   javax.servlet.sip.SipApplicationSession appSession =
8:      factory.createApplicationSession();
9:   javax.servlet.sip.Address to = 
10:     factory.createAddress("sip:localhost:5080");
11:   javax.servlet.sip.Address from = 
12:     factory.createAddress("sip:localhost:5060");
13:   javax.servlet.sip.SipServletRequest invite =
14:      factory.createRequest(appSession, "INVITE", from, to);
15:   javax.servlet.sip.SipSession sess = invite.getSession(true);
16:     sess.setHandler(“sipClickToDial");
17:   //invite.setContent(content, contentType);
18:   invite.send();
19:  }
20:%>
21:<p>
22:Message sent ...
23:</p>
24:</body>
25:</html>

The JSP example would need to be packaged in the same application as a SIP Servlet. The entire application is a skeleton of a click-to-dial application (called sipClickToDial), where by clicking on a Web page you initiate a SIP call.

The HTTP Servlet creates a SIP Request from a factory and sends it to a SIP URI. When an HTTP POST Request is sent to the HTTP Servlet it obtains the SipFactory on line 5-6. Next, it creates an application session (line 7-8). The application session is the center piece for all of the application's SIP and HTTP interactions. The overall purpose is to send out a SIP Request, which is done in lines 13-14, but first the application creates the From and To headers to be used when forming the INVITE request.

On line 16 the application assigns a handler to the SipSession that is associated with the INVITE Request that was created, and this ensures that the Response sent by a UAS that receives the request is dispatched to a SIP Servlet for processing.

In the example shown below, the application receives a SUBSCRIBE Request and sends out a NOTIFY Request. The application then waits for the notification recipient for three seconds, and if does not receive a success response (a 2xx class response), then it may take some other action (for example, log a message).

1:public class Sample_TimerServlet extends SipServlet
2:  implements TimerListener {
3:  private TimerService timerService;
4:  private static String TIMER_ID = "NOTIFY_TIMEOUT_TIMER";
5:  public void init() throws ServletException {
6:    try {
7:      timerService = 
8:(TimerService)getServletContext().getAttribute
9:      ("javax.servlet.sip.TimerService");
10:    } 
11:    catch(Exception e) {
12:      log ("Exception initializing the servlet "+ e);
13:    }
14:  }
15:  protected void doSubscribe(SipServletRequest req)
16:  throws ServletException, IOException {
17:    req.createResponse(200).send();
18:    req.getSession().createRequest("NOTIFY").send();
19:    ServletTimer notifyTimeoutTimer = 
20:      timerService.createTimer(req.getApplicationSession(), 3000, 
21:  false, null);
22:    req.getApplicationSession().setAttribute(TIMER_ID, 
23:notifyTimeoutTimer);
24:  }
25:  protected void doSuccessResponse(SipServletResponse res) 
26:  throws javax.servlet.ServletException, java.io.IOException {
27:    if (res.getMethod().equals("NOTIFY")) {
28:      ServletTimer notifyTimeoutTimer =      
29:  (ServletTimer)(res.getApplicationSession().getAttribute(TIMER_ID));
30:      if (notifyTimeoutTimer != null) {
31:        notifyTimeoutTimer.cancel();
32:        res.getApplicationSession().removeAttribute(TIMER_ID);
33:      }
34:    }
35:  }
36:  public void timeout(ServletTimer timer) {
37:    // This indicates that the timer has fired because a 200 to
38:    // NOTIFY was not received. Here you can take any timeout 
39:    // action. 
40:    // .........
41:    timer.getApplicationSession().removeAttribute
("NOTIFY_TIMEOUT_TIMER");
42:  }   
43:}

The Servlet itself implements TimerListener so that it will be notified of the timeout. The example starts by obtaining the TimerService from the ServletContext in lines 7-9. The timer is then set for 3000 ms (3 seconds) upon receiving the SUBSCRIBE request on line 20. Note that the timer could be set at any stage. There is also an option to attach an object to the timer. The object could be used as an identifier or an invocable message at a later stage. This sample simply associates the timer with a literal.

After sending the NOTIFY the application creates the timer and saves its reference in the SipApplicationSession for later use on line 22.

If the application receives a 200 response to the NOTIFY, it can then extract the timer reference and cancel the timer (line 25). However, if no response is received in 3 seconds, then the timer fires and the container calls the timeout() callback method (line 36).

The example above can be rewritten using an annotated POJO as shown in the example below.

@SipServlet(loadOnStartup = 1);
public class Sample_TimerServlet {
 
  // Inject the TimerService using the @Resource annotation...
  @Resource TimerService timerService;
  private static String TIMER_ID = "NOTIFY_TIMEOUT_TIMER";
 
  @Subscribe
  protected void handleSubscribeRequest(SipServletRequest req) throws IOException {
    req.createResponse(200).send();
    req.getSession().createRequest("NOTIFY").send();
    ServletTimer notifyTimeoutTimer = timerService.createTimer(
    req.getApplicationSession(), 3000, false, null);
    req.getApplicationSession().setAttribute(TIMER_ID, notifyTimeoutTimer);
  }
 
  @SuccessResponse
  protected void handleSuccessResponse(SipServletResponse res) throws IOException {
    if (res.getMethod().equals("NOTIFY")) {
      ServletTimer notifyTimeoutTimer =
      (ServletTimer)(res.getApplicationSession().getAttribute(TIMER_ID));
      if (notifyTimeoutTimer != null) {
        notifyTimeoutTimer.cancel();
        res.getApplicationSession().removeAttribute(TIMER_ID);
      }
    }
  }
 
  public void timeout(ServletTimer timer) {
    // This indicates that the timer has fired because a 200 to
    // NOTIFY was not received. Here you can take any timeout
    // action.
    // .........
    timer.getApplicationSession().removeAttribute ("NOTIFY_TIMEOUT_TIMER");
  }
}