An IMS Application Example Based on SIP Servlets and VoiceXML

Application Description

The Personal Assistant application described in this article is a full-featured example built for the purposes of demonstrating how to create applications consistent with the IMS architecture using SIP servlets and VoiceXML. Figure 3 illustrates the application flow.

Figure 3

Figure 3. Personal Assistant application flow

The application commences with the caller placing an INVITE to the AS indicating the SIP URI of the callee. The callee's Personal Assistant answers and plays a greeting. The caller is asked to record a name. The Personal Assistant then gets a list of device SIP URIs for the callee that have been previously configured. A call is placed to each SIP URI, one at a time. If the callee does not answer, the next URI is tried. If the Personal Assistant runs out of URIs to try, it plays a valediction message to the caller and terminates. If the callee answers, the callee is asked whether he or she wishes to accept the call. The callee responds via DTMF touch-tone. If the callee accepts the call, he or she is connected to the caller, otherwise the caller is terminated. The personal greeting can be changed by pressing the "*" key while the greeting is being played.

The SIP flows for the application are given as part of the code discussion later in the article.

A simple Web page is provided (http://<app_server_host>:7001/PersonalAssistant/) to configure the mapping of a user's public address (address of record) to one or more device URIs corresponding to different terminals, for example, home phone or office phone (see Figure 4).

Figure 4

Figure 4. Adding SIP addresses

Running the Application

To run the application, you need to perform the following steps:

  1. Download and install BEA WebLogic SIP Server 2.1 evaluation.
  2. Download and install a SIP phone. A free download is available from SJ Labs; alternatively, CounterPath offers a low-cost phone called Eyebeam that also supports video.
  3. Download the application ZIP archive, extract it, and follow the instructions in docs\AppSetupInstructions.pdf.

Application Code

This section discusses some of the architecturally significant aspects of the application code. Here we assume the reader has basic understanding of SIP servlets and VoiceXML; see the References at the end of this article for pointers to some introductory material.

Overview

The Personal Assistant application is a converged SIP servlet and HTTP servlet application. The SIP servlet code is responsible for performing SIP back-to-back user agent (B2BUA) functionality. The HTTP servlet code manages the VoiceXML dialogs by delivering VoiceXML documents to the Voxpilot MRF. The HTTP servlet code is also used to provide a HTML interface for configuring the application. Figure 5 illustrates an overview of the top-level assistant package.

Figure 5

Figure 5. The assistant package (click the image for a full-size screen shot)

The Personal Assistant application has one SIP servlet ( AssistantSipServlet) and one HTTP servlet ( AssistantHttpServlet) that act as the SIP and HTTP entry points to the application. The important classes comprising the assistant package are described below.

AssistantHttpServlet

This servlet behaves as a controller by responding to HTTP requests from the MRF, and triggers the associated AssistedCall object to perform various functions depending on the choices given by the person interacting with the VoiceXML application running on the MRF. This servlet will respond to the MRF with the appropriate VoiceXML documents or audio bytes depending on the HTTP request parameters. The servlet also acts as a controller for HTTP requests from a Web browser. In all cases, the servlet dispatches to JSP files that contain the VoiceXML or HTML, therefore providing a clean partitioning between the control logic and the presentation.

AssistantSipServlet

The AssistantSipServlet is configured in the deployment descriptor (sip.xml) to receive SIP INVITE requests. When an INVITE is received, a SipApplicationSession and AssistedCall object is created, as shown in the following code snippet:

protected void doInvite(SipServletRequest req) throws

                  ServletException, IOException {

    List calleeContacts = new ContactDAO().getContactsForAor(aorURI);

    SipApplicationSession appSession = factory.createApplicationSession();

    AssistedCall call = AssistantService.createAssistedCall(req,
                    appSession, calleeContacts);
    call.startAssistedCall();
}

The AssistantSipServlet also receives SIP requests and responses via its doRequest() and doResponse() methods. These methods pass on the SIP messages to the appropriate targets (see the description for the ISipDialog interface, next).

ISipDialog

This interface is implemented by classes that wish to receive SIP dialog messages. The ISipDialog references are stored in the SipSession, allowing it to be retrieved later. The ISipDialog interface enables the AssistantSipServlet to dispatch SIP messages appropriately. The getSession() method on the SipServletResponse class returns the SIP session associated with the current SIP dialog. The reference to the ISipDialog is available from the SIP session having been inserted into it previously. See the code example below:

protected void doResponse(SipServletResponse arg0) throws
                 ServletException, IOException {

    super.doResponse(arg0);

    ISipDialog dialog = (ISipDialog) arg0.getSession().
        getAttribute(ISipDialog.SESSION_KEY);

    if (dialog != null)
        dialog.doSipServletMessage(arg0);
}