Home > Java, SIP, Telecom > A study on Java APIs for SIP. Part 2: SIP Servlets API

A study on Java APIs for SIP. Part 2: SIP Servlets API

Now let’s take a look on JAIN SIP API‘s younger brother called SIP Servlets API. This guy was ambitious from the birth, so he joined a mob called “JEE” to receive money from big business. But big business never gives money for free, so SIP Servlets API had to cover all behaviour specified for SIP and to provide as large framework as possible, so programmers who work for big business will not bother thinking about protocol details and about execution model. An attempt has failed miserably, because SIP, unlike HTTP, is not about content.

SipServlet interface

First obvious problem of SIP Servlets API is that it is an extension of Generic Servlets API. The cornerstone class of Generic Servlets API is called Servlet, and has only three methods: init(), service() and destroy(). In my opinion, the main problem here is that this class is essentially a too generic framework. Behaviour of container is always protocol-dependent, so servlets are also protocol-dependant. Still, everybody are forced to use this narrow interface for interaction. Are there any convergent servlets which handle several protocols through their service() method ? No, there are convergent applications instead. I think that service() method should be removed from Servlet class. Instead, all concrete servlets would have their own service() method, accepting protocol-specific requests and responses.

I understand that most people don’t bother with problem of downcasting request and response in service() method, so it is not a big deal. I just don’t like it working in this way.

Applications always do some dispatch for incoming messages, so APIs provide some dispatch out-of-box to help application developers. Unlike JAIN SIP API, which has dispatch based on local endpoint and on message type (request/response), SIP Servlets API have built-in dispatch based on request method and response status code. I think that this approach is more useful for applications.


Next bad thing in SIP Servlets API is an existence of SipServletMessage interface. It’s exactly the same case as with JAIN SIP API: this abstraction is not used by anyone. Yes, it is good that signatures of methods in SipServletRequest and SipServletResponse are the same, but nothing will break if these signatures would differ. Authors of SIP Servlet API have ignored the lesson of HTTP Servlets API, which doesn’t have common interface. I understand that HTTP is much more assymmetric then SIP, so in HTTP servlets people are reading headers of requests and writing headers and body to responses, so syntaxic similarity is not related to behaviour. But I still don’t see how syntaxic symmetry of SIP requests and responses could be used in practice.

Syntax part of SIP Servlets API is much smaller and simpler then of JAIN SIP API. Obtaining header will return you a string, adding or changing a header will also accept value as string. Additional parsing is supported only for address headers.


SipServletMessage interface includes not only syntax-related methods but also method send(). Message is a nice context for method send(), because it is the message which should be sent. The fact that method send() belongs to SipServletMessage interface shows that SIP Servlets API doesn’t strive for separation of syntax and behaviour. SipServletMessage is not just a header, start line and body, but it is a gateway to SIP stack, hiding transactions, dialogs and all other protocol layers. This means that you can’t just “forward” incoming message, because it can’t be separated from all internal state. Instead you should either create a new message and manually copy all necessary data from original message into new message, or use hacks provided by API (like proxyTo() or createRequest() method which accepts original request). Thus the amount of interfaces in API is low, but the amount of behavioural methods is large, and their semantics is more complex. However, as long as “message=syntax+state” approach was selected, all methods which implement SIP behaviour are also belong to SipServletRequest or SipServletResponse classes, so message is a context for an action. Such approach is easy to understand by beginners.

Another problem of method send() is that compiler will not complain if you’ll try to invoke it for incoming message. Of course SIP stack will not send such message, you’ll get IllegalStateException in runtime. Thus, SIP Servlets API is not designed to use type system for preventing errors.  A correct solution would be to have separate classes like IncomingRequest, OutgoingRequest, IncomingResponse, OutgoingResponse. There are other behaviour-related methods which could be moved to specific classes instead of throwing an IllegalStateException: createCancel(), createResponse(), createAck(). Some special requests (like ACK and CANCEL) could also be represented by specific classes which would not have methods createResponse().

SIP Servlets API provide large application framework, with different listeners. However, it doesn’t provide a powerfull protocol framework. Instead, you have a SipSession which represents either dialog or proxying session. This SipSession is used for two purposes. First, as a factory for in-dialog requests. Second, as a storage for application context. This means that for every incoming subsequent message an application should restore its context from SipSession object. Such manual contextualization is not a very convenient thing to program, but it allows application server to be distributed and fault-tolerant. Ability to set a servlet which will handle the session can’t be considered as a protocol framework, since that servlet also can’t have its own context and should contextualize itself from SipSession. A little bit more information is given in subsequent post.


SIP Servlets API is not an API for SIP stack. Instead it is an API for application server which means that it tries to be as complete as possible and it is not designed to be extensible. Container should provide all nesessary functionality, and servlets should just contain business logic needed to handle incoming messages. This makes it attactive to beginners who enjoy it’s protocol power. This API will not allow you to violate SIP rules, however it is usually done by throwing exceptions in runtime. Protocol framework is absent, all you have is a SipSession to store and restore your context.

Next article will compare both APIs, will discuss lots of general API-related stuff and will propose better solutions.

Categories: Java, SIP, Telecom Tags: , ,
  1. max
    September 30, 2010 at 2:24 pm

    thank you for useful post

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: