This documentation relates to last stable version of Cipango.
visit the last unstable documentation home.

Skip to end of metadata
Go to start of metadata

In this tutorial, we'll show you how to develop a first SIP Servlets application in a few minutes using a Maven Archetype. If you run into any issue during this tutorial, please feel free to ask for help on the cipango-users list.


Maven is a project management, build and deployment tool developed by the Apache foundation. It has become the de-facto standard for Java development lifecycle management, it is used by most open source projects and is adopted also by many software companies.

To install Maven and find out how to use it, a good starting point is:

Unknown macro: {link-window}

We'll assume now that you have Maven installed on your system.

Bootstrapping your Maven project using archetypes

Maven archetypes are project templates, somewhat similar to IDE wizards. They provide a quick and easy way to get a working Maven project with all the needed dependencies and the required structure. We'll use a SIP Servlets specific archetype provided by Cipango to create our first application.

To use a cipango-provided archetype, simply type:

mvn archetype:generate -DarchetypeCatalog=

You should then see an output similar to:

[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO] >>> maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom >>>
[INFO] <<< maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom <<<
[INFO] --- maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)

Choose archetype: 1: -> maven-archetype-sipapp (Sample Sip Servlets Application Maven Archetype)

Choose archetype 1, you are then asked to enter the three required fields for a Maven project. These are:

  • groupId: unique identifier amongst an organization or project, for instance: org.cipango
  • artifactId: it is generally the name that the project is known by, for instance: my-first-app
  • versionId: version of your project. You may leave it empty to use default value.

You are then asked for the package name, which is simply the package to use for the Java sources. By default, it is equal to the groupId.
You have then to confirm and you're done ! The project is being created in a directory named after your project name (given artifactId). You should have now a directory structure similar to this one:

$ tree my-first-app/
|-- pom.xml
`-- src
    `-- main
        |-- java
        |   `-- org
        |       `-- cipango
        |           `--
        |-- resources
            `-- webapp
                `-- WEB-INF
                    |-- sip.xml
                    `-- web.xml

The is a simple SIP servlet which answers to incoming OPTIONS message with a header indicating the server version.
The archetype created the Maven project as well as a SIP Application with the servlet and deployment descriptors. To build the application, simply cd to the created directory and enter:

mvn install

If you have just installed Maven on your system, do not worry if the first build is rather long. Maven has a very modular architecture and downloads required modules only when needed. As a result, first uses of Maven generally lead to a lot of downloads. Once everything installed, subsequent runs are way faster.

When the build ends, you should see BUILD SUCCESSFUL at the end of the output. The SIP Application is now built and packaged as a .war in the target directory.

Running with cipango plugin

You can now deploy the SIP Application in your preferred SIP Servlets container. To quickly test it, we'll skip this step and use the Cipango Maven Plugin. It consists in a Maven plugin which embeds a Cipango Application Server and allows to run SIP Applications directly from Maven without copying anything. To start it, enter:

mvn cipango:run

Again, the first execution may takes time as Maven downloads a lot of modules, this is done only once.

The application is now running. The plugin indicates on the standard output on which address and port it listens to. For instance, you should see on the standard output something like:

2011-04-07 15:13:26.761:INFO::Started UdpConnector@
2011-04-07 15:13:26.763:INFO::Started TcpConnector@

To test it, we now have to send it a SIP OPTIONS message. This can be done using sipsak, a simple multi-platform tool that allows to perform various tests on SIP servers. Installation is very easy and is detailed at

Unknown macro: {link-window}

Once sipsak has been installed, you are able to send an OPTIONS message as follows:

sipsak -v -s sip:cipango_address:cipango_port

For instance, as explained above, our plugin runs on, sipsak should then be run as:

sipsak -v -s sip:

This should yield something like:

SIP/2.0 200 OK
Via: SIP/2.0/UDP;alias;rport=37170;branch=z9hG4bK.4c0c8c9e
From: <sip:sipsak@>;tag=78cf6b42
To: <sip:>;tag=72f4d22c
Call-ID: 2026859330@
Server: cipango-2.0
Content-Length: 0

Modifying the application

The plugin can be configured to scan target/classes for any changes in your Java sources and will automatically reload the modified classes. To enable this feature, open the pom.xml file and add a <configuration> tag as follows:


Restart the cipango plugin and in another window edit the src/main/java/org/cipango/ servlet source code as follows:

protected void doOptions(SipServletRequest options) throws ServletException, IOException
    SipServletResponse ok = options.createResponse(SipServletResponse.SC_OK);
    ok.addHeader("Server", serverInfo);
    ok.addHeader("Foo", "Bar"); // added this line

Compile the modified servlet:

mvn compile

Wait for a few seconds, the plugin should indicate that it has restarted the application. Using Sipsak, you can check that the Foo header has been added.

  • No labels