target="_blank">Session Initiation Protocol (SIP)
is a signaling protocol that is used to set up, modify, and terminate a
session between two endpoints. SIP can be used to
set up a two-party call, a multi-party call, or even a multicast
session for Internet calls, multimedia calls, and multimedia
distribution. target="_blank">JSR 116: SIP Servlet API
is a server-side interface describing a container of SIP components or
services. SIP servlets, servlets that run
in a SIP container, are similar to HTTP Servlets, but also support the
SIP protocol. Together, SIP and SIP servlets,
are behind many popular telecommunications-based applications that
provide services such as Voice-over-IP (VoIP), instant
messaging, presence and buddy list management, as well as web
SIP and SIP servlets are also important in the enterprise. Combined
with Java EE technology, SIP servlets can be used to
add rich media interactions to enterprise applications.
SIP Servlet v1.1 updates the SIP Servlet API
and defines a standard application programming model to mix SIP
servlets and Java EE components. SIP servlets are going to
play an even bigger part in building the next generation of
This Tech Tip covers some of the basic concepts underlying SIP and SIP
servlets. It also presents a sample
application that uses SIP servlets and HTTP servlets to provide VoIP
What is SIP?
An easy way to describe SIP is to examine a usage scenario.
Let's say a user identified as A wants to set up a call with a user
identified as B. In a telecommunications
setting, user A and B would communicate through what are called user
agents. One example of a user agent is
a soft phone -- a software program for making telephone calls over the
Internet. Another example is
a VoIP Phone -- a phone that uses VoIP. Here are the steps that need to
happen to set up the call:
Figure 1 illustrates the steps in setting up a call.
|Figure 1. Steps in Setting Up a Call|
SIP provides a standardized way of carrying out these steps. It does
this by defining specific request methods,
responses, response codes, and headers for signaling and call control.
The protocol has been standardized by
the Internet Engineering Task Force (IETF) under href="http://www.ietf.org/rfc/rfc3261.txt" target="_blank">RFC3261
and is now accepted as the standard signaling protocol for the
Partnership Project (3GPP) and as a permanent element
in the target="_blank">IP Multimedia Subsystem (IMS)
How is SIP related to HTTP?
People often ask if SIP uses HTTP as the underlying protocol. The
answer is no.
SIP is a protocol that operates at the same layer as HTTP, that is, the
application layer, and uses TCP, UDP, or SCTP
as the underlying protocol. However, SIP does have a lot of
similarities with HTTP. For example, like HTTP, SIP is text based
and user readable. Also like HTTP, SIP uses a request-response
mechanism with specific methods, response codes, and headers.
A notable difference between HTTP and SIP is that the request-response
mechanism is asynchronous in SIP -- a request does not
need to be followed by a corresponding response. In fact, a SIP request
could result in one or more requests being generated.
SIP is a peer-to-peer protocol. This means that a user agent can act as
a server as well as a client. This is another
difference between SIP and HTTP. In HTTP, a client is always a client
and a server is always a server.
SIP supports the following request methods and response codes:
REGISTER. Used by a client to register an address
INVITE. Indicates that the user or service is being
ACK. Confirms that the client has received a final
CANCEL. Used to cancel a pending request.
BYE. Sent by a user agent client to indicate to the
OPTIONS. Used to query a server about its
1xx: Provisional. An
3xx: Redirection. Further action is required to
4xx: Client Error. The request contains incorrect
5xx: Server Error. The server failed to fulfill an
6xx: Global Failure. The request cannot be fulfilled
Session Description Protocol
Session Description Protocol (SDP) is a format for describing the media
format and type to be used in a multimedia session.
SIP uses SDP as a payload in its messages to facilitate the exchange of
capabilities between various user agents. For example,
the content of an SDP might specify the codecs supported by the user
agent and the protocol to be used such as
Real-time Transport Protocol (RTP).
Figure 2 shows the composition of a SIP message .
There are three major parts:
|Figure 2. Composition of a SIP Message|
The SIP Servlet Model
The SIP servlet programming model is based on the servlet programming
model. It brings programming in SIP closer
to Java EE. Servlets are server-side objects that process incoming
requests and send an appropriate response to the client.
They are typically deployed in a servlet container and have a
well-defined life cycle. The servlet container is
responsible for managing the life cycle of the servlets within the
container and managing resources related
to technologies such as JNDI and JDBC that the servlet uses. The
servlet container also manages network connections for
As mentioned earlier, SIP servlets are similar to HTTP Servlets, except
that they process SIP requests.
They do this by defining specific methods to process each of the SIP
For example, HTTP servlets define the
which overrides the
POST requests. By comparison, SIP servlets
doInvite() method, which also
service() method, to handle
defined SIP Servlet API 1.0. It specified:
The initial SIP Servlet API specification is being revised by
SIP Servlet v1.1.
SIP Servlet API -- Key Concepts
The key concepts that underlie SIP servlets are similar to those that
underlie HTTP servlets. The following
sections briefly describe some of those concepts.
The request-response methodology in SIP is similar to that for HTTP
servlets. A request is defined in a
SipServletRequest object and a response in a
However, only one
object is non-null. That's because
a SIP request does not result in a symmetric response. There is also a
common super interface, called
SipServletMessage, for both
SipServletMessage interface defines the methods that
are common to
Figure 3 illustrates the hierarchy of the
|alt="Composition of a SIP Message" height="326" width="500">|
|Figure 3. Hierarchy of |
The servlet context as defined in the servlet specification also
applies to SIP servlets. The servlet specification defines
specific context attributes that are used to store and retrieve
information specific to SIP servlets and interfaces from the
context. The servlet context can be shared with HTTP servlets within
the same application. This is explained in the
section Converged Applications.
An XML-based deployment descriptor is used to describe the SIP
servlets, the rules for invoking them, as well as
the resources and environment property used in the application. This
descriptor is in a
sip.xml file and
is similar to the
file is defined by an XML
SIP Application Packaging
SIP applications have the same packaging structure as web applications.
They are packaged in the JAR format with a file
.sar (Sip archive) or
.war (web archive).
Converged Context and Converged Application
An application may use both SIP and HTTP servlets to create a service.
To allow for HTTP and SIP servlets being in the same application
package, the SIP servlet specification
ConvergedContext object. This object holds the
servlet context shared
by both HTTP and SIP servlets and provides the same view of the
application to SIP and HTTP servlets in terms of
servlet context attributes, resources, and JNDI namespaces.
When an application includes both SIP and HTTP servlets it is known as
a converged application. This is in contrast
to a SIP-only application, which is called a SIP application. A
converged application is similar in structure to
a SIP application except that it has a
web.xml file as a
deployment descriptor in addition to
sip.xml file. In SIP Servlet API 1.1 (JSR289), the
concept of converged applications has been extended
to also cover enterprise applications. Enterprise applications can now
include a SIP application or a converged application
as a module. This type of enterprise application is called a converged
The SIP servlet specification defines
to represent a session over SIP in the same way as
HttpSession objects represent sessions over HTTP. Because
a single application such as a converged
application may have sessions over HTTP and SIP, the specification also
is a session object at the application level. The
object acts as a parent to HTTP and
SIP sessions (that is, protocol sessions) in an application.
Recall that the SIP Servlet API 1.1 aims to align SIP servlets with
Java EE 5. As a result, the specification
introduces the use of annotations defined by Java EE 5 within SIP
servlets and listeners. It also defines custom
annotations to represent interfaces defined by the SIP servlet
specification. The specification introduces the following
@SipServlet. Used to indicate that a particular class is
@SipApplication. Used to define a SIP application. This
SipApplicationannotation can be used to create a logical collection of
@SipListener. Allows a particular class to be
SipListenerfor a particular SIP application. The name
@SipApplicationKey. A method level that helps define a
SipApplicationKeyfor a SIP application. The
Project Sailfin - an Open Source SIP Application Server
A SIP servlet container can be standalone, that is, supporting only SIP
servlets, or it can be a converged container
supporting both HTTP and SIP servlets. However, for most enterprise
uses, a SIP servlet container needs to be
a converged container within an application server.
is an effort to
produce an open source implementation of a SIP servlet container using
application server. The project is being
developed under java.net, with Sun and Ericsson as the major
contributors. Sailfin, the SIP servlet container
implementation in GlassFish being developed in the SailFin project,
supports SIP Servlet API 1.0 and aims to support
SIP Servlet API 1.1 when the specification is finalized.
The CallSetup Sample Application
The sample application for this tip, named CallSetup, is available as
part of the SailFin download. You can download
SailFin from the
target="_blank">Download SailFin Builds page.
target="_blank">SailFin Project - Instructions
to install and configure SailFin. The code for the CallSetup
application is in the
<sailfin-install-home> is the directory where you
The CallSetup application uses SIP servlets and HTTP servlets to
provide VoIP phone service. The application
places VoIP calls with the help of a Back-to-Back User Agent (B2BUA)
SIP servlet. A B2BUA sets up a call between
two user agents by calling each user agent individually and then
connecting the two of them.
CallSetup includes the following components:
Registration.java. A plain old Java object (POJO)
RegistrarServlet. A SIP servlet that allows users to
RegistrationBrowserServlet.java. An HTTP Servlet
SipCallSetupServlet.java. An HTTP Servlet that sends
web.xml. Deployment descriptor for the HTTP servlets.
sip.xml. Deployment descriptor for the SIP servlets.
sun-web.xml. A product-specific deployment
persistence.xml. Defines the persistence unit.
Figure 4 shows the sequence of execution of the
|Figure 4. CallSetup Sequence of Execution|
Let's look at some of the code in the components that comprise
CallSetup. Not all of the components for the application
are shown here and not necessarily all the code in each component.
You're encouraged to explore the entire code for the
application in the SailFin download.
When a user agent sends a
REGISTER request, the
method is invoked and the
registration data is stored. A response with a status code is then sent
to the user agent.
This is an HTTP Servlet that provides an interface to list registered
users and to set up calls between the two of them.
This HTTP Servlet is called from the
acts like a B2BUA by setting up a call between the two users.
This SIP Servlet receives and handles the response to the
request sent by
The servlet processes the response headers and body, gets the SDP, and
INVITE request to the
other user agent, along with the SDP metadata. After it receives the
response from other user with a success response
code, the servlet sets up the call between the two users.
sip.xml file defines the SIP servlets and specifies
their mapping. The mapping for a SIP servlet
operators to define a condition
in which the servlet is invoked. In this case, the match is on the
request method being either
persistence.xml file defines the persistence unit,
which is used to persist
the registration data in the database. The application uses the default
JDBC resource available with Sailfin,
Running the Sample Application
To run the CallSetup application, follow the instructions on the
target="_blank">SailFin Project - Instructions
page. If you follow the instructions successfully, you should be able
to set up a call between two softphone clients.
The phone should ring sequentially at two selected end points.
This tip covered some of the basic concepts underlying SIP and SIP
servlets. It also presented a sample
application that uses SIP servlets and HTTP servlets to provide VoIP
phone service. And it introduced the SailFin
project, which is building an open source implementation of a SIP
servlet container using the GlassFish application server.
To learn more about SIP, SIP servlets, and the SailFin project, consult
the following resources:
Note that there is a NetBeans plugin available for SIP servlets, which
allows you to create a SIP application using
the NetBeans IDE. The plugin is available as a part of SailFin. You can
learn more about the NetBeans plugin
in the blog entry
target="_blank">NetBeans 6.1 and Project Sailfin.
About the Author
Prasad Subramanian is a staff engineer at Sun Microsystems and is the
engineering lead for Project Sailfin.
and Participate With GlassFish
Try GlassFish for a chance to win an iPhone. This sweepstakes ends on
March 23, 2008. Submit your entry today.