vendredi 20 novembre 2009

Developping a Simple SIP application with Mobicents and Eclipse

Introduction

This article is a tutorial showing how to create a simple Sip Application with Mobicents, Tomcat and Eclipse. Using JBoss instead of Tomcat should be straightforward.

The procedure is validated under Windows at this time (will be checked under Linux as soon as my Linux PC will be fixed !).
The minimal configuration is winXP, with at least 2GB RAM.

I suppose you are starting from scratch. The main steps are the following :
  • Installing Eclipse
  • Installing the Tomcat/Mobicents plugin
  • Installing Mobicents
  • Declaring a server for your Mobicents instance in Eclipse
  • Creating a new simple project in Eclipse, and deploy it
  • Configure the Mobicents default application router to call your application
  • Configure x-lite (softphone)
  • Test the application with the x-lite client
In each step, you will find a couple of links, if you need to go further.

Links :
The user guide can be found here.

Installing Eclipse

The required version of Eclipse is 3.4.
Download the package here (Need the JavaEE distro, to have the Web toolkit installed by default).
Just unzip it somewhere (say c:\eclipse), and run the eclipse.exe.

Choose a location for your source (an Eclipse workspace).
Once Eclipse is loaded, display the workbench (right-top icon).


Installing the Tomcat/Mobicents plugin

What we need at the moment is the Sip Servlet Core plugin.

  • Click Help / Install new software
  • Click Add

  • Enter the following :
Name = Mobicents
Location = http://mobicents.googlecode.com/svn/downloads/sip-servlets-eclipse-update-site/





  • Select Sip Servlets core plugin


  • Click Next a couple of time. Accept the Licence (which is LGPL), confirm that you are OK to install unsigned software, restart Eclipse. Pretty straightforward...

Testing
Once Eclipse is restarted :

Click File / New / Dynamic Web Project.
In the "Configuration" dropdown list, you should have the item "Converged Sip/Web Project".



Links
Vladimir's blog
Video showing plugin's insallation (for Eclipse 3.4).


Installing Mobicents

The installation is well described in the Mobicents user guide.
Install the Tomcat version, which is smaller than the JBoss one and is enough to start.


Declaring a server for your Mobicents instance in Eclipse

  • Open the Servers view (if you can't see it, click Window / Show view / Servers)

  • In the Servers pane, right click. Choose new / server
  • In the dialog, select Apache Tomcat 6

  • Select a name for your server, as well as the location (root directory) of your Mobicents Installation ("Tomcat Installation Directory").

  • The next dialog is empty at this time, because we still do not have created any project. Simply click Finish.

  • In the "Servers" pane, double click on your server. Modify the deploy path from "wtpwebapps" to "webapps".
[ If anybody knows how to make Mobicents work with wtpwebapps as deployment directory, let me know !]


  • Save the server's configuration (CTRL + S).

Creating a new simple project in Eclipse

  • Click File / New / Dynamic Web Project
We will generate a simple SIP application without any Web support (only basic JSP).
  • In the dialog
  1. enter "SimpleServlet" as project name.
  2. select 2.4 as module version (2.5 version does not allow simple SIP app)
  3. Select "Converged SIP / Web" as configuration
  • Click "Finish". This will generate a simple project.
  • Right click on your server in the "servers" pane, then select "Add and Remove".
  • In the dialog, select "SimpleServlet" on the left side, and make it available ("Add" button). Click "Finish".

  • Open the file Servers / Mobicents at localhost-config / server.xml
  • At the end of the file, locate the Context definition :
<context docbase="SimpleServlet" path="/SimpleServlet" reloadable="true" source="org.eclipse.jst.j2ee.server:SimpleServlet"></host>

  • Remove the Context tag. KEEP </host> the tag only !!
Guru's help needed : if you do not remove the context definition from server.xml, Sip servlets are not started at launch time.......
  • Edit the SimpleServlet.java file (the core of your servlet) :
Cut-n'paste the following content (replace all) :

package org.example.servlet.sip;

import java.io.IOException;

import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.sip.SipServlet;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServletResponse;

public class SimpleServlet extends SipServlet {

public void doInvite(SipServletRequest request) {

System.out.println("*** Received INVITE ***");

try {
request.createResponse(SipServletResponse.SC_RINGING).send();
//request.createResponse(SipServletResponse.SC_OK).send();
} catch (IOException e) {
e.printStackTrace();
}

}

public void doCancel(SipServletRequest request) {

System.out.println("*** Received CANCEL ***");

try {
request.createResponse(SipServletResponse.SC_REQUEST_TERMINATED).send();
} catch (IOException e) {
e.printStackTrace();
}

}


@Override
public void init(ServletConfig servletConfig) throws ServletException {
System.out.println("****** the simple sip servlet has been started ********* ");
super.init(servletConfig);
}
}

  • Deploy your application : in the servers pane, right clic on your server, then deploy.
  • Now start the server. On the servers pane, right click on your server, then choose Deploy, and Start
  • Check the log file ("console" view). Check that you do not have any error (no excpetion).
  • You should see the log ****** the simple sip servlet has been started *********
  • Now, the server should be listening on the UDP port 5080 (can be checked by the netstat -an command). It should contain the following line. (if you want grep, I recommand you install MINGW to get grep and tail).

UDP 127.0.0.1:5080 *:*

  • Your application is deployed in the following directory :
\.metadata\.plugins\org.eclipse.wst.server.core\tmp0\webapps

(useful to know to debug sometimes).

  • Now, your application is running. We still need to tell Mobicents to route the SIP requests to your application

Configure the Mobicents default application router to call your application

  • In your Mobicents installation (e.g. c:\Mobicents), edit the following file :
conf\dars\mobicents-dar.properties

  • Replace the content by the following :
INVITE=("SimpleServlet", "DAR\:From", "TERMINATING", "", "NO_ROUTE", "0")

The application "Sip Servlet Management" allows to modify this directly from your browser (avoids typos). Will be explained in a next version.

  • Restart Mobicents from Eclipse (servers pane, right clic, Stop + Start).
Stopping server hangs under Eclipse. After a few seconds, a dialog box requests you to terminate the server. Any help from a guru is welcome !

Configure x-lite

  • Download and install x-lite from Counterpath .
  • From the menu (arrow on the top), select "Sip account settings", then Add

  • In the dialog, enter the following :

  1. Display name = mobicents
  2. User name = mobicents
  3. Password = mobicents
  4. Auth user name = mobicents@mobicents
  5. Domain = mobicents.org
  6. Important : uncheck "register with proxy"
  7. proxy = localhost:5080
  • Click OK and Close. After a few seconds, x-lite should become "Ready".
  • Now, the first "call". Dial 1234 (or whatever). This should call the "doInvite" method of your servlet, which will send a 180 response. You whould then hear the ringback tone in x-lite.
  • In the Eclipse console view, check the log :
*** Received INVITE ***
  • Click the Hangup button. x-lite will send a Cancel to Mobicents, which will be processed by your app (doCancel method). Mobicents will send a 487 response, making x-lite cleanly terminate the call.
  • In the Eclipse console view, check the log :
*** Received CANCEL ***



Now, you're ready to start developping a real app !
Good luck and see you later.

Ben

26 commentaires:

  1. Hey Ben,

    Nice blog post ! Thx.

    Regarding the Context, if you use this that should work to recognize the sip servlet application so that it gets deployed

    <context docbase="SimpleServlet" path="/SimpleServlet" reloadable="true" source="org.eclipse.jst.j2ee.server:SimpleServlet" className="org.mobicents.servlet.sip.startup.SipStandardContext" configClass="org.mobicents.servlet.sip.startup.SipContextConfig">
    <Manager className="org.mobicents.servlet.sip.core.session.SipStandardManager"/>
    </Context>

    You may want to add those attributes to the Host xml tag as well :
    hostConfigClass="org.mobicents.servlet.sip.startup.SipHostConfig" configClass="org.mobicents.servlet.sip.startup.SipContextConfig"

    This tell Tomcat to use Mobicents deployment classes to override the standard Tomcat deployment classes so that sip.xml and sip servlets annotations can be recognized and that the application gets deployed as a sip servlets application

    Jean

    RépondreSupprimer
  2. Please don't use the bad style of printing stacktrace and ignore when you cannot handle an exception. Just throw a Runtime exception with the checked exception as source.

    RépondreSupprimer
  3. Thanks for your advise ! It means that you get interested by this article.

    By the way, of course, it is not a clean code. Its only goal is to show how to handle SIP messages with Mobicents, and debug it with Eclipse.

    RépondreSupprimer
  4. Hello, thanks for the nice tutorial. I followed this tutorial and everything are fine until I pushed the INVITE using XLite, the class cast exception error was occurred (the error is attached below). I tried to change the version of mobicents but it didnt work (I tried mss-1.0-apache-tomcat-6.0.14-0907231439 and mss-1.1-apache-tomcat-6.0.14-0912031229).

    Do you have any advice about this ? Thank you very much in advance.

    Kirati

    java.lang.ClassCastException: org.mobicents.servlet.sip.message.SipServletRequestImpl cannot be cast to javax.servlet.sip.SipServletRequest
    at javax.servlet.sip.SipServlet.service(SipServlet.java:325)
    at org.mobicents.servlet.sip.core.dispatchers.MessageDispatcher.callServlet(MessageDispatcher.java:230)
    at org.mobicents.servlet.sip.core.dispatchers.InitialRequestDispatcher$InitialDispatchTask.dispatch(InitialRequestDispatcher.java:686)
    at org.mobicents.servlet.sip.core.dispatchers.DispatchTask.dispatchAndHandleExceptions(DispatchTask.java:55)
    at org.mobicents.servlet.sip.core.dispatchers.DispatchTask.run(DispatchTask.java:50)
    at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(Unknown Source)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
    at java.lang.Thread.run(Unknown Source)

    RépondreSupprimer
  5. I tried with the jboss version and it's now working :) thanks !

    Kirati

    RépondreSupprimer
    Réponses
    1. please help me how to do
      i have tried as above shown but i cant run

      Supprimer
  6. This is a great tutorial; thanks for taking the time to put it together.

    One comment on the doCancel() method: according to JSR289 section 11.2.3, the container will respond with 200 to the CANCEL and 487 to the original INVITE; the application should not send a response in this case.

    RépondreSupprimer
  7. hello, i tried it with jboss contain 4.3.2 of mobicents. i doesnt work. i reveals errors and the server stops after 300sec (time i allowed to server to start).

    could you give me a hand for doing this.

    thanks in advance.

    nasser

    RépondreSupprimer
  8. Hi Benoit,
    I'd like to ask you a question please. When I add my JBoss server (Add n Remove) I can see it on the server pane but cannot see the server folder containing Server.xml file !! What do u suggest ? Am I missing something ? Therefore, I'm not able to modify the context in Server.xml !

    Thnx in advance.

    RépondreSupprimer
  9. I have same error as Kirati. And I try to use jboss, but it still have error:
    10:38:08,803 ERROR [SipApplicationDispatcherImpl] Unexpected exception while processing request INVITE sip:1234@mobicents.org SIP/2.0
    Via: SIP/2.0/UDP 157.159.22.48:5060;rport=5060;branch=z9hG4bK4381BB9C4C9F29CEBD0C52B0B034DDDF;received=127.0.0.1
    From: "mobicents" ;tag=601756035
    To:
    Contact:
    Call-ID: 45ABDE82-92FC-A88B-49B3-B858B932E1C3@192.168.8.67
    CSeq: 19821 INVITE
    Max-Forwards: 70
    Content-Type: application/sdp
    User-Agent: X-Lite release 1105d
    Content-Length: 316

    org.mobicents.servlet.sip.core.dispatchers.DispatcherException: Unexpected Exception while trying to forward statefully the following subsequent request INVITE sip:1234@mobicents.org SIP/2.0
    Via: SIP/2.0/UDP 157.159.22.48:5060;rport=5060;branch=z9hG4bK4381BB9C4C9F29CEBD0C52B0B034DDDF;received=127.0.0.1
    From: "mobicents" ;tag=601756035
    To:
    Contact:
    Call-ID: 45ABDE82-92FC-A88B-49B3-B858B932E1C3@192.168.8.67
    CSeq: 19821 INVITE
    Max-Forwards: 70
    Content-Type: application/sdp
    User-Agent: X-Lite release 1105d
    Content-Length: 316

    Thank you in advance for all your helps.

    RépondreSupprimer
  10. For the error

    java.lang.ClassCastException: org.mobicents.servlet.sip.message.SipServletRequestImpl cannot be cast to javax.servlet.sip.SipServletRequest


    Remove the sip-servlet-spec jar from WEB-INF/lib
    It is already provided by the container

    RépondreSupprimer
  11. please I need help .. I am really glad to see this tutorial but I have the error

    HTTP Status 500 -

    when I run the servlet in the Tomcat server


    Servlet.service() for servlet SimpleServlet threw exception
    java.lang.ClassCastException: org.apache.catalina.connector.RequestFacade cannot be cast to javax.servlet.sip.SipServletRequest

    RépondreSupprimer
  12. TQTuan, to solve your error try to replace mobicents.org domain in the Softphone (X-lite) with "localhost". I've seen that using mobicents.org as domain, the app tries to redirect the call to mobicents. Don't know if I've missed something, it is a bug or it is the supposed behaviour.

    RépondreSupprimer
  13. I followed the tutorial but I always have this Exception

    I need help it is critical for me

    java.lang.ClassCastException: org.apache.catalina.connector.RequestFacade cannot be cast to javax.servlet.sip.SipServletRequest

    RépondreSupprimer
  14. I noticed this message

    ***** the simple sip servlet has been started *********

    but I did not see

    *** Received INVITE ***

    or


    *** Received cancel ***


    I do not know where is the error !!!!

    RépondreSupprimer
  15. I follow the tutorial, also see the log entry "**** the simple sip servlet has been started ****".

    However, the application router seems can't correct route the INVITE request to the SimpleServlet since the "*** Received INVITE ***" statement cannot be found in the Tomcat console log.

    Also, I try the custom application router and hope to dig in to the router and see how it work but the Tomcat cannot load the router provider class. I have add the jar file under launch configuration, and also put it under the Servlet project WEB-INF/lib directory, but tomcat still can't locate the class.

    RépondreSupprimer
  16. Also, I've the domain set to "localhost" ... but found an exception on the console:

    org.mobicents.servlet.sip.core.dispatchers.DispatcherException: the Request-URI does not point to another domain, and there is no Route header,the container should not send the request as it will cause a loop. Instead, the container must reject the request with 404 Not Found final response with no Retry-After header. You may want to check your dar configuration file to see if the request can be handled or make sure you use the correct Application Router jar.

    RépondreSupprimer
    Réponses
    1. Even i am facing same problem... Any solution for this???

      Supprimer
  17. * Deploy your application : in the servers pane, right clic on your server, then deploy.

    * Now start the server. On the servers pane, right click on your server, then choose Deploy, and Start

    IN above steps i can see the deploy i mean will u see a deploy tab or there is any other way to do the deployment

    RépondreSupprimer
  18. Hi,thanks for the tutorial. I started the server in eclipse and after the call I did not see the log
    *** Received INVITE ***
    he did not call the "doInvite" method of my servlet.
    what can I do?
    I really need help :(.
    thanks

    RépondreSupprimer
  19. Ce commentaire a été supprimé par l'auteur.

    RépondreSupprimer
  20. a if your problem is not solved! erase your service method if you got one! that was my problem

    RépondreSupprimer
  21. can some help me? im tryin to make a server which receives a response/request from a client and create a response.request to forward to the terminating client.. thanks in advance

    RépondreSupprimer
  22. i cant deploy in jboss or tomcat please help me its showing there is no resources

    RépondreSupprimer
  23. i'm unable to see ***** the sip servlet has started ****

    RépondreSupprimer