oddthesis Telco support

<p>Support for converged web/telco multi language application is now supported directly as part of the jboss rails deployer.</p>
<h2>Prerequisites</h2>
<p>Download the <a title="Mobicents SIP Servlets" href="http://hudson.jboss.org/hudson/view/Mobicents/job/MobicentsSipServletsRelease/">latest snapshot version of Mobicents Sip Servlets</a> on JBoss 5.</p>
<p>Follow the steps to get <a title="Your first app on JBoss-Rails" href="/theses/jboss-rails/projects/jboss-rails/pages/your-first-app-on-jboss-rails">your first JBoss-Rails application running</a>.</p>
<h2>How it works ?</h2>
<p>To be able to make phone calls from your JRuby-Rails application here is what you need to do:<br /><br />In your JRuby-Rails application, edit your controller and add this piece of code to be able to make phone calls:</p>
<pre># get the sip factory from the servlet context<br />@sip_factory = $servlet_context.get_attribute('javax.servlet.sip.SipFactory')<br />puts @sip_factory<br /><br /># create a new sip application session<br />@app_session = request.env['servlet_request'].get_session().get_application_session();<br /><br /># create a new sip servlet request to start a call to the sip phone with from header equals to "sip:my_jruby_app_rocks@mobicents.org" and the to header equals to the sip_uri from the complaint variable<br />@sip_request = @sip_factory.create_request(@app_session, 'INVITE', 'sip:my_jruby_app_rocks@mobicents.org', @complaint.sip_uri);<br /><br /># actually sending the request out to the sip phone<br />@sip_request.send();</pre>
<p>This piece of code will create a SIP Request and send it out. But when the user will answer OK, you need to have some code to handle the response and this can be done in 2 ways :</p>
<ul>
<li>through a Ruby SIP Handler (JBoss powered ! :-))</li>
<li>through Java Sip Servlets 1.1 compliant code</li>
</ul>
<h3>SIP Ruby Handler<br /></h3>
<p>You need to create a sip directory under app directory into your ruby application and add a sip_handler.rb (the file could really be anything, just make sure the classname and the filename are similar) file containing this piece of code :</p>
<pre># Note that the class extend a JBoss provided sip controller called JBoss::Sip::SipBaseHandler<br /># that mimic the Java Sip Servlet class the ruby way<br />class SipHandler &lt; JBoss::Sip::SipBaseHandler<br />  # Handle INVITE request to setup a call by answering 200 OK<br />  def do_invite(request)  <br />    request.create_response(200).send<br />  end<br />  # Handle BYE request to tear down a call by answering 200 OK<br />  def do_bye(request)  <br />    request.create_response(200).send<br />  end<br />  # Handle REGISTER request so that a SIP Phone can register with the application by answering 200 OK<br />  def do_register(request)  <br />    request.create_response(200).send<br />  end<br />  # Handle a successful response to an application initiated INVITE to set up a call (when a new complaint is filed throught the web part) by send an acknowledgment<br />  def do_success_response(response)<br />    response.create_ack.send<br />  end<br />end</pre>
<p>You're all set build you app with <strong>mvn clean install</strong> and deploy it to JBoss with <strong>rake jboss:rails:deploy</strong> as mentioned in the <a title="Your first app on JBoss-Rails" href="/theses/jboss-rails/projects/jboss-rails/pages/your-first-app-on-jboss-rails">"Your first app on JBoss-Rails" tutorial</a>.</p>
<p>When you have deployed the application, edit the<strong> $JBOSS_HOME/server/default/deploy/twiggl.yml</strong> and add the sip section (<em>appname</em> and <em>rubycontroller</em>) as mentioned in the page <a title="*-rails.yml" href="/theses/jboss-rails/projects/jboss-rails/pages/x-rails-yml">*-rails.yml</a>.</p>
<p>&nbsp;</p>
<h3>Java Sip Servlets 1.1 compliant code</h3>
<p>through Java Sip Servlets 1.1 compliant code only(support for handling this in ruby will be offered later). So you need to create a multi-language java app by <a title="Using maven" href="/theses/jboss-rails/projects/jboss-rails/pages/using-maven">following the instructions for using Maven</a>.</p>
<p>So create a new package in your src/main/java directory with the Sip Servlets code. Here is an example of the code to handle the call setup and teardown:</p>
<pre>@javax.servlet.sip.annotation.SipServlet<br />public class JRubySipServlet extends SipServlet {<br />&nbsp;&nbsp;&nbsp; private static Log logger = LogFactory.getLog(JRubySipServlet.class);<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <br />&nbsp;&nbsp;&nbsp; @Override<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; protected void doSuccessResponse(SipServletResponse resp)<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; throws ServletException, IOException {<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if (resp.getStatus() == SipServletResponse.SC_OK) {<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; resp.createAck().send();&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }<br />&nbsp;&nbsp;&nbsp; }<br />&nbsp;&nbsp;&nbsp; <br />&nbsp;&nbsp;&nbsp; @Override<br />&nbsp;&nbsp;&nbsp; protected void doBye(SipServletRequest request) throws ServletException,<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; IOException {<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; SipServletResponse ok = request.createResponse(SipServletResponse.SC_OK);<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ok.send();<br />&nbsp;&nbsp;&nbsp; }<br />}<br /><br /></pre>
<p>As you notice, since there is no <strong>sip.xml</strong> (deployment descriptor for Sip Servlets application) in this kind of converged application, you need to use Sip Servlets annotations in your application.</p>
<p>You'll need to use annotations to describe your servlets and so on. So that your application can be recognized as converged sip servlets application, you also need to put a package-info.java into the package with the following code (change the package name and application name to yours) :</p>
<pre>@javax.servlet.sip.annotation.SipApplication(name="TwigglApplication",sessionTimeout=5)<br />package org.mobicents.servlet.sip.demo.jruby;<br /></pre>
<p>Don't forget to add the following dependencies to your pom.xml</p>
<pre>&lt;dependencies&gt;&nbsp;&nbsp;&nbsp; <br />  &lt;dependency&gt;<br />&nbsp;   &lt;groupId&gt;org.mobicents.servlet.sip&lt;/groupId&gt;<br />&nbsp;&nbsp;&nbsp; &lt;artifactId&gt;sip-servlets-spec&lt;/artifactId&gt;<br />&nbsp;&nbsp;&nbsp; &lt;version&gt;1.1.9-SNAPSHOT&lt;/version&gt;<br />&nbsp;&nbsp;&nbsp; &lt;scope&gt;provided&lt;/scope&gt;<br />&nbsp; &lt;/dependency&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <br />&nbsp; &lt;dependency&gt;<br />&nbsp;   &lt;groupId&gt;org.apache.tomcat&lt;/groupId&gt;<br />&nbsp;&nbsp;&nbsp; &lt;artifactId&gt;annotations-api&lt;/artifactId&gt;<br />&nbsp;&nbsp;&nbsp; &lt;version&gt;6.0.14&lt;/version&gt;<br />&nbsp;&nbsp;&nbsp; &lt;scope&gt;provided&lt;/scope&gt;<br />&nbsp; &lt;/dependency&gt;<br />&lt;/dependencies&gt;<br /><br /></pre>
<p>and the JBoss repositories :</p>
<pre>&lt;repositories&gt;<br />  &lt;repository&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <br />&nbsp;&nbsp;&nbsp; &lt;id&gt;JbossRepository&lt;/id&gt;<br />&nbsp;&nbsp;&nbsp; &lt;name&gt;Jboss Repository&lt;/name&gt;<br />&nbsp;&nbsp;&nbsp; &lt;url&gt;http://repository.jboss.org/maven2&lt;/url&gt;<br />&nbsp;&nbsp;&nbsp; &lt;snapshots&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;enabled&gt;true&lt;/enabled&gt;<br />&nbsp;&nbsp;&nbsp; &lt;/snapshots&gt;<br />&nbsp;&nbsp;&nbsp; &lt;releases&gt;<br />&nbsp;&nbsp;&nbsp;   &lt;enabled&gt;true&lt;/enabled&gt;<br />&nbsp;&nbsp;&nbsp; &lt;/releases&gt;<br />&nbsp; &lt;/repository&gt;<br />&nbsp; &lt;repository&gt;<br />&nbsp;   &lt;id&gt;jboss-snapshots&lt;/id&gt;<br />&nbsp;&nbsp;&nbsp; &lt;name&gt;JBoss Snapshot Repository&lt;/name&gt;<br />&nbsp;&nbsp;&nbsp; &lt;url&gt;http://snapshots.jboss.org/maven2&lt;/url&gt;<br />&nbsp;&nbsp;&nbsp; &lt;releases&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;enabled&gt;false&lt;/enabled&gt;<br />&nbsp;&nbsp;&nbsp; &lt;/releases&gt;<br />&nbsp;&nbsp;&nbsp; &lt;snapshots&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;enabled&gt;true&lt;/enabled&gt;<br />&nbsp;&nbsp;&nbsp; &lt;/snapshots&gt;<br />&nbsp; &lt;/repository&gt;<br />&lt;/repositories&gt;<br /></pre>
<p>You're all set build you app with <strong>mvn clean install</strong> and deploy it to JBoss with <strong>rake jboss:rails:deploy</strong> as mentioned in the <a title="Your first app on JBoss-Rails" href="/theses/jboss-rails/projects/jboss-rails/pages/your-first-app-on-jboss-rails">"Your first app on JBoss-Rails" tutorial</a>.</p>
<p>When you have deployed the application, edit the<strong> $JBOSS_HOME/server/default/deploy/twiggl.yml</strong> and add the sip section (<em>appname</em> and <em>mainservlet</em>) as mentioned in the page <a title="*-rails.yml" href="/theses/jboss-rails/projects/jboss-rails/pages/x-rails-yml">*-rails.yml</a>.</p>