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: http://maven.apache.org/users/index.html
We'll assume now that you have Maven installed on your system.
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:
You should then see an output similar to:
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:
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:
|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.
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:
|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:
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 http://sipsak.org/#install.
Once sipsak has been installed, you are able to send an OPTIONS message as follows:
For instance, as explained above, our plugin runs on 127.0.1.1:5060, sipsak should then be run as:
This should yield something like:
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/MainServlet.java servlet source code as follows:
Compile the modified servlet:
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.