Mobicents

You should ensure that a few requirements have been met before continuing with the install.

When you download the Mobicents JAIN SLEE Server binary distribution, you can also choose to verify the integrity of the zip file you download, which is both preferred and safer. If you are setting up Mobicents in a production environment (as opposed to, say, merely playing around with Mobicents' capabilities on your personal machine), we recommend verifying the integrity of the downloaded distribution. The first procedure following shows you how to simply download the Mobicents JAIN SLEE Server binary distribution, while the second procedure following details how to download and verify the installation zip file.

Once the requirements and prerequisites have been met and you have downloaded the binary distribution zip file, you are ready to install Mobicents. Follow the instructions below for your platform, whether Linux or Windows.

Configuring the Mobicents JAIN SLEE Server consists in setting the JBOSS_HOME environment variable.

Before running the Mobicents server you are installing, you should consider if you need to set the JBOSS_HOME environment variable. Setting it (or re-setting it to the new value) will always work. Whether or not you need to set JBOSS_HOME depends on the following factors:

The following instructions detail how to set JBOSS_HOME on both Linux and Windows.

Once installed, you can run the Mobicents JAIN SLEE Server by executing the one of the startup scripts in the <topmost_directory>/jboss-4.2.2.GA/bin directory (on Linux or Windows), or by double-clicking the run.bat executable batch file in that same directory (on Windows only). However, we suggest always starting the JAIN SLEE Server using the terminal or Command Prompt because you are then able to read—and act upon—any startup messages, and possibly debug any problems that might arise. In the Linux terminal or Command Prompt, you will be able to tell that the JAIN SLEE Server started successfully if the last line of output is similar to the following (ending with “Started in 25s:527ms”):

16:29:15,442 INFO  [ManagementConsole] Mobicents Management Console initialized
16:29:15,551 INFO  [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080
16:29:15,586 INFO  [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
16:29:15,622 INFO  [Server] JBoss (MX MicroKernel) [4.2.2.GA (build: SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 25s:527ms

Detailed instructions are given below, arranged by platform.

Just as there are multiple ways to run the JAIN SLEE Server, there are multiple ways to stop it. Detailed instructions for stopping the JAIN SLEE Server are given below, arranged by platform. Note that if you properly stop the server, you will see the following three lines as the last output in the Linux terminal or Command Prompt:

16:44:29,745 INFO  [Server] Shutdown complete
Shutdown complete
Halting VM

To uninstall the JAIN SLEE Server, simply delete the directory you decompressed the binary distribution archive into.

Currently, the JAIN SIP resource adapter can be configured in three different ways.

Configuring the SIP RA Via the Provisioning Mechanism

You can set provisioned properties in the resource-adaptor.xml file, which is located in resources/sipra/ra/xml/ [TBD: this directory does not exist in the binary installation: exactly which files should we be modifying?].

Configuring the SIP RA Via Passing Properties to an MBean

HttpSessionActivity represents the HttpSession created from the incoming javax.servlet.http.HttpServletRequest received by HttpServletRaServlet, which in turn passes it on to HttpServletResourceEntryPoint.

HttpServletResourceEntryPoint is the link between the servlet and HttpServletResourceAdaptor. HttpServletResourceAdaptor fires the appropriate event like GET, POST, PUT, DELETE, etc., depending on the method of HttpServletRequest, and the service interested in these events will receive it as initial event. The service will use the HttpServletRequestEvent passed as an argument to an on something event method to get an HttpServletResponse object. A service can add content to the response, modify headers etc. Calling the flushBuffer() function on an HttpServletResponse will flush the buffer and the response will be committed.

The service can explicitly end the HttpSessionActivity by calling the invalidate() function on HttpSession. Calling invalidate() will invoke the sessionDestroyed() method of HttpServletRaSessionListener by the web container. Within the sessionDestroyed() method, the resource adapter's endHttpSessionActivity() is called to end the activity. If HttpSession times out, then it is the responsibility of the container to invoke the sessionDestroyed() function and the above steps in order to end activity.

HttpServletResourceAdaptor uses the request.getPathInfo() function to form the web address used to fire the Event:

//PathInfo can be an empty string and the creation of Address will throw exception
//for empty String hence hardcoding prefix /mobicents
String pathInfo = "/mobicents" + request.getPathInfo();

Address address = new Address(AddressPlan.URI, pathInfo);
sleeEndpoint.fireEvent(ah, event, eventID, address);

SBBs which are interested in events emmitted by HttpServletResourceAdaptor should use

<initial-event-select variable="Address" />

for calculating the convergence name, this way we can make sure that URL's submitted to HttpServletResourceAdaptor are mapped to convergence names

For example:

A Service Building Block Example

An SBB can be inetersted in any of the HTTP Methods OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, and for each HttpMethod, the resource adapter fires a corresponding event.

The following code is an example of Service Building Block code:

public void onPost(HttpServletRequestEvent event, ActivityContextInterface aci) {
	try {

		HttpServletResponse response = event.getResponse();
		PrintWriter w = response.getWriter();
		w.print("onPost OK! Served by SBB = " + getSbbId());
		w.flush();
		response.flushBuffer();
		log
				.info("HttpServletRAExampleSbb: POST Request received and OK! response sent.");
	} catch (IOException e) {
		e.printStackTrace();
	}

}

public void onGet(HttpServletRequestEvent event,
		ActivityContextInterface aci) {
	.....
	.....

}

public void onHead(HttpServletRequestEvent event,
		ActivityContextInterface aci) {
	// The HEAD method is identical to GET except that the server MUST NOT
	// return a message-body in the response.
	log.info("HttpServletRAExampleSbb: HEAD Request received.");

}

public void onPut(HttpServletRequestEvent event,
		ActivityContextInterface aci) {
	...........

}

public void onDelete(HttpServletRequestEvent event,
		ActivityContextInterface aci) {
	   .............

}

public void onOptions(HttpServletRequestEvent event,
		ActivityContextInterface aci) {
		   .............
}

public void onTrace(HttpServletRequestEvent event,
		ActivityContextInterface aci) {
		   ..............
}

In order to deploy the HTTP Servlet resource adapter, execute 'ant build-and-deploy-ra' from mobicents/ra/http-servlet-ra folder. Make sure to set the MOBICENTS_HOME and JBOSS_HOME.

TBD: is this correct? Format and ensure the correctness of these last 2-3 paragraphs

To execute the test-case, follow the steps in mobicents/ra/http-servlet-ra/tests/build.xml

There is a working example httpservletra-example to demonstarte the usage of http-servlet-ra. Follow the link to download example https://mobicents-examples.dev.java.net/source/browse/mobicents-examples/httpservletra-example/ and read instructions README.txt to deploy the example

Note: Http Servlet RA is only for processing incoming HttpServletRequest and sending back the HttpServletResponse. If there is a need to create the Request from within the service make use of Http Client RA.

The Hypertext Transfer Protocol (HTTP) is probably the most significant protocol used on the Internet today. Web services, network-enabled appliances and the growth of network computing continue to expand the role of the HTTP protocol beyond user-driven web browsers, while increasing the number of applications that require HTTP support. Applications developed using the Service Logic Execution Environment fall into this category. The Jakarta Commons HttpClient component provides an efficient, up-to-date, and feature-rich package implementing the client side of the most recent HTTP standards and recommendations. The HTTP Client resource adapter provides the client-side HTTP standard within the SLEE execution environment using the popular Apache Commons HTTP Client library.

A Service Building Block (SBB) can use the HTTP Client resource adapter to make a request and get the response either synchronously or asynchronously.

Configuring

Configuring your system for the JDK consists in two tasks: setting the JAVA_HOME environment variable, and ensuring that the system is using the proper JDK (or JRE) using the alternatives command. Setting JAVA_HOME usually overrides the values for java, javac and java_sdk_1.5.0 in alternatives, but we will set them all just to be safe and consistent.

Testing

Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in your PATH, run the java -version command in the terminal from your home directory:

~]$ java -version
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03)
Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)

Uninstalling

There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily using alternatives, and/or by setting JAVA_HOME.

Uninstalling the JDK on Linux

On RPM-based systems, you can uninstall the JDK using the yum remove <jdk_rpm_name> command.

Uninstalling the JDK on Windows

On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.

You can also run Mobicents SIP Servlets on top of the Apache Tomcat Servlet Container. This section provides information on the requirements and prerequisites for running MSS for Tomcat, as well as instructions on how to download, install, configure, run, use, stop, test and uninstall it.

Keep in mind that not all capabilities provided by running Mobicents SIP Servlets Server on top of the JBoss Application Server are available with MSS for Tomcat. In particular, MSS for Tomcat lacks support for both clustering and failover; MSS for Tomcat nodes can utilize the SIP load balancer, however.

Concurrency control and congestion control refer to settings you can tune that define the way in which messages are processed under heavy load. Needless to say, such configurable settings become highly-important in production environments. Tuning the concurrency control mode changes the way in which the SIP Servlets Server processes messages. Tuning the congestion control parameter means increasing or decreasing the point at which the server begins rejecting new requests. Both of these parameters can be set in one of four different ways: through the SIP Servlets Management Console; by editing the server's server.xml configuration file; from the dispatcher MBean; or from the Embedded Jopr integrated management platform.

Concurrency Control

Although the JSR 289 expert group could not agree on a concurrency control mechanism for JSR 289, leaving the details up to individual implementors, we believe that concurrency control as implemented in the Mobicents SIP Servlets Servers provides a highly-useful feature necessary in production environments. Concurrency control is implemented in both MSS for JBoss and MSS for Tomcat as a configurable mode which defines the way in which the SIP Servlets Server processes messages. There are a total of three different modes to choose from, based upon the individual requirements of your setup:

Congestion Control

Congestion control currently refers to tuning the size of the SIP message queue, though further tunable settings are planned.

All SIP messages which cannot be processed immediately are put into a queue, and therein wait for either a free thread or for the lock on their session to be released. The exact size of this SIP message queue is a tunable parameter, and it currently defaults to 1500. If the SIP message queue becomes full, the container immediately begins rejecting any new SIP requests with a 503 (Service Unavailable) response until the queue is once again diminished. Note that in this situation, only new SIP requests are rejected; SIP responses which arrive in the milieu of a full queue are appropriately stored and are processed eventually.

Configuring the Concurrency and Congestion Control Settings

The concurrency and congestion control settings can be configured through the SIP Servlets Management Console, by editing the server's server.xml configuration file, from the dispatcher MBean, or from the Embedded Jopr integrated management platform. Instructions for each method are given below.

The Mobicents SIP load balancer is used to balance the load of SIP service requests and responses between nodes in a SIP Servlets Server cluster. Both MSS for JBoss and MSS for Tomcat servers can be used in conjunction with the SIP load balancer to increase the performance and availability of SIP services and applications. In terms of functionality, the Mobicents SIP load balancer is a simple proxy server that intelligently forwards SIP session requests and responses between User Agents (UAs) on a Wide Area Network (WAN), and SIP Servlets Server nodes, which are almost always located on a Local Area Network (LAN). All SIP requests and responses pass through the SIP load balancer.

SIP Load Balancing Basics

All User Agents send SIP messages, such as INVITE, MESSAGE and so on, to the same SIP URI—the IP address and port number of the SIP load balancer on the WAN—and the load balancer then parses, alters, and forwards those messages to an available and healthy node in the cluster. If the message was sent as a part of an existing SIP session, it will be forwarded to the cluster node which processed that User Agent's original transaction request. The SIP Servlets Server which receives the message then acts upon it and sends its response back to the SIP load balancer which, again, parses, alters and forwards the message back to the original User Agent. Needless to say, this entire proxying and provisioning process is carried out unbeknownst to the User Agent, which need only concern itself with the SIP service or application it is using.

By using the load balancer, SIP traffic is balanced across a pool of healthy and available SIP Servlets Servers, increasing the overall throughput of the SIP service or application running on either individual nodes of the cluster, or, if using MSS for JBoss's </distributed> capabilities, across the entire cluster.

The SIP load balancer is also able to fail over requests mid-call from unhealthy or unavailable nodes to healthy and available ones, thus increasing the reliability of the SIP service or application. In this way, the load balancer increases throughput and reliability by dynamically provisioning SIP service requests and resonses across responsive nodes in a cluster, thus enabling SIP applications to meet the real-time demand for SIP services.

The Mobicents SIP load balancer implementation, its installation, configuration and an example application, are all detailed below.

Implementation of the Mobicents SIP Servlets Load Balancer

Mobicents supports the clustering of SIP Servlets-enabled JBoss Application Servers for performance, reliability and failover purposes. Note that only MSS for JBoss Servers can be used as cluster nodes; MSS for Tomcat Containers are not supported.

Just as with a Mobicents JAIN SLEE cluster, a Mobicents SIP Servlets Server for JBoss cluster does not employ any standby nodes. Typically, therefore, proxies and/or registrars will need to share the user location table by using a database cluster.

The Mobicents SIP load balancer, which is a SIP Call-ID-aware load balancer, is used as the man-in-the-middle. Its job is to forward stateful transaction requests to cluster nodes based on its provisioning algorithm.

This choice of implementation has many benefits. Among them are:

modify the JBOSS_HOME variable in prepare-jboss-server-for-clustering-failover.sh script to map your own run sh prepare-jboss-server-for-clustering-failover.sh uas (or proxy, b2bua or uac if you want to test something else) from this directory run sh start-lb.sh from this directory run sh start-jboss-server-port-1.sh from this directory When server is fully started run sh start-jboss-server-port-2.sh from this directory When server is fully started run sh clustering-failover-test.sh uas (or proxy, b2bua, b2bua-remote-send-bye, uac if you want to test something else) from this directory When the ACK has been received kill the first node, the second node still handles the BYE and sends the OK to it :-) Beware in case you test uac, because the shootist application that is used is compiled 2 times. First time with a parameter saying that the application sends the INVITE when it starts (this one is deployed on jboss server port 1) and the second time with the parameter saying that the application doesn't send the INVITE when it starts (this one is deployed on jboss server port 2) The second time is used only for failover when the first node will crash to get the subsequent requests. So you need to first start the jboss server port 2, then start the jboss server port 1 but before it is fully started (When you see SIP Load Balancer Found ! printed) you need to run sh clustering-failover-test.sh uac so that it listen for the incoming INVITE from the application

We provide an example to run the Mobicents Sip Servelts cluster (comprised of 2 nodes), the load balancer and client application on different machines. Please checkout our clustering and mid-call failover example and follow the README-network.txt instructions. Cluster on the same machine We provide an example to run the Mobicents Sip Servelts cluster (comprised of 2 nodes), the load balancer and client application on the same machine for ease of testing purposes. Please checkout our clustering and mid-call failover example and follow the README.txt instructions. Here is the modifications needed to run two application servers running at the same time on the same machine. (Those steps are done in the above example as part of the prepare-jboss-server-for-clustering-failover.sh script) As we need two application servers running at the same time, we must avoid any conflict. For instance we will need JBoss Tomcat to bind its socket on two different ports otherwise a network conflict will occur. We will leverage the service binding manager this chapter of the JBoss AS documentation. The first step is to copy the all configuration of JBoss into two separate configurations that we name ports-01 and ports-02 : cd JBOSS_HOME/server cp -r all ports-01 cp -r all ports-02 Edit the file JBOSS_HOME/server/ports-01/conf/jboss-service.xml and uncomment the service binding manager : <mbean code="org.jboss.services.binding.ServiceBindingManager" name="jboss.system:service=ServiceBindingManager" > <attribute name="ServerName">ports-01</attribute > <attribute name="StoreURL">${jboss.home.url}/docs/examples/binding-manager/sample-bindings.xml</attribute > <attribute name="StoreFactoryClassName">org.jboss.services.binding.XMLServicesStoreFactory</attribute > </mbean > Edit the file JBOSS_HOME/server/ports-02/conf/jboss-service.xml , uncomment the service binding manager and change the value ports-01 into ports-02: <mbean code="org.jboss.services.binding.ServiceBindingManager" name="jboss.system:service=ServiceBindingManager" > <attribute name="ServerName">node-02</attribute > <attribute name="StoreURL">${jboss.home.url}/docs/examples/binding-manager/sample-bindings.xml</attribute > <attribute name="StoreFactoryClassName">org.jboss.services.binding.XMLServicesStoreFactory</attribute > </mbean > Limitations Mobicents Sip Servlets doesn't currently support mid call failover for converged applications only pure sip applications (Uas, Uac, B2BUA, Proxy).

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 is 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:

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: