Here I would like to start a series of blogs to talk about how to build advanced VoIP services with SIP servlet technology.
This blog covers some of the basic concepts about SIP servlet technology and demonstrate a simple SIP proxy server using SIP servlet programming model.
What is a Servlet and a Servlet Container?
A servlet is a Java component which is managed by a servlet Container and which responds to messages of an application protocol.
A servlet container, typically part of an application server, manages the lifecycle of servlets, sends and receives the messages for servlets. It also provides other services such as security to servlets as well.
The following diagram shows the relationship of a servlet, servlet container, application server, and Java virtual machine.
When needed, the servlet container loads the servlet class, instantiates (a.k.a. new()) the servlet and invokes its init() method with the configuration in the form of ServletConfig object. Once initialized, the servlet is able to serve the messages. The servlet container repeatedly invokes the servlet’s service() method with the incoming messages in the form of ServletRequest and ServletResponse objects. The servlet container can deactivate a servlet by invoking its destroy() method and makes the servlet eventually be garbage collected.
As you can tell, the lifecycle of a servlet is rather simple. The service() method is where all the interesting actions are during its life. What a servlet does in its service() method fundamentally depends on the application protocol the servlet supports.
What is a HTTP and a SIP Servlet?
Simply speaking, a HTTP servlet is a kind of servlet that supports HyperText Transfer Protocol, and a SIP servlet is a kind of servlet that supports Session Initiation Protocol. If you are familiar with Object Oriented programming, you should be able to think of the following class diagram.
The latest HTTP servlet specification (and the generic servlet specification) is Servlet 2.5. The latest SIP servlet specification is SIP Servlet 1.1. You may notice that the APIs of both specifications are quite similar. However there are many subtle differences due to the differences of the protocols.
The most fundamental difference of a HTTP servlet and a SIP servlet is what a servlet can do in the service() method.
HTTP is a synchronous protocol where a HTTP servlet is expected to receive a HTTP request and respond with a HTTP response before it can serve another HTTP request. In the HttpServlet.service(HttpServletRequest request, HttpServletResponse response) method, a HTTP servlet is expected to process the request and write the output into the response within the method invocation.
SIP is an asynchronous protocol where a SIP servlet can receive a SIP request and response at any time. In the SipServlet.service(SipServletRequest request, SipServletResponse response) method, only one of the parameters – either the request or the response – is valid. The SIP servlet is expected to receive the request or response in the service() method but can either process it within the method invocation or save it for processing at a later time. A SIP servlet can also issue requests or responses at any time as long as the servlet is in the initialized state.
How to write a SIP servlet?
Writing a SIP servlet starts with creating a subclass of the SipServlet class. Instead of overwriting the service() method, you typically overwrite one of the doXXX() methods.
The doXXX() methods are defined to modularize the logic within the service() method. The default implementation of SipServlet.service() method calls one of the doXXX() methods based on the type of the message it receives. For example, for a SIP INVITE request, doInvite() method is invoked.
Because most of SIP protocol details, such as message parsing, retransmission, transaction and dialog management, are abstracted away from a SIP servlet, the logic with these doXXX() methods shall just focus on the high level functionality.
Here I demonstrate how easy it is to write a stateful SIP proxy with a SIP servlet – just 4 lines of code, including one optional line.
public class ProxyServlet extends SipServlet {
public void doInvite(SipServletRequest request) throws ServletException, IOException {
if (request.isInitial()) {
Proxy proxy = request.getProxy();
proxy.setRecordRoute(true); //optional
proxy.proxyTo(request.getRequestURI());
}
}
}
In the doInvite() method, I first check to see if the request is an initial request – a request that doesn’t match any existing SIP dialogs. If true, I simply create a Proxy object out of the request. I can optionally invoke Proxy.setRecordRoute() method to indicate this SIP proxy records the route. Then just simply proxy the request to its destination by invoking Proxy.proxyTo() method with the original request URI.
That’s it – now I have a functional stateful SIP proxy. What about all the complex Proxy Behavior in RFC 3261? The SIP servlet container has taken care of most of the standard work once it knows the SIP dialog associated the INVITE request is intended for proxy. Isn’t this wonderful to an application developer?
How to build a SIP servlet application?
A typical SIP servlet application probably involves more than just one SIP servlet class. In order for the SIP servlet container to properly load and run a SIP servlet application, the application has to be assembled into a hierarchical directory structure with additional deployment descriptors, as shown in the following.
|-- WEB-INF
| |-- classes (where all the java classes are)
| | |-- com
| | |-- voxeo
| | |-- sipmethod
| | |-- tutorial
| | |-- one
| | |-- ProxyServlet.class
| |-- lib (where all the library JARs are, if any)
| |-- sip.xml (optional SIP deployment descriptor XML)
| |-- web.xml (optional HTTP deployment descriptor XML)
|-- index.html (document files)
The root of the hierarchy is where all the documents, such as index.html, are, although there is none in this tutorial.
A special directory under root is WEB-INF, which is where all other stuff are, such as Java classes, libraries, deployment descriptors, etc.
All the Java classes including servlets shall be placed under WEB-INF/classes directory. The above diagram shows how ProxyServlet.class is placed. WEB-INF/lib is where all the third-party libraries (i.e. JARs) are, in which I don’t have any in this tutorial. All the deployment descriptors – sip.xml and web.xml – are also under WEB-INF directory.
A deployment descriptor is an XML file that conveys information about how the application is assembled and to be deployed. In other words, these are meta data about the application.
With the latest servlet standards, these meta data can also be specified in the Java classes using Java annotations. For example, to specify deployment information about the ProxyServlet, we add a class level annotation – @SipServlet – to specify the name for the servlet
@javax.servlet.sip.annotation.SipServlet(name="Proxy")
public class ProxyServlet extends SipServlet {
...
}
sip.xml is the deployment descriptor for all the SIP related meta data. Here I specify the application name, the default timeout value for proxy and the main servlet of the application. (These information can be specified using Java annotation as well.)
<sip-app xmlns="http://www.jcp.org/xml/ns/sipservlet"
xmlns:javaee="http://java.sun.com/xml/ns/javaee">
<app-name>SIP Proxy Server</app-name>
<main-servlet>Proxy</main-servlet>
<proxy-config>
<proxy-timeout>300</proxy-timeout>
</proxy-config>
</sip-app>
I don’t have web.xml in this tutorial. I will cover web.xml when talking about converged applications.
Typically we package the above directory structure into a Servlet Archive (SAR) using the standard Java Archieve (JAR) format, which is essentially a ZIP file. Here is the SAR file of the above SIP proxy sample.
How to deploy and run a SIP servlet application?
Deploying a SIP servlet application typically means deploying the SAR of the application to a SIP servlet container. Running the SIP servlet container typically runs all the SIP servlet applications deployed within that container.
The exact steps of deploying and running a SIP servlet application depends on which SIP servlet container and application server you use. The following steps are based on SIPMethod Application Server.
- Make sure you have JDK 1.5 or later installed on your system.
- Install SIPMethod Application Server 4.0 (beta). Let’s call where SIPMethod Application Server is installed <sm_home>.
- Remove all all the files and directories under <sm_home>/apps. This step is to simplify the application routing since we haven’t talked about the concept of Application Router yet.
- Copy the SAR file of the above sample into <sm_home>/apps directory.
- Assuming environment variable JAVA_HOME is pointing to where the JDK is installed, running <sm_home>/bin/startup.[bat | sh] shall start SIPMethod Application Server.
- Now your SIP proxy server is up and running.
To test your SIP proxy server, you can try any softphone that can be configured with an outbound proxy server. Once you configure SIPMethod Application Server as the outbound proxy server (by default, SIPMethod listens on port 5060 on all local IPs), the call made from the softphone shall be proxied through your SIP servlet based SIP proxy server to its destination.
Hopefully this blog gives you some basic ideas about SIP servlet programming. There are still quite a lot to be covered, such as converged applications, application composition, etc. So stay tuned for more SIP servlet programming blogs.
If you found this post interesting or helpful, please consider either
subscribing via RSS, becoming
a fan on Facebook, or
following us on Twitter.
RSS Feed
