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|http://groups.google.com/group/cipango-users].

h3. Maven

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: {link-window:http://maven.apache.org/users/index.html}http://maven.apache.org/users/index.html{link-window}

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

h3. 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:

{code}mvn archetype:generate -DarchetypeCatalog=http://repository.cipango.org{code}

You should then see an output similar to:
{code:language=none}
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom <<<
[INFO]
[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: http://repository.cipango.org -> maven-archetype-sipapp (Sample Sip Servlets Application Maven Archetype)
{code}

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:

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

The {{MainServlet.java}} 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:

{code}mvn install{code}

{info}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.{info}

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.

h3. 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:
{code}mvn cipango:run{code}

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

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:
{code:language=none}2011-04-07 15:13:26.761:INFO::Started UdpConnector@127.0.1.1:5060
2011-04-07 15:13:26.763:INFO::Started TcpConnector@127.0.1.1:5060{code}

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 {link-window:http://sipsak.org/#install}http://sipsak.org/#install{link-window}.
Once sipsak has been installed, you are able to send an {{OPTIONS}} message as follows:
{code}sipsak -v -s sip:cipango_address:cipango_port{code}

For instance, as explained above, our plugin runs on {{127.0.1.1:5060}}, sipsak should then be run as:
{code}sipsak -v -s sip:127.0.1.1:5060{code}

This should yield something like:
{code:language=none}
SIP/2.0 200 OK
Via: SIP/2.0/UDP 127.0.1.1:33950;alias;rport=37170;branch=z9hG4bK.4c0c8c9e
From: <sip:sipsak@127.0.1.1:33950>;tag=78cf6b42
To: <sip:127.0.1.1>;tag=72f4d22c
Call-ID: 2026859330@127.0.1.1
CSeq: 1 OPTIONS
Server: cipango-2.0
Content-Length: 0
{code}

h3. 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:

{code:language=xml}
<plugin>
  <groupId>org.cipango</groupId>
  <artifactId>cipango-maven-plugin</artifactId>
  <version>${cipango.version}</version>
  <configuration>
    <scanIntervalSeconds>10</scanIntervalSeconds>
  </configuration>
</plugin>
{code}
Restart the cipango plugin and in another window edit the {{src/main/java/org/cipango/MainServlet.java}} servlet source code as follows:
{code}
@Override
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
    ok.send();
}
{code}
Compile the modified servlet:
{code}mvn compile{code}
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.