Chapter 3. Services for Mobicents SIP Servlets

3.1. The Location Service

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.

The Location Service Mappings Cannot Currently Be Configured

The Location Service currently performs a lookup on a hard-coded list of addresses. This model is evolving towards the eventual use of a database.

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:

A user—let us call her Alice—makes a call to sip:receiver@sip-servlets.com. The INVITE is received by the servlet container, which then starts the Location Service.
The Location Service, using non-SIP means, determines that the callee (i.e. the receiver) is registered at two locations, identified by the two SIP URIs, sip:receiver@127.0.0.1:5090 and sip:receiver@127.0.0.1:6090.
The Location Service proxies to those two destinations in parallel, without record-routing, and without making use of supervised mode.
One of the destinations returns a 200 OK status code; the second proxy is then cancelled.
The 200 OK is forwarded to Alice, and call setup is completed as usual.

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

sip:receiver@sip-servlets.com

sip:receiver@127.0.0.1:5090
sip:receiver@127.0.0.1:6090

3.1.1. The Location Service: Installing, Configuring and Running

Pre-Install Requirements and Prerequisites

Software Prerequisites

Either an MSS for JBoss or an MSS for Tomcat Installation: The Location Service requires either an MSS for JBoss or an MSS for Tomcat binary installation.
You can find detailed instructions on installing MSS for JBoss here: Section 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.
You can find detailed instructions on installing MSS for Tomcat here: Section 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”.

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.1/location-service-1.1.war.

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

Installing

Both the location-service-1.1.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:

MSS for JBoss: Place location-service-1.1.war into the JBOSS_HOME/server/default/deploy/ directory, and locationservice-dar.properties into the JBOSS_HOME/server/default/conf/dars/ directory.
MSS for Tomcat: Place location-service-1.1.war into the CATALINA_HOME/webapps/ directory, and locationservice-dar.properties into the CATALINA_HOME/conf/dars/ directory.

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:

MSS for JBoss

Open the JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml configuration file and find the Service element. Add an attribute to it called darConfigurationFileLocation, and set it to conf/dars/locationservice-dar.properties:

<Service
	name="jboss.web"
	className="org.mobicents.servlet.sip.startup.SipStandardService"
	sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl"
	darConfigurationFileLocation="conf/dars/locationservice-dar.properties">

Example 3.1. Editing MSS for JBoss's server.xml for the Location Service

Make sure that the configuration file only contains one darConfigurationFileLocation attribute: your new one.

MSS for Tomcat

Open the CATALINA_HOME/conf/server.xml configuration file and find the Service element. Add an attribute to it called darConfigurationFileLocation, and set it to conf/dars/locationservice-dar.properties:

<Service
	name="Sip-Servlets"
	className="org.mobicents.servlet.sip.startup.SipStandardService"
	sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl"
	darConfigurationFileLocation="conf/dars/locationservice-dar.properties">

Example 3.2. Editing MSS for Tomcat's server.xml for the Location Service

Make sure that the configuration file only contains one darConfigurationFileLocation attribute: your new one.

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.

Procedure 3.1.

Start two SIP softphones. The first phone should be set up as sip:receiver@sip-servlets.com at IP address 127.0.0.1 on port 5090. The second phone can be set up in any way you like. Note that the SIP phones do not have to be registered.
Using the second phone, make a call to sip:receiver@sip-servlets.com. If the Location Service has been set up correctly and is running, the first phone—as the receiver or callee—should now be ringing.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to bssswjicar-binary-SIP_Servlets_Server_with_JBoss-Stopping.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to bbssswticar-binary-SIP_Servlets_Server_with_Tomcat-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.