JBoss.orgCommunity Documentation

Chapter 4. SIP Servlet Example Applications

4.1. Operating the Example Applications
4.1.1. The Location Service
4.1.2. The Diameter Event-Changing Service
4.1.3. The Call-Blocking Service
4.1.4. The Call-Forwarding Service
4.1.5. The Call-Controller Service
4.1.6. Media IPBX

The SIP Servlet server has a selection of examples which demonstrate particular capabilities of the server. Table 4.1, “Available Examples” lists the available examples, their location, and a brief description about the functionality each example demonstrates. The examples can also provide a useful starting point for developing SIP Applications, therefore it is encouraged to experiment and adapt the base examples. Each example is available in both binary and source formats.

Table 4.1. Available Examples

ExampleDescription
Section 4.1.3, “The Call-Blocking Service” Demonstrates how to block calls by specifying that the INVITE SIP Extension checks the From address to see if it is specified in the block list. If the blocked SIP address matches, the Call Blocking application send a FORBIDDEN response.
Section 4.1.4, “The Call-Forwarding Service” Demonstrates how to forward calls by specifying that the INVITE SIP Extension checks the To address to see if it is specified in the forward list. If the SIP address matches, the application acts as a back-to-back user agent (B2BUA).
Section 4.1.5, “The Call-Controller Service” Call Blocking and Call Forwarding are merged to create a new service.
Speed Dial Demonstrates how to implement speed dialing for SIP addresses. The demonstration uses a static list of speed dial numbers. The numbers are translated into a complete address based on prior configuration. The SIP addresses are proxied without record-routing, or supervised mode.
Section 4.1.1, “The Location Service” Demonstrates a location service that performs a lookup based on the request URI, into a hard-coded list of addresses. The request is proxied to the set of destination addresses associated with that URI.
Composed Speed Dial and Location Speed Dial and Location are merged to create a new service. Speed Dial proxies the speed dial number to a SIP address, then Location Service proxies the call to the actual location of the call recipient.
Click to Call Demonstrates how SIP Servlets can be used along with HTTP servlets as a converged application to place calls from a web portal. The example is a modified version of the click to dial example from the Sailfin project, but has been reworked to comply with JSR 289.
Chat Server Demonstrates MESSAGE SIP Extension support. This example is based on the chatroom server demonstration from the BEA dev2dev project, and has been modified to meet JSR 289 requirements.
Media Demonstrates how the media playback SIP Servlet can build a media file customized with the name of the user, based on the information in the FROM header. This example is only compatible with JBoss AS. The solution is know to work with Ekiga and linphone SIP soft-phones.
Shopping Demonstrates integration with Seam and Java Enterprise Edition (JEE), and Media integration with text to speech (TTS) and dual-tone multi-frequency (DTMF) tones. The demonstration builds on the Converged Demo example, and adds support for the SIP Servlets v1.1 specification.
JSLEE/SIP Servlets Interoperability Demonstrates how the Mobicents platform components can work in concert with each other to provide a integrated solution. All major components of the platform are used in this example, which was created to demonstrate to JavaOne 2008 delegates a possible use case scenario for the platform.
Facebook Click to Call Demonstrates how SIP Servlets and HTTP Servlets can be used can be used to create a Facebook plug-in that allows user to call POTS phones through a SIP-PSTN gateway provider. This demonstration is only available from the source repository; no binary is available.
Section 4.1.2, “The Diameter Event-Changing Service” Demonstrates how the Diameter Event Charging, and the Location service, can be used to perform fixed-rated charging of calls (event charging). When a call is initiated, a debit of ten euros is applied to the A Party account. If the call is rejected by the B Party, or A Party hangs up before B Party can answer the call, the ten euro charge is credited to the A Party account.
Diameter Sh OpenIMS Integration Demonstrates the integration between Mobicents and OpenIMS, using the Diameter Sh interface to receive profile updates and SIP.
Conference Demonstrates the capabilities of the Media Server, such as endpoint composition and conferencing, as well as proving that SIP Servlets are capable of working seamlessly with any third-party web framework, without repackaging or modifying the deployment descriptors. The demonstration uses Google's GWT Ajax framework with server-push updates to provide a desktop-like user interface experience.
Media IPBX Demonstrates how a SIP PBX solution can be deployed using the Mobicents platform. For more information, refer to Section 4.1.6, “Media IPBX”.
JRuby on Rails SIP Servlets Demonstrates how JRuby on Rails can be used by the Mobicents platform to provide a multi-language application that can initiate phone calls to customers after they log a complaint through a web portal.
Pure JRuby on Rails Telco Builds on the JRuby on Rails SIP Servlets demonstration, but adds the ability to call the application rather that initially interact through the web portal. The application has the ability to set up and tear down the call.

