Rapid Converged Web-Telecom Application Development with Grails, SIP Servlets and SailFin

Gautam Arora
[gautamsarora@gatech.edu]
(Research Assistant, GT-RNOC , Georgia Tech, Atlanta, U.S.A)

This tutorial demonstrates the development of Converged Applications using Grails Web Application
framework with SIP Servlets and deployment on Sailfin SIP Application Server.

Introduction

Grails: is a MVC action-based agile web application framework that follows the principles of
Convention Over Configuration and DRY (Don't Repeat Yourself). It builds on existing mature Java
technologies like Spring, Hibernate, Sitemesh and uses Groovy to bind them together. It provides
seamless integration with Java technologies (thats as simple as dropping the jar in the lib folder).

SIP Servlets:
The SIP Servlet API (JSR 289) is an extension of the HTTP Servlet API and enables the development
of server components that can talk SIP. These can be deployed alongside Java EE components on SIP
Applications Servers (SIP AS) like Sailfin[1] and allow the development of Converged Applications
like ClickToDial etc.

The motivation here is to demonstrate the integration of SIP Servlets with a Grails Web Application
for rapid development of converged [HTTP+SIP] applications. The integration procedure for HTTP,
SIP Servlets would be relevant for adding support for server-side components of other protocols as
well e.g. XMPP

We build a sample converged ClickToDial [C2D] application (grails-c2app), which will provide a
webpage displaying a list of users registered with SIP AS and allow the user to click on a link on the
webpage to setup a call between 2 users.

The ClickToDial feature is similar to a Skype Me! Button that can be embedded on a webpage, but
with our custom ClickToDial application, the call will be setup by the converged application developed
by us allowing us to integrate it with our business logic and other 3 rd party services.
Following a detailed explanation of the guts of the integration effort, we introduce the
Grails ClickToDial plugin (grails-c2d) which eliminates the manual effort in building the c2dgrails
app and demonstrates building the same capability by simply installing the plugin.

Setup
The application will be developed using the latest versions for Groovy (1.6), Grails (1.1) and deployed
on Sailfin (1.0)

The various strategies to integrate SIP Servlets with Web applications include:
1. Java EE Web App with Java SIP Servlets [existing Sailfin ClickToDial app]
2. Grails Web App with Java SIP Servlets [covered below]
3. Grails Plugin to configure Java SIP Servlets [covered below]
4. Grails Web App with SIP Groovlets (SIP Servlets in Groovy) [future work]

Additional features for this web app like authentication, using other web services is similar to the
procedure followed with existing web applications and we will focus on the Servlet integration.

In his tutorial, "E4SS/Grails/Sailfin tutorial"[3], Gregory Bond demonstrates the integration of E4SS
with Grails.
The goal of this tutorial is to demonstrate the integration of regular SIP Servlets with Grails. For this
project, code from the Sailfin ClickToDial project was modified to replace the JPA support with Grails
ORM (GORM) layer.

The integration of SIP Servlets in the Grails web application is similar in parts to the integration with
(HTTP) Servlets. Therefore, we will first list out the steps to get regular Servlets to work with a Grails
web application and then move onto the SIP Servlet specific bits.

In the following sections, we show the Grails/HttpServlet integration, then Grails/SipServlet integration
and the Grails/ClickToDial plugin.

Building the skeleton Grails app

The following steps show the development of a simple Grails application containing a single model
'Person' class and applying static scaffolding (use dynamic scaffolding is also possible and works fine)
to generate a CRUD web interface for it.

1. $ grails create-app grails-c2dapp

2. $ cd grails-c2dapp
3. $ grails install-plugin hibernate
4. $ grails create-domain-class Person
Edit Person class to add name(String) and telephone(String)
5. $ grails generate-all Person
6. $ grails run-app
Test the application at "http://localhost:8080/grails-c2dapp/"
In order to enable quick testing of the application, default accounts for 'alice' and 'bob' can be created in
[grails-app/conf/BootStrap.groovy]

Note: Due to a bug in grails 1.1, we need to install the hibernate plugin to allow us to generate the
scaffolded views.
Integrating Grails and HTTP Servlets

1. Grails web app packaged with Servlets

1. $ grails install-templates
Produces a web.xml at src/templates/war
2. Develop the servlets at src/java [refer: HelloWorldServlet.java code snippet#1]
3. Add <servlet> and <servlet-mapping> for the servlets in web.xml [refer: src/templates/war/]
4. $ grails run-app
Test the servlet integration at "http://localhost:8080/grails-c2dapp/hello"
5. $ grails war [optional]
Build a war file that can be deployed on a web container like Jetty, Tomcat, Glassfish etc.

2. HTTP Servlets access the GORM domain classes using Service

As shown in the E4SS/Grails/Sailfin tutorial, we build a grails service inorder to gain access to the
Grails Domain classes from the Servlets. This approach requires Service class, ServiceInterface and a
SpringUtility class.

Note: In context with the SIP Servlets, this would be used by the SIP Servlet to set the User telephone
field on REGISTER sip request and get the value for building an INVITE message. Of course, we could
have the Servlet directly access the tables to get/set the values, but that won't be true integration!

1. $ grails create-service DomainAccess

Builds the DomainAccessService class at [services/DomainAccessService.groovy] that exposes
methods which will be called by the Servlet
2. Build an interface[src/java/DomainAccessServiceInterface] and make the service class
implement this interface [refer code]
3. Build a Spring Utility class [src/java/SpringUtils.java] that will inject the grails service in the
servlet at runtime [refer code]
4. Develop the servlets at src/java [refer to code snippet#2 in HelloWorldServlet in sourcecode
that shows how to use the DomainAccess grails service]
5. $ grails run-app
Test the servlet and service integration at "http://localhost:8080/grails-c2dapp/hello?
from=bob&to=alice"
Note: Before testing, create person by names alice and bob along with telephone information to
view result of the previous request
For a more detailed explanation of these steps, refer to the E4SS/Grails/Sailfin tutorial [3].

3. Grails web link calls a HTTP Servlet

There could be multiple ways to implement this (the simplest being calling the servlet directly from the
view or a CallController and use a CallService to call the servlet) We'll choose the first simpler
approach.

1. Edit the list.gsp[views/person/list.gsp] and create a "ClickToDial" link that will call the servlet
and pass the 2 users as parameters e.g. /hello?from=alice&to=bob
[refer: list.gsp for the code additions]
Note: If we implement a login-based system, we would need to pass only the caller as param
2. $ grails run-app
 Test the application at "http://localhost:8080/grails-c2dapp/person/list" where the
ClickToDial link is accessible.
Note: To test this replace the /placecall link in the list.gsp to /hello in the sourcecode.

Integrating Grails and SIP Servlets

The above section sets the ground for us to look at the specific steps for Grails integration with SIP
Servlets in the ClickToDial app.

1. Put the SIP Servlet API jar [ssa-api.jar] available with Sailfin to lib directory in the Grails
project
2. Similar to the servlets in the previous section, we put the SIP Servlets in src/java of the Grails
project. For this example, we use the Servlets in the Sailfin ClickToDial application
(RegistrarServlet, PlaceCallServlet, CallSipServlet) with editing to replace the JPA with Grails
ORM using the DomainAccess grails service as demonstrated in the previous section.
3. Like the web.xml, we create <servlet> and <servlet-mapping> for the SIP servlets at at
web-app/WEB-INF/sip.xml
4. $ grails war c2d.war
This will build a war file that include all the servlets, web.xml and sip.xml
Testing the Grails and SIP Servlets Converged Application on Sailfin:

1. Deploy the converged app 'c2d' war on Sailfin using the Web Admin Console

2. Go to the application page on a browser "http://localhost:8080/c2d/person/" and create accounts

for 'alice' and 'bob'
3. Start 2 SIP softphones like X-Lite, SIP Communicator and configure them as 'alice', 'bob' to
connect to the SIP AS

4. Click on a 'Call' link on the webpage

 This should first ring the phone at the caller(alice) end and on accepting, will ring on the
callee(bob) side which on accept will setup a call between the 2 users.

The code for the sample application 'grails-c2dapp' is available at:

https://sailfin-samples.dev.java.net/

Grails ClickToDial Plugin

After manually configuring the various elements required for integration, I realized that this was an
excellent opportunity to build a plugin to automate all the above required steps. I was able to use the
excellent hooks available in the Grails Plugin architecture to build a converged application plugin.

The primary extension points that this plugin hooks into are:
1. The Plugin.groovy file to participate in the building of the web.xml for HTTP Servlet
integration and to add a telephone field to the Person class (packaged with the plugin) at
runtime using meta-programming facilities in groovy.
2. Introduce a CallController and CallService (to handle call requests from view)
3. Add the WEB-INF/sip.xml into the plugin directory (using scripts/_Events.groovy) when
packaging the plugin
4. The grails-app, web-app, groovy and java source code and jars (in src and lib) is packaged into
the plugin directory by default
5. Copy the WEB-INF/sip.xml into the application (using scripts/InstallSipXml.groovy) when
installing the plugin.

How the plugin works:

We create the application, install the plugin and package it into a war using the steps below:
1. $ grails create-app convergedapp
2. $ cd convergedapp
3. $ grails install-plugin c2d
4. $ grails install-sip-xml
5. $ grails war convergedapp.war

Follow the steps from previous section to deploy the war on Sailfin SIP AS, register the SIP
softphones and place the call by clicking the link on the web page

The code for the 'grails-c2d' plugin is available at:

https://sailfin-samples.dev.java.net/
and will be hosted in the Grails Plugin repository

References:
1. Sailfin SIP Application Server [https://sailfin.dev.java.net/]
2. Sailfin ClickToDial [http://wiki.glassfish.java.net/Wiki.jsp?page=SipClickToDialExample2]
3. "Rapid Converged Telecom Application Development with E4SS, Grails and SailFin" by
Gregory Bond [http://echarts.org/Blog/E4SS-Grails-and-SailFin.html]