The SIP Servlet Tutorial


This is The SIP Servlet Tutorial, a tutorial that describes how to develop telecommunications applications that use the session initialization protocol (SIP) on the Java EE platform. This tutorial also covers how you can integrate SIP applications with other Java EE technologies, like web applications and enterprise beans.

Who Should Use This Book

This tutorial is intended for programmers who are interested in developing and deploying SIP applications on the Sun Java System Communications Application Server 1.5, a Java EE server that integrates a SIP servlet container. Communications Application Server 1.5 is based on the open-source GlassFish and SailFin projects.

This tutorial is intended for the following readers:

This tutorial assumes you are conversant in reading Java programming language source code, and you have a basic understanding of client/server network applications.

About the Examples

This section tells you everything you need to know to install, build, and run the examples included in the tutorial bundle.

Required Software

The following software is required to run the examples.

Java Platform, Standard Edition

To build, deploy, and run the examples, you need a copy of Java Platform, Standard Edition 5.0 (Java SE 5.0) or higher. You can download the Java SE 5.0 software from Download the current JDK update that does not include any other software (such as the NetBeans IDE or Java EE).

Communications Application Server 1.5

Communications Application Server 1.5 is targeted as the build and runtime environment for the tutorial examples. Communications Application Server 1.5 is based on the GlassFish and SailFin open-source projects.

NetBeans IDE

The NetBeans integrated development environment (IDE) is a free, open-source IDE for developing Java programming language applications, including enterprise applications. NetBeans IDE supports the Java EE 5 platform. You can build, package, deploy, and run the tutorial examples from within NetBeans IDE.

SIP Modules for NetBeans IDE

Integrate the SailFin plug-in modules, which add SIP application development functionality to NetBeans IDE. The modules are bundled with Communications Application Server 1.5.

  1. In NetBeans IDE, select Tools->Plugins.

  2. Click the Downloaded tab and click Add Plugins.

  3. Navigate to the Install/tools/netbeans directory and select all the files in this directory.

  4. Click Install, then Next.

  5. Select I Agree in the License Agreement window and click Install.

  6. Click Continue to install the unsigned modules, then click Finish.

Sample Applications

The tutorial uses several sample applications available on the SailFin website.

  1. Go to the following URL:

  2. Follow the instructions to download the SipProxy and SIP Servlet 1.1 Click-To-Dial sample applications.

SIPp Test Application

SIPp is an application to test SIP clients and servers. It is available from

X-Lite Soft Phone

X-Lite is a free multi-platform soft phone used in the examples. It is available from

Apache Ant

Ant is a Java technology-based build tool developed by the Apache Software Foundation (, and is used to build, package, and deploy the tutorial examples. Ant is included with the Communications Application Server 1.5. To use the ant command, add JAVAEE_HOME/lib/ant/bin to your PATH environment variable.

Building the Examples

The tutorial examples are distributed with a configuration file for either NetBeans IDE or Ant. Directions for building the examples are provided in each chapter. Either NetBeans IDE or Ant may be used to build, package, deploy, and run the examples.

ProcedureBuilding the Examples Using NetBeans IDE

To run the tutorial examples in NetBeans IDE, you must register your Communications Application Server 1.5 installation as a NetBeans Server Instance. Follow these instructions to register the Communications Application Server 1.5 in NetBeans IDE.

  1. Select Tools-->Server Manager to open the Server Manager dialog.

  2. Click Add Server.

  3. Under Server, select Sun Java System Application Server and click Next.

  4. Under Platform Location, enter the location of your Application Server installation.

  5. Select Register Local Default Domain and click Next.

  6. Under Admin Username and Admin Password, enter the admin name and password created when you installed the Application Server.

  7. Click Finish.

Tutorial Example Directory Structure

To facilitate iterative development and keep application source separate from compiled files, the tutorial examples use the Java BluePrints application directory structure.

Each application module has the following structure:

The Ant build files (build.xml) distributed with the examples contain targets to create a build subdirectory and to copy and compile files into that directory; a dist subdirectory, which holds the packaged module file; and a client-jar directory, which holds the retrieved application client JAR.

Related Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note –

Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Documentation, Support, and Training

The Sun web site provides information about the following additional resources:

Typographic Conventions

The following table describes the typographic conventions that are used in this book.

Table P–1 Typographic Conventions





The names of commands, files, and directories, and onscreen computer output 

Edit your .login file.

Use ls -a to list all files.

machine_name% you have mail.


What you type, contrasted with onscreen computer output 

machine_name% su



Placeholder: replace with a real name or value 

The command to remove a file is rm filename.


Book titles, new terms, and terms to be emphasized 

Read Chapter 6 in the User's Guide.

A cache is a copy that is stored locally.

Do not save the file.

Note: Some emphasized items appear bold online.

Shell Prompts in Command Examples

The following table shows the default UNIX® system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell.

Table P–2 Shell Prompts



C shell 


C shell for superuser 


Bourne shell and Korn shell 


Bourne shell and Korn shell for superuser