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. 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. Adding SIP addresses
Running the Application
To run the application, you need to perform the following steps:
- Download and install BEA WebLogic SIP Server 2.1 evaluation.
- 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.
- 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. 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);
}