The Mobicents Location Service contains a list of mappings of request URIs to destination addresses. When the Location Service receives a request, it performs a lookup on that mapping and proxies the request simultaneously to the destination address (or addresses) associated with that URI.

Regardless of whether you are using the JBoss Application Server or the Tomcat Servlet Container as the Servlets Server, the application, container and Location Service perform the following steps:

Here is the current list of hard-coded contacts and their location URIs:

 

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The Location Service is comprised of two archive files, a Web Archive (WAR) and a Default Application Router (DAR) configuration file, which you need to add to your installed SIP Servlets Server. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C.

Download the Location Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/location-service/1.4/location-service-1.4.war.

Download the Location Service's DAR file from here: http://www.mobicents.org/locationservice-dar.properties.

Installing

Both the location-service-1.4.war WAR file and the locationservice-dar.properties DAR file that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Location Service with MSS for JBoss or with MSS for Tomcat:

Configuring

The darConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/locationservice-dar.properties. The instructions are given below by SIP Servlets Server type:

Running

Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in a server.xml file), then you should go ahead and run SIP Servlets Server.

To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.

To learn how to run the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.7, “Running”.

Testing

The following procedure shows how to test the Location Service.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.10, “Stopping”.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.8, “Stopping”.

Uninstalling

Unless disk space is at a premium, there is usually no need to uninstall the Location Service. However, if you will not be using it again, you may want to unset or reset the darConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.

You may also wish to delete the WAR and DAR files for the Location Service, which you installed in Installing.

The Diameter Event-Changing Service is based on the Location Service, which performs call-charging at a fixed rate. Upon the initiation of a call, a debit of €10.00 occurs. In the cases of a call being rejected or the caller disconnecting (hanging up) before an answer is received, the caller's account is refunded.

Note that an MSS for JBoss installation is required to run this example; it will not work with MSS for Tomcat.

Provided here is a step-by-step description of the procedure as performed by the application and container:

Preparing your MSS for JBoss server to run the Diameter Event-Changing example requires downloading a WAR archive, a DAR archive, the Ericsson Charging Emulator, setting an attribute in JBoss's server.xml configuration file, and then running JBoss AS. Detailed instructions follow.

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The following procedure describes how to download the required files.

Installing

The following procedure describes how to install the downloaded files.

Configuring

To configure the server for the Event-Changing example, simply open the server.xml configuration file in your server's $JBOSS_HOME/server/<profile>/deploy/jboss-web.deployer/ directory, and edit the value of the darConfigurationFileLocation attribute of the Service element so that it is conf/dars/mobicents-dar.properties.


Running

The following procedure describes how to run the Diameter Event-Changing Service.

Procedure 4.3. Diameter Event-Changing Service

  1. First, you should run your MSS for JBoss server. For instructions on doing so, refer to Section 2.1.7, “Running”.

  2. Then, run the Ericsson Charging Emulator. Open a terminal, change the working directory to the location of the unzipped Charging Emulator files (in ChargingSDK-1_0_D31E or a similarly-named directory), and run it with the java -jar PPSDiamEmul.jar command:

    ~]$ java -jar PPSDiamEmul.jar

Using

Using the Event-Changing service means, firstly, inserting some parameters into the Charging Emulator, and then, by using two SIP (soft)phones, calling one with the other. The following sequential instructions show you how.

Procedure 4.4. Using the Diameter Event-Changing Service

  1. Configure the Ericsson SDK Charging Emulator

    Once you have started the Charging Emulator, you should configure it exactly as portrayed in Figure 4.1, “Configuring the Charging Emulator”.


    1. Set the Peer Id to: aaa://127.0.0.1:21812

    2. Set the Realm to: mobicents.org

    3. Set the Host IP to: 127.0.0.1

  2. Start two SIP (soft)phones. You should set the first phone up with the following parameters: sip:receiver@sip-servlets on IP address 127.0.0.1 on port 5090. The other phone can be set up any way you like.

  3. Before making a call, open the ConfigOptions dialog window, as shown in the image.

    In the Account Configuration window of the Charging Emulator, you can see the user's balances. Select a user to watch the balance. You can also stretch the window lengthwise to view the user's transaction history.

  4. Time to call! From the second, “any-configuration” phone, make a call to sip:receiver@sip-servlets.com. Upon doing so, the other phone should ring or signal that it is being contacted .

  5. You should be able to see a request—immediately following the invite and before the other party (i.e. you) accepts or rejects the call—sent to the Charging Emulator. That is when the debit of the user's account is made. In the case that the call is rejected, or the caller gives up, a second, new Diameter request is sent to refund the initial amount charged by the call. On the other hand, if the call is accepted, nothing else related to Diameter happens, and no second request takes place.

    Please not that this is not the truly-correct way to do charging, as Diameter provides other means, such as unit reservation. However, for the purpose of a demonstration it is sufficient to show the debit and follow-up credit working. Also, this is a fixed-price call, regardless of the duration. Charging can, of course, be configured so that it is time-based.

The Mobicents Call-Blocking Service, upon receiving an INVITE request, checks to see whether the sender's address is a blocked contact. If so, it returns a FORBIDDEN reply; otherwise, call setup proceeds as normal.

Here is the current hard-coded list of blocked contacts:

 

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The Call-Blocking Service is comprised of two archive files, a Web Archive (WAR) and a Default Application Router (DAR) configuration file, which you need to add to your installed SIP Servlets Server. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C.

Download the Call-Blocking Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-blocking/1.4/call-blocking-1.4.war.

Download the Call-Blocking Service's DAR file from here: http://www.mobicents.org/call-blocking-servlet-dar.properties.

Installing

Both the call-blocking-1.4.war WAR file and the call-blocking-servlet-dar.properties DAR file that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Call-Blocking Service with MSS for JBoss or with MSS for Tomcat:

Configuring

The darConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/call-blocking-servlet-dar.properties. The instructions for doing so are given below by SIP Servlets Server type:

Running

Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in a server.xml file), then you should go ahead and run SIP Servlets Server.

To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.

To learn how to run the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.7, “Running”.

Testing

The following procedure shows how to test the Call-Blocking Service.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.10, “Stopping”.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.8, “Stopping”.

Uninstalling

Unless disk space is at a premium, there is usually no need to uninstall the Call-Blocking Service. However, if you will not be using it again, you may want to unset or reset the darConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.

You may also wish to delete the WAR and DAR files for the Call-Blocking Service, which you installed in Installing.

The Mobicents Call-Forwarding Service, upon receiving an INVITE request, checks to see whether the sender's address is among those in a list of addresses which need to be forwarded. If so, then the Call-Forwarding Service acts as a Back-to-Back User Agent (B2BUA), and creates a new call leg to the destination. When the response is received from the new call leg, it sends it an acknowledgment (ACK) and then responds to the original caller. If, on the other hand, the server does not receive an ACK, then it tears down the new call leg with a BYE. Once the BYE is received, then it answers OK directly and sends the BYE to the new call leg.

Here is the current hard-coded list of contacts to forward:

 

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The Call-Forwarding Service is comprised of two archive files, a Web Archive (WAR) and a Data Archive (DAR), which you need to add to your installed SIP Servlets Server. For more information about WAR and DAR files, refer to the JBoss Application Server Administration and Development Guide.

Download the Call-Forwarding Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-forwarding/1.4/call-forwarding-1.4.war.

Download the Call-Forwarding Service's DAR file from here: http://www.mobicents.org/call-forwarding-servlet-dar.properties.

Installing

Both the call-forwarding-1.4.war WAR file and the call-forwarding-servlet-dar.properties DAR file that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Call-Forwarding Service with MSS for JBoss or with MSS for Tomcat:

Configuring

The darConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/call-forwarding-b2bua-servlet-dar.properties. The instructions for doing so are given below by SIP Servlets Server type:

Running

Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in a server.xml file), then you should go ahead and run SIP Servlets Server.

To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.

To learn how to run the SIP Servlets-enabled Tomcat Container, refer to bbssswticar-binary-SIP_Servlets_Server_with_Tomcat-Running.

Testing

The following procedure shows how to test the Call-Forwarding Service.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.10, “Stopping”.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.8, “Stopping”.

Uninstalling

Unless disk space is at a premium, there is usually no need to uninstall the Call-Forwarding Service. However, if you will not be using it again, you may want to unset or reset the darConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.

You may also wish to delete the WAR and DAR files for the Call-Forwarding Service, which you installed in Installing.

The Call-Controller service is a composition of two other services: Call-Blocking and Call-Forwarding. Essentially, it performs the services of both call-forwarding and call-blocking.

The Call-Controller service requires the two WAR files for the Call-Blocking and Call-Forwarding services to be placed in the correct directory inside your Mobicents SIP Servlets Server binary installation. However, the Call-Controller service does not require their corresponding DAR files: you need only to download and install a DAR file customized for the Call-Controller service. The instructions below show you how to do precisely this; there is no need, therefore, to first install either the Call-Blocking or the Call-Forwarding services, though it is helpful to at least be familiar with them.

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The Call-Controller Service is comprised of two WAR files, one for the Call-Forwarding service and one for Call-Blocking, and a customized Call-Controller DAR file. You do not need to install the DAR files for the Call-Forwarding or the Call-Blocking services. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C

Download the Call-Blocking Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-blocking/1.4/call-blocking-1.4.war.

Download the Call-Forwarding Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-forwarding/1.4/call-forwarding-1.4.war.

Download the Call-Controller Service's DAR file from here: http://www.mobicents.org/call-controller-servlet-dar.properties.

Installing

The call-blocking-1.4.war, call-forwarding-1.4.war and call-controller-servlet-dar.properties archive files that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Call-Controller Service with MSS for JBoss or with MSS for Tomcat:

Configuring

The darConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/call-controller-servlet-dar.properties. Instructions for doing so are given below by SIP Servlets Server type:

Running

Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in a server.xml file), then you should go ahead and run SIP Servlets Server.

To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.

To learn how to run the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.7, “Running”.

Testing

Two use-cases can be distinguished for the Call-Controller service: one in which a call is blocked, and another in which a call is forwarded. Therefore, we have two cases for which we can test the Call-Controller.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.10, “Stopping”.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.8, “Stopping”.

Uninstalling

Unless disk space is at a premium, there is usually no need to uninstall the Call-Controller Service. However, if you will not be using it again, you may want to unset or reset the darConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.

You may also wish to delete the WAR and DAR files for the Call-Controller Service, which you installed in Installing.

Note

Chapter 4, SIP Servlet Example Applications provides more information about other service examples available.

The Media IPBX provides an extensible and customizable SIP PBX solution, based on the Seam Telco Framework (STF). While the PBX is currently provided as a capability demonstration, the ultimate goal is to transition Media IPBX into a fully-fledged SIP PBX solution.

Media IPBX terminates all calls to Mobicents Media Server conference endpoints, which provides flexibility in manipulating established calls including server-side conferencing and ring-back tones. The PBX can also be implemented as a Session Border Controller.

Media IPBX provides the following major features:

Many of the features in Media IPBX are presented to the user as hints on the GUI portal pages. It is recommended to install Media IPBX and experiment with the demonstration to gain an understanding of how the solution works.

For information about installing and running Media IPBX, including binary and source code locations, visit the Media IPBX homepage.