JBoss.org Community Documentation
Copyright ©
Abstract
Mobicents is a highly scalable event-driven application server with a robust component model. Mobicents is the first and only Open Source Platform certified for JSLEE 1.0 compliance. It complements J2EE to enable the convergence of voice, video and data in next-generation intelligent applications. Web and SIP can be combined together to achieve more sophisticated and natural user experience.
Certain words in this manual are represented in different fonts, styles, and weights. This highlighting indicates that the word is part of a specific category. The categories include the following:
Courier font
Courier font represents commands, file names and paths, and prompts .
When shown as below, it indicates computer output:
Desktop about.html logs paulwesterberg.png Mail backupfiles mail reports
bold Courier font
Bold Courier font represents text that you are to type, such as:
service jonas start
If you have to run a command as root, the root prompt (#) precedes the command:
#
gconftool-2
italic Courier font
Italic Courier font represents a variable, such as an installation directory:
install_dir
/bin/
Bold font represents application programs and text found on a graphical interface .
When shown like this: OK , it indicates a button on a graphical application interface.
Additionally, the manual uses different strategies to draw your attention to pieces of information. In order of how critical the information is to you, these items are marked as follows:
A note is typically information that you need to understand the behavior of the system.
A tip is typically an alternative way of performing a task.
Important information is necessary, but possibly unexpected, such as a configuration change that will not persist after a reboot.
A caution indicates an act that would violate your support agreement, such as recompiling the kernel.
A warning indicates potential data loss, as may happen when tuning hardware for maximum performance.
The Mobicents Communication Platform is the best architecture for creating, deploying and managing services and applications integrating voice, video and data across a range of IP and communications networks. The Mobicents Communication Platform drives convergence by leveraging the following four core capabilities.
Core Capabilities of the Mobicents Converged Application Server
Mobicents JAIN SLEE provides a highly-scalable event-driven application server with a robust component model and a fault-tolerant execution environment. Mobicents JAIN SLEE is the first and only Open Source Platform certified for JSLEE 1.0 compliance. It complements J2EE to enable the convergence of voice, video and data in next-generation intelligent applications. Web and SIP can be combined together to achieve more sophisticated and natural user experience.
The Mobicents Media Server is an open sourced server based on the Java Media Framework implementation, and aimed to:
Aims of the Mobicents Media Server
Deliver a competitive, complete, best-of-breed media gateway functionality of the highest quality.
Meet the demands of converged wireless, wireline, cable broadband access and fixed-mobile converged VoIP networks from a single media gateway platform.
Increase flexibility with a media gateway that supports a wide variety of call control protocols, and which scales down to meet the demands of enterprises and small carrier providers.
React quickly to dynamic market requirements.
The first free and open source implementation of an XML Document Management (XDM) server, as defined in the Open Mobile Alliance (OMA) specifications. This functional element of next-generation IP communication networks is responsible for handling the management of users' XML documents stored on the network side, such as presence authorization rules, contact and group lists (also known as resource lists), static presence information, and much more.
The JBoss Microcontainer is the state-of-the-art hosting environment in which higher-level containers reside. It provides service registration, configuration and dependency management, classloading isolation control, package versioning, deployment, thread pooling and many other fundamental building blocks necessary for highly-scalable, fault-tolerant middleware servers.
In the scope of telecommunications' Next Generation Intelligent Networks (NGINs), Mobicents fits in as a high-performance core engine for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes).
Mobicents enables the composition of Service Building Blocks (SBBs) such as call control, billing, user-provisioning, administration, and presence-sensing features. The JAIN SLEE [1] specification allows popular protocol stacks such as SIP to be plugged in as resource adapters. The SLEE Service Building Blocks have many similarities to Enterprise Java Beans (EJBs), and naturally accommodate integration with enterprise applications, the Web, Customer Relationship Management (CRM) and Service-Oriented Architecture (SOA) end points.
Out-of-the-box monitoring and management of Mobicents components is achieved via SLEE standard-based Java Management Extensions (JMXes) and Simple Network Management Profile (SNMP) interfaces.
Beyond telecommunications, Mobicents is applicable to a wider variety of problems demanding high-volume, low-latency signaling. Examples include financial trading, online gaming, RFID sensor network integration, and distributed control.
The Mobicents Converged Application Server has a wide variety of use cases, including all of the following domains:
Voice-over-Internet Protocol (VoIP) services are some of the primary use cases for Mobicents. Examples of VoIP services include call routing, forwarding, termination, voice mailbox, conferencing and user provisioning.
SLEE is a great platform for Massively Multi-Player (MMP games. The following are some of the principle requirements for MMP servers, provided by the leader of Java.net Games community:
Worst-case latencies from end-to-end in the back-end system, including all database operations, of no more than 100 ms.
A programming model that allows the game programmer to program simple persistent objects, with no more work than any other standard Java object, and have them execute on data events coming into the system. These objects must be "real objects" in the simulation sense of the term.
A programming model that is optimistically parallel while appearing to the programmer as a single-threaded event-driven model. Each event has to be ACID-transactional (Atomicity, Consistency, Isolation, Durability), and atomic unto itself. The programmer cannot be required to be aware in any way of multiple threads, database access, or locking. It must be inherently and transparently race-condition-proof and deadlock-proof.
It must scale to massive numbers of simultaneous users (5-to-6 figures) online simultaneously accessing the same database of objects.
It needs to provide failover, fault-tolerance and efficient load-balancing. The last is critical. Game applications are cost-sensitive. Without the ability to load-balance the potentially heavy loads of multiple apps over banks of low-cost computers used to maximal efficiency, the economic model falls apart.
If you are familiar with SLEE, then you have already noticed that these requirements closely track the fundamental SLEE design principles.
Here are some pointers to books, blogs and papers on the subject of Massive Multi-Player games:
Financial trading is a well-understood problem domain demanding highly-available, fast-response technology to serve billions of trading calls per day. Each trading call is a concise message identifying the trader, ticker and price. Day trading applications fit nicely on top of event-driven containers.
We live in an unsafe world. Project P25 is focused on public safety communications digital radio interoperability. It is spurred on by growing concern which has driven many countries' governmentsincluding the US Federal Governmentto reorganize in order to create focused positions to address homeland security. The National Institute of Standards and Technology (NIST) is building a test system for Radio-Frequency subsystem interoperability Standard, which is based on these three protocols: the Session Initiation Protocol (SIP), the Service Discovery Protocol (SDP), and the Real-time Transport Protocol (RTP). The reference implementation and test system will be built as SLEE services.
Gartner predicts that sensor technologies will be part of our everyday life by the year 2015. Sensors will be everywhere: as RFID tags on consumer products, devices monitoring tire pressure, location-tracking tags carried by workers in sensitive or hazardous environments, etc. In addition, all enterprise activities will be monitored using enterprise tools connected to the network; by 2010 these, as embedded Internet devices, will represent 95% of all Internet-connected systems.
Pervasive sensor technologies will transform the objective of IT from providing support for fundamentally manual processes to automating the execution of tasks in response to a continuously-changing environment monitored by sensors. This requires a new kind of architecture capable of delivering extreme transaction processing.
[1] JAIN SLEE stands for Java API for Intelligent Network Service Logic and Execution Environment architecture. JSLEE (Java Service Logic Execution Environment) is a short synonym for JAIN SLEE.
The Mobicents Converged Application Server can be installed by downloading the ready-to-go binary distribution, or, alterately, the source code can be obtained using the Subversion version control system (VCS) and then Mobicents can be built from source. Installing the binary distribution is recommended for most users, and obtaining and building the source code distribution is recommended for those who want access to the latest revisions and capabilities.
Mobicents is written in Java; therefore, before running any Mobicents server, you must have a working Java Runtime Environment (JRE) or Java Development Kit (JDK) installed on your system. In addition, the JRE or JDK you are using to run Mobicents must be version 5 or higher[2].
Although you can run the Mobicents servers using the Java Runtime Environment, we assume that most Mobicents users are developers interested in developing Java-based, Mobicents-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.
Briefly stated: if you are running on a 64-Bit Linux or Windows platform, you should consider installing and running the 64-bit JDK over the 32-bit one. Here are some heuristics for determining whether you would rather run the 64-bit Java Virtual Machine (JVM) over its 32-bit cousin for your application:
Wider datapath: the pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications when using a 64-bit JVM.
64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.
Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.
Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.
Note that the following instructions detail how to download and install the 32-bit JDK, although the steps are nearly identical for installing the 64-bit version.
You can download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click on the
Download
link next to "JDK 5.0 Update <x>" (where <x> is the latest minor version release number). On the next page, select your language and platform (both architecture—whether 32- or 64-bit—and operating system), read and agree to the Java Development Kit 5.0 License Agreement, and proceed to the download page.
The Sun website will present two download alternatives to you: one is an RPM inside a self-extracting file (for example, jdk-1_5_0_16-linux-i586-rpm.bin), and the other is merely a self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin). If you are installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, we suggest that you download the self-extracting file containing the RPM package, which will set up and use the SysV service scripts in addition to installing the JDK. We also suggest installing the self-extracting RPM file if you will be running Mobicents in a production environment.
Procedure 2.1. Installing the JDK on Linux
Regardless of which file you downloaded, you can install it on Linux by moving into the directory you downloaded the installer to, making sure the file is executable, and then running it:
~]$ cd downloads downloads]$ chmod +x “jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin” downloads]$ ./“jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin”
If you download the non-RPM self-extracting file (and installed it), and you are running on an RPM-based system, you can still set up the SysV service scripts by downloading and installing one of the -compat packages from the JPackage project. Remember to download the -compat package which corresponds correctly to the minor release number of the JDK you installed. The compat packages are available from ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-free/.
You do not need to install a -compat package in addition to the JDK if you installed the self-extracting RPM file! The -compat package merely performs the same SysV service script set up that the RPM version of the JDK installer does.
Procedure 2.2. Installing the JDK on Windows
Using Explorer, simply double-click the downloaded self-extracting installer and follow the instructions to install the JDK.
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.
JAVA_HOME Environment Variable
After installing the JDK, you must ensure that the JAVA_HOME environment variable exists and points to the location of your JDK installation.
JAVA_HOME Environment Variable on LinuxYou can determine whether JAVA_HOME is set on your system by echoing it on the command line:
~]$ echo $JAVA_HOME
If JAVA_HOME is not set already, then you must set its value to the location of the JDK installation on your system. You can do this by adding two lines to your personal ~/.bashrc configuration file. Open ~/.bashrc (or create it if it doesn't exist) and add a line similar to the following one anywhere inside the file:
export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"
You should also set this environment variable for any other users who will be running Mobicents (any environment variables exported from ~/.bashrc files are local to that user).
JAVA_HOME Environment Variable on Windowsjava, javac and java_sdk_1.5.0 Using alternatives
On systems with the alternatives command, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as which java and javac executables should be run when called.
As the root user
, call /usr/sbin/alternatives with the --config java option to select between JDKs and JREs installed on your system:
root@localhost ~]$ /usr/sbin/alternatives --config java There are 3 programs which provide 'java'. Selection Command ----------------------------------------------- 1 /usr/lib/jvm/jre-1.5.0-gcj/bin/java 2 /usr/lib/jvm/jre-1.6.0-sun/bin/java *+ 3 /usr/lib/jvm/jre-1.5.0-sun/bin/java Enter to keep the current selection[+], or type selection number:
In our case, we want to use the Sun JDK, version 5, that we downloaded and installed, to run the java executable. In the alternatives information printout above, a “plus” (“
+
”) next to a number indicates the one currently being used. As per alternatives' instructions, pressing
Enter
will simply keep the current JVM, or you can enter the number corresponding to the JVM you would prefer to use.
Repeat the procedure above for the javac command and the java_sdk_1.5.0 environment variable,
as the root user
:
~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
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 command in the terminal from your home directory:-version
~]$ 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)
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.
On RPM-based systems, you can uninstall the JDK using the yum command.remove <jdk_rpm_name>
On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.
The Mobicents JAIN SLEE Server binary distribution is comprised of—and comes bundled with—all of the following components:
the JBoss Application Server, version 4.2.2 GA
the Mobicents JAIN SLEE Server
the Mobicents Media Server
the Mobicents SIP Servlets Server
the Mobicents SIP Presence Service
a large number of resource adapters
multiple demonstration examples
You should ensure that a few requirements have been met before continuing with the install.
Hardware Requirements
You must have sufficient disk space in order to install the Mobicents binary release. Once unzipped, version 1.2.0 of the Mobicents binary release requires at least 100 MB of free disk space. Keep in mind that disk space requirements may change from release to release.
The Mobicents JAIN SLEE Server is 100% Java, along with all of its bundled servers, resource adapters and demonstration examples. Therefore, the Mobicents JAIN SLEE Server will run on the same hardware that the JBoss Application Server runs on.
Software Prerequisites
A working installation of the Java Development Kit (JDK) version 5 or higher is required in order to run the Mobicents JAIN SLEE Server. Note that the JBoss Application Server is a runtime dependency of Mobicents and, as mentioned, comes bundled with the binary distribution.
For instructions on how to install the JDK, refer to Chapter 2, Installation of the Mobicents Converged Application Server .
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.
Procedure 2.3. Downloading Without Verifying
You can download the latest version of the Mobicents JAIN SLEE Server from http://www.mobicents.org/jainsleedownload.html. The top row of the table hold the latest version. Click the Download link on the right to start the download from Sourceforge.net.
Procedure 2.4. Downloading and Verifying
The preferred—and safer—way to obtain the JAIN SLEE Server binary distribution is to download the binary zip file as well as its corresponding sha1 file, and use the sha1 file to verify the integrity of the zip file. To do this, first go to http://www.mobicents.org/jainsleedownload.html and, at the top of the page, click on the here in “Browse all files here
” link. The most recent releases are located near the top. Download both the zip file and its attendant sha1 file. For example, if you wanted to download the Mobicents JAIN SLEE Server version 1.20 Release Candidate 1, you would download both of the following files:
mobicents-all-1.2.0.CR1-jboss-4.2.2.GA.zip
mobicents-all-1.2.0.CR1-jboss-4.2.2.GA.zip.sha1.asc
Next, verify the integrity of the zip file with the sha1 file, which contains a checksum which is used to do precisely this, and which can alert you if the file has been changed since it was uploaded, or if it was corrupted upon download.
On a Linux system you can use the sha1sum command to verify the integrity of the binary distribution zip file.
On a Windows system you will need to download a sha1sum-generating program such as the sha1sum.exe program. This program will generate a checksum that you can compare with the sum in the sha1 file.
If the two checksums are identical, then the downloaded binary distribution zip file's integrity is assured, and it is safe to proceed with installation.
If the two checksums are not identical, it means that the downloaded zip file was corrupted upon download, or has been changed since it was last uploaded to the server. In this case, you should first re-download the two files (the zip file and the sha1 file) and compare once more. If this second comparison fails, it could indicate a problem with the install file, and you should contact the Mobicents team by email to alert them to the conflict.
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.
For clarity, the command line instructions presented in this chapter use specific version numbers and directory names. Remember to replace them with version numbers and file names relevant to those you are actually working with.
Procedure 2.5. Installing the Mobicents Binary Distribution on Linux
First, move to the directory to which you downloaded the binary distribution zip file. For this example, we'll assume you're currently in your home directory, and that you downloaded the zip file to a subdirectory of it, referred to as <downloads>.
~]# cd <downloads>
In <downloads>, create a subdirectory to hold the unzipped Mobicents files. It is good practice to include the version number in this directory name; if you do so, remember to correctly match it with the version of the Mobicents binary distribution you downloaded.
<downloads>]$ mkdir "mobicents-<version>"
Move the downloaded zip file into the directory you just created:
<downloads>]$ mv "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip" "mobicents-<version>"
Move into that directory:
<downloads>]$ cd "mobicents-<version>"
Finally, use Java's jar command to extract the contents of the zip file into the current directory, thus completing the install:-xvf
mobicents-<version>]$ jar -xvf "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
Alternatively, if Linux's unzip utility is present on your system or is installable, you can use it in lieu of Java's jar command:-xvf
mobicents-<version>]$ unzip "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
You can also use unzip's -d
option to extract the zip file's contents to a location other than the current directory.<unzip_to_location>
To free disk space, you may want to delete the zip file once you've extracted its contents:
mobicents-<version>]$ rm "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
Procedure 2.6. Installing the Mobicents Binary Distribution on Windows
For this example, we'll assume that you downloaded the binary distribution zip file to the My Downloads folder. First, using Windows Explorer, create a subfolder in My Downloads to extract the zip file's contents into. When you name this folder, it is good practice to include the version number; if you do so, remember to correctly match it with the version of the Mobicents binary distribution you downloaded. In these instructions, we will refer to this folder as mobicents-<version>.
Double-click the downloaded zip file, selecting as the destination folder the one you just created to hold the zip file's contents.
Alternatively, it is also possible to use Java's jar command to extract the binary distribution files from the zip archive. To use this method instead, first move the downloaded zip file from -xvf
My Downloads to the folder that you just created to hold the Mobicents files.
Then, open the Windows Command Prompt and navigate to the folder holding the archive using the cd command:
If you are using Windows Vista®, you can open the Command Prompt directly from Explorer. Hold down the Shift key and right-click on either a folder, the desktop, or inside a folder. This will cause an Open Command Window Here context menu item to appear, which can be used to open the Command Prompt with the current working directory set to either the folder you opened, or opened it from.
C:\Users\Me>cd "My Downloads\mobicents-<version>"
Finally, use the jar command to extract the archive contents into the current folder.-xvf
C:\Users\Me\My Downloads\mobicents-<version>>jar -xvf "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
At this point, you may want to move the folder holding the Mobicents binary files (in this example, the folder named mobicents-<version>) to another location. This step is not strictly necessary, but it is probably a good idea to move the Mobicents folder from My Downloads to a user-defined location for storing runnable programs. Any location will suffice, however.
You may also want to delete the zip file after extracting its contents in order to free disk space:
C:\Users\Me\My Downloads\mobicents-<version>delete "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
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:
If you are installing a
binary
Mobicents server and JBOSS_HOME is not set on your system, then you
do not need
to set it, but doing so will do no harm.
If you are installing a binary Mobicents server and JBOSS_HOME is (already) set on your system, then you need to make sure it points to the location of the new Mobicents server.
If you are installing a Mobicents server from source which uses the JBoss Application Server, then you
must
set JBOSS_HOME.
The following instructions detail how to set JBOSS_HOME on both Linux and Windows.
Procedure 2.7. Setting the JBOSS_HOME Environment Variable on Linux
The JBOSS_HOME environment variable must point to the location of your JBoss installation. Any Mobicents server which runs on top of the JBoss Application Server has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, a bin directory. JBOSS_HOME must be set to the topmost directory of your Mobicents server installation.
Setting this variable in your personal ~/.bashrc file has the advantage that it will always be set (for you, as a user) each time you log in or reboot the system. To do so, open ~/.bashrc in a text editor (or create the file if it doesn't already exist) and insert the following line anywhere in the file, taking care to substitute <mobicents_server> for the topmost directory of the Mobicents server you installed:
export JBOSS_HOME="/home/<username>/<path>/<to>/<mobicents_server>"
Save and close .bashrc.
You can—and should—source your .bashrc file to make your change take effect (so that JBOSS_HOME is set) for the current session:
~]$ source ~/.bashrc
Finally, make sure that JBOSS_HOME has been set correctly (that it leads to the right directory), and has taken effect in the current session.
The following command will show the path to the directory pointed to by JBOSS_HOME:
~]$ echo $JBOSS_HOME
To be absolutely sure, change your directory to the one pointed to by JBOSS_HOME:
~]$ cd $JBOSS_HOME && pwd
Procedure 2.8. Setting the JBOSS_HOME Environment Variable on Windows
The JBOSS_HOME environment variable must point to the location of your JBoss installation. Any Mobicents server which runs on top of the JBoss Application Server has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, a bin directory. JBOSS_HOME must be set to the topmost directory of your Mobicents server installation.
If you are planning on running the JBoss Application Server as the Administrator, then you should, of course, set the JBOSS_HOME environment variable
as the administrator
, and if you planning to run Tomcat as a normal user, then set JBOSS_HOME as a user environment variable.
For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
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.
Procedure 2.9. Running the JAIN SLEE Server on Linux
Change your working directory to the JAIN SLEE Server's topmost directory (the one which you extracted the zip file's contents to):
downloads]$ cd "mobicents-<version>"
(Optional) Ensure that the jboss-4.2.2.GA/bin/run.sh start script is executable:
mobicents-<version>]$ chmod +x jboss-4.2.2.GA/bin/run.sh
Finally, execute the run.sh Bourne shell script:
mobicents-<version>]$ ./jboss-4.2.2.GA/bin/run.sh
Instead of executing the Bourne shell script to start the server, you may alternatively run the run.jar executable Java archive in the jboss-4.2.2.GA/bin directory:
mobicents-<version>]$ java -jar jboss-4.2.2.GA/bin/run.jar
Procedure 2.10. Running the JAIN SLEE Server on Windows
There are several different ways to start the JAIN SLEE Server on Windows. All of the following methods accomplish the same task.
Using Windows Explorer, change your folder to the one in which you unzipped the downloaded zip file, and then to the jboss-4.2.2.GA\bin subfolder.
Although not the preferred way (see below), it is possible to start the JAIN SLEE Server by double-clicking on the run.bat executable batch file.
As mentioned above, the best way to start the JAIN SLEE Server is by using the Command Prompt. Doing it this way will allow you to view all of the server startup details, which will enable you to easily determine whether any problems were encountered during the startup process. You can open the Command Prompt directly from the <topmost_directory>\jboss-4.2.2.GA\bin folder in Windows Explorer (see Opening the Command Prompt from Windows Explorer for details), or you can open the Command Prompt via the
Start
menu and navigate to the correct folder:
C:\Users\Me\My Downloads> cd "mobicents<version>"
Start the JAIN SLEE Server by running the executable run.bat batch file:
C:\Users\Me\My Downloads\mobicents<version>>jboss-4.2.2.GA\bin\run.bat
It is also possible to start the JAIN SLEE Server by running the run.jar executable Java archive:
C:\Users\Me\My Downloads\mobicents<version>>java -jar jboss-4.2.2.GA\bin\run.jar
The JAIN SLEE Server can be observed and controlled using the Mobicents Management Console, which is started along with the server. For information on configuring the JAIN SLEE Server with the Management Console, refer to Chapter 3, Working with the Mobicents Management Console .
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
Procedure 2.11. Stopping the JAIN SLEE Server on Linux by Issuing a Control Code
Assuming that you started the JAIN SLEE Server as a foreground process in the terminal, the easiest way to stop it is by pressing the Ctrl + c key combination in the same terminal in which you started it.
Procedure 2.12. Stopping the JAIN SLEE Server on Linux by Executing shutdown.sh or shutdown.jar
Another way to shut down the JAIN SLEE Server is by executing the shutdown.sh Bourne shell script in the <topmost_directory>/jboss-4.2.2.GA/bin directory. To do so, first change your working directory to the JAIN SLEE Server's topmost directory (the one to which you extracted the downloaded zip file's contents):
downloads]$ cd "mobicents-<version>"
(Optional) Ensure that the jboss-4.2.2.GA/bin/shutdown.sh start script is executable:
mobicents-<version>]$ chmod +x jboss-4.2.2.GA/bin/shutdown.sh
Finally, run the shutdown.sh executable Bourne shell script, and remember to add the -S option (which is the short option for --shutdown) as a command line argument:
mobicents-<version>]$ ./jboss-4.2.2.GA/bin/shutdown.sh -S
Instead of executing the Bourne shell script to stop the server, you may alternatively run the shutdown.jar executable Java archive to do so (and remembering, again, to add the -S command line argument):
mobicents-<version>]$ java -jar jboss-4.2.2.GA/bin/shutdown.jar -S
Procedure 2.13. Stopping the JAIN SLEE Server on Windows
Stopping the JAIN SLEE Server on Windows consists in executing either the shutdown.bat or the shutdown.jar executable file in the jboss-4.2.2.GA\bin subfolder of the JAIN SLEE Server binary distribution. Make sure to add the -S option (which is the short option for --shutdown) as a command line argument.
C:\Users\Me\My Downloads\mobicents-<version>>jboss-4.2.2.GA\bin\shutdown.bat -S
Alternatively, you can execute the shutdown.jar Java archive by running the java command, and remembering to add the -jar
-S option as a command line argument:
C:\Users\Me\My Downloads\mobicents-<version>>java -jar jboss-4.2.2.GA\bin\shutdown.jar -S
[2] At this point in time, it is possible to run most Mobicents servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the Mobicents XML Document Management Server does not. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the Mobicents XML Document Management Server with Java 6.
Once Mobicents is running, you can access the management console by pointing your browser to
http://localhost:8080/management-console/
. If you are working with a remote machine, replace
localhost
with the name of the remote machine's host, and
8080
with the correct port.
The management console screen has the following components:
The Main Menu, on the left.
The Current View, on the right.
The Log Console, on the bottom.
New views my be selected by clicking on the Main Menu items. The Log Console displays important and relevant notifications when operations are executed, such as error and status messages.
The initial management console view, which can also be accessed by clicking on SLEE at the top of the Main Menu, displays a status message indicating whether Mobicents is currently running or not, and provides controls to start, stop, and shut down the Mobicents Converged Application Server.
Deployable Units
This view can be selected by clicking on Deployable Units from the Main Menu, and shows a list of all deployable units that can be deployed with the Mobicents Converged Application Server.
A tab bar at the top of the view allows one to browse, search for, and install deployable units.
Components
The next view on the Main Menu is the Components view, which displays a list of component types, such as services, SBBs, resource adapters, etc., and their current count. Clicking on a component type will cause the management console to show a list of components for that type. From there, you can click on the different components to see their details.
Services
The Services view shows the list of available services, their state, whether ACTIVE or INACTIVE, and all currently possible actions for that resource adapter, such as activate, deactivate or remove.
The tab bar at the top of the Services view also allows you to control the usage parameters of services.
Resource Adapters
Choosing Resources from the Main Menu will put the currently-deployed resource adapters in view. There, you can see their name, type, vendor and version. Clicking on one of the resource adapters will provide further information such as the name of the deployable unit, its state, whether ACTIVE or INACTIVE, and the currenty possible actions for specific services, such as activating, deactivating, or removing them.
Activity Contexts
The Activity Contexts view can be displayed by clicking on Activities from the Main Menu, and shows the current activity contexts. The TTL field shows how much time the activity can remain idle before being marked for garbage collection.
Resource adapters are JAIN SLEE components that can be deployed (i.e. “loaded” or “installed”) into the Mobicents Converged Application Server, and undeployed (“uninstalled”) from it. At the file level, resource adapters consist of specially-named files called deployable unit files. Two of these deployable unit files must be loaded/installed before the Mobicents Converged Application Server will deploy the resource adapter. The next few sections will teach you how to locate where resource adapters and their files live, and how to deploy them and undeploy them through several different, though equivalent ways: via the command line; by copying the correct files to a special directory, or removing them from it; or with the Mobicents Management Console.
Which of these various ways of accomplishing the same task is easier depends on you. If you are comfortable with the command line, or like to script behavior, then deploying via the command line will probably be the preferred way for you. If you would prefer to simply copy or delete some files with the file manager, you can do it that way. And for those who prefer graphical user interfaces (GUIs), the Management Console provides an interface to the Mobicents Converged Application Server, and can easily be used to accomplish such tasks both locally and remotely. Note that if you are running Mobicents on the Windows platform, then you will want to deploy resource adapters by either copying files or using the Management Console. However, no matter which method you eventually choose, it will be necessary to read the following explanatory paragraphs, on where to find the directories corresponding to the resource adapters you want to install, and on how to recognize deployable unit files, and on the correct order in which to install the deployable unit files, before reading any or all of the method sections.
The files belonging to resource adapters, and which you will need to access in order to deploy and undeploy them, are located in
. It is trivial to figure out which directory in <topmost_mobicents_directory>
/resourcesresources corresponds to the resource adapter that you wish to deploy or undeploy. For example, the sipra directory holds the files necessary for running the SIP resource adapter, and the xmppra directory holds the XMPP and Google Talk resource adapter.
Deployable unit files are JAR (Java ARchive) files. There are two deployable unit files in each resource adapter's directory. The following two patterns describe the file names:
Deployable Unit File Name Conventions
<resource_adapter_abbreviation>
-ra-DU.jar
...where
ra
stands for “resource adapter”, and
DU
stands for "Deployable Unit (file). For example, if we want to deploy the SIP resource adapter, and we are located in
, then this deployable unit file will be named <topmost_mobicents_directory>
/resources/siprasip-ra-DU.jar.
<resource_adapter_abbreviation>
-ratype-DU.jar
...where
ratype
stands intuitively for “resource adapter type”, and
DU
again for “Deployable Unit (file)”. The file name for the “ratype” deployable unit file for the SIP resource adapter is therefore sip-ratype-DU.jar.
Deployable unit files must be installed in a certain order, starting with the
ratype
deployable unit file, whose file name has the form:
.<resource_adapter_abbreviation>
-ratype-DU.jar
The second (and last) deployable unit file you must install is the
ra
file:
.<resource_adapter_abbreviation>
-ra-DU.jar
For example, if you wanted to deploy the SIP resource adapter, then you would want to first install the deployable unit file named
, followed by the <resource_adapter_abbreviation>
-ratype-DU.jar
file. <resource_adapter_abbreviation>
-ra-DU.jar
The introductory section titled Section 4.1.2.1, “Before You Begin: Resource Adapters and Deployable Unit Files” should be read before proceeding to one of the following sections.
Section 4.1.2.2.1, “Deploying Resource Adapters Via the Command Line”
Section 4.1.2.2.2, “Deploying Resource Adapters By Copying Deployable Unit Files”
Section 4.1.2.2.3, “Deploying Resource Adapters With the Management Console”
Resource adapters can be deployed by simply issuing an ant task command from the topmost Mobicents directory. Make sure that the Mobicents Converged Application Server has been started, and then change to the topmost directory:
cd <topmost_mobicents_directory>
Run the ant build-and-deploy script, remembering to replace
with the correct directory name (refer to Where to Find Resource Adapters in the Mobicents Installation if you are unsure):<resource_adapter>
tools/ant/bin/ant -f resources/<resource_adapter>/build.xml ra-deploy
For example, the directory name in
corresponding to the JAIN SIP resource adapter is (currently) named <topmost_mobicents_directory>
/resourcessipra ("SIP Resource Adapter"). To deploy the SIP resource adapter, therefore, you would issue the following command:
tools/ant/bin/ant -f resources/sipra/build.xml ra-deploy
If the resource adapter builds successfully, then a message similar to the following will be written to standard output:
ra-activate: ra-deploy: BUILD SUCCESSFUL Total time: 5 seconds
To undeploy a resource adapter via the command line, refer to Section 4.1.2.3.1, “Undeploying Resource Adapters Via the Command Line”.
It is essential to have read the previous sections on locating resource adapter directories, recognizing deployable unit files, and determining the correct order for installing the files, before continuing. See Section 4.1.2.1, “Before You Begin: Resource Adapters and Deployable Unit Files”.
You can deploy resource adapters by simply copying deployable unit files to a special directory with your file manager, or by doing the same via the command line. These instructions assume that you are using the file manager. You can also copy the two necessary files simultaneously, or one-after-the-other in the correct order, which is the way we will do it.
Make sure that you copy the deployable unit files, instead of moving them. If you accidentally move them, then make sure you copy them back to the correct resource adapter directory where they came from. If you accidentally move them and then delete them, you will probably have to reinstall Mobicents, so be careful to copy instead of move!
Open your file manager and move to the directory corresponding to the resource adapter you want to deploy. Find the
file and copy it.<resource_adapter_abbreviation>
-ratype-DU.jar
Copying the first deployable unit file, the ratype file, in order to deploy the SIP resource adatper.
Figure 4.1. Locating and Copying the First Deployable Unit File
Copying the first deployable unit file, the ratype file, in order to deploy the SIP resource adatper.
Where you will paste it to depends on whether you installed the Mobicents binary release, or built Mobicents from source. If you installed the binary version, then the correct directory to copy the files into is
(remembering that the bundled JBoss installation that comes with the binary Mobicents release is located in <topmost_mobicents_directory>
/server/server/default/deploy
; you are actually copying the file into JBoss's <topmost_mobicents_directory>
/server/server/defaultdeploy directory). If, on the other hand, you installed Mobicents and JBoss separately and set the JBOSS_HOME environment variable, then the correct directory to copy the file to is
.$JBOSS_HOME/deploy
After copying the ratype deployable unit file, Mobicents will send a message like the following to standard output, indicating that the file was successfully installed.
19:59:03,651 INFO [RaTypeDeployer] Added RA Type with id ResourceAdaptorTypeID[JAIN SIP#javax.sip#1.2] 19:59:03,683 INFO [STDOUT] 19:59:03,682 INFO [DeploymentMBeanImpl] Deployable unit with URL file:/home/silas/Desktop/temp/apps/mobicents/mobicents-all-1_2_0_BETA2/server/server/default/deploy/sip-ratype-DU.jar deployed as DeployableUnitID[0]
After successfully copying the
file, proceed to copy the <resource_adapter_abbreviation>
-ratype-DU.jar
file to the same directory. Copying the
ra
file (after the
ratype
file, of course) will lead to successful installation of the resource adapter, and the Mobicents Converged Application Server will output information similar to the following to standard output:<resource_adapter_abbreviation>
-ra-DU.jar
19:59:59,940 INFO [STDOUT] 19:59:59,940 INFO [ResourceManagementMBeanImpl] Activated RA Entity SipRA 20:00:00,191 INFO [STDOUT] 20:00:00,190 INFO [ResourceManagementMBeanImpl] Created Link between RA Entity SipRA and Name SipRA
The easier way is simply to select and copy both deployable unit files and paste them simultaneously into
(or <topmost_mobicents_directory>
/server/server/default/deploy
if you installed JBoss separately). When you do it that way, Mobicents can figure out in which order it should install the files.$JBOSS_HOME/deploy
To undeploy a resource adapter by removing or deleting deployable unit files, refer to Section 4.1.2.3.2, “Undeploying Resource Adapters By Removing Files”.
The Mobicents Management Console provides a graphical way to deploy and undeploy resource adapters. This section requires that you are familiar with the Management Console; for an introduction to the Console, refer first to Chapter 3, Working with the Mobicents Management Console .
The following instructions also assume that you have already read introductory sections on locating resource adapter directories, recognizing deployable unit files, and determining their correct order for installation. It is essential to read those sections before attempting to deploy a resource adapter with the Management Console. See Section 4.1.2.1, “Before You Begin: Resource Adapters and Deployable Unit Files”
Once the Mobicents Converged Application Server is running, point your browser to
http://localhost:8080/management-console/
to open the Management Console. Click on
Deployable Units
in the Main Menu; this will open the
Deployable Units
main view, where you will see a list of currently-deployed units under the
Browse
tab, which will read No deployable unit found at first. Two other tabs provide the possibility of searching for and installing deployable units. Click on the
Install
tab, and you will see a
Package file:
prompt and a text-entry field in which the name of the deployable unit file you want to install will be listed.
But first we must locate the correct deployable unit file, so click the
Browse
button to the right of the text-entry field.
Before continuing, make sure that you know which deployable unit file to install first by reading the section titled How to Determine the Correct Order for Installing Deployable Unit Files.
Once armed with this knowledge, click the Browse button to find and install the first deployable unit file, whose file name will appear in the text entry field, and then click the Install button. Then install the second deployable unit file. If you install the files in the incorrect order, a message similar to the following will appear in the Log Console at the bottom of the Management Console main view:
[ERROR] javax.slee.management.DeploymentException: Could not deploy: No DeployableUniDeploymentDescriptor descriptor (META-INF/deployable-unit.xml) was found in deployable...
If you receive this error message, try installing the other deployable unit file first. Installing the right files in the correct order will lead to [INFO] Deployable unit installed messages in the
Log Console
.
If you see the name of the resource adapter you wanted to install listed in the Resources view of the Management Console, then that resource adapter has been successfully deployed.
To undeploy a resource adapter with the Management Console, refer to Section 4.1.2.3.3, “Undeploying Resource Adapters With the Management Console”.
The introductory section titled Section 4.1.2.1, “Before You Begin: Resource Adapters and Deployable Unit Files” should be read before proceeding to one of the following sections.
Section 4.1.2.3.1, “Undeploying Resource Adapters Via the Command Line”
Section 4.1.2.3.2, “Undeploying Resource Adapters By Removing Files”
Section 4.1.2.3.3, “Undeploying Resource Adapters With the Management Console”
It is as easy to undeploy resource adapters via the command line as it is to deploy them that way: by simply issuing an ant task command from the topmost Mobicents directory, after the Mobicents Converged Application Server has been started, of course.
cd <topmost_mobicents_directory>
You will run the same ant script that you ran to build and deploy the resource adapter, but note that the last argument has changed from ra-deploy to ra-undeploy:
tools/ant/bin/ant -f resources/<resource_adapter>/build.xml ra-undeploy
For example, to undeploy the SIP resource adapter you would issue the following command:
tools/ant/bin/ant -f resources/sipra/build.xml ra-undeploy
Upon success, a message similar to the following will be written to standard output:
ra-uninstall:
[echo] Uninstalling SipRA.
[slee-management] Apr 8, 2008 8:49:12 PM org.mobicents.ant.tasks.UninstallTask run
[slee-management] INFO: No response
[slee-management] Apr 8, 2008 8:49:12 PM org.mobicents.ant.tasks.UninstallTask run
[slee-management] INFO: No response
ra-undeploy:
BUILD SUCCESSFUL
Total time: 2 seconds
If you deployed a resource adapter by copying the deployable unit files from the resource adapter's directory to the
directory[3], then you can undeploy that same resource adapter merely by removing the two deployable unit files from the <topmost_jboss_directory>
/deploydeploy directory. In the file manager or on the command line, simply go to
and either move the correct two deployable unit files out of it, or delete both of them from it.<topmost_jboss_directory>
/deploy
If you choose to delete the two deployable unit files,
make sure
that you indeed
copied
them into the deploy directory, and that they both still exist in the directory of the resource adapter you want to undeploy!
Successfully removing or deleting both files from the deploy directory will result in a long string of messages sent to standard output, and ending with a line similar to: 17:48:10,705 INFO [STDOUT] 17:48:10,705 INFO [DeploymentMBeanImpl] Uninstalled DU with id DeployableUnitID[6]. It is also possible to simply remove or delete only the
file and have Mobicents undeploy the resource adapter, but it is recommended to always remove or delete both files.<resource_adapter_abbreviation>
-ra-DU.jar
One convenient way to have the Mobicents Converged Application Server deploy the correct resource adapters every time you start the server is to leave the deployable unit files in the
directory. Upon startup, Mobicents will notice that the two files are still there, and will automatically deploy the resource adapter.<topmost_jboss_directory>
/deploy
If you are looking to undeploy a resource adapter with the Management Console, then it is assumed that you have first read Section 4.1.2.1, “Before You Begin: Resource Adapters and Deployable Unit Files” and Section 4.1.2.2.3, “Deploying Resource Adapters With the Management Console”.
You can undeploy resource adapters from the Deployable Units view in the Management Console by uninstalling the two deployable unit files. Click on Deployable Units from the Main Menu, and then make sure that the Browse tab is selected at the top of the view. You will see a list of deployable unit files for the currently-installed resource adapters.
The Browse tab of the Deployable Units view shows all deployable unit files for all resource adapters that are currently deployed
Figure 4.4. Uninstalling Deployable Unit Files with the Management Console
Find the deployable unit file that corresponds to the
pattern, and click on the
Uninstall
link in the
Actions
column. This will uninstall the file, and a message similar to <resource_adapter_abbreviation>
-ra-DU.jar[INFO] Deployable unit sip-ra-DU uninstalled will appear in the
Console Log
below. After uninstalling the
ra
file, then uninstall the
file, which will print a success message like the previous one to the
Console Log
.<resource_adapter_abbreviation>
-ratype-DU.jar
If you try to uninstall the
ratype
deployable unit file before the
ra
file, then you will receive a message similar to the following one, alerting you to the mistake: [ERROR] javax.slee.management.ManagementException: Exception removing deployable Unit.
The Mobicents SIP resource adapter is a Mobicents sub-project that aims to create a high-performance SLEE extenson for the Session Iniation Protocol (SIP).
The most recent version of the SIP resource adapter includes several enhancements which allow for more convenient development of SIP resources for a wide range of applications. The type name of this latest version is JSIP v1.2, the type vendor is net.java.slee.sip, and the type version is 1.2.
In Java Specification Request 22 (JSR-22), this resource adapter type name is denoted as JAIN SIP, and the type vendor as javax.sip. This resource adapter type version is 1.1. Mobicents provides a fully-compliant implementation of this specification.
To install the JAIN SIP Resource Adapter, you must first acquire the latest version. Navigate to the Mobicents Sourceforge project page and click on the Download Mobicents link. On the next page, click on the SLEE SIP RA link so that it expands to reveal the necessary JAR file, which you can click to download[4] As of the time of this writing, the latest version was 1.2 RC1 - core rc2 .
Currently, the JAIN SIP resource adapter can be configured in three different ways.
Via the provisioning mechanism, by altering the resource-adaptor.xml configuration file.
“Via properites file jared with classes ( atleast to configure port and ip, it still is place to put gov.nist properties to configure other stack props)”
Baranowb: is this deprecated? You wrote: “Properties also can be present in properties file present in ra/src/org/mobicents/slee/resources/sip/ diretory. It will be packed to jar with all classes, and wil be used to configure RA and stack(however its deprecated!!!).”
Via properties passed to the MBean which created the Resource Adapter Entity
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?].
Provided here are explanations of the various property values which you can set. All of the following configuration entries, which are <config-property> elements in the XML file, should be unordered children of their parent <resource-adapter> element [5]
This configuration property sets the timeout on dialogs, in milliseconds. After this amount of time, if the dialog hasn't received any requests or responses, and didn't send any, it is considered to be a “dead end” and is terminated.
<config-property> <description>uS after which dialog if it has not received/send any message is considered to be dead and is expunged</description> <config-property-name>dialogIdleTimeTimeout</config-property-name> <config-property-type>java.lang.Long</config-property-type> <config-property-value>360000</config-property-value> </config-property>
This configuration property sets the amount of time, in milleseconds, between receiving a CANCEL and triggering logic to handle it.
<config-property> <description>uS after CANCEL event is going to be fired into SLEE. This atleast gives Sbbs chance to see INVITE and respond, rather than receiving INVITE in on Tx that is in terminated state.</description> <config-property-name>cancelWait</config-property-name> <config-property-type>java.lang.Long</config-property-type> <config-property-value>1000</config-property-value> </config-property>
This configuration property sets the port number on which the underlying SIP stack will listen.
<config-property> <config-property-name>port</config-property-name> <config-property-type>java.lang.Integer</config-property-type> <config-property-value>5060</config-property-value> </config-property>
This configuration property sets the IP address of the underlying stack. If it is set to null, then the SIP resource adapter will use the binding address of the container as its IP address.
<config-property> <description>IP to which SIP RAs stack should attach - if "null" it will cause RA to pick up Container bind address address</description> <config-property-name>ip</config-property-name> <config-property-type>java.lang.String</config-property-type> <config-property-value>null</config-property-value> </config-property>
This configuration property sets the transports to be used by the stack. It is a string.
<config-property> <description>List of transports, separated with ","</description> <config-property-name>transports</config-property-name> <config-property-type>java.lang.String</config-property-type> <config-property-value>UDP</config-property-value> </config-property>
The Asterisk resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the Asterisk resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
asteriskra
The Diameter resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the Diameter resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
diameterra
The Media resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the Media resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
media-ra
The SMPP resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the SMPP resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
smppra
The HTTP Servlet resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the HTTP Servlet resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
http-servlet-ra
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
event method to get an something
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:
The URL URL http://localhost:8080/mobicents/x/y maps to the convergence name /mobicents/x/y.
URL http://localhost:8080/mobicents/sum/dum maps to the convergence name /mobicents/sum/dum.
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) {
..............
}
<?xml version="1.0" encoding="utf-8"?>
<sbb-jar>
<sbb>
<description/>
<sbb-name>HttpServletRAExampleSBB</sbb-name>
<sbb-vendor>org.mobicents</sbb-vendor>
<sbb-version>1.0</sbb-version>
<sbb-classes>
<sbb-abstract-class>
<sbb-abstract-class-name>org.mobicents.slee.service.httpservletra.example.HttpServletRAExampleSbb</sbb-abstract-class-name>
</sbb-abstract-class>
</sbb-classes>
<event initial-event="True" event-direction="Receive">
<event-name>Post</event-name>
<event-type-ref>
<event-type-name>net.java.slee.resource.http.events.incoming.POST</event-type-name>
<event-type-vendor>net.java.slee</event-type-vendor>
<event-type-version>1.0</event-type-version>
</event-type-ref>
<initial-event-select variable="Address" />
</event>
<event initial-event="True" event-direction="Receive">
<event-name>Get</event-name>
..................
</event>
.....
....
<event-name>Head</event-name>
...
<event-name>Put</event-name>
.....
....
<resource-adaptor-type-binding>
<resource-adaptor-type-ref>
<resource-adaptor-type-name>HttpServletResourceAdaptorType</resource-adaptor-type-name>
<resource-adaptor-type-vendor>org.mobicents</resource-adaptor-type-vendor>
<resource-adaptor-type-version>1.0</resource-adaptor-type-version>
</resource-adaptor-type-ref>
<activity-context-interface-factory-name>
slee/resources/http-servlet-ra/http-servlet-ra-acif
</activity-context-interface-factory-name>
<resource-adaptor-entity-binding>
<resource-adaptor-object-name>slee/resources/http-servlet-ra/org.mobicents/1.0.00/http-servlet-ra/factoryprovider</resource-adaptor-object-name>
<resource-adaptor-entity-link>HttpServletRA</resource-adaptor-entity-link>
</resource-adaptor-entity-binding>
</resource-adaptor-type-binding>
</sbb>
</sbb-jar>
Example 4.1. A sample sbb-jar.xml configuration file
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 HTTP Client resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the HTTP Client resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
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.
HTTP Client Resource Adapter Methods
Provides the SBB with the interface to interact with the HTTP Client resource adapter. HttpClientResourceAdaptorSbbInterface is a wrapper over org.apache.commons.httpclient.HttpClient and exposes the most commonly-used methods of HttpClient.
createHttpMethod(String method, String uri)
HttpClientResourceAdaptorSbbInterface is used by the SBB to generate the GET, POST, HEAD (etc.) requests (HttpMethod) by calling this method. The URI can be any external URI.
public void executeMethod(HttpMethod method)
Calling this method will send the request synchronously and the calling application can then process the HttpMethod to get the response.
public HttpClientActivity createHttpClientActivity()
Creates an instance of HttpClientActivity for a service that wants to send the request asynchronously. By default the value for endOnReceivingResponse is set to false, and the service has to explicitly end activity.
public HttpClientActivity createHttpClientActivity(boolean endOn>>>ReceivingResponse)
Same method as above, with the only difference being that the service can pass endOnReceivingResponse as true, which means the activity ends as soon as the resource adapter executes the method and emits a ResponseEvent.
HttpClient
The HTTP protocol parameters associated with this HttpClient.
The HTTP state associated with the HttpClient.
The HTTP protocol parameters for this HttpClient.
Assigns the HTTP state for the HttpClient.
The HTTP Client resource adapter can be used in a synchronous or asynchronous way. HttpClientActivity is useful only when the HTTP Client resource adapter is used to send the Request asynchronously.
Gets the unique Session ID.
To end the HttpClientActivity. If endOnReceivingResponse is set to true and if the SBB tries to forcefully end activity by calling endActivity(), it should throw an exception. endActivity() should only be allowed when endOnReceivingResponse is set to false.
Returns true or false depending on the value passed when the request is sent asynchronously.
The service that wants to send the request asynchronously first has to create an instance of HttpMethod by calling createHttpMethod() of HttpClientResourceAdaptorSbbInterface The service also creates an activity, attaches itself to this activity, and then calls executeMethod, passing the instance of HttpMethod.
ResponseEvent is fired by the HTTP Client resource adapter as soon as HttpClient.executeMethod() returns. The response can be a proper response or an exception depending on the environment and application logic.
The interested SBB receives this event and can act on a response.
There may be exception due to a network failure or application logic. Interested SBBs can get the exact Exception using this method.
This is the wrapper over the response part of org.apache.commons.httpclient.HttpMethod.
Returns the response body of the HTTP method, if any, as an array of bytes.
The response body of the HTTP method, if any, as a String.
The status code associated with the latest response.
The response headers from the most recent execution of this request.
This is simple example of the code. To look at fully-working example, look at the httpclientra-example at https://mobicents-examples.dev.java.net/source/browse/mobicents-examples/httpclientra-example/.
//get the resource adapter Sbb Interface
HttpClientResourceAdaptorSbbInterface raSbbInterface = ;
//create HttpMethod by passing the link
HttpMethod httpMethod = raSbbInterface.createHttpMethod("GET", "http://www.mobicents.org-a.googlepages.com/index.html"));
//send the request and get a response
Response response = raSbbInterface.executeMethod(httpMethod);
//get ResponseBody
String responseBody = response.getResponseBodyAsString();
//get the resource adapter sbb Interface and aci factory
HttpClientResourceAdaptorSbbInterface raSbbInterface = ;
HttpClientActivityContextInterfaceFactory httpClientAci = ;
//create HttpMethod by passing the link
HttpMethod httpMethod = raSbbInterface.createHttpMethod("GET", "http://www.mobicents.org-a.googlepages.com/index.html"));
//create HttpClientActivity
HttpClientActivity clientActivity = raSbbInterface.createHttpClientActivity(true);
// get the aci for the activity and attach an sbb local object
ActivityContextInterface clientAci = httpClientAci.getActivityContextInterface(clientActivity);
clientAci.attach(sbbContext.getSbbLocalObject());
//send a request by calling executeMethod
clientActivity.executeMethod(httpMethod);
The response arrives asynchronously
public void onResponseEvent(ResponseEvent event, ActivityContextInterface aci) {
//Get the Response from Event
Response response = event.getResponse();
//get ResponseBody
String responseBody = response.getResponseBodyAsString();
The HTTP Servlet resource adapter and HTTP Client resource adapter compliment each other in creating a complete SLEE Application capable of receiving requests as well as initiating them.
TBD: eventually remove this: If you have any suggestions/feedback or find a bug please discuss at http://forums.java.net/jive/thread.jspa?messageID=228634𷴚
The Persistence resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the Persistence resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
persistencera
The XCAP Client resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the XCAP Client resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
xcapclientra
The Rules resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the Rules resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
rulesra
The TTS resource adapter can be installed by referring to Section 4.1.2, “Deploying and Undeploying Resource Adapters”.
Remember to replace
with the name of the directory in <resource_adapter>
corresponding to the TTS resource adapter (currently this directory is named <topmost_mobicents_directory>
/resources
, but this could change in the future).
ttsra
[3] The location of the
directory depends on whether you installed the binary distribution of Mobicents, in which case it is <topmost_jboss_directory>
/deploy
, or downloaded and installed JBoss yourself, in which case it is <topmost_mobicents_directory>
/server/server/default/deploy
.$JBOSS_HOME/deploy
[4] As of the time this was written, the JAR file was named jsipv1.2ra-package-10-02-2007.jar.
[5] Here is an example of the complete resource-adaptor.xml configuration file.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE resource-adaptor-jar PUBLIC "-//Sun Microsystems, Inc.//DTD JAIN SLEE Resource Adaptor 1.0//EN" "http://java.sun.com/dtd/slee-resource-adaptor-jar_1_0.dtd">
<resource-adaptor-jar>
<resource-adaptor
id="jain-sip_1.1_RA">
<description>JAIN SIP Resource Adaptor</description>
<resource-adaptor-name>JainSipResourceAdaptor</resource-adaptor-name>
<resource-adaptor-vendor>net.java.slee.sip</resource-adaptor-vendor>
<resource-adaptor-version>1.2</resource-adaptor-version>
<resource-adaptor-type-ref>
<resource-adaptor-type-name>JAIN SIP</resource-adaptor-type-name>
<resource-adaptor-type-vendor>javax.sip</resource-adaptor-type-vendor>
<resource-adaptor-type-version>1.2</resource-adaptor-type-version>
</resource-adaptor-type-ref>
<!--added oc-resource-adaptor.xml lines here altogether-->
<resource-adaptor-classes>
<resource-adaptor-class>
<resource-adaptor-class-name>
org.mobicents.slee.resource.sip.SipResourceAdaptor
</resource-adaptor-class-name>
</resource-adaptor-class>
</resource-adaptor-classes>
<config-property>
<description>uS after which dialog if it has not received/send any message is considered to be dead and is expunged</description>
<config-property-name>dialogIdleTimeTimeout</config-property-name>
<config-property-type>java.lang.Long</config-property-type>
<config-property-value>360000</config-property-value>
</config-property>
<config-property>
<description>uS after CANCEL event is going to be fired into SLEE. This atleast gives Sbbs chance to see INVITE and respond, rather than receiving INVITE in on Tx that is in terminated state.</description>
<config-property-name>cancelWait</config-property-name>
<config-property-type>java.lang.Long</config-property-type>
<config-property-value>1000</config-property-value>
</config-property>
<config-property>
<config-property-name>port</config-property-name>
<config-property-type>java.lang.Integer</config-property-type>
<config-property-value>5060</config-property-value>
</config-property>
<config-property>
<description>IP to which SIP RAs stack should attach - if "null" it will cause RA to pick up Container bind address address</description>
<config-property-name>ip</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>null</config-property-value>
</config-property>
<config-property>
<description>List of transports, separated with ","</description>
<config-property-name>transports</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>UDP</config-property-value>
</config-property>
</resource-adaptor>
</resource-adaptor-jar>
Mobicents SIP (Session Initiation Protocol) Servlets deliver a consistent, open platform on which to develop and deploy portable and distributed SIP and Converged Java Enterprise Edition (J2EE) services. The Mobicents SIP Servlets Server is a certified implementation of the SIP Servlet v1.1 (JSR 289) specification that runs on top of either the JBoss Application Server or the Tomcat Servlet Container.
Mobicents SIP Servlets for JBoss (MSS for JBoss) strives to develop interoperability standards between SIP Servlets and the Java Service Logic Execution Environment (JSLEE) so that applications can exploit the strengths of both. The JAIN-SIP Reference Implementation is leveraged as the SIP stack, and the Mobicents JAIN SLEE Server is used as the SLEE implementation.
Features of the Mobicents SIP Servlets Server
the first certified SIP Servlet v1.1 (JSR 289) implementation
a current call rate of 100 calls per second over a 24-hour duration: 8,640,000 total calls
load balancing, cluster and failover support
merged SIP and HTTP session management
a browser-based Management Console
a bundled JSLEE/SIP interoperability demonstration application for MSS for JBoss
Mobicents Media Server
extensions such as SUBSCRIBE/NOTIFY, among others
Mobicents is written in Java; therefore, before running any Mobicents server, you must have a working Java Runtime Environment (JRE) or Java Development Kit (JDK) installed on your system. In addition, the JRE or JDK you are using to run Mobicents must be version 5 or higher[6].
Although you can run the Mobicents servers using the Java Runtime Environment, we assume that most Mobicents users are developers interested in developing Java-based, Mobicents-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.
Briefly stated: if you are running on a 64-Bit Linux or Windows platform, you should consider installing and running the 64-bit JDK over the 32-bit one. Here are some heuristics for determining whether you would rather run the 64-bit Java Virtual Machine (JVM) over its 32-bit cousin for your application:
Wider datapath: the pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications when using a 64-bit JVM.
64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.
Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.
Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.
Note that the following instructions detail how to download and install the 32-bit JDK, although the steps are nearly identical for installing the 64-bit version.
You can download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click on the
Download
link next to "JDK 5.0 Update <x>" (where <x> is the latest minor version release number). On the next page, select your language and platform (both architecture—whether 32- or 64-bit—and operating system), read and agree to the Java Development Kit 5.0 License Agreement, and proceed to the download page.
The Sun website will present two download alternatives to you: one is an RPM inside a self-extracting file (for example, jdk-1_5_0_16-linux-i586-rpm.bin), and the other is merely a self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin). If you are installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, we suggest that you download the self-extracting file containing the RPM package, which will set up and use the SysV service scripts in addition to installing the JDK. We also suggest installing the self-extracting RPM file if you will be running Mobicents in a production environment.
Procedure 6.1. Installing the JDK on Linux
Regardless of which file you downloaded, you can install it on Linux by moving into the directory you downloaded the installer to, making sure the file is executable, and then running it:
~]$ cd downloads downloads]$ chmod +x “jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin” downloads]$ ./“jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin”
If you download the non-RPM self-extracting file (and installed it), and you are running on an RPM-based system, you can still set up the SysV service scripts by downloading and installing one of the -compat packages from the JPackage project. Remember to download the -compat package which corresponds correctly to the minor release number of the JDK you installed. The compat packages are available from ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-free/.
You do not need to install a -compat package in addition to the JDK if you installed the self-extracting RPM file! The -compat package merely performs the same SysV service script set up that the RPM version of the JDK installer does.
Procedure 6.2. Installing the JDK on Windows
Using Explorer, simply double-click the downloaded self-extracting installer and follow the instructions to install the JDK.
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.
JAVA_HOME Environment Variable
After installing the JDK, you must ensure that the JAVA_HOME environment variable exists and points to the location of your JDK installation.
JAVA_HOME Environment Variable on LinuxYou can determine whether JAVA_HOME is set on your system by echoing it on the command line:
~]$ echo $JAVA_HOME
If JAVA_HOME is not set already, then you must set its value to the location of the JDK installation on your system. You can do this by adding two lines to your personal ~/.bashrc configuration file. Open ~/.bashrc (or create it if it doesn't exist) and add a line similar to the following one anywhere inside the file:
export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"
You should also set this environment variable for any other users who will be running Mobicents (any environment variables exported from ~/.bashrc files are local to that user).
JAVA_HOME Environment Variable on Windowsjava, javac and java_sdk_1.5.0 Using alternatives
On systems with the alternatives command, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as which java and javac executables should be run when called.
As the root user
, call /usr/sbin/alternatives with the --config java option to select between JDKs and JREs installed on your system:
root@localhost ~]$ /usr/sbin/alternatives --config java There are 3 programs which provide 'java'. Selection Command ----------------------------------------------- 1 /usr/lib/jvm/jre-1.5.0-gcj/bin/java 2 /usr/lib/jvm/jre-1.6.0-sun/bin/java *+ 3 /usr/lib/jvm/jre-1.5.0-sun/bin/java Enter to keep the current selection[+], or type selection number:
In our case, we want to use the Sun JDK, version 5, that we downloaded and installed, to run the java executable. In the alternatives information printout above, a “plus” (“
+
”) next to a number indicates the one currently being used. As per alternatives' instructions, pressing
Enter
will simply keep the current JVM, or you can enter the number corresponding to the JVM you would prefer to use.
Repeat the procedure above for the javac command and the java_sdk_1.5.0 environment variable,
as the root user
:
~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
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 command in the terminal from your home directory:-version
~]$ 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)
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.
On RPM-based systems, you can uninstall the JDK using the yum command.remove <jdk_rpm_name>
On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.
You can run the Mobicents SIP Servlets Server on top of either the JBoss Application Server or the Tomcat Servlet Container. This section details how to install the SIP Servlets Server on top of the JBoss Application Server. If you would rather run the SIP Servlets Server on top of the Tomcat Servlet Container, go to Section 6.1.3, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running” [7]
Provided here is a list of differences between a standard JBoss Application Server installation one customized for SIP Servlets. The differences include:
The server/default/deploy directory contains both HTTP and SIP Servlet applications (WAR and SAR2 files).
The server/default/deploy/jboss-web.deployer unit has been modified to provide extended classes to the standard JBoss container classes, in order to allow SIP applications to be loaded and the SIP stack to be started.
The server/default/deploy/jboss-web.deployer/context.xml file has been modified to provide the extended manager to be able to manage SIP sessions and SIP application sessions in addition to HTTP sessions.
The server/default/deploy/jboss-web.deployer/META-INF/jboss-service.xml file and the server/default/deploy/jboss-web.deployer/META-INF/webserver-xmbean.xml file have been modified so that it is now possible for JBoss containers to correctly deploy SIP servlets and converged applications.
A dars directory containing all of the default applications' router properties files for using the various SIP Servlets applications (which come bundled with the release) has been added to the server/default/conf directory.
a dars directory containing all the default applications router properties files for using the SIP servlets applications bundled with the release has been added to server/default/conf.
Additional JAR files have been added to enable SIP Servlet functionality. Here is a more-or-less complete list of the JAR files added to the server/default/deploy/jboss-web.deployer/ directory:
sip-servlets-impl-0.6.jar
sip-servlets-spec-1.1.6.jar
sip-servlets-application-router-0.6.jar
sip-balancer-1.0-SNAPSHOT.jar
jain-sip-api-1.2.jar
jain-sip-ri-1.2.83.jar
concurrent-1.3.4.jar
log4j-1.2.14.jar
stun4j-1.0-MOBICENTS.jar
dnsjava-2.0.6.jar
Hardware Requirements
You must have sufficient disk space in order to install the MSS for JBoss binary release. Once unzipped, version 0.6 of MSS for JBoss binary release requires at least 120 MB of free disk space. Keep in mind that disk space requirements may change from release to release.
MSS for JBoss is 100% Java. It will run on the same hardware that the JBoss Application Server runs on.
Software Prerequisites
A working installation of the Java Development Kit (JDK) version 5 or higher is currently required in order to run MSS for JBoss binary distribution. For instructions on how to install the JDK, refer to Section 6.1, “Mobicents SIP Servlets Server”.
You can download the latest version of MSS for JBoss from http://www.mobicents.org/mss-downloads.html. The top row of the table holds the latest version. Note that each version of the Mobicents SIP Servlets Server is comprised of two separate binary distribution files: one which is MSS for JBoss, and the other which is MSS for Tomcat. Download Mobiceesnts SIP Servlets Server for JBoss and continue with the following instructions.
Once the requirements and prerequisites have been met and you have downloaded the binary distribution zip file, you are ready to install the MSS for JBoss binary distribution. Follow the instructions below for your platform, whether Linux or Windows.
For clarity, the command line instructions presented in this chapter use specific version numbers and directory names. Remember to replace them with version numbers and file names relevant to those you are actually working with.
Procedure 6.3. Installing the MSS for JBoss Binary Distribution on Linux
First, move to the directory to which you downloaded the binary distribution zip file. For this example, we'll assume you're currently in your home directory, and that you downloaded the zip file to a subdirectory of it, referred to as downloads.
~]# cd downloads
In downloads, create a subdirectory to hold the unzipped MSS for JBoss files. It is good practice to include the version number in this directory name; if you do so, remember to correctly match it with the version of the MSS for JBoss distribution you downloaded.
downloads]$ mkdir "mss-jboss-0.6"
Move the downloaded zip file into the directory you just created:
downloads]$ mv "mss-0.6-jboss-4.2.2.GA-0809301055.zip" "mss-jboss-0.6"
Move into that directory:
downloads]$ cd "mss-jboss-0.6"
Finally, use Java's jar command to extract the contents of the zip file into the current directory, thus completing the install:-xvf
mss-jboss-0.6]$ jar -xvf "mss-0.6-jboss-4.2.2.GA-0809301055.zip"
Alternatively, if Linux's unzip utility is present on your system or is installable, you can use it in lieu of Java's jar command:-xvf
mss-jboss-0.6]$ unzip "mss-0.6-jboss-4.2.2.GA-0809301055.zip"
You can also use unzip's -d
option to extract the zip file's contents to a location other than the current directory.<unzip_to_location>
To free disk space, you may want to delete the zip file once you've extracted its contents:
mss-jboss-0.6]$ rm "mss-0.6-jboss-4.2.2.GA-0809301055.zip"
Procedure 6.4. Installing the MSS for JBoss Binary Distribution on Windows
For this example, we'll assume that you downloaded the binary distribution zip file to the My Downloads folder. First, using Windows Explorer, create a subfolder in My Downloads to extract the zip file's contents into. When you name this folder, it is good practice to include the version number; if you do so, remember to correctly match it with the version of the MSS for JBoss binary distribution you downloaded. In these instructions, we will refer to this folder as mss-jboss-0.6.
Double-click the downloaded zip file, selecting as the destination folder the one you just created to hold the zip file's contents.
Alternatively, it is also possible to use Java's jar command to extract the binary distribution files from the zip archive. To use this method instead, first move the downloaded zip file from -xvf
My Downloads to the folder that you just created to hold the SIP Servlets Server files.
Then, open the Windows Command Prompt and navigate to the folder holding the archive using the cd command:
If you are using Windows Vista®, you can open the Command Prompt directly from Explorer. Hold down the Shift key and right-click on either a folder, the desktop, or inside a folder. This will cause an Open Command Window Here context menu item to appear, which can be used to open the Command Prompt with the current working directory set to either the folder you opened, or opened it from.
C:\Users\Me>cd "My Downloads\mss-jboss-0.6"
Finally, use the jar command to extract the archive contents into the current folder.-xvf
C:\Users\Me\My Downloads\mss-jboss-0.6>jar -xvf "mss-0.6-jboss-4.2.2.GA-0809301055.zip"
At this point, you may want to move the folder holding the MSS for JBoss files (in this example, the folder named mss-jboss-0.6) to another location. This step is not strictly necessary, but it is probably a good idea to move the installation folder from My Downloads to a user-defined location for storing runnable programs. Any location will suffice, however.
You may also want to delete the zip file after extracting its contents in order to free disk space:
C:\Users\Me\My Downloads\mss-jboss-0.6>delete "mss-0.6-jboss-4.2.2.GA-0809301055.zip"
Configuring MSS for JBoss consists in setting the JBOSS_HOME environment variable, and then, optionally, either running the JBoss Application Server (in which case you should jump to Section 6.1.2.5, “Running” while remembering to return to this section later), or further customizing MSS for JBoss, which is detailed in the immediately-following sections. Those sections detail how MSS for JBoss can be further customized by adding SIP Connectors and by configuring the application router.
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:
If you are installing a
binary
Mobicents server and JBOSS_HOME is not set on your system, then you
do not need
to set it, but doing so will do no harm.
If you are installing a binary Mobicents server and JBOSS_HOME is (already) set on your system, then you need to make sure it points to the location of the new Mobicents server.
If you are installing a Mobicents server from source which uses the JBoss Application Server, then you
must
set JBOSS_HOME.
The following instructions detail how to set JBOSS_HOME on both Linux and Windows.
Procedure 6.5. Setting the JBOSS_HOME Environment Variable on Linux
The JBOSS_HOME environment variable must point to the location of your JBoss installation. Any Mobicents server which runs on top of the JBoss Application Server has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, a bin directory. JBOSS_HOME must be set to the topmost directory of your Mobicents server installation.
Setting this variable in your personal ~/.bashrc file has the advantage that it will always be set (for you, as a user) each time you log in or reboot the system. To do so, open ~/.bashrc in a text editor (or create the file if it doesn't already exist) and insert the following line anywhere in the file, taking care to substitute <mobicents_server> for the topmost directory of the Mobicents server you installed:
export JBOSS_HOME="/home/<username>/<path>/<to>/<mobicents_server>"
Save and close .bashrc.
You can—and should—source your .bashrc file to make your change take effect (so that JBOSS_HOME is set) for the current session:
~]$ source ~/.bashrc
Finally, make sure that JBOSS_HOME has been set correctly (that it leads to the right directory), and has taken effect in the current session.
The following command will show the path to the directory pointed to by JBOSS_HOME:
~]$ echo $JBOSS_HOME
To be absolutely sure, change your directory to the one pointed to by JBOSS_HOME:
~]$ cd $JBOSS_HOME && pwd
Procedure 6.6. Setting the JBOSS_HOME Environment Variable on Windows
The JBOSS_HOME environment variable must point to the location of your JBoss installation. Any Mobicents server which runs on top of the JBoss Application Server has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, a bin directory. JBOSS_HOME must be set to the topmost directory of your Mobicents server installation.
If you are planning on running the JBoss Application Server as the Administrator, then you should, of course, set the JBOSS_HOME environment variable
as the administrator
, and if you planning to run Tomcat as a normal user, then set JBOSS_HOME as a user environment variable.
For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
You can add SIP Connectors in the same way that you add HTTP Connectors: by adding a Connector element under the Service element in the container's server.xml configuration file.
For example, to add a SIP Connector on the IP address 127.0.0.1, on port 5080, using the UDP transport protocol, you should insert the following XML element:
<Connector
port="5080"
ipAddress="127.0.0.1"
protocol="org.mobicents.servlet.sip.startup.SipProtocolHandler"
signalingTransport="udp"
threadPoolSize="64"
isReentrantListener="true"
useStun="false"
stunServerAddress="stun01.sipphone.com"
stunServerPort="3478"
logLevel="DEBUG"
debugLog="logs/debuglog.txt"
serverLog="logs/serverlog.txt"
sipStackName="Sip-Servlet-Server"
sipPathName="gov.nist"/>
Example 6.1. Adding a SIP Connector to server.xml
Provided here are descriptions of the SIP Connector element's attributes:
The number of the port on which the container will be able to receive SIP messages.
The IP address at which the container will be able to receive SIP messages.
This attribute specifies that this is a SIP Connector and not an HTTP Connector. There is no need to change this property.
the transport on which the container will be ab/le to receive SIP messages: “udp” for example
This attribute is for concurrency control on the number of simultaneous active threads in the NIST SIP stack. Refer to the NIST SIP stack Javadoc API documentation for more information.
If the listener is re-entrant, then the SIP stack manages a thread pool and synchronously calls the listener from the same thread which read the message. Refer to the NIST SIP stack Javadoc API documentation for more information.
Setting this attribute to “true” enables STUN support for this Connector. If you set it to “true”, ensure that the ipAddress attribute is
not
set to 127.0.0.1. This attribute defaults to “false”. Refer to the documentation on STUN support for more information regarding STUN support.
Set this to the STUN server address that will be used to discover the public IP address of this SIP Connector. This attribute is only required if the useStun attribute is set to “true”. Refer to the documentation on STUN support for more information regarding STUN support.
This attribute should be set to the STUN server port of the STUN server used in the stunServerAddress attribute. You should rarely need to change this attribute; also, it is only needed if the useStun attribute is set to “true”. Refer to the documentation on STUN support for more information regarding STUN support.
The log level of the underlying JAIN SIP stack.
The debug log location of the underlying JAIN SIP stack.
The server log location of the underlying JAIN SIP stack.
The name of the underlying JAIN SIP sack.
The JAIN SIP stack implementation to use. You will probably never need to change the value of this attribute. It defaults to the famous NIST SIP stack. If you ever do change this value, you should remember to insert the JAIN SIP JAR implementation in the container's lib directory.
The application router is called by the container—whether JBoss or Tomcat—to select a SIP Servlet application to service an initial request. It embodies the logic used to choose which applications to invoke. An application router is required for a container to function, but it is a separate logical entity from the container. The application router is solely responsible for application selection and must not implement application logic. For example, the application router cannot modify a request or send a response.
For more information about the application router, refer to the following sections of the JSR 289 specification: Application Router Packaging and Deployment, Application Selection Process, and Appendix C.
In order to configure the application router, you should edit the Service element in the container's server.xml configuration file:
<Service name="Sip-Servlets" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="file:///home/silas/workspaces/mobicents-sip-servlets/sip-servlets-examples/reinvite-demo/reinvite-dar.properties">
Example 6.2. Configuring the Service Element in the Container's server.xml
Provided here is a description of the SIP Service element's attributes:
This attribute specifies that the servlet container is a converged (i.e. SIP + HTTP) servlet container. This attribute can also be used to handle load-balancing and failover.
This attribute specifies the class name of the org.mobicents.servlet.sip.core.SipApplicationDispatcher implementation to use. The routing algorithm and application selection process is performed in that class.
The default application router file location. This is used by the default application router to determine the application selection logic. Refer to Appendix C of the JSR 289 specification for more details.
There are two separate levels of logging:
Logging at the container level, which can be configured using the log4j.xml configuration file, which is usually located in the container's lib directory.
Logging of the NIST SIP stack, which is configured in the Connector element of the container's server.xml configuration file.
Once installed, you can run MSS for JBoss by executing the one of the startup scripts in the 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 JBoss Application 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 may arise. In the Linux terminal or Command Prompt, you will be able to tell that the server started successfully if the last line of output is similar to the following (ending with “Started in 23s:648ms”):
17:48:01,247 INFO [Server] JBoss (MX MicroKernel) [4.2.2.GA (build: SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 20s:861ms
Detailed instructions are given below, arranged by platform.
Procedure 6.7. Running MSS for JBoss on Linux
Change your working directory to MSS for JBoss's topmost directory (the one in which you extracted the zip file's contents to):
downloads]$ cd "mss-jboss-0.6"
(Optional) Ensure that the bin/run.sh start script is executable:
mss-jboss-0.6]$ chmod +x bin/run.sh
Finally, execute the run.sh Bourne shell script:
mss-jboss-0.6]$ ./bin/run.sh
Instead of executing the Bourne shell script to start the server, you may alternatively run the run.jar executable Java archive in the bin directory:
mss-jboss-0.6]$ java -jar bin/run.jar
Procedure 6.8. Running MSS for JBoss on Windows
There are several ways to start MSS for JBoss on Windows. All of the following methods accomplish the same task.
Using Windows Explorer, change your folder to the one in which you unzipped the downloaded zip file, and then to the bin subfolder.
Although not the preferred way (see below), it is possible to start MSS for JBoss by double-clicking on the run.bat executable batch file.
As mentioned above, the best way to start MSS for JBoss is by using the Command Prompt. Doing it this way will allow you to view all of the server startup details, which will enable you to easily determine whether any problems were encountered during the startup process. You can open the Command Prompt directly from the <topmost_directory>\bin folder in Windows Explorer (see Opening the Command Prompt from Windows Explorer for details), or you can open the Command Prompt via the
Start
menu and navigate to the correct folder:
C:\Users\Me\My Downloads> cd "mss-jboss-0.6"
Start the JBoss Application Server by running the executable run.bat batch file:
C:\Users\Me\My Downloads\mss-jboss-0.6>bin\run.bat
It is also possible to start the server by running the run.jar executable Java archive:
C:\Users\Me\My Downloads\mss-jboss-0.6>java -jar bin\run.jar
Once the server is running, you can access the SIP Servlets Management Console by opening your browser and navigating to http://localhost:8080/sip-servlets-management/.
Just as there are multiple ways to run MSS for JBoss, there are multiple ways to stop it. Detailed instructions for stopping the JBoss Application 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:
[Server] Shutdown complete Shutdown complete Halting VM
Procedure 6.9. Stopping MSS for JBoss on Linux by Issuing a Control Code
Assuming that you started the JBoss Application Server as a foreground process in the terminal, the easiest way to stop it is by pressing the Ctrl + c key combination in the same terminal in which you started it.
Procedure 6.10. Stopping MSS for JBoss on Linux by Executing shutdown.sh or shutdown.jar
Another way to shut down the JBoss Application Server is by executing the shutdown.sh Bourne shell script in the <topmost_directory>/bin directory. To do so, first change your working directory to the binary distribution's topmost directory (the one to which you extracted the downloaded zip file's contents):
downloads]$ cd "mss-jboss-0.6"
(Optional) Ensure that the bin/shutdown.sh start script is executable:
mss-jboss-0.6]$ chmod +x bin/shutdown.sh
Finally, run the shutdown.sh executable Bourne shell script, and remember to add the -S option (which is the short option for --shutdown) as a command line argument:
mss-jboss-0.6]$ ./bin/shutdown.sh -S
Instead of executing the Bourne shell script to stop the server, you may alternatively run the shutdown.jar executable Java archive to do so (and remembering, again, to add the -S command line argument):
mss-jboss-0.6]$ java -jar bin/shutdown.jar -S
Procedure 6.11. Stopping MSS for JBoss on Windows
Stopping the JBoss Application Server on Windows consists in executing either the shutdown.bat or the shutdown.jar executable file in the bin subfolder of the MSS for JBoss binary distribution. Make sure to add the -S option (which is the short option for --shutdown) as a command line argument.
C:\Users\Me\My Downloads\mss-jboss-0.6>bin\shutdown.bat -S
Alternatively, you can execute the shutdown.jar Java archive by running the java command, and remembering to add the -jar
-S option as a command line argument:
C:\Users\Me\My Downloads\mss-jboss-0.6>java -jar bin\shutdown.jar -S
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.
If you are interested in clustering and failover support, or would rather run the Mobicents SIP Servlets Server on top of the JBoss Application Server, go to Section 6.1.2, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.
Provided here is a list of differences between a standard Tomcat Servlet Container installation and the Mobicents-provided SIP Servlets for Tomcat installation. The differences include:
The server.xml configuration file has been modified to provide extended classes to the standard Tomcat container classes, in order to allow SIP applications to be loaded and the SIP stack started.
A dars directory containing the default applications' router properties files for using the SIP Servlet Click-to-Call application (which comes bundled with the release) has been added to the conf directory.
Additional JAR files have been added to enable SIP Servlet functionality. Here is a more-or-less complete list of the JAR files added to the server/default/lib directory:
sip-servlets-impl-0.6.jar
sip-servlets-spec-1.1.6.jar
sip-balancer-1.0-SNAPSHOT.jar
jain-sip-api-1.2.jar
jain-sip-ri-1.2.83.jar
concurrent-1.3.4.jar
log4j-1.2.14.jar
stun4j-1.0-MOBICENTS.jar
dnsjava-2.0.6.jar
Hardware Requirements
You must have sufficient disk space in order to install the MSS for Tomcat binary release. Once unzipped, version 0.5 of the MSS for Tomcat binary release requires at least 20 MB of free disk space. Keep in mind that disk space requirements may change from release to release.
MSS for Tomcat is 100% Java. It will run on the same hardware that the Tomcat Servlet Container runs on.
Software Prerequisites
A working installation of the Java Development Kit (JDK) version 5 or higher is required in order to run MSS for Tomcat.
For instructions on how to install the JDK, refer to Section 6.1, “Mobicents SIP Servlets Server”.
You can download the latest version of MSS for Tomcat from http://www.mobicents.org/mss-downloads.html. The top row of the table holds the latest version. Note that each release of the Mobicents SIP Servlets Server is comprised of two separate binary distribution files: one which is MSS for JBoss, and the other which is MSS for Tomcat. Download Mobicents SIP Servlets Server for Tomcat and continue with the following instructions.
Once the requirements and prerequisites have been met and you have downloaded the binary distribution zip file, you are ready to install MSS for Tomcat. Follow the instructions below for your platform, whether Linux or Windows.
For clarity, the command line instructions presented in this chapter use specific version numbers and directory names. Remember to replace them with version numbers and file names relevant to those you are actually working with.
Procedure 6.12. Installing the MSS for Tomcat Binary Distribution on Linux
First, move to the directory to which you downloaded the binary distribution zip file. For this example, we'll assume you're currently in your home directory, and that you downloaded the zip file to a subdirectory of it, referred to as downloads.
~]$ cd downloads
In downloads, create a subdirectory to hold the unzipped MSS for Tomcat files. It is good practice to include the version number in this directory name; if you do so, remember to correctly match it with the version of the MSS for Tomcat binary distribution you downloaded.
downloads]$ mkdir "mss-tomcat-0.6"
Move the downloaded zip file into the directory you have just created:
downloads]$ mv "mss-0.6-apache-tomcat-6.0.14-0809301055.zip" "mss-tomcat-0.6"
Move into that directory:
downloads]$ cd "mss-tomcat-0.6"
Finally, use Java's jar command to extract the contents of the zip file into the current directory, thus completing the install:-xvf
mss-tomcat-0.6]$ jar -xvf "mss-0.6-apache-tomcat-6.0.14-0809301055.zip"
Alternatively, if Linux's unzip utility is present on your system or is installable, you can use it in lieu of Java's jar command:-xvf
mss-tomcat-0.6]$ unzip "mss-0.6-apache-tomcat-6.0.14-0809301055.zip"
You can also use unzip's -d
option to extract the zip file's contents to a location other than the current directory.<unzip_to_location>
To free disk space, you may want to delete the zip file once you've extracted its contents:
mss-tomcat-0.6]$ rm "mss-0.6-apache-tomcat-6.0.14-0809301055.zip"
Procedure 6.13. Installing the MSS for Tomcat Binary Distribution on Windows
For this example, we'll assume that you downloaded the binary distribution zip file to the My Downloads folder. First, using Windows Explorer, create a subfolder in My Downloads to extract the zip file's contents into. When you name this folder, it is good practice to include the version number; if you do so, remember to correctly match it with the version of the MSS for Tomcat binary distribution you downloaded. In these instructions, we will refer to this folder as mss-tomcat-0.6.
Double-click the downloaded zip file, selecting as the destination folder the one you just created to hold the zip file's contents.
Alternatively, it is also possible to use Java's jar command to extract the binary distribution files from the zip archive. To use this method instead, first move the downloaded zip file from -xvf
My Downloads to the folder that you just created to hold the SIP Servlets Server files.
Then, open the Windows Command Prompt and navigate to the folder holding the archive using the cd command.
If you are using Windows Vista®, you can open the Command Prompt directly from Explorer. Hold down the Shift key and right-click on either a folder, the desktop, or inside a folder. This will cause an Open Command Window Here context menu item to appear, which can be used to open the Command Prompt with the current working directory set to either the folder you opened, or opened it from.
Finally, use the jar command to extract the archive contents into the current folder.-xvf
C:\Users\Me\My Downloads\mss-tomcat-0.6>jar -xvf "mss-0.6-apache-tomcat-6.0.14-0809301055.zip"
At this point, you may want to move the folder holding the MSS for Tomcat binary files (in this example, the folder named mss-tomcat-0.6) to another location. This step is not strictly necessary, but it is probably a good idea to move the installation folder from My Downloads to a user-defined location for storing runnable programs. Any location will suffice, however.
You may want to delete the zip file after extracting its contents in order to free disk space:
C:\Users\Me\My Downloads\mss-tomcat-0.6>delete "mss-0.6-apache-tomcat-6.0.14-0809301055.zip"
Configuring MSS for Tomcat consists in setting the CATALINA_HOME environment variable, and then, optionally, either running MSS for Tomcat (in which case you should jump to Section 6.1.2.5, “Running”, while remembering to return to this section later), or further customizing the Tomcat container, which is detailed in the immediately-following sections. Those sections detail how MSS for Tomcat can be further customized by adding SIP Connectors and configuring the application router.
Before running the Mobicents server you are installing, you should consider if you need to set the CATALINA_HOME environment variable. Setting it (or re-setting it) will always work. Whether or not you
need
to set CATALINA_HOME depends on the following factors:
If you are installing a binary Mobicents server and CATALINA_HOME is not set on your system, then you
do not need
to set it, but doing so will do no harm.
If you are installing a binary Mobicents server and CATALINA_HOME is (already) set on your system, then you need to make sure it points to the location of the new Mobicents server.
If you are installing a Mobicents server from source which uses the Tomcat servlet container, then you
must
set CATALINA_HOME.
The following instructions detail how to set CATALINA_HOME on both Linux and Windows.
Procedure 6.14. Setting the CATALINA_HOME Environment Variable on Linux
The CATALINA_HOME environment variable must point to the location of your Tomcat installation. Any Mobicents server which runs on top of the Tomcat servlet container has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, a bin directory. CATALINA_HOME must be set to the topmost directory of your Mobicents server installation.
Setting this variable in your personal ~/.bashrc file has the advantage that it will always be set (for you, as a user) each time you log in or reboot the system. To do so, open ~/.bashrc in a text editor (or create the file if it doesn't already exist) and insert the following line anywhere in the file, taking care to substitute <mobicents_server> for the topmost directory of the Mobicents server you installed:
export CATALINA_HOME="/home/<username>/<path>/<to>/<mobicents_server>"
Save and close .bashrc.
You can—and should—source your .bashrc file to make your change take effect (so that CATALINA_HOME is set) for the current session:
~]$ source ~/.bashrc
Finally, make sure that CATALINA_HOME has been set correctly (that it leads to the right directory), and has taken effect in the current session.
The following command will show the path to the directory pointed to by CATALINA_HOME:
~]$ echo $CATALINA_HOME
To be absolutely sure, change your directory to the one pointed to by CATALINA_HOME:
~]$ cd $CATALINA_HOME && pwd
Procedure 6.15. Setting the CATALINA_HOME Environment Variable on Windows
The CATALINA_HOME environment variable must point to the location of your Tomcat installation. Any Mobicents server which runs on top of the Tomcat servlet container has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, a bin directory. CATALINA_HOME must be set to the topmost directory of your Mobicents server installation.
If you are planning on running the Tomcat container as the Administrator, then you should, of course, set the CATALINA_HOME environment variable
as the administrator
, and if you planning to run Tomcat as a normal user, then set CATALINA_HOME as a user environment variable.
For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
You can add SIP Connectors in the same way that you add HTTP Connectors: by adding a Connector element under the Service element in the container's server.xml configuration file.
For example, to add a SIP Connector on the IP address 127.0.0.1, on port 5080, using the UDP transport protocol, you should insert the following XML element:
<Connector
port="5080"
ipAddress="127.0.0.1"
protocol="org.mobicents.servlet.sip.startup.SipProtocolHandler"
signalingTransport="udp"
threadPoolSize="64"
isReentrantListener="true"
useStun="false"
stunServerAddress="stun01.sipphone.com"
stunServerPort="3478"
logLevel="DEBUG"
debugLog="logs/debuglog.txt"
serverLog="logs/serverlog.txt"
sipStackName="Sip-Servlet-Server"
sipPathName="gov.nist"/>
Example 6.3. Adding a SIP Connector to server.xml
Provided here are descriptions of the SIP Connector element's attributes:
The number of the port on which the container will be able to receive SIP messages.
The IP address at which the container will be able to receive SIP messages.
This attribute specifies that this is a SIP Connector and not an HTTP Connector. There is no need to change this property.
the transport on which the container will be ab/le to receive SIP messages: “udp” for example
This attribute is for concurrency control on the number of simultaneous active threads in the NIST SIP stack. Refer to the NIST SIP stack Javadoc API documentation for more information.
If the listener is re-entrant, then the SIP stack manages a thread pool and synchronously calls the listener from the same thread which read the message. Refer to the NIST SIP stack Javadoc API documentation for more information.
Setting this attribute to “true” enables STUN support for this Connector. If you set it to “true”, ensure that the ipAddress attribute is
not
set to 127.0.0.1. This attribute defaults to “false”. Refer to the documentation on STUN support for more information regarding STUN support.
Set this to the STUN server address that will be used to discover the public IP address of this SIP Connector. This attribute is only required if the useStun attribute is set to “true”. Refer to the documentation on STUN support for more information regarding STUN support.
This attribute should be set to the STUN server port of the STUN server used in the stunServerAddress attribute. You should rarely need to change this attribute; also, it is only needed if the useStun attribute is set to “true”. Refer to the documentation on STUN support for more information regarding STUN support.
The log level of the underlying JAIN SIP stack.
The debug log location of the underlying JAIN SIP stack.
The server log location of the underlying JAIN SIP stack.
The name of the underlying JAIN SIP sack.
The JAIN SIP stack implementation to use. You will probably never need to change the value of this attribute. It defaults to the famous NIST SIP stack. If you ever do change this value, you should remember to insert the JAIN SIP JAR implementation in the container's lib directory.
The application router is called by the container—whether JBoss or Tomcat—to select a SIP Servlet application to service an initial request. It embodies the logic used to choose which applications to invoke. An application router is required for a container to function, but it is a separate logical entity from the container. The application router is solely responsible for application selection and must not implement application logic. For example, the application router cannot modify a request or send a response.
For more information about the application router, refer to the following sections of the JSR 289 specification: Application Router Packaging and Deployment, Application Selection Process, and Appendix C.
In order to configure the application router, you should edit the Service element in the container's server.xml configuration file:
<Service name="Sip-Servlets" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="file:///home/silas/workspaces/mobicents-sip-servlets/sip-servlets-examples/reinvite-demo/reinvite-dar.properties">
Example 6.4. Configuring the Service Element in the Container's server.xml
Provided here is a description of the SIP Service element's attributes:
This attribute specifies that the servlet container is a converged (i.e. SIP + HTTP) servlet container. This attribute can also be used to handle load-balancing and failover.
This attribute specifies the class name of the org.mobicents.servlet.sip.core.SipApplicationDispatcher implementation to use. The routing algorithm and application selection process is performed in that class.
The default application router file location. This is used by the default application router to determine the application selection logic. Refer to Appendix C of the JSR 289 specification for more details.
There are two separate levels of logging:
Logging at the container level, which can be configured using the log4j.xml configuration file, which is usually located in the container's lib directory.
Logging of the NIST SIP stack, which is configured in the Connector element of the container's server.xml configuration file.
Once installed, you can run the Tomcat Servlet Container by executing the one of the startup scripts in the 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 Tomcat 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 may arise. In the Linux terminal or Command Prompt, you will be able to tell that the container started successfully if the last line of output is similar to the following:
Using CATALINA_BASE: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.6 Using CATALINA_HOME: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.6 Using CATALINA_TMPDIR: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.6/temp Using JRE_HOME: /etc/java-config-2/current-system-vm
Detailed instructions are given below, arranged by platform.
Procedure 6.16. Running MSS for Tomcat on Linux
Change your working directory to the SIP Servlets-customized Tomcat's topmost directory (the one in which you extracted the zip file's contents to):
downloads]$ cd "mss-tomcat-0.6"
(Optional) Ensure that the bin/startup.sh start script is executable:
mss-tomcat-0.6]$ chmod +x bin/startup.sh
Finally, execute the startup.sh Bourne shell script:
mss-tomcat-0.6]$ ./bin/startup.sh
Procedure 6.17. Running MSS for Tomcat on Windows
There are several different ways to start the Tomcat Servlet Container on Windows. All of the following methods accomplish the same task.
Using Windows Explorer, change your folder to the one in which you unzipped the downloaded zip file, and then to the bin subfolder.
Although not the preferred way (see below), it is possible to start the Tomcat Servlet Container by double-clicking on the startup.bat executable batch file.
As mentioned above, the best way to start the Tomcat Servlet Container is by using the Command Prompt. Doing it this way will allow you to view all of the server startup details, which will enable you to easily determine whether any problems were encountered during the startup process. You can open the Command Prompt directly from the <topmost_directory>\bin folder in Windows Explorer (see Opening the Command Prompt from Windows Explorer for details), or you can open the Command Prompt via the
Start
menu and navigate to the correct folder:
C:\Users\Me\My Downloads> cd "mss-tomcat-0.6"
Start the Tomcat Servlet Container by running the executable startup.bat batch file:
C:\Users\Me\My Downloads\mss-tomcat-0.6>bin\startup.bat
Just as there are multiple ways to run MSS for Tomcat, there are multiple ways to stop it. Detailed instructions for stopping the Tomcat Servlet Container 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 (both running and stopping the Tomcat Servlet Container produces the same output):
Using CATALINA_BASE: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.6 Using CATALINA_HOME: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.6 Using CATALINA_TMPDIR: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.6/temp Using JRE_HOME: /etc/java-config-2/current-system-vm
Procedure 6.18. Stopping MSS for Tomcat on Linux by Executing shutdown.sh
Another way to shut down the Tomcat Servlet Container is by executing the shutdown.sh Bourne shell script in the <topmost_directory>/bin directory. To do so, first change your working directory to the binary distribution's topmost directory (the one to which you extracted the downloaded zip file's contents):
downloads]$ cd "mss-tomcat-0.6"
(Optional) Ensure that the bin/shutdown.sh start script is executable:
mss-tomcat-0.6]$ chmod +x bin/shutdown.sh
Finally, run the shutdown.sh executable Bourne shell script
mss-tomcat-0.6]$ ./bin/shutdown.sh
After starting the server successfully, you can access the default web applications included with MSS for Tomcat by opening the following URL in your browser: http://localhost:8080/.
You can also access the SIP Servlets Management Console by opening http://localhost:8080/sip-servlets-management/ in your browser.
Once you have installed and started either an MSS for JBoss or MSS for Tomcat instance, you can access the SIP Servlets Management Console by opening your browser and navigating to http://localhost:8080/sip-servlets-management/.
Helpful Information on how to use the SIP Servlets Management Console is available immediately from within the AJAX application itself: simply click on the Help link on the top main menu bar, and a Default Application Router Help popup will appear. This help box can be repositioned and resized by dragging.
More recent versions of the SIP Servlets Management Console also have a Server Settings tab, in which you can tune settings for concurrency and congestion control.
For more information on tuning for concurrency and congestion control, refer to Configuring the Concurrency and Congestion Control Settings.
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.
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:
All SIP messages are processed as soon as possible in a thread from the global thread pool. Note that when using the None concurrency control mode, two messages belonging to the same SipSession can be processed simultaneously, so you must take measures to ensure that access to a shared resource such as the session attribute is synchronized in a thread-safe manner.
SIP messages are processed as soon as possible except that two messages from the same SipSession are guaranteed never to be processed simultaneously. Messages from the same SipSession are processed sequentially in their order-of-arrival. However, two (or more) messages from different SipSessions in the same SipApplicationSession may be processed simultaneously, in which case you should take measures to ensure shared resource synchronization. You should also pay special attention to Back-to-Back User Agent (B2BUA) cases in which each leg of the B2BUA consists of a different SipSession in the same SipApplicationSession.
SIP messages are processed as soon as possible with the guarantee that no two messages from the same SipSession
or
from the same SipApplicationSession will ever be processed simultaneously: they are instead processed sequentially in their order-of-arrival. This mode is the most thread-safe. However, you must still be careful if you are accessing shared resources in an unmanaged way, such as by accessing a SipSession attribute from an unmanaged thread, or from an Enterprise JavaBean. If you do so, be aware that such access will not be synchronized.
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.
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 easiest way to configure the
SIP Mesage Queue Size
and
Concurrency Control Mode
tunable parameters is to open the SIP Servlets Management Console in your browser (by going to http://localhost:8080/sip-servlets-management), making your changes, and then
Apply
ing them. Note that configuring the settings in the SIP Servlets Management Console does not persist across reboots. To make your settings changes permanent, you should edit your server's server.xml configuration file; instructions for doing so follow.
server.xml
Alternatively, you can edit your server's server.xml configuration file, which has the benefit of making your chosen settings changes permanent. Instructions follow, grouped by the SIP Servlets Server you are running:
Procedure 6.20. Tuning MSS for JBoss Server Settings for Concurrency and Congestion Control
Open the
configuration file in a text editor.$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml
Find the Service element and add a concurrencyControlMode and/or a sipMessageQueueSize attribute to it.
The default value of the sipMessageQueueSize attribute is
1500
. That is the default value which is used even if the attribute is not present in server.xml. You will need to play around with this setting for the optimal value, which depends on the hardware running your SIP Servlets Server.
Possible values for the concurrencyControlMode attribute include:
None
,
SipSession
or
SipApplicationSession
.
SipSession
is the value of this attribute when it is not present—and overridden—in server.xml.
<Service name="jboss.web" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="conf/dars/mobicents-dar.properties" concurrencyControlMode="SipApplicationSession" SipApplicationSession="1600">
Example 6.5. Permanently Changing Tunable Parameters by Editing JBoss's server.xml
Procedure 6.21. Tuning MSS for Tomcat Server Settings for Concurrency and Congestion Control
Open the
configuration file in your text editor.
$CATALINA_HOME/conf/server.xml
Find the Service element and add a concurrencyControlMode and/or a sipMessageQueueSize attribute to it.
The default value of the sipMessageQueueSize attribute is
1500
. That is the default value which is used even if the attribute is not present in server.xml. You will need to play around with this setting for the optimal value, which depends on the hardware running your SIP Servlets Server.
Possible values for the concurrencyControlMode attribute include:
None
,
SipSession
or
SipApplicationSession
.
SipSession
is the value of this attribute if when it is not present and overridden in server.xml.
<Service name="jboss.web" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="conf/dars/mobicents-dar.properties" concurrencyControlMode="SipApplicationSession" SipApplicationSession="1600">
Example 6.6. Permanently Changing Tunable Parameters by Editing Tomcat's server.xml
You can navigate to the dispatcher MBean from MSS for JBoss's JMX console. All changes performed at run time are effective immediately, but are not persisted across reboots (which, if you want to happen, would require editing your server's server.xml configuration file as well, or instead).
When editing the dispatcher MBean from MSS for JBoss's JMX console, values allowed for the concurrency control mode are
None
,
SipSession
or
SipApplicationSession
.
Finally, once you have installed Embedded Jopr, you can change the tunable parameters by pointing your browser at http://localhost:8080/embedded-jopr.
Telecommunications applications demand High-Availability (HA), fault tolerance, scalability and performance. Providing highly-available end-user applications that deal are performant and tolerant of faults is usually and primarily achieved through the use of clustering technologies. Clustering is a complex subject that is often used to collectively address a variety of techniques aimed at improving the high-availability and scalability of services and applications. Such techniques include distributed state replication, load balancing, and failover capabilities. The usage of any one of these techniques improves either reliability or performance, but for the sake of the other. It requires careful analysis of real-world scenarios to arrive at an architecture which represents the optimal balance of performance and reliability.
Based on experience with production deployments and extensive feedback from the Open Source community, Mobicents HA has undergone several iterations of refinement. In its current incarnation, the architecture can be described as a “star topology” with symmetric application servers and a smart, lightweight load-balancing element with built-in failover logic. The amount of state replication is kept to a minimum for maximum scalability with sufficiently-high reliability.
For purposes of clarity, the SIP Servlets High-Availability sections use terms—such as cluster —with meanings specific to the context of Mobicents SIP Servlets. Therefore, the following definitions are provided to clarify more precisely what is meant by the terms cluster , node , SIP Servlets Server and so on, in the subsequent sections, and in the context of Mobicents High-Availability.
The crux of possible confusion is this: any heterogeneous group of SIP Servlets Servers behind a SIP load balancer is, by definition, a cluster . Those SIP Servlets Servers can be either MSS for JBoss servers or MSS for Tomcat servers. However, a homogeneous group of MSS for JBoss servers served by a SIP load balancer, in addition to being a cluster, also possesses JBoss-specific clustering capabilities . Those clustering capabilities include, principally, state replication and the ability to fail over. Therefore, when specific clustering capabilities are spoken of, they are always referring to the context of a homogeneous cluster of MSS for JBoss server nodes served by a load balancer.
Glossary of Cluster-Related Terms
A Mobicents SIP Servlets Server refers to either a SIP Servlets-enabled JBoss Application Server (MSS for JBoss) or a SIP Servlets-enabled Tomcat Servlet Container (MSS for Tomcat). Anywhere the term SIP Servlets Server is used, you are free to substitute the JBoss or the Tomcat variety depending on the one you are interested in.
A node is simply a SIP Servlets Server in a cluster . In this document, a node can be either an MSS for JBoss server or an MSS for Tomcat server.
A cluster , as used in this document, refers simply to a group of one or more nodes , i.e. SIP Servlets Servers , behind a SIP load balancer. The minimum number of nodes in a cluster is one. The case of a cluster with one node almost always occurs in a degraded cluster : one in which other nodes, for some reason, have become unavailable.
The Mobicents SIP load balancer is not a full-fledged SIP Servlets Server itself. Rather, it is a simple proxy server whose primary purpose is to intelligently route SIP requests and replies between healthy and available SIP Servlets Servers residing in a cluster on a Local Area Network (LAN), and User Agents (UAs) accessing a SIP service or application from a Wide Area Network (WAN). The SIP load balancer therefore acts as a kind of gateway between a Wide Area Network with User Agents, and a Local Area Network wherein the SIP Servlets Server cluster nodes reside.
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.
Before reading further, you should ensure that you are familiar with the terminology employed across all sections of the Mobicents SIP Servlets High-Availability chapter: Section 6.1, “Mobicents SIP Servlets Server”.
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.
Each individual Mobicents SIP Servlets Server in the cluster is responsible for contacting the SIP load balancer and relaying its health status and regular “heartbeats” to it. From these health status reports and heartbeats, the SIP load balancer creates and maintains a list of all available and healthy nodes in the cluster. The load balancer will then forward SIP requests to and from these cluster nodes based upon a provisioning algorithm for as long as they are healthy and are still sending heartbeats. A failure to do so will cause the SIP load balancer to remove the unhealthy or unresponsive node from its list. In addition, mid-session and mid-call messages can be failed over. The Failover section goes into more detail about this aspect of the load balancer; see: Section 6.4.3, “MSS for JBoss: Failover Support”.
The SIP load balancer first receives SIP requests from endpoints on a port that is specified in its Configuration Properties configuration file. The SIP load balancer, using a round-robin algorithm, then selects a node to which it forwards the SIP requests. The load balancer will forward all same-session requests to the node first selected to initiate the session, as long as that node is healthy and available.
The Mobicents SIP load balancer adds itself to the Via header of requests so that responses return to the SIP Balancer before they are sent to the orginating endpoint. The load balancer also adds itself to the path of subsequent requests by adding Record-Route headers. It can thus handle mid-call failover by forwarding subsequent requests to a different node in the cluster if the node that had originally handled an initial request failed somehow fails or becomes unavailable. The SIP load balancer wil immediately fail over if it stops receiving heartbeats from a node, or receives an “unhealthy” status alert. As mentioned, supplying both of these to the SIP load balancer is the responsibility of the nodes themselves.
SIP Servlets Server extend the SipStandardService class, which extends the Tomcat StandardService class, which implements the Tomcat Service interface. In Tomcat's architecture, a service is an intermediate component which lives inside a server and ties one or more Connectors to exactly one Engine. When the service is started, the new SipStandardBalancerNodeService looks up its configuration and gets the address of the SIP load balancer and sends a heartbeat and health status to it, so as to identify itself as an available node of the cluster.
The parameters of the nodes are configurable through their MBean interfaces; information on their configuration is provided in the following sections.
Note that, in advanced configurations, it is also possible to run more than one SIP load balancer.
Software Prerequisites
Running the SIP load balancer requires at least one SIP Servlets Server as a client node, although you obviously cannot test or do anything interesting with your setup until you start at least two nodes. Therefore, before configuring the SIP load balancer, we should make sure we've installed a SIP Servlets Server first. The Mobicents SIP load balancer will work with a SIP Servlets-enabled JBoss Application Server or a SIP Servlets-enabled Tomcat Container.
However, if you intend to cluster multiple nodes for performance, reliability and failover purposes, then you will want to install and set up SIP Servlets-enabled JBoss AS nodes, because only they can be clustered, and not SIP-Servletized Tomcat Containers.
To install a SIP Servlet-enabled JBoss Application Server, follow the instructions here: Section 6.1.2, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.
To install a SIP Servlet-enabled Tomcat Servlet Container, follow these instructions: Section 6.1.3, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”.
You should ensure that you have downloaded the following files before installing and configuring:
First, you need to download the Mobicents SIP load balancer executable JAR file.
In addition, you must download the default Load Balancer Configuration Properties file. You will need to invoke the SIP load balancer with a modified copy of this file.
Installation is simple: put the SIP load balancer executable JAR file anywhere you like.
Configuring the SIP load balancer and the two SIP Servlets-enabled Server nodes is not difficult.
Procedure 6.22. Configuring the Mobicents SIP Load Balancer and Servlet Server Nodes
First, configure the SIP load balancer's Configuration Properties file which you downloaded by substituting valid values for your personal setup. Here is a sample lb.properties file; descriptions of the important lines are provided beneath.
host=127.0.0.1 internalPort=5065 externalPort=5060 #JSIP stack configuration javax.sip.STACK_NAME = SipBalancerForwarder javax.sip.AUTOMATIC_DIALOG_SUPPORT = off // You need 16 for logging traces. 32 for debug + traces. // Your code will limp at 32 but it is best for debugging. gov.nist.javax.sip.TRACE_LEVEL = 32 gov.nist.javax.sip.DEBUG_LOG = logs/sipbalancerforwarderdebug.txt gov.nist.javax.sip.SERVER_LOG = logs/sipbalancerforwarder.xml gov.nist.javax.sip.THREAD_POOL_SIZE = 64 gov.nist.javax.sip.REENTRANT_LISTENER = true
Example 6.7. Complete Sample lb.properties File
This is the local IP address, or interface, on which the SIP load balancer will listen for incoming requests.
This is the port on which the SIP load balancer will listen for incoming requests from SIP User Agents.
This is the port on which the SIP load balancer will forward incoming requests to available and healthy SIP Servlets Server cluster nodes.
The rest of the keys and properties in the Configuration Properties file can be used to tune the JAIN SIP stack, but do not need to be changed for our purposes. If you wish to tune the stack using these properties, refer to the JAIN SIP JavaDoc on the SipStack and SipStackImpl classes for further information on them.
Configure the server.xml configuration files for all of your Servlet container nodes according to the following scheme. Pay special attention to the location of the server.xml configuration file. On MSS for Tomcat server installations, this file will be located in <topmost_directory>/conf, and for MSS for JBoss installations
with JBoss clustering support for session replication and other capabilities
, you want to edit the server.xml file for the “all” Configuration Profile. This file is therefore located in the server/all/deploy/jboss-web.deployer directory. If, on the other hand, you will
not
be utilizing JBoss's clustering capabilities on your MSS for JBoss instance, then you will probably be using the “default” Configuration Profile. In that case, you would want to edit the server.xml file in server/default/deploy/jboss-web.deployer.
If you are unsure whether to run the “all” or default profile on your MSS for JBoss installation(s), refer to Section 6.4.2, “MSS for JBoss: Clustering Support”.
the className attribute of the Service element should have the value org.mobicents.servlet.sip.startup.failover.SipStandardBalancerNodeService instead of org.mobicents.servlet.sip.startup.SipStandardService.
Add an attribute called “
balancers
” to the Service element which has as its values the IP address (or addresses) of the SIP load balancer(s) to which it should send heartbeats.
Procedure 6.23. Running the SIP Load Balancer and Servlet Server Nodes
First, start the SIP load balancer, making sure to pass as an argument the name of your Configuration Properties file (lb.properties in this example). In the Linux terminal, or using the Windows Command Prompt, you can start the SIP Load Balance by issuing a command similar to this one:
java -jar sip-balancer-1.0-20080829.103906-21-jar-with-dependencies.jar lb-configuration.properties
Running the SIP load balancer should produce output similar to the following:
silas@localhost ~ $ java -jar sip-balancer-1.0-20080829.103906-21-jar-with-dependencies.jar lb-configuration.properties Oct 21, 2008 1:10:58 AM org.mobicents.tools.sip.balancer.SIPBalancerForwarder start INFO: Sip Balancer started on address 127.0.0.1, external port : 5060, port : 5065 Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer INFO: Node registry starting... Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer INFO: Node expiration task created Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer INFO: Node registry started
In the output above, you can see the IP address on which the SIP load balancer is listening, as well as on which external and internal ports it is paying attention.
All well and good so far, but we're still in need of SIP Servlets Server nodes. Your nodes can run atop either the JBoss Application Server or the Tomcat Servlet Container. You should have already installed the binary distributions for type (or types) of SIP Servlets Server you will run as client nodes of the SIP load balancer (see Software Prerequisites if you have not). And finally, you can simply use your server's server.xml configuration file [8], nearly-unchanged, to configure the client nodes. Because you will have more than one client node, you should assign different ports for each of them to listen on for HTTP and/or SIP connections. Here is the relevant portion of the server.xml configuration file where you should change the value for each new node you add to the cluster:
Finally, start all of your SIP load balancer client nodes.
Deploy the same application, let's say location service on both nodes (you need to deploy the application manually on both nodes, when deployed on one node it won't deploy automatically in the whole cluster for now and don't forget to setup the dar file in the server.xml on both nodes neither)
Start a sip client with following sip address sip:sender@sip-servlets-com on port 5055, with outbound proxy the sip-balancer 127.0.0.1:5060
Start a second sip client with following sip address sip:receiver-failover@sip-servlets.com on port 5090
From first sip client, start a call to sip:receiver-failover@sip-servlets.com. Tear down the call when you're done
Redo it another, from first sip client, start a call to sip:receiver-failover@sip-servlets.com. Tear down the call when you're done. The request should have been handled by the other node
Assuming that you started the JBoss Application Server as a foreground process in the Linux terminal, the easiest way to stop it is by pressing the Ctrl + c key combination in the same terminal in which you started it.
This should produce similar output to the following:
^COct 21, 2008 1:11:57 AM org.mobicents.tools.sip.balancer.SipBalancerShutdownHook run INFO: Stopping the sip forwarder
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.
As the SIP Servlets Server employs JBoss AS as its servlet container and takes advantage of its capabilities, including clustering and failover, familiarity with the basics of JBoss Clustering is helpful. Refer to this chapter in the Clustering Guide for background or if you wish to dig further: JBoss Application Server Clustering Guide.
Software Prerequisites
Before proceeding, you should follow the instructions for installing, configuring, running and testing MSS for JBoss from the binary distribution:
The easiest way to set up a cluster of SIP Servlets-enabled JBoss Application Servers is to install, configure and test the binary distribution on one machine, and then simply copy the entire installation (directory) to the other machines in the cluster. This is the approach taken in this chapter.
Once installed, the MSS for JBoss binary distribution requires only minor configuration in order to enable clustering. SIP and HTTP session state clustering are preconfigured and ready-to-go straight out of the binary distribution. However, to enable session replication in your node, you must tag it as <distributable/> in the web.xml descriptor.
You will notice that the following instructions modify one or more properties in the configuration files for the “all” Server Configuration Profile. This is evident in the path names given below. When we start each MSS for JBoss node, we will invoke run.sh (or run.bat) with the -c all option, which activates the clustering capabilities for that node. The server will then consult the configuration files under the <topmost_directory>/server/all/ directory, and
not
in the the <topmost_directory>/server/default/ subdirectories. Therefore, it is important to modify the correct files.
To do so, open the web.xml configuration file, which lives in the <topmost_directory>/server/all/deploy/jboss-web.deployer/conf/ directory, and add the empty element <distributable/> as a child of the document root element, web-app:
<?xml version="1.0" encoding="utf-8"?><?xml version="1.0" encoding="ISO-8859-1"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <!-- ======================== Introduction ============================== --> <!-- This document defines default values for *all* web applications --> <!-- loaded into this instance of Tomcat. As each application is --> <!-- deployed, this file is processed, followed by the --> <!-- "/WEB-INF/web.xml" deployment descriptor from your own --> <!-- applications. --> <!-- --> <!-- WARNING: Do not configure application-specific resources here! --> <!-- They should go in the "/WEB-INF/web.xml" file in your application. --> <!-- =========== Common Context Params ================================== --> <!-- JBossInjectionProvider provides resource injection for managed beans. --> <!-- See JSF 1.2 spec section 5.4 for details. --> <distributable/> <context-param> <param-name>com.sun.faces.injectionProvider</param-name> <param-value>org.jboss.web.jsf.integration.injection.JBossInjectionProvider</param-value> </context-param>
Example 6.9. Enabling Node Session Replication in the web.xml Deployer
This one configuration change is sufficient for enabling clustering capabilities in MSS for JBoss servers. For further information on session replication and clustering with JBoss, refer to Enabling session replication in your application in the JBoss Application Server Getting Started Guide.
Clustering with MSS for JBoss nodes requires running all of the nodes using the “all” Server Configuration Profile, which is specified when you invoke run.sh or run.bat.
To run the server on Linux using the “all” Configuration Profile, start the server with the following command:
mss-jboss-0.6]$ ./bin/run.sh -c all
To run the server on Windows using the “all” Configuration Profile, open the Command Prompt, change your folder to the topmost folder of your MSS for JBoss installation, and issue the following command:
C:\Users\Me\My Downloads\mss-jboss-0.6>bin\run.bat -c all
Individual nodes in the cluster should be stopped one-by-one, followed by the SIP load balancer. Refer to:
Stopping the SIP load balancer: Section 6.4.1.1.7, “Stopping”
Stopping MSS for JBoss: Section 6.1.2.7, “Stopping”
Stopping MSS for Tomcat: Section 6.1.3.6, “Stopping”
To test your MSS for JBoss cluster setup for mid-call failover, refer to:
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:
There is no need for standby nodes, because the remaining nodes in a degraded cluster automatically and transparently (to the user) take on the load of the failed node. This can be done because both the SIP load balancer and SIP Servlet-enabled JBoss Application Servers support mid-call failover.
There is no need to ensure that requests are directed to the “right node”, because in a SIP Servlets-enabled JBoss Application Server (or Mobicents JAIN SLEE server) cluster, any node can serve any request to any User Agent (UA).
All hardware is in use, reducing costs.
Maintenance is easier, due to all nodes having nearly-identical configurations.
Procedure 6.24. Preparing for Clustering
Modify the JBOSS_HOME environment variable in the prepare-jboss-server-for-clustering-failover-network.sh shell script so that it points to the topmost directory of your MSS for JBoss installation (the one of which bin/ is a subdirectory).
Replace the hard-coded IP address in the files used by the scripts with your own IP address.
The easiest way to do this is to use an editor which allows you to search (and perhaps replace) all of the scripts and files for “192.168.1.21”.
On the Linux command line, you can use the grep command to find all of the files containing the “192.168.1.21” string of characters:
clustering]$ grep "192.168.1.21" *
Then, you can use a similar command to open all the files in which that hard-coded IP address is found, for easy-editing (we'll open them in the Gnome Text Editor, gedit , in this example):
clustering]$ gedit $(grep "192.168.1.21" *) &
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.
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 is the Servlets Server, the application, container and Location Service perform the following steps:
A user—let's call her Alice—makes a call to sip:receivers@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
Software Prerequisites
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-binary-SIP_Servlets_Server_with_JBoss-Installing_Configuring_and_Running.
You can find detailed instructions on installing MSS for Tomcat here: section-binary-SIP_Servlets_Server_with_Tomcat-Installing_Configuring_and_Running.
The Location 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 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.
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 hierachy. Which directory depends on whether you are using the Location Service with MSS for JBoss or with MSS for Tomcat:
Place location-service-1.1.war into the
directory, and JBOSS_HOME/server/default/deploy/locationservice-dar.properties into the
directory.JBOSS_HOME/server/default/conf/dars/
Place location-service-1.1.war into the
directory, and CATALINA_HOME/webapps/locationservice-dar.properties into the
directory.CATALINA_HOME/conf/dars/
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:
Open the
configuration file and find the JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xmlService 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 6.10. 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.
Open the
configuration file and find the CATALINA_HOME/conf/server.xmlService 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 6.11. 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.
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-binary-SIP_Servlets_Server_with_JBoss-Running.
To learn how to run the SIP Servlets-enabled Tomcat Container, refer to section-binary-SIP_Servlets_Server_with_Tomcat-Running.
The following procedure shows how to test the Location Service.
Procedure 6.25.
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.
To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to section-binary-SIP_Servlets_Server_with_JBoss-Stopping.
To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to section-binary-SIP_Servlets_Server_with_Tomcat-Stopping.
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:
Procedure 6.26. Diameter Event-Changing Service Step-By-Step
A user, Alice, makes a call to sip:receiver@sip-servlets.com. The INVITE is received by the servlet container, which sends a request to debit Alice's account to the Charging Server. The servlet container then invokes the location service.
the Location Service determines, without using the SIP protocol itself, where the callee—or receiver—is registered. The callee may be registered at two locations identified by 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 simultaneously, without record-routing and without using supervised mode.
One of the destinations returns 200 (OK), and so the container cancels the other.
The 200 (OK) is forwarded upstream to Alice and the call setup is carried out as usual.
If neither or none of the registered destinations accepts the call, a Diameter Accounting-Request for refund is sent to the Diameter Charging Server in order to debit the already-credited €10.00
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.
Software Prerequisites
Before proceeding, you should follow the instructions for installing, configuring, running and testing MSS for JBoss from the binary distribution.
First, download the Web Application Archive (WAR) file corresponding to this example, the current version of which is named diameter-event-charging-1.0.war, from http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/diameter-event-charging/1.0/.
Secondly, download the corresponding Disk ARchive (DAR) configuration file here: , from http://www.mobicents.org/diametereventcharging-dar.properties.
Finally, you will need to download the Ericsson Charging Emulator, version 1.0, from http://www.ericsson.com/mobilityworld/developerszonedown/downloads/tools/charging_solutions/ChargingSDK-1_0_D31E.zip.
Place the diameter-event-charging-1.0.war WAR archive into the jboss_home/server/<profile>/deploy directory, where <deploy> is your Configuration Profile, whether “default” or “all” (the latter if you are using MSS for JBoss's clustering capabilities).
Place the diametereventcharging-dar.properties DAR file in your
directory.$JBOSS_HOME/server/<profile>/conf/dars
Finally, open the terminal, move into the directory to which you downloaded the Ericsson Charging SDK (for the sake of this example, we will call this directory charging_sdk), and then unzip the downloaded zip file (you can use Java's jar command for this:-xvf
~]$ cd charging_sdk charging_sdk]$ jar -xvf ChargingSDK-1_0_D31E.zip
Alternatively, you can use Linux's unzip command to do the dirty work:
charging_sdk]$ unzip ChargingSDK-1_0_D31E.zip
To configure the server for the Event-Changing example, simply open the server.xml configuration file in your server's
directory, and edit the value of the $JBOSS_HOME/server/<profile>/deploy/jboss-web.deployer/darConfigurationFileLocation attribute of the Service element so that it is “
conf/dars/mobicents-dar.properties
”. For example:
...
<Service name="jboss.web"
className="org.mobicents.servlet.sip.startup.SipStandardService"
sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl"
sipApplicationRouterClassName="org.mobicents.servlet.sip.router.DefaultApplicationRouter"
darConfigurationFileLocation="conf/dars/mobicents-dar.properties">
...
Example 6.12. Editing the darConfigurationFileLocation Attribute of the Service Tag
Procedure 6.27. Diameter Event-Changing Service
First, you should run your MSS for JBoss server. For instructions on doing so, refer to Section 6.1.2.5, “Running”.
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 command:PPSDiamEmul.jar
~]$ java -jar PPSDiamEmul.jar
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.
The Mobicents team recommends one of the following SIP phones, and has found that they work well: the 3CX Phone, teh SJ Phone or the WengoPhone.
Procedure 6.28. Using the Diameter Event-Changing Service
Configure the Ericsson SDK Charging Emulator
Once you have started the Charging Emulator, you should configure it exactly as portrayed in the screenshot.
Set the Peer Id to:
aaa://127.0.0.1:21812
Set the Realm to:
mobicents.org
Set the Host IP to:
127.0.0.1
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.
Before making a call, open the Config → Options 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.
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 .
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.
Blocked contacts are currently hard-coded addresses. This model is evolving towards the eventual use of a database.
Here is the current hard-coded list of blocked contacts:
sip:blocked-sender@sip-servlets.com
sip:blocked-sender@127.0.0.1
Software Prerequisites
The Call-Blocking 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-binary-SIP_Servlets_Server_with_JBoss-Installing_Configuring_and_Running.
You can find detailed instructions on installing MSS for Tomcat here: section-binary-SIP_Servlets_Server_with_Tomcat-Installing_Configuring_and_Running.
The Call-Blocking 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-Blocking Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-blocking/1.1/call-blocking-1.1.war.
Download the Call-Blocking Service's DAR file from here: http://www.mobicents.org/call-blocking-servlet-dar.properties.
Both the call-blocking-1.1.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 hierachy. Which directory depends on whether you are using the Call-Blocking Service with MSS for JBoss or with MSS for Tomcat:
Place call-blocking-1.1.war into the
directory, and JBOSS_HOME/server/default/deploy/call-blocking-servlet-dar.properties into the
directory.JBOSS_HOME/server/default/conf/dars/
Place call-blocking-servlet-dar.properties into the
directory, and CATALINA_HOME/webapps/call-blocking-servlet-dar.properties into the
directory.CATALINA_HOME/conf/dars/
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:
Open the
configuration file and find the JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xmlService element. Add an attribute to it called
darConfigurationFileLocation
, and set it to
conf/dars/call-blocking-servlet-dar.properties
:
<Service name="jboss.web" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="conf/dars/call-blocking-servlet-dar.properties">
Example 6.13. Editing MSS for JBoss's server.xml for the Call-Blocking Service
Make sure that the configuration file only contains one darConfigurationFileLocation