Platform User Guide
A Complete Set of Guides to the JBoss Communications Platform
Abstract
JBCP, the JBoss Communications Platform, is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. JBCP serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes) by leveraging J2EE to enable the convergence of data and video in Next-Generation
Intelligent Network (NGIN) applications.
The JBoss Communications Platform enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration
and Presence-Sensing. Out-of-the-box monitoring and management of JBCP components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise
applications with end points such as the Web, Customer Relationship
Management (CRM) systems and Service-Oriented Architectures (SOAs). The JBoss Communications Platform is the natural choice for telecom Operations Support Systems
(OSSes) and Network Management Systems (NMSes).
In addition to telecom, JBCP is suitable for a variety of problem domains demanding an
Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial
trading, online gaming, (RFID) sensor network integration, and distributed control.
- Platform Installation Guide
- JAIN SLEE Server User Guide
- SIP Servlets Server User Guide
- Preface
- 1. Introduction to the SIP Servlets Server
- 2. SIP Servlets Server-Installing, Configuring and Running
- 3. Services for Mobicents SIP Servlets
- 4. Advanced Features of the SIP Servlets Server
- A. Revision History
- Index
- Media Server User Guide
- Preface
- 1. Introduction to the Mobicents Media Server
- 2. Installing the Mobicents Media Server
- 3. Configuring the Mobicents Media Server
- 4. Controlling and Programming the Mobicents Media Server
- 5. MMS: Event Packages
- 6. MMS Demonstration Example
- 7. MMS: Best Practices
- A. Revision History
- Index
- SIP Presence Service User Guide
- Preface
- 1. Introduction to the Mobicents SIP Presence Service
- 2. Installing the SIP Presence Service
- 3. Mobicents SIP Presence Server
- 4. Mobicents XML Document Management Server
- 5. Mobicents Resource List Server
- A. Revision History
- Index
JBoss Communications Platform 1.2.0
Platform Installation Guide
The JBoss Communications Platform Installation Guide
Edition 1.0
Legal Notice
Copyright © 2009 Red Hat Inc. This material may only be distributed subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License (which is presently available at http://creativecommons.org/licenses/by-nc-sa/3.0/).
Red Hat, the "Shadow Man" logo and JBoss are registered trademarks of Red Hat,
Inc. in the United States and other countries.
All other trademarks referenced herein are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072USAPhone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588Research Triangle Park, NC 27709USA
Abstract
JBCP, the JBoss Communications Platform, is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. JBCP serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes) by leveraging J2EE to enable the convergence of data and video in Next-Generation
Intelligent Network (NGIN) applications.
The JBoss Communications Platform enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration
and Presence-Sensing. Out-of-the-box monitoring and management of JBCP components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise
applications with end points such as the Web, Customer Relationship
Management (CRM) systems and Service-Oriented Architectures (SOAs). The JBoss Communications Platform is the natural choice for telecom Operations Support Systems
(OSSes) and Network Management Systems (NMSes).
In addition to telecom, JBCP is suitable for a variety of problem domains demanding an
Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial
trading, online gaming, (RFID) sensor network integration, and distributed control.
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:
To see the contents of the filemy_next_bestselling_novelin your current working directory, enter thecat my_next_bestselling_novelcommand at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.
Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:
Press Enter to execute the command.Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session.
The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in
Mono-spaced Bold. For example:
File-related classes includefilesystemfor file systems,filefor files, anddirfor directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).To insert a special character into a gedit file, choose from the main menu bar. Next, choose from the Character Map menu bar, type the name of the character in the Search field and click . The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the button. Now switch back to your document and choose from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.
Note the shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select from the sub-menu in the menu of the main menu bar' approach.
Mono-spaced Bold ItalicProportional Bold Italic
Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, typesshat a shell prompt. If the remote machine isusername@domain.nameexample.comand your username on that machine is john, typessh john@example.com.Themount -o remountcommand remounts the named file system. For example, to remount thefile-system/homefile system, the command ismount -o remount /home.To see the version of a currently installed package, use therpm -qcommand. It will return a result as follows:package.package-version-release
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.
1.2. Pull-quote Conventions
Two, commonly multi-line, data types are set off visually from the surrounding text.
Output sent to a terminal is set in
Mono-spaced Roman and presented thus:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in
Mono-spaced Roman but are presented and highlighted as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring Important boxes won't cause data loss but may cause irritation and frustration.
Warning
A Warning should not be ignored. Ignoring warnings will most likely cause data loss.
2. We Need Feedback!
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product JBoss Communications Platform.
When submitting a bug report, be sure to mention the manual's identifier: Platform_Installation_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
Chapter 1. Installing the JBoss Communications Platform
You can install the JBoss Communications Platform by downloading the binary distribution.
Before installing the JBoss Communications Platform, you should ensure that you have installed a suitable Java Development Kit or Java Runtime Environment.
1.1. Java Development Kit: Installing, Configuring and Running
The JBoss Communications Platform is written in Java; therefore, before running any JBCP 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 JBCP must be version 5 or higher[1].
Should I Install the JRE or JDK?
Although you can run JBCP servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, JBCP-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?
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.
Downloading
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 JBCP in a production environment.
Installing
The following procedures detail how to install the Java Development Kit on both Linux and Windows.Procedure 1.1. Installing the JDK on Linux
- Regardless of which file you downloaded, you can install it on Linux by simply making sure the file is executable and then running it:
~]$ chmod +x "jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin" ~]$ ./"jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin"
You Installed Using the Non-RPM Installer, but Want the SysV Service Scripts
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/.
Important
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 1.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
Configuring your system for the JDK consists in two tasks: setting theJAVA_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.
- Setting the
JAVA_HOMEEnvironment Variable on Generic Linux - After installing the JDK, you must ensure that the
JAVA_HOMEenvironment variable exists and points to the location of your JDK installation.Setting the
You can determine whetherJAVA_HOMEEnvironment Variable on LinuxJAVA_HOMEis set on your system byechoing it on the command line:~]$ echo $JAVA_HOME
IfJAVA_HOMEis 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~/.bashrcconfiguration 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 JBCP (any environment variablesexported from~/.bashrcfiles are local to that user). - Setting
java,javacandjava_sdk_1.5.0Using thealternativescommand Selecting the Correct System JVM on Linux using
On systems with thealternativesalternativescommand, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as whichjavaandjavacexecutables should be run when called.As the root user, call/usr/sbin/alternativeswith the--config javaoption 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 thejavaexecutable. In thealternativesinformation printout above, a plus (+) next to a number indicates the one currently being used. As peralternatives' 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 thejavaccommand and thejava_sdk_1.5.0environment variable, as the root user:~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
- Setting the
JAVA_HOMEEnvironment Variable on Windows - For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
Testing
Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in yourPATH, run the java -version command in the terminal from your home directory:
~]$ java -version java version "1.5.0_16" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03) Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling
There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily usingalternatives, and/or by setting JAVA_HOME.
Uninstalling the JDK on Linux
On RPM-based systems, you can uninstall the JDK using theyum remove <jdk_rpm_name> command.
Uninstalling the JDK on Windows
On Windows systems, check the JDK entry in theStart menu for an uninstall command, or use Add/Remove Programs.
1.2. JBoss Communications Platform: Installing, Configuring and Running
1.2.1. Pre-Install Requirements and Prerequisites
You should ensure that a few requirements have been met before continuing with the install.
Hardware Requirements
- Sufficient Disk Space
- You must have sufficient disk space in order to install the JBoss Communications Platform. Once unzipped, version 1.2.0 of the binary release requires at least 310 MB of free disk space. Keep in mind that disk space requirements may change from release to release.
- Anything Java Itself Will Run On
- The JBoss Communications Platform JAIN SLEE Server is 100% Java, as are its bundled servers, resource adapters and demonstration examples. The JBCP JAIN SLEE Server will run on the same hardware that the JBoss Application Server runs on.
Software Prerequisites
- JDK 5 or Higher
- A working installation of the Java Development Kit (JDK) version 5 or higher is required in order to run JBoss Communications Platform servers. Note that the JBoss Application Server is a runtime dependency of the JAIN SLEE Server, and is included along with it in the JBoss Communications Platform release.
1.2.2. Downloading
The JBoss Communications Platform can be downloaded from the Customer Service Portal.
1.2.3. Installing
Once the requirements and prerequisites have been met and you have downloaded the binary distribution zip file, you are ready to install the JBoss Communications Platform. Follow the instructions below for your operating system platform, whether Linux or Windows.
Use Version Numbers Relevant to Your Installation!
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 1.3. Installing the JBoss Communications Platform Binary Distribution on Linux
- Assuming that you downloaded the binary distribution zip file to your home folder, you want to create a subdirectory to which to unzip the JBoss Communications Platform 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 binary distribution you downloaded.
~]$ mkdir "jbcp-
<version>" - Move the downloaded zip file into the directory you just created:
~]$ mv "JBCP-1.2.0.GA-jboss-eap-4.3.zip" "jbcp-
<version>" - Move into that directory:
~]$ cd "jbcp-
<version>" - Finally, use Java's
jarcommand to extract the contents of the zip file into the current directory, thus completing the install:-xvfjbcp-
<version>]$ jar -xvf "JBCP-1.2.0.GA-jboss-eap-4.3.zip"- Alternatively, if Linux's
unziputility is present on your system or is installable, you can use it in lieu of Java'sjarcommand:-xvfjbcp-
<version>]$ unzip "JBCP-1.2.0.GA-jboss-eap-4.3.zip"Note
You can also useunzip's-d<unzip_to_location>
- To free disk space, you may want to delete the zip file once you've extracted its contents:
jbcp-
<version>]$ rm "JBCP-1.2.0.GA-jboss-eap-4.3.zip"
Procedure 1.4. Installing the JBoss Communications Platform Binary Distribution on Windows
- For this example, we'll assume that you downloaded the binary distribution zip file to the
My Downloadsfolder. First, using Windows Explorer, create a subfolder inMy Downloadsto 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 JBoss Communications Platform binary distribution you downloaded. In these instructions, we will refer to this folder asjbcp-.<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
jarcommand to extract the binary distribution files from the zip archive. To use this method instead, first move the downloaded zip file from-xvfMy Downloadsto the folder that you just created to hold the JBoss Communications Platform files. - Then, open the Windows Command Prompt and navigate to the folder holding the archive using the
cdcommand:Opening the Command Prompt from Windows Explorer
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 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\jbcp-
<version>" - Finally, use the
jarcommand to extract the archive contents into the current folder.-xvfC:\Users\Me\My Downloads\jbcp-
<version>>jar -xvf "JBCP-1.2.0.GA-jboss-eap-4.3.zip"
- At this point, you may want to move the folder holding the JBoss Communications Platform binary files (in this example, the folder named
jbcp-) to another location. This step is not strictly necessary, but it is probably a good idea to move the folder from<version>My Downloadsto 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\jbcp-
<version>>delete "JBCP-1.2.0.GA-jboss-eap-4.3.zip"
1.2.4. Configuring (and Setting the JBOSS_HOME Environment Variable)
1.2.4.1. Setting the JBOSS_HOME Environment Variable
The JBoss Communications Platform (JBCP) is built on top of the JBoss Enterprise Application Platform (JBoss EAP). You do not need to set the
JBOSS_HOME environment variable to run any of the JBoss Communications Platform servers unless JBOSS_HOME is already set.
The best way to know for sure whether
JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.
Checking to See If JBOSS_HOME is Set on Linux
At the command line,echo$JBOSS_HOME to see if it is currently defined in your environment:
~]$ echo $JBOSS_HOME
Silence on the command line (a completely blank line) means that it is not set, in which case you can proceed with running the JBoss Communications Platform.
Checking to See if JBOSS_HOME is Set on Windows
For information on determining whether environment variables are set in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.
If
JBOSS_HOME is already set on your system, then you have three options:
unsetit, which only takes effect for the current session and is therefore not advised;- find where
JBOSS_HOMEis defined, such as in your local~/.bashrcstartup script in Linux, or, possibly, system-wide in/etc/bashrc, and remove it or comment it out; - or point it to the correct location, in which case you should refer to the following instructions on how to set
JBOSS_HOME.
Setting the JBOSS_HOME Environment Variable on Linux
TheJBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform that you installed. As another hint, this topmost directory contains a bin subdirectory.
Setting
JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Linux, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.
Procedure 1.5. To Set JBOSS_HOME on Linux...
- Open the
~/.bashrcstartup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:export JBOSS_HOME="/home/
<username>/<path>/<to>/<install_directory>" - Save and close the
.bashrcstartup script. - You should
sourcethe.bashrcscript to force your change to take effect, so thatJBOSS_HOMEbecomes set for the current session[2].~]$ source ~/.bashrc
- Finally, ensure that
JBOSS_HOMEis set in the current session, and actually points to the correct location:Note
The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output,JBOSS_HOMEhas been set correctly to thetopmost_directoryof the JBCP installation. Note that if you are installing one of the standalone JBCP servers (with JBoss AS bundled!), thenJBOSS_HOMEwould point to thetopmost_directoryof your server installation.~]$ echo $JBOSS_HOME /home/silas/jboss-eap-4.3/jboss-as
Setting the JBOSS_HOME Environment Variable on Windows
TheJBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform that you installed. As another hint, this topmost directory contains a bin subdirectory.
For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.
1.2.5. Running
Once installed, you can run the JBoss Communications Platform JAIN SLEE Server by executing the one of the startup scripts in the
<install_directory>/jboss-eap-4.3/jboss-as/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 1.6. Running the JAIN SLEE Server on Linux
- Change your working directory to the JAIN SLEE Server's topmost directory (the one to which you extracted the zip file's contents):
~]$ cd "jbcp-
<version>" - (Optional) Ensure that the
jboss-eap-4.3/jboss-as/bin/run.shstart script is executable:jbcp-
<version>]$ chmod +x "jboss-eap-4.3/jboss-as/bin/run.sh" - Finally, execute the
run.shBourne shell script:jbcp-
<version>]$ "./jboss-eap-4.3/jboss-as/bin/run.sh"- Instead of executing the Bourne shell script to start the server, you may alternatively run the
run.jarexecutable Java archive in thejboss-eap-4.3/jboss-as/bin/directory:jbcp-
<version>]$ java -jar "jboss-eap-4.3/jboss-as/bin/run.jar"
Procedure 1.7. 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
<install_directory>\jboss-eap-4.3\jboss-as\bin\subfolder. - Although not the preferred way (see below), it is possible to start the JAIN SLEE Server by double-clicking on the
run.batexecutable 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
<install_directory>\jboss-eap-4.3\jboss-as\bin\folder in Windows Explorer, or you can open the Command Prompt via the Start menu and navigate to the correct folder:C:\Users\Me\My Downloads> cd "jbcp-
<version>" - Start the JAIN SLEE Server by running the executable
run.batbatch file:C:\Users\Me\My Downloads\jbcp-
<version>>jboss-eap-4.3\jboss-as\bin\run.bat- It is also possible to start the JAIN SLEE Server by running the
run.jarexecutable Java archive:C:\Users\Me\My Downloads\jbcp-
<version>>java -jar jboss-eap-4.3\jboss-as\bin\run.jar
1.2.6. Using
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 the JBoss Communications Platform JAIN SLEE Server User Guide.
1.2.7. Stopping
Detailed instructions for stopping the JAIN SLEE Server are given below, arranged by operating system. Note that if you properly stop the server, you will see lines similar to the following as the last output in the Linux terminal or Command Prompt:
16:44:29,745 INFO [Server] Shutdown complete Shutdown complete Halting VM
Procedure 1.8. 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.shBourne shell script in the<install_directory>/jboss-eap-4.3/jboss-as/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):~]$ cd "jbcp-
<version>" - (Optional) Ensure that the
jboss-eap-4.3/jboss-as/bin//shutdown.shstart script is executable:jbcp-
<version>]$ chmod +x "jboss-eap-4.3/jboss-as/bin/shutdown.sh" - Finally, run the
shutdown.shexecutable Bourne shell script, and remember to add the-Soption (which is the short option for--shutdown) as a command line argument:jbcp-
<version>]$ "./jboss-eap-4.3/jboss-as/bin/shutdown.sh" -S- Instead of executing the Bourne shell script to stop the server, you may alternatively run the
shutdown.jarexecutable Java archive to do so (and remembering, again, to add the-Scommand line argument):jbcp-
<version>]$ java -jar "jboss-eap-4.3/jboss-as/bin/shutdown.jar" -S
Procedure 1.9. Stopping the JAIN SLEE Server on Windows
- Stopping the JAIN SLEE Server on Windows consists in executing either the
shutdown.bator theshutdown.jarexecutable file in the<install_directory>\jboss-eap-4.3\jboss-as\bin\subfolder of the JBoss Communications Platform binary distribution. Make sure to add the-Soption (which is the short option for--shutdown) as a command line argument.C:\Users\Me\My Downloads\jbcp-
<version>>jboss-eap-4.3\jboss-as\bin\shutdown.bat -S- Alternatively, you can execute the
shutdown.jarJava archive by running thejavacommand, and remembering to add the-jar-Soption as a command line argument:C:\Users\Me\My Downloads\jbcp-
<version>>java -jar jboss-eap-4.3\jboss-as\bin\shutdown.jar -S
1.2.8. Testing
For information on testing the JAIN SLEE Server, refer to the JBoss Communications Platform JAIN SLEE Server User Guide.
1.2.9. Uninstalling
To uninstall the JBoss Communications Platform, simply delete the directory you decompressed the binary distribution archive into.
[1] At this point in time, it is possible to run most JBCP servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.
[2]
Note that any other terminals which were opened prior to your having altered .bashrc will need to source~/.bashrc as well should they require access to JBOSS_HOME.
Revision History
| Revision History | |||
|---|---|---|---|
| Revision 2.0 | Fri Mar 06 2009 | ||
| |||
| Revision 1.0 | Wed Mar 04 2009 | ||
| |||
Index
F
- feedback
- contact information for this manual, We Need Feedback!
JBoss Communications Platform 1.2.0
JAIN SLEE Server User Guide
The First Open Source JAIN SLEE 1.0-Certified Application Server
Edition 1.0
Legal Notice
Copyright © 2009 Red Hat Inc. This material may only be distributed subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License (which is presently available at http://creativecommons.org/licenses/by-nc-sa/3.0/).
Red Hat, the "Shadow Man" logo and JBoss are registered trademarks of Red Hat,
Inc. in the United States and other countries.
All other trademarks referenced herein are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072USAPhone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588Research Triangle Park, NC 27709USA
Abstract
JBCP, the JBoss Communications Platform, is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. JBCP serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes) by leveraging J2EE to enable the convergence of data and video in Next-Generation
Intelligent Network (NGIN) applications.
The JBoss Communications Platform enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration
and Presence-Sensing. Out-of-the-box monitoring and management of JBCP components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise
applications with end points such as the Web, Customer Relationship
Management (CRM) systems and Service-Oriented Architectures (SOAs). The JBoss Communications Platform is the natural choice for telecom Operations Support Systems
(OSSes) and Network Management Systems (NMSes).
In addition to telecom, JBCP is suitable for a variety of problem domains demanding an
Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial
trading, online gaming, (RFID) sensor network integration, and distributed control.
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:
To see the contents of the filemy_next_bestselling_novelin your current working directory, enter thecat my_next_bestselling_novelcommand at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.
Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:
Press Enter to execute the command.Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session.
The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in
Mono-spaced Bold. For example:
File-related classes includefilesystemfor file systems,filefor files, anddirfor directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).To insert a special character into a gedit file, choose from the main menu bar. Next, choose from the Character Map menu bar, type the name of the character in the Search field and click . The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the button. Now switch back to your document and choose from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.
Note the shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select from the sub-menu in the menu of the main menu bar' approach.
Mono-spaced Bold ItalicProportional Bold Italic
Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, typesshat a shell prompt. If the remote machine isusername@domain.nameexample.comand your username on that machine is john, typessh john@example.com.Themount -o remountcommand remounts the named file system. For example, to remount thefile-system/homefile system, the command ismount -o remount /home.To see the version of a currently installed package, use therpm -qcommand. It will return a result as follows:package.package-version-release
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.
1.2. Pull-quote Conventions
Two, commonly multi-line, data types are set off visually from the surrounding text.
Output sent to a terminal is set in
Mono-spaced Roman and presented thus:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in
Mono-spaced Roman but are presented and highlighted as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring Important boxes won't cause data loss but may cause irritation and frustration.
Warning
A Warning should not be ignored. Ignoring warnings will most likely cause data loss.
2. We Need Feedback!
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product JBoss Communications Platform.
When submitting a bug report, be sure to mention the manual's identifier: Platform_Installation_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
Chapter 1. Introduction to the JAIN SLEE Server
JBoss Communications Platform JAIN SLEE provides a highly-scalable, event-driver application server with a robust component model and a fault-tolerant execution environment. JBoss Communications Platform JSLEE 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. The Web and SIP can be combined to achieve a more sophisticated and natural user experience.
Overview of JAIN SLEE Server components
The JBoss Communications Platform enables the composition of Service Building Blocks (SBBs) such as call control, billing, user-provisioning, administration, and presence-sensing features. The JAIN SLEE 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 JBCP components is achieved via SLEE standard-based Java Management Extensions (JMXes) and Simple Network Management Profile (SNMP) interfaces.
Beyond telecommunications, the JBoss Communications Platform is applicable to a wider variety of problems demanding high-volume, low-latency signaling. Examples include financial trading, online gaming, Radio Frequency Identification (RFID) sensor network integration, and distributed control.
Chapter 2. ERROR
Chapter 3. Working with Resource Adapters
3.1. Deploying and Undeploying Resource Adapters
Resource adapters can be deployed using the Mobicents Management Console or, alternatively, by invoking
ant tasks, or by copying deployable unit files from the resources/resource_adapter subdirectory of a JBCP installation into JBoss's deploy directory. This section illustrates deploying resource adapters using the Mobicents Management Console.
Deploying Resource Adapters Using the MMC
Resource adapters can be deployed from the Install tab of the Deployable Units section of the Mobicents Management Console.
Deployable Units Install tab
Clicking on the button opens your browser's file selector. Navigate to the
<topmost_directory>/resources/resource_adapter/ subdirectory, where resource_adapter corresponds to the resource adapter you want to install. For example, if you wanted to install the HTTP Servlet resource adapter:
Selecting the HTTP Servlet deployable unit
Deployable units are JAR files which contain
-ra-DU in their file names. Simply select that file in the file chooser and click . Finally, you must click the button to install the deployable unit file, and therefore the corresponding resource adapter.
Ensuring the Resource Adapter Is Installed
You can ensure that the resource adapter deployed successfully by clicking on the Resources section in the Mobicents Management Console. There, under Resource Adapters, you should now see all of the resource adapters listed which you have deployed so far. In the screenshot, you can see that both the HTTP Servlet and HTTP Client resource adapters have been deployed.
HTTP Servlet and HTTP Client RAs successfully deployed
3.2. Resource Adapters
The following links to the current documentation for individual resource adapters can be found on this mobicents-public page.
3.2.1. Asterisk
For information on the Parlay resource adapter, refer to http://wiki.java.net/bin/view/Communications/MobicentsAsteriskRA.
3.2.2. Diameter
For information on the Diameter resource adapter, refer to http://groups.google.com/group/mobicents-public/web/mobicents-diameter-ra.
3.2.3. HTTP Client
For information on the HTTP Client resource adapter, refer to http://groups.google.com/group/mobicents-public/web/mobicents-http-client-ra.
3.2.4. HTTP Servlet
For information on the HTTP Servlet resource adapter, refer to http://groups.google.com/group/mobicents-public/web/mobicents-http-servlet-ra.
3.2.5. Media
The Media resource adapter is under active development, but for the current information on it, refer to http://groups.google.com/group/mobicents-public/web/mobicents-media-ra.
3.2.6. MGCP
For information on the MGCP resource adapter, refer to http://groups.google.com/group/mobicents-public/web/mobicents-mgcp-resource-adaptor-v2.
3.2.7. Parlay
For information on the Parlay resource adapter, refer to http://wiki.java.net/bin/view/Communications/MobicentsExamplesParlayRACallBlocking.
3.2.8. Persistence
For information on the Persistence resource adapter, refer to http://groups.google.com/group/mobicents-public/web/persistence-ra-design.
3.2.9. Rules
For information on the Rules resource adapter, refer to http://groups.google.com/group/mobicents-public/web/mobicents-rules-ra.
3.2.10. SIP
For information on the SIP resource adapter, refer to http://groups.google.com/group/mobicents-public/web/mobicents-sip-resources.
3.2.11. SMPP
For information on the SMPP resource adapter, refer to http://groups.google.com/group/mobicents-public/web/smpp-resource-adaptor.
3.2.12. TTS
http://groups.google.com/group/mobicents-public/web/mobicents-tts-ra
3.2.13. XCAP Client
For information on the XCAP Client resource adapter, refer to http://groups.google.com/group/mobicents-public/web/xcap-client-resource-adaptor.
3.2.14. XMPP
For information on the XMPP resource adapter, refer to http://wiki.java.net/bin/view/Communications/MobicentsExamplesXMPPSBB.
Chapter 4. Working with the JAIN SLEE Server Management Console
4.1. Introduction to the Mobicents Management Console
Once the JAIN SLEE Server 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.
The JAIN SLEE Server Management Console, initial view
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 the Management Console is currently running or not, and provides controls to start, stop, and shut down the JAIN SLEE 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 JAIN SLEE Server.
The
Deployable Units view
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.
The
Components view
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
Services view
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 currently possible actions for specific services, such as activating, deactivating, or removing them.
The
Resources view
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.
The
Activities view
Revision History
| Revision History | |||
|---|---|---|---|
| Revision 2.0 | Fri Mar 06 2009 | ||
| |||
| Revision 1.0 | Tue Jan 20 2009 | ||
| |||
Index
F
- feedback
- contact information for this manual, We Need Feedback!
JBoss Communications Platform 1.2.0
SIP Servlets Server User Guide
The Guide to the SIP Servlets v1.1-Certified Server
Edition 1.0
Legal Notice
Copyright © 2009 Red Hat Inc. This material may only be distributed subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License (which is presently available at http://creativecommons.org/licenses/by-nc-sa/3.0/).
Red Hat, the "Shadow Man" logo and JBoss are registered trademarks of Red Hat,
Inc. in the United States and other countries.
All other trademarks referenced herein are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072USAPhone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588Research Triangle Park, NC 27709USA
Abstract
The JBoss Communications Platform—JBCP is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. JBCP serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes) by leveraging J2EE to enable the convergence of data and video in Next-Generation
Intelligent Network (NGIN) applications.
The JBoss Communications Platform enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration
and Presence-Sensing. Out-of-the-box monitoring and management of JBCP components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise
applications with end points such as the Web, Customer Relationship
Management (CRM) systems and Service-Oriented Architectures (SOAs). The JBoss Communications Platform is the natural choice for telecom Operations Support Systems
(OSSes) and Network Management Systems (NMSes).
In addition to telecom, JBCP is suitable for a variety of problem domains demanding an
Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial
trading, online gaming, (RFID) sensor network integration, and distributed control.
- Preface
- 1. Introduction to the SIP Servlets Server
- 2. SIP Servlets Server-Installing, Configuring and Running
- 3. Services for Mobicents SIP Servlets
- 4. Advanced Features of the SIP Servlets Server
- A. Revision History
- Index
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:
To see the contents of the filemy_next_bestselling_novelin your current working directory, enter thecat my_next_bestselling_novelcommand at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.
Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:
Press Enter to execute the command.Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session.
The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in
Mono-spaced Bold. For example:
File-related classes includefilesystemfor file systems,filefor files, anddirfor directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).To insert a special character into a gedit file, choose from the main menu bar. Next, choose from the Character Map menu bar, type the name of the character in the Search field and click . The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the button. Now switch back to your document and choose from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.
Note the shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select from the sub-menu in the menu of the main menu bar' approach.
Mono-spaced Bold ItalicProportional Bold Italic
Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, typesshat a shell prompt. If the remote machine isusername@domain.nameexample.comand your username on that machine is john, typessh john@example.com.Themount -o remountcommand remounts the named file system. For example, to remount thefile-system/homefile system, the command ismount -o remount /home.To see the version of a currently installed package, use therpm -qcommand. It will return a result as follows:package.package-version-release
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.
1.2. Pull-quote Conventions
Two, commonly multi-line, data types are set off visually from the surrounding text.
Output sent to a terminal is set in
Mono-spaced Roman and presented thus:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in
Mono-spaced Roman but are presented and highlighted as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring Important boxes won't cause data loss but may cause irritation and frustration.
Warning
A Warning should not be ignored. Ignoring warnings will most likely cause data loss.
2. We Need Feedback!
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product JBoss Communications Platform.
When submitting a bug report, be sure to mention the manual's identifier: SIP_Servlets_Server_User_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
Chapter 1. Introduction to the SIP Servlets Server
JBCP SIP (Session Initiation Protocol) Servlets deliver a consistent, open platform on which to develop and deploy portable and distributed SIP and Java Enterprise Edition services. The JBCP SIP Servlets Server is a certified implementation of the SIP Servlet v1.1 (JSR 289) specification that can run on top of either the JBoss Application Server or the Tomcat Servlet Container.
JBCP 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 JBCP 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
1.1. High-Availability: SIP Servlets Server Load Balancing, Clustering and Failover
Telecommunications applications demand High-Availability (HA), fault tolerance, scalability and performance. Providing highly-available end-user applications that 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.
A cluster of Mobicents SIP Servlets Servers, showing the star network topology.
Clustering Terms and Definitions for Mobicents SIP Servlets
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.Distinguishing Between a Cluster and Clustering Capabilities
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
- SIP Servlets Server
- 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.
- node
- 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.
- cluster
- 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.
- SIP load balancer
- 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.
1.2. Working with the SIP Servlets Management Console
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/.
The SIP Servlets Management Console: 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 pop-up will appear. This help box can be repositioned and resized by dragging.
SIP Servlets Management Console: Default Application Router Help
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.
Tunable SIP Servlets Server Settings
For more information on tuning for concurrency and congestion control, refer to Configuring the Concurrency and Congestion Control Settings.
Chapter 2. SIP Servlets Server-Installing, Configuring and Running
2.1. SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running
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 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”[3]
Differences Between a Standard JBoss Installation and One Customized for Mobicents SIP Servlets
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/deploydirectory contains both HTTP and SIP Servlet applications (WAR and SAR2 files). - The
server/default/deploy/jboss-web.deployerunit 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.xmlfile 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.xmlfile and theserver/default/deploy/jboss-web.deployer/META-INF/webserver-xmbean.xmlfile have been modified so that it is now possible for JBoss containers to correctly deploy SIP servlets and converged applications. - A
darsdirectory containing all of the Default Application Router (DAR) properties files for using the various SIP Servlets applications (which come bundled with the release) has been added to theserver/default/confdirectory. - Additional JAR files have been added to enable SIP Servlet functionality; these can be seen in the
server/default/deploy/jboss-web.deployer/directory.
Installing the Java Development Kit
2.1.1. Java Development Kit: Installing, Configuring and Running
The JBoss Communications Platform is written in Java; therefore, before running any JBCP 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 JBCP must be version 5 or higher[4].
Should I Install the JRE or JDK?
Although you can run JBCP servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, JBCP-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?
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.
Downloading
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 JBCP in a production environment.
Installing
The following procedures detail how to install the Java Development Kit on both Linux and Windows.Procedure 2.1. Installing the JDK on Linux
- Regardless of which file you downloaded, you can install it on Linux by simply making sure the file is executable and then running it:
~]$ chmod +x "jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin" ~]$ ./"jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin"
You Installed Using the Non-RPM Installer, but Want the SysV Service Scripts
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/.
Important
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
Configuring your system for the JDK consists in two tasks: setting theJAVA_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.
- Setting the
JAVA_HOMEEnvironment Variable on Generic Linux - After installing the JDK, you must ensure that the
JAVA_HOMEenvironment variable exists and points to the location of your JDK installation.Setting the
You can determine whetherJAVA_HOMEEnvironment Variable on LinuxJAVA_HOMEis set on your system byechoing it on the command line:~]$ echo $JAVA_HOME
IfJAVA_HOMEis 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~/.bashrcconfiguration 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 JBCP (any environment variablesexported from~/.bashrcfiles are local to that user). - Setting
java,javacandjava_sdk_1.5.0Using thealternativescommand Selecting the Correct System JVM on Linux using
On systems with thealternativesalternativescommand, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as whichjavaandjavacexecutables should be run when called.As the root user, call/usr/sbin/alternativeswith the--config javaoption 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 thejavaexecutable. In thealternativesinformation printout above, a plus (+) next to a number indicates the one currently being used. As peralternatives' 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 thejavaccommand and thejava_sdk_1.5.0environment variable, as the root user:~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
- Setting the
JAVA_HOMEEnvironment Variable on Windows - For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
Testing
Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in yourPATH, run the java -version command in the terminal from your home directory:
~]$ java -version java version "1.5.0_16" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03) Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling
There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily usingalternatives, and/or by setting JAVA_HOME.
Uninstalling the JDK on Linux
On RPM-based systems, you can uninstall the JDK using theyum remove <jdk_rpm_name> command.
Uninstalling the JDK on Windows
On Windows systems, check the JDK entry in theStart menu for an uninstall command, or use Add/Remove Programs.
2.1.2. Pre-Install Requirements and Prerequisites
Hardware Requirements
- Sufficient Disk Space
- You must have sufficient disk space in order to install the MSS for JBoss binary release. Once unzipped, version 0.7.2 of the 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.
- Anything Java Itself Will Run On
- MSS for JBoss is 100% Java. It will run on the same hardware that the JBoss Application Server runs on.
Software Prerequisites
- JDK 5 or Higher
2.1.3. Downloading
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 Mobicents SIP Servlets Server for JBoss and continue with the following instructions.
2.1.4. Installing
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.
Use Version Numbers Relevant to Your Installation!
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.3. Installing the MSS for JBoss Binary Distribution on Linux
- For this example, we'll assume you're currently in your home directory, which is where you downloaded the zip file to. First, 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.
~]$ mkdir "mss-jboss-<version>"
- Move the downloaded zip file into the directory you just created:
~]$ mv "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip" "mss-jboss-<version>"
- Move into that directory:
~]$ cd "mss-jboss-<version>"
- Finally, use Java's
jarcommand to extract the contents of the zip file into the current directory, thus completing the install:-xvfmss-jboss-<version>]$ jar -xvf "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
- Alternatively, if Linux's
unziputility is present on your system or is installable, you can use it in lieu of Java'sjarcommand:-xvfmss-jboss-<version>]$ unzip "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
Note
You can also useunzip's-d<unzip_to_location>
- To free disk space, you may want to delete the zip file once you've extracted its contents:
mss-jboss-<version>]$ rm "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
Procedure 2.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 Downloadsfolder. First, using Windows Explorer, create a subfolder inMy Downloadsto 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 asmss-jboss-.<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
jarcommand to extract the binary distribution files from the zip archive. To use this method instead, first move the downloaded zip file from-xvfMy Downloadsto 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
cdcommand:Opening the Command Prompt from Windows Explorer
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 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-<version>"
- Finally, use the
jarcommand to extract the archive contents into the current folder.-xvfC:\Users\Me\My Downloads\mss-jboss-<version>>jar -xvf "mss-0.7.2-jboss-4.2.3.GA-0901261304.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-) to another location. This step is not strictly necessary, but it is probably a good idea to move the installation folder from<version>My Downloadsto 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-<version>>delete "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
2.1.5. Setting the JBOSS_HOME Environment Variable
Configuring MSS for JBoss consists in setting the
JBOSS_HOME environment variable and then, optionally, customizing your MSS for JBoss server by adding SIP Connectors, configuring the application router, and configuring logging.
After setting
JBOSS_HOME in the instructions in the following section, see Section 2.3, “Configuring” to learn what and how to configure MSS for JBoss.
Alternatively, after having set
JBOSS_HOME, you can simply run your MSS for JBoss server now and return to this section to configure it later.
2.1.5.1. Setting the JBOSS_HOME Environment Variable
The JBoss Communications Platform (JBCP) is built on top of the JBoss Enterprise Application Platform (JBoss EAP). You do not need to set the
JBOSS_HOME environment variable to run any of the JBoss Communications Platform servers unless JBOSS_HOME is already set.
The best way to know for sure whether
JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.
Checking to See If JBOSS_HOME is Set on Linux
At the command line,echo$JBOSS_HOME to see if it is currently defined in your environment:
~]$ echo $JBOSS_HOME
Silence on the command line (a completely blank line) means that it is not set, in which case you can proceed with running the JBoss Communications Platform.
Checking to See if JBOSS_HOME is Set on Windows
For information on determining whether environment variables are set in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.
If
JBOSS_HOME is already set on your system, then you have three options:
unsetit, which only takes effect for the current session and is therefore not advised;- find where
JBOSS_HOMEis defined, such as in your local~/.bashrcstartup script in Linux, or, possibly, system-wide in/etc/bashrc, and remove it or comment it out; - or point it to the correct location, in which case you should refer to the following instructions on how to set
JBOSS_HOME.
Setting the JBOSS_HOME Environment Variable on Linux
TheJBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform that you installed. As another hint, this topmost directory contains a bin subdirectory.
Setting
JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Linux, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.
Procedure 2.5. To Set JBOSS_HOME on Linux...
- Open the
~/.bashrcstartup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:export JBOSS_HOME="/home/
<username>/<path>/<to>/<install_directory>" - Save and close the
.bashrcstartup script. - You should
sourcethe.bashrcscript to force your change to take effect, so thatJBOSS_HOMEbecomes set for the current session[5].~]$ source ~/.bashrc
- Finally, ensure that
JBOSS_HOMEis set in the current session, and actually points to the correct location:Note
The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output,JBOSS_HOMEhas been set correctly to thetopmost_directoryof the JBCP installation. Note that if you are installing one of the standalone JBCP servers (with JBoss AS bundled!), thenJBOSS_HOMEwould point to thetopmost_directoryof your server installation.~]$ echo $JBOSS_HOME /home/silas/jboss-eap-4.3/jboss-as
Setting the JBOSS_HOME Environment Variable on Windows
TheJBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform that you installed. As another hint, this topmost directory contains a bin subdirectory.
For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.
2.1.6. Configuring
To configure MMS for JBoss, refer to Section 2.3, “Configuring”.
2.1.7. Running
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 2.6. 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-<version>"
- (Optional) Ensure that the
bin/run.shstart script is executable:mss-jboss-<version>]$ chmod +x bin/run.sh
- Finally, execute the
run.shBourne shell script:mss-jboss-<version>]$ ./bin/run.sh
- Instead of executing the Bourne shell script to start the server, you may alternatively run the
run.jarexecutable Java archive in thebindirectory:mss-jboss-<version>]$ java -jar bin/run.jar
Procedure 2.7. 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
binsubfolder. - Although not the preferred way (see below), it is possible to start MSS for JBoss by double-clicking on the
run.batexecutable 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>\binfolder in Windows Explorer, 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-<version>"
- Start the JBoss Application Server by running the executable
run.batbatch file:C:\Users\Me\My Downloads\mss-jboss-<version>>bin\run.bat
- It is also possible to start the server by running the
run.jarexecutable Java archive:C:\Users\Me\My Downloads\mss-jboss-<version>>java -jar bin\run.jar
2.1.8. Using
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/.
2.1.9. Stopping
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 2.8. Stopping MSS for JBoss on Linux by Executing shutdown.sh or shutdown.jar
- You can shut down the JBoss Application Server by executing the
shutdown.shBourne shell script in the<topmost_directory>/bindirectory. 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-<version>"
- (Optional) Ensure that the bin/shutdown.sh start script is executable:
mss-jboss-<version>]$ chmod +x bin/shutdown.sh
- Finally, run the
shutdown.shexecutable Bourne shell script, and remember to add the-Soption (which is the short option for--shutdown) as a command line argument:mss-jboss-<version>]$ ./bin/shutdown.sh -S
- Instead of executing the Bourne shell script to stop the server, you may alternatively run the
shutdown.jarexecutable Java archive to do so (and remembering, again, to add the-Scommand line argument):mss-jboss-<version>]$ java -jar bin/shutdown.jar -S
Procedure 2.9. Stopping MSS for JBoss on Windows
- Stopping the JBoss Application Server on Windows consists in executing either the
shutdown.bator theshutdown.jarexecutable file in thebinsubfolder of the MSS for JBoss binary distribution. Make sure to add the-Soption (which is the short option for--shutdown) as a command line argument.C:\Users\Me\My Downloads\mss-jboss-<version>>bin\shutdown.bat -S
- Alternatively, you can execute the
shutdown.jarJava archive by running thejavacommand, and remembering to add the-jar-Soption as a command line argument:C:\Users\Me\My Downloads\mss-jboss-<version>>java -jar bin\shutdown.jar -S
2.1.10. Uninstalling
To uninstall MSS for JBoss, simply delete the directory you decompressed the binary distribution archive into.
2.2. SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running
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 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.
Differences Between the Standard Tomcat Installation and One Customized for Mobicents SIP Servlets
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.xmlconfiguration 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
darsdirectory 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 theconfdirectory. - Additional JAR files which can be found in the
libdirectory have been added to enable SIP Servlet functionality.
Installing the Java Development Kit
2.2.1. Java Development Kit: Installing, Configuring and Running
The JBoss Communications Platform is written in Java; therefore, before running any JBCP 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 JBCP must be version 5 or higher[6].
Should I Install the JRE or JDK?
Although you can run JBCP servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, JBCP-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?
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.
Downloading
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 JBCP in a production environment.
Installing
The following procedures detail how to install the Java Development Kit on both Linux and Windows.Procedure 2.10. Installing the JDK on Linux
- Regardless of which file you downloaded, you can install it on Linux by simply making sure the file is executable and then running it:
~]$ chmod +x "jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin" ~]$ ./"jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin"
You Installed Using the Non-RPM Installer, but Want the SysV Service Scripts
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/.
Important
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.11. Installing the JDK on Windows
- Using Explorer, simply double-click the downloaded self-extracting installer and follow the instructions to install the JDK.
Configuring
Configuring your system for the JDK consists in two tasks: setting theJAVA_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.
- Setting the
JAVA_HOMEEnvironment Variable on Generic Linux - After installing the JDK, you must ensure that the
JAVA_HOMEenvironment variable exists and points to the location of your JDK installation.Setting the
You can determine whetherJAVA_HOMEEnvironment Variable on LinuxJAVA_HOMEis set on your system byechoing it on the command line:~]$ echo $JAVA_HOME
IfJAVA_HOMEis 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~/.bashrcconfiguration 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 JBCP (any environment variablesexported from~/.bashrcfiles are local to that user). - Setting
java,javacandjava_sdk_1.5.0Using thealternativescommand Selecting the Correct System JVM on Linux using
On systems with thealternativesalternativescommand, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as whichjavaandjavacexecutables should be run when called.As the root user, call/usr/sbin/alternativeswith the--config javaoption 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 thejavaexecutable. In thealternativesinformation printout above, a plus (+) next to a number indicates the one currently being used. As peralternatives' 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 thejavaccommand and thejava_sdk_1.5.0environment variable, as the root user:~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
- Setting the
JAVA_HOMEEnvironment Variable on Windows - For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
Testing
Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in yourPATH, run the java -version command in the terminal from your home directory:
~]$ java -version java version "1.5.0_16" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03) Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling
There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily usingalternatives, and/or by setting JAVA_HOME.
Uninstalling the JDK on Linux
On RPM-based systems, you can uninstall the JDK using theyum remove <jdk_rpm_name> command.
Uninstalling the JDK on Windows
On Windows systems, check the JDK entry in theStart menu for an uninstall command, or use Add/Remove Programs.
2.2.2. Pre-Install Requirements and Prerequisites
Hardware Requirements
- Sufficient Disk Space
- 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.
- Anything Java Itself Will Run On
- MSS for Tomcat is 100% Java. It will run on the same hardware that the Tomcat Servlet Container runs on.
Software Prerequisites
- JDK 5 or Higher
- A working installation of the Java Development Kit (JDK) version 5 or higher is required in order to run MSS for Tomcat.
2.2.3. Downloading
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.
2.2.4. Installing
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.
Use Version Numbers Relevant to Your Installation!
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.12. Installing the MSS for Tomcat Binary Distribution on Linux
- For this example, we'll assume you're currently in your home directory, which is where you downloaded the zip file to. First, 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 distribution you downloaded.
~]$ 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.~]$ mkdir "mss-tomcat-<version>"
- Move the downloaded zip file into the directory you have just created:
~]$ mv "mss-0.7.2-apache-tomcat-6.0.14-0901261255.zip" "mss-tomcat-<version>"
- Move into that directory:
~]$ cd "mss-tomcat-<version>"
- Finally, use Java's
jarcommand to extract the contents of the zip file into the current directory, thus completing the install:-xvfmss-tomcat-<version>]$ jar -xvf "mss-0.7.2-apache-tomcat-6.0.14-0901261255.zip"
- Alternatively, if Linux's
unziputility is present on your system or is installable, you can use it in lieu of Java'sjarcommand:-xvfmss-tomcat-<version>]$ unzip "mss-0.7.2-apache-tomcat-6.0.14-0901261255.zip"
Note
You can also useunzip's-d<unzip_to_location>
- To free disk space, you may want to delete the zip file once you've extracted its contents:
mss-tomcat-<version>]$ rm "mss-0.7.2-apache-tomcat-6.0.14-0901261255.zip"
Procedure 2.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 Downloadsfolder. First, using Windows Explorer, create a subfolder inMy Downloadsto 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 asmss-tomcat-.<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
jarcommand to extract the binary distribution files from the zip archive. To use this method instead, first move the downloaded zip file from-xvfMy Downloadsto 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
cdcommand.Opening the Command Prompt from Windows Explorer
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 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
jarcommand to extract the archive contents into the current folder.-xvfC:\Users\Me\My Downloads\mss-tomcat-<version>>jar -xvf "mss-0.7.2-apache-tomcat-6.0.14-0901261255.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-) to another location. This step is not strictly necessary, but it is probably a good idea to move the installation folder from<version>My Downloadsto 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-<version>>delete "mss-0.7.2-apache-tomcat-6.0.14-0901261255.zip"
2.2.5. Setting the CATALINA_HOME Environment Variable
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_HOMEis 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_HOMEis (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 2.14. Setting the CATALINA_HOME Environment Variable on Linux
- The
CATALINA_HOMEenvironment 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, abindirectory.CATALINA_HOMEmust be set to the topmost directory of your Mobicents server installation.Setting this variable in your personal~/.bashrcfile 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~/.bashrcin 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—
sourceyour.bashrcfile to make your change take effect (so thatCATALINA_HOMEis set) for the current session:~]$ source ~/.bashrc
- Finally, make sure that
CATALINA_HOMEhas 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 byCATALINA_HOME:~]$ echo $CATALINA_HOME
To be absolutely sure, change your directory to the one pointed to byCATALINA_HOME:~]$ cd $CATALINA_HOME && pwd
Procedure 2.15. Setting the CATALINA_HOME Environment Variable on Windows
- The
CATALINA_HOMEenvironment 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, abindirectory.CATALINA_HOMEmust 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 theCATALINA_HOMEenvironment variable as the administrator, and if you planning to run Tomcat as a normal user, then setCATALINA_HOMEas a user environment variable.For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
2.2.6. Configuring
Configuring MSS for Tomcat consists in setting the
CATALINA_HOME environment variable and then, optionally, customizing your MSS for Tomcat container by adding SIP Connectors, configuring the application router, and configuring logging. See Section 2.3, “Configuring” to learn what and how to configure MSS for Tomcat.
Alternatively, you can simply run your MSS for Tomcat container now and return to this section to configure it later.
2.2.7. Running
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.7.2 Using CATALINA_HOME: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.7.2 Using CATALINA_TMPDIR: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.7.2/temp Using JRE_HOME: /etc/java-config-2/current-system-vm
Detailed instructions are given below, arranged by platform.
Procedure 2.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):
~]$ cd "mss-tomcat-<version>"
- (Optional) Ensure that the
bin/startup.shstart script is executable:mss-tomcat-<version>]$ chmod +x bin/startup.sh
- Finally, execute the
startup.shBourne shell script:mss-tomcat-<version>]$ ./bin/startup.sh
Procedure 2.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
binsubfolder. - Although not the preferred way (see below), it is possible to start the Tomcat Servlet Container by double-clicking on the
startup.batexecutable 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>\binfolder in Windows Explorer, 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-<version>"
- Start the Tomcat Servlet Container by running the executable
startup.batbatch file:C:\Users\Me\My Downloads\mss-tomcat-<version>>bin\startup.bat
2.2.8. Stopping
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.7.2 Using CATALINA_HOME: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.7.2 Using CATALINA_TMPDIR: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-0.7.2/temp Using JRE_HOME: /etc/java-config-2/current-system-vm
Procedure 2.18. Stopping MSS for Tomcat on Linux by Executing shutdown.sh
- You can shut down the Tomcat Servlet Container by executing the
shutdown.shBourne shell script in the<topmost_directory>/bindirectory. 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-<version>"
- (Optional) Ensure that the bin/shutdown.sh start script is executable:
mss-tomcat-<version>]$ chmod +x bin/shutdown.sh
- Finally, run the
shutdown.shexecutable Bourne shell scriptmss-tomcat-<version>]$ ./bin/shutdown.sh
Procedure 2.19. Stopping MSS for Tomcat on Windows
- Stopping the Tomcat Servlet Container on Windows consists in executing the
shutdown.batexecutable batch script in thebinsubfolder of the SIP Servlets-customized Tomcat binary distribution:C:\Users\Me\My Downloads\mss-tomcat-<version>>bin\shutdown.bat
2.2.9. Using
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.
2.2.10. Testing
2.2.11. Uninstalling
To uninstall MSS for Tomcat, simply delete the directory you decompressed the binary distribution archive into.
2.3. Configuring
2.3.1. Configuring SIP Connectors
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:
Provided here are descriptions of the SIP Connector element's attributes:
- port
- The number of the port on which the container will be able to receive SIP messages.
- ipAddress
- The IP address at which the container will be able to receive SIP messages.
- protocol
- This attribute specifies that this is a SIP Connector and not an HTTP Connector. There is no need to change this property.
- signalingTransport
- the transport on which the container will be able to receive SIP messages: “udp” for example
- useStun
- Setting this attribute to “true” enables STUN support for this Connector. If you set it to “true”, ensure that the
ipAddressattribute is not set to127.0.0.1. This attribute defaults to “false”. Refer to the documentation on STUN support for more information regarding STUN support. - stunServerAddress
- 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
useStunattribute is set to “true”. Refer to the documentation on STUN support for more information regarding STUN support. - stunServerPort
- This attribute should be set to the STUN server port of the STUN server used in the
stunServerAddressattribute. You should rarely need to change this attribute; also, it is only needed if theuseStunattribute is set to “true”. Refer to the documentation on STUN support for more information regarding STUN support. - sipStackPropertiesFile
- The underlying JAIN SIP stack implementation can be further configured through a set of properties (see JAIN SIP configuration properties and the NIST SIP implementation configuration properties ). You should set this property to the location of the file that that contains key-value pairs corresponding to the stack configuration properties. If this property is omitted, the following default values are assumed:
- gov.nist.javax.sip.LOG_MESSAGE_CONTENT=true
- gov.nist.javax.sip.TRACE_LEVEL=32
- gov.nist.javax.sip.DEBUG_LOG=logs/mss-jsip-debuglog.txt
- gov.nist.javax.sip.SERVER_LOG=logs/mss-jsip-messages.xml
- javax.sip.STACK_NAME=Mobicents-SIP-Servlets
- javax.sip.AUTOMATIC_DIALOG_SUPPORT=off
- gov.nist.javax.sip.DELIVER_UNSOLICITED_NOTIFY=true
- gov.nist.javax.sip.THREAD_POOL_SIZE=64
- gov.nist.javax.sip.REENTRANT_LISTENER=true
- logLevel
- The log level of the underlying JAIN SIP stack.
- debugLog
- The debug log location of the underlying JAIN SIP stack.
- serverLog
- The server log location of the underlying JAIN SIP stack.
- sipStackName
- The name of the underlying JAIN SIP sack.
- sipPathName
- 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
libdirectory.
2.3.2. Application Routing and Service Configuration
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:
1 <Service name="Sip-Servlets" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" 5 darConfigurationFileLocation="file:///home/silas/workspaces/mobicents-sip-servlets/sip-servlets-examples/reinvite-demo/reinvite-dar.properties">
Example 2.1. Configuring the Service Element in the Container's server.xml
Provided here is a description of the SIP Service element's attributes:
- className
- 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.
- sipApplicationDispatcherClassName
- This attribute specifies the class name of the
org.mobicents.servlet.sip.core.SipApplicationDispatcherimplementation to use. The routing algorithm and application selection process is performed in that class. - darConfigurationFileLocation
- 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.
2.3.3. SIP Servlets Server Logging
There are two separate levels of logging:
- Logging at the container level, which can be configured using the
log4j.xmlconfiguration file, which is usually located in the container'slibdirectory. - Logging of the NIST SIP stack, which is configured in the
Connectorelement of the container'sserver.xmlconfiguration file.
[3] Keep in mind that not all capabilities enjoyed by MSS for JBoss are available for MSS for Tomcat.
[4] At this point in time, it is possible to run most JBCP servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.
[5]
Note that any other terminals which were opened prior to your having altered .bashrc will need to source~/.bashrc as well should they require access to JBOSS_HOME.
[6] At this point in time, it is possible to run most JBCP servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.
Chapter 3. Services for Mobicents SIP Servlets
3.1. The Location Service
The Mobicents Location Service contains a list of mappings of request URIs to destination addresses. When the Location Service receives a request, it performs a lookup on that mapping and proxies the request simultaneously to the destination address (or addresses) associated with that URI.
The Location Service Mappings Cannot Currently Be Configured
The Location Service currently performs a lookup on a hard-coded list of addresses. This model is evolving towards the eventual use of a database.
Regardless of whether you are using the JBoss Application Server or the Tomcat Servlet Container as the Servlets Server, the application, container and Location Service perform the following steps:
- A user—let us call her Alice—makes a call to
sip:receiver@sip-servlets.com. TheINVITEis 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:5090andsip: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 OKstatus code; the second proxy is then cancelled. - The
200 OKis 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:5090sip:receiver@127.0.0.1:6090
3.1.1. The Location Service: Installing, Configuring and Running
Pre-Install Requirements and Prerequisites
Software Prerequisites
- Either an MSS for JBoss or an MSS for Tomcat Installation
- The Location Service requires either an MSS for JBoss or an MSS for Tomcat binary installation.You can find detailed instructions on installing MSS for JBoss here: Section 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.You can find detailed instructions on installing MSS for Tomcat here: Section 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”.
Downloading
The Location Service is comprised of two archive files, a Web Archive (WAR) and a Default Application Router (DAR) configuration file, which you need to add to your installed SIP Servlets Server. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C.
Download the Location Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/location-service/1.1/location-service-1.1.war.
Download the Location Service's DAR file from here: http://www.mobicents.org/locationservice-dar.properties.
Installing
Both thelocation-service-1.1.war WAR file and the locationservice-dar.properties DAR file that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Location Service with MSS for JBoss or with MSS for Tomcat:
- MSS for JBoss
- Place
location-service-1.1.warinto theJBOSS_HOME/server/default/deploy/locationservice-dar.propertiesinto theJBOSS_HOME/server/default/conf/dars/ - MSS for Tomcat
- Place
location-service-1.1.warinto theCATALINA_HOME/webapps/locationservice-dar.propertiesinto theCATALINA_HOME/conf/dars/
Configuring
ThedarConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/locationservice-dar.properties. The instructions are given below by SIP Servlets Server type:
- MSS for JBoss
- Open the
JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xmlServiceelement. Add an attribute to it calleddarConfigurationFileLocation, and set it toconf/dars/locationservice-dar.properties:<Service name="jboss.web" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="conf/dars/locationservice-dar.properties">
Example 3.1. Editing MSS for JBoss's server.xml for the Location Service
Make sure that the configuration file only contains onedarConfigurationFileLocationattribute: your new one. - MSS for Tomcat
- Open the
CATALINA_HOME/conf/server.xmlServiceelement. Add an attribute to it calleddarConfigurationFileLocation, and set it toconf/dars/locationservice-dar.properties:<Service name="Sip-Servlets" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="conf/dars/locationservice-dar.properties">
Example 3.2. Editing MSS for Tomcat's server.xml for the Location Service
Make sure that the configuration file only contains onedarConfigurationFileLocationattribute: your new one.
Running
Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in aserver.xml file), then you should go ahead and run SIP Servlets Server.
To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.
To learn how to run the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.7, “Running”.
Testing
The following procedure shows how to test the Location Service.Procedure 3.1.
- Start two SIP softphones. The first phone should be set up as
sip:receiver@sip-servlets.comat IP address127.0.0.1on port5090. The second phone can be set up in any way you like. Note that the SIP phones do not have to be registered. - Using the second phone, make a call to
sip:receiver@sip-servlets.com. If the Location Service has been set up correctly and is running, the first phone—as the receiver or callee—should now be ringing.
Stopping
To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to bssswjicar-binary-SIP_Servlets_Server_with_JBoss-Stopping.
To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to bbssswticar-binary-SIP_Servlets_Server_with_Tomcat-Stopping.
Uninstalling
Unless disk space is at a premium, there is usually no need to uninstall the Location Service. However, if you will not be using it again, you may want to unset or reset thedarConfigurationFileLocation 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.
3.2. The Diameter Event-Changing Service
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 3.2. Diameter Event-Changing Service Step-By-Step
- A user, Alice, makes a call to
sip:receiver@sip-servlets.com. TheINVITEis 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:5090andsip: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
3.2.1. Diameter Event-Changing Service: Installing, Configuring and Running
Preparing your MSS for JBoss server to run the Diameter Event-Changing example requires downloading a WAR archive, a DAR archive, the Ericsson Charging Emulator, setting an attribute in JBoss's
server.xml configuration file, and then running JBoss AS. Detailed instructions follow.
Pre-Install Requirements and Prerequisites
Software Prerequisites
- One MSS for JBoss Installation
- Before proceeding, you should follow the instructions for installing, configuring, running and testing MSS for JBoss from the binary distribution.
Downloading
- 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.
Installing
- Place the
diameter-event-charging-1.0.warWAR archive into thejboss_home/server/<profile>/deploydirectory, 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.propertiesDAR file in your$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'sjarcommand for this:-xvf~]$ cd charging_sdk charging_sdk]$ jar -xvf ChargingSDK-1_0_D31E.zip
Alternatively, you can use Linux'sunzipcommand to do the dirty work:charging_sdk]$ unzip ChargingSDK-1_0_D31E.zip
Configuring
To configure the server for the Event-Changing example, simply open theserver.xml configuration file in your server's $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:
1 ... <Service name="jboss.web" className="org.mobicents.servlet.sip.startup.SipStandardService" 5 sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" sipApplicationRouterClassName="org.mobicents.servlet.sip.router.DefaultApplicationRouter" darConfigurationFileLocation="conf/dars/mobicents-dar.properties"> ... 10
Example 3.3. Editing the darConfigurationFileLocation Attribute of the Service Tag
Running
Procedure 3.3. Diameter Event-Changing Service
- First, you should run your MSS for JBoss server. For instructions on doing so, refer to Section 2.1.7, “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_D31Eor a similarly-named directory), and run it with thejava -jarcommand:PPSDiamEmul.jar~]$ java -jar PPSDiamEmul.jar
Using
Using the Event-Changing service means, firstly, inserting some parameters into the Charging Emulator, and then, by using two SIP (soft)phones, calling one with the other. The following sequential instructions show you how.SIP (Soft)Phone? Which?
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 3.4. 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.
Configuring the Charging Emulator- Set the
Peer Idto:aaa://127.0.0.1:21812 - Set the
Realmto:mobicents.org - Set the
Host IPto:127.0.0.1
- Start two SIP (soft)phones. You should set the first phone up with the following parameters:
sip:receiver@sip-servletson IP address127.0.0.1on port5090. The other phone can be set up any way you like. - Before making a call, open the → dialog window, as shown in the image.
Configuring Accounts in the Charging EmulatorIn 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.
3.3. The Call-Blocking Service
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 Cannot Currently Be Configured
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.comsip:blocked-sender@127.0.0.1
3.3.1. The Call-Blocking Service: Installing, Configuring and Running
Pre-Install Requirements and Prerequisites
Software Prerequisites
- Either an MSS for JBoss or an MSS for Tomcat Installation
- 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 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.You can find detailed instructions on installing MSS for Tomcat here: Section 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”.
Downloading
The Call-Blocking Service is comprised of two archive files, a Web Archive (WAR) and a Default Application Router (DAR) configuration file, which you need to add to your installed SIP Servlets Server. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C.
Download the Call-Blocking Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-blocking/1.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.
Installing
Both thecall-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:
- MSS for JBoss
- Place
call-blocking-1.1.warinto theJBOSS_HOME/server/default/deploy/call-blocking-servlet-dar.propertiesinto theJBOSS_HOME/server/default/conf/dars/ - MSS for Tomcat
- Place
call-blocking-servlet-dar.propertiesinto theCATALINA_HOME/webapps/call-blocking-servlet-dar.propertiesinto theCATALINA_HOME/conf/dars/
Configuring
ThedarConfigurationFileLocation 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:
- MSS for JBoss
- Open the
JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xmlServiceelement. Add an attribute to it calleddarConfigurationFileLocation, and set it toconf/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 3.4. Editing MSS for JBoss's server.xml for the Call-Blocking Service
Make sure that the configuration file only contains onedarConfigurationFileLocationattribute: your new one. - MSS for Tomcat
- Open the
CATALINA_HOME/conf/server.xmlServiceelement. Add an attribute to it calleddarConfigurationFileLocation, and set it toconf/dars/call-blocking-servlet-dar.properties:<Service name="Sip-Servlets" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="conf/dars/call-blocking-servlet-dar.properties">
Example 3.5. Editing MSS for Tomcat's server.xml for the Call-Blocking Service
Make sure that the configuration file only contains onedarConfigurationFileLocationattribute: your new one.
Running
Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in aserver.xml file), then you should go ahead and run SIP Servlets Server.
To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.
To learn how to run the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.7, “Running”.
Testing
The following procedure shows how to test the Call-Blocking Service.Procedure 3.5.
- Start a SIP softphone of your choice. The account name should be
blocked-sender. TheFrom Headershould list one of the following addresses:sip:blocked-sender@sip-servlets.comorsip:blocked-sender@127.0.0.1. The SIP softphone does not need to be registered. - Make a call to any address, and you should receive a
FORBIDDENresponse.
Stopping
To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to bssswjicar-binary-SIP_Servlets_Server_with_JBoss-Stopping.
To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to bssswjicar-binary-SIP_Servlets_Server_with_Tomcat-Stopping.
Uninstalling
Unless disk space is at a premium, there is usually no need to uninstall the Call-Blocking Service. However, if you will not be using it again, you may want to unset or reset thedarConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.
You may also wish to delete the WAR and DAR files for the Call-Blocking Service, which you installed in Installing.
3.4. The Call-Forwarding Service
The Mobicents Call-Forwarding Service, upon receiving an
INVITE request, checks to see whether the sender's address is among those in a list of addresses which need to be forwarded. If so, then the Call-Forwarding Service acts as a Back-to-Back User Agent (B2BUA), and creates a new call leg to the destination. When the response is received from the new call leg, it sends it an acknowledgement (ACK) and then responds to the original caller. If, on the other hand, the server does not receive an ACK, then it tears down the new call leg with a BYE. Once the BYE is received, then it answers OK directly and forwards the BYE to the new call leg.
Contacts to Forward Cannot Currently Be Configured
Contacts to forward are currently hard-coded addresses. This model is evolving towards the eventual use of a database.
Here is the current hard-coded list of contacts to forward:
sip:receiver@sip-servlets.comsip:receiver@127.0.0.1
3.4.1. The Call-Forwarding Service: Installing, Configuring and Running
Pre-Install Requirements and Prerequisites
Software Prerequisites
- Either an MSS for JBoss or an MSS for Tomcat Installation
- The Call-Forwarding Service requires either an MSS for JBoss or an MSS for Tomcat binary installation.You can find detailed instructions on installing MSS for JBoss here: Section 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.You can find detailed instructions on installing MSS for Tomcat here: Section 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”.
Downloading
The Call-Forwarding Service is comprised of two archive files, a Web Archive (WAR) and a Data Archive (DAR), which you need to add to your installed SIP Servlets Server. For more information about WAR and DAR files, refer to the JBoss Application Server Administration and Development Guide.
Download the Call-Forwarding Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-forwarding/1.1/call-forwarding-1.1.war.
Download the Call-Forwarding Service's DAR file from here: http://www.mobicents.org/call-forwarding-servlet-dar.properties.
Installing
Both thecall-forwarding-1.1.war WAR file and the call-forwarding-servlet-dar.properties DAR file that you downloaded should be placed into different directories in your SIP Servlet Server installation hierachy. Which directory depends on whether you are using the Call-Forwarding Service with MSS for JBoss or with MSS for Tomcat:
- MSS for JBoss
- Place
call-forwarding-1.1.warinto theJBOSS_HOME/server/default/deploy/call-forwarding-servlet-dar.propertiesinto theJBOSS_HOME/server/default/conf/dars/ - MSS for Tomcat
- Place
call-forwarding-1.1.warinto theCATALINA_HOME/webapps/call-forwarding-servlet-dar.propertiesinto theCATALINA_HOME/conf/dars/
Configuring
ThedarConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/call-forwarding-b2bua-servlet-dar.properties. The instructions for doing so are given below by SIP Servlets Server type:
- MSS for JBoss
- Open the
JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xmlServiceelement. Add an attribute to it calleddarConfigurationFileLocation, and set it toconf/dars/call-forwarding-b2bua-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-forwarding-b2bua-servlet-dar.properties">
Example 3.6. Editing MSS for JBoss's server.xml for the Call-Forwarding Service
Make sure that the configuration file only contains onedarConfigurationFileLocationattribute: your new one. - MSS for Tomcat
- Open the
CATALINA_HOME/conf/server.xmlServiceelement. Add an attribute to it calleddarConfigurationFileLocation, and set it toconf/dars/call-forwarding-b2bua-servlet-dar.properties:<Service name="Sip-Servlets" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="conf/dars/call-forwarding-b2bua-servlet-dar.properties">
Example 3.7. Editing MSS for Tomcat's server.xml for the Call-Forwarding Service
Make sure that the configuration file only contains onedarConfigurationFileLocationattribute: your new one.
Running
Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in aserver.xml file), then you should go ahead and run SIP Servlets Server.
To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.
To learn how to run the SIP Servlets-enabled Tomcat Container, refer to bbssswticar-binary-SIP_Servlets_Server_with_Tomcat-Running.
Testing
The following procedure shows how to test the Call-Forwarding Service.Procedure 3.6.
- Start two SIP softphones of your choice. Set the account settings of the first SIP softphone to:
- Account name:
forward-receiver - IP address:
127.0.0.1 - Port:
5090
Neither of the SIP softphones needs to be registered. - From the second phone, make a call to
sip:receiver@sip-servlets.com. The first phone, “forward-receiver”, should now be ringing.
Stopping
To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to bssswjicar-binary-SIP_Servlets_Server_with_JBoss-Stopping.
To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to bbssswticar-binary-SIP_Servlets_Server_with_Tomcat-Stopping.
Uninstalling
Unless disk space is at a premium, there is usually no need to uninstall the Call-Forwarding Service. However, if you will not be using it again, you may want to unset or reset thedarConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.
You may also wish to delete the WAR and DAR files for the Call-Forwarding Service, which you installed in Installing.
3.5. The Call-Controller Service
The Call-Controller service is a composition of two other services: Call-Blocking and Call-Forwarding. Essentially, it performs the services of both call-forwarding and call-blocking.
- To learn about how the Call-Blocking service works, refer to Section 3.3, “The Call-Blocking Service”.
- To learn about how the Call-Forwarding service works, refer to Section 3.4, “The Call-Forwarding Service”.
Blocked Contacts and Contacts to Forward Cannot Currently Be Configured
Both the list of blocked contacts and the list of contacts to forward are currently both hard-coded. However, both of those models are evolving towards the eventual use of databases.
3.5.1. The Call-Controller Service: Installing, Configuring and Running
The Call-Controller service requires the two WAR files for the Call-Blocking and Call-Forwarding services to be placed in the correct directory inside your Mobicents SIP Servlets Server binary installation. However, the Call-Controller service does not require their corresponding DAR files: you need only to download and install a DAR file customized for the Call-Controller service. The instructions below show you how to do precisely this; there is no need, therefore, to first install either the Call-Blocking or the Call-Forwarding services, though it is helpful to at least be familiar with them.
Pre-Install Requirements and Prerequisites
Software Prerequisites
- Either an MSS for JBoss or an MSS for Tomcat Installation
- The Call-Controller Service requires either an MSS for JBoss or an MSS for Tomcat binary installation.You can find detailed instructions on installing MSS for JBoss here: Section 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.You can find detailed instructions on installing MSS for Tomcat here: Section 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”.
Downloading
The Call-Controller Service is comprised of two WAR files, one for the Call-Forwarding service and one for Call-Blocking, and a customized Call-Controller DAR file. You do not need to install the DAR files for the Call-Forwarding or the Call-Blocking services. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C
Download the Call-Blocking Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-blocking/1.1/call-blocking-1.1.war.
Download the Call-Forwarding Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-forwarding/1.1/call-forwarding-1.1.war.
Download the Call-Controller Service's DAR file from here: http://www.mobicents.org/call-controller-servlet-dar.properties.
Installing
Thecall-blocking-1.1.war, call-forwarding-1.1.war and call-controller-servlet-dar.properties archive files 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-Controller Service with MSS for JBoss or with MSS for Tomcat:
- MSS for JBoss
- Place
call-blocking-1.1.warandcall-forwarding-1.1.warinto theJBOSS_HOME/server/default/deploy/call-controller-servlet-dar.propertiesinto theJBOSS_HOME/server/default/conf/dars/ - MSS for Tomcat
- Place
call-blocking-1.1.warandcall-forwarding-1.1.warinto theCATALINA_HOME/webapps/call-controller-servlet-dar.propertiesinto theCATALINA_HOME/conf/dars/
Configuring
ThedarConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/call-controller-servlet-dar.properties. Instructions for doing so are given below by SIP Servlets Server type:
- MSS for JBoss
- Open the
JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xmlServiceelement. Add an attribute to it calleddarConfigurationFileLocation, and set it toconf/dars/call-controller-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-controller-servlet-dar.properties ">
Example 3.8. Editing MSS for JBoss's server.xml for the Call-Controller Service
Make sure that the configuration file only contains onedarConfigurationFileLocationattribute: your new one. - MSS for Tomcat
- Open the
CATALINA_HOME/conf/server.xmlServiceelement. Add an attribute to it calleddarConfigurationFileLocation, and set it toconf/dars/call-controller-servlet-dar.properties:<Service name="Sip-Servlets" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" darConfigurationFileLocation="conf/dars/call-controller-servlet-dar.properties ">
Example 3.9. Editing MSS for Tomcat's server.xml for the Call-Controller Service
Make sure that the configuration file only contains onedarConfigurationFileLocationattribute: your new one.
Running
Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in aserver.xml file), then you should go ahead and run SIP Servlets Server.
To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.
To learn how to run the SIP Servlets-enabled Tomcat Container, refer to bbssswticar-binary-SIP_Servlets_Server_with_Tomcat-Running.
Testing
Two use-cases can be distinguished for the Call-Controller service: one in which a call is blocked, and another in which a call is forwarded. Therefore, we have two cases for which we can test the Call-Controller.Procedure 3.7. Blocking a Call with Call-Controller
- Start two SIP softphones of your choice. Set the account settings of the SIP softphones to:
Relevant First Softphone Settings
- Account name:
forward-receiver - IP address:
127.0.0.1 - Port:
5090
Relevant Second Softphone Settings
- Account name:
blocked-sender
Neither of the SIP softphones needs to be registered. - From the second phone,
blocked-sender, make a call tosip:receiver@sip-servlets.com. You should receive aFORBIDDENresponse.
Procedure 3.8. Forwarding a Call with Call-Controller
- Start two SIP softphones of your choice. Set the account settings of the SIP softphones to:
Relevant First Softphone Settings
- Account name:
forward-receiver - IP address:
127.0.0.1 - Port:
5090
Relevant Second Softphone Settings
- Account name:
forward-sender
Neither of the SIP softphones needs to be registered. - From the second softphone,
forward-sender, make a call tosip:receiver@sip-servlets.com. The first phone,forward-receiver, should now be ringing.
Stopping
To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to bssswjicar-binary-SIP_Servlets_Server_with_JBoss-Stopping.
To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to bbssswticar-binary-SIP_Servlets_Server_with_Tomcat-Stopping.
Uninstalling
Unless disk space is at a premium, there is usually no need to uninstall the Call-Controller Service. However, if you will not be using it again, you may want to unset or reset thedarConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.
You may also wish to delete the WAR and DAR files for the Call-Controller Service, which you installed in Installing.
Chapter 4. Advanced Features of the SIP Servlets Server
The advanced features of JBCP SIP Servlets include Concurrency and Congestion Control, Load Balancing with the Mobicents Load Balancer, and, exclusively for MSS for JBoss, clustering and failover support.
4.1. MSS Concurrency and Congestion Control
Concurrency control and congestion control refer to settings you can tune that define the way in which messages are processed under heavy load. Needless to say, such configurable settings become highly-important in production environments. Tuning the concurrency control mode changes the way in which the SIP Servlets Server processes messages. Tuning the congestion control parameter means increasing or decreasing the point at which the server begins rejecting new requests. Both of these parameters can be set in one of four different ways: through the SIP Servlets Management Console; by editing the server's
server.xml configuration file; from the dispatcher MBean; or from the Embedded Jopr integrated management platform.
Concurrency Control
Although the JSR 289 expert group could not agree on a concurrency control mechanism for JSR 289, leaving the details up to individual implementors, we believe that concurrency control as implemented in the Mobicents SIP Servlets Servers provides a highly-useful feature necessary in production environments. Concurrency control is implemented in both MSS for JBoss and MSS for Tomcat as a configurable mode which defines the way in which the SIP Servlets Server processes messages. There are a total of three different modes to choose from, based upon the individual requirements of your setup:- None
- All SIP messages are processed as soon as possible in a thread from the global thread pool. Note that when using the
Noneconcurrency control mode, two messages belonging to the sameSipSessioncan 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. - SipSession
- SIP messages are processed as soon as possible except that two messages from the same
SipSessionare guaranteed never to be processed simultaneously. Messages from the sameSipSessionare processed sequentially in their order-of-arrival. However, two (or more) messages from differentSipSessions in the sameSipApplicationSessionmay 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 differentSipSessionin the sameSipApplicationSession. - SipApplicationSession
- SIP messages are processed as soon as possible with the guarantee that no two messages from the same
SipSessionor from the sameSipApplicationSessionwill 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 aSipSessionattribute from an unmanaged thread, or from an Enterprise JavaBean. If you do so, be aware that such access will not be synchronized.
Congestion Control
Congestion control currently refers to tuning the size of the SIP message queue, though further tunable settings are planned.
All SIP messages which cannot be processed immediately are put into a queue, and therein wait for either a free thread or for the lock on their session to be released. The exact size of this SIP message queue is a tunable parameter, and it currently defaults to
1500. If the SIP message queue becomes full, the container immediately begins rejecting any new SIP requests with a 503 (Service Unavailable) response until the queue is once again diminished. Note that in this situation, only new SIP requests are rejected; SIP responses which arrive in the milieu of a full queue are appropriately stored and are processed eventually.
Configuring the Concurrency and Congestion Control Settings
The concurrency and congestion control settings can be configured through the SIP Servlets Management Console, by editing the server'sserver.xml configuration file, from the dispatcher MBean, or from the Embedded Jopr integrated management platform. Instructions for each method are given below.
- Tuning Parameters with the SIP Servlets Management Console
- Tuning the concurrency and congestion control settings in the SIP Servlets Management ConsoleThe easiest way to configure the SIP Message Queue Size and Concurrency Control Mode tunable parameters is to open the
SIP Servlets Management Consolein your browser (by going to http://localhost:8080/sip-servlets-management), making your changes, and then 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'sserver.xmlconfiguration file; instructions for doing so follow. - Tuning Parameters Permanently by Editing
server.xml - Alternatively, you can edit your server's
server.xmlconfiguration file, which has the benefit of making your chosen settings changes permanent. Instructions follow, grouped by the SIP Servlets Server you are running:Procedure 4.1. Tuning MSS for JBoss Server Settings for Concurrency and Congestion Control
- Open the
$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml - Find the
Serviceelement and add aconcurrencyControlModeand/or asipMessageQueueSizeattribute to it.The default value of thesipMessageQueueSizeattribute is1500. That is the default value which is used even if the attribute is not present inserver.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 theconcurrencyControlModeattribute include:None,SipSessionorSipApplicationSession.SipSessionis the value of this attribute when it is not present—and overridden—inserver.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 4.1. Permanently Changing Tunable Parameters by Editing JBoss's server.xml
Procedure 4.2. Tuning MSS for Tomcat Server Settings for Concurrency and Congestion Control
- Open the
$CATALINA_HOME/conf/server.xml - Find the
Serviceelement and add aconcurrencyControlModeand/or asipMessageQueueSizeattribute to it.The default value of thesipMessageQueueSizeattribute is1500. That is the default value which is used even if the attribute is not present inserver.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 theconcurrencyControlModeattribute include:None,SipSessionorSipApplicationSession.SipSessionis the value of this attribute if when it is not present and overridden inserver.xml.1 <Service name="jboss.web" className="org.mobicents.servlet.sip.startup.SipStandardService" sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl" 5 darConfigurationFileLocation="conf/dars/mobicents-dar.properties" concurrencyControlMode="SipApplicationSession" SipApplicationSession="1600">
Example 4.2. Permanently Changing Tunable Parameters by Editing Tomcat's server.xml
- Tuning Parameters from the dispatcher MBean
- You can navigate to the
dispatcherMBean 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'sserver.xmlconfiguration file as well, or instead).When editing thedispatcherMBean from MSS for JBoss's JMX console, values allowed for the concurrency control mode areNone,SipSessionorSipApplicationSession. - Tuning Parameters from Embedded Jopr
- Finally, once you have installed Embedded Jopr, you can change the tunable parameters by pointing your browser at http://localhost:8080/embedded-jopr.
4.2. MSS Load Balancer
The “star cluster topology” with the Mobicents SIP load balancer as the central element.
The Mobicents SIP load balancer is used to balance the load of SIP service requests and responses between nodes in a SIP Servlets Server cluster. Both MSS for JBoss and MSS for Tomcat servers can be used in conjunction with the SIP load balancer to increase the performance and availability of SIP services and applications. In terms of functionality, the Mobicents SIP load balancer is a simple proxy server that intelligently forwards SIP session requests and responses between User Agents (UAs) on a Wide Area Network (WAN), and SIP Servlets Server nodes, which are almost always located on a Local Area Network (LAN). All SIP requests and responses pass through the SIP load balancer.
SIP Load Balancing Basics
All User Agents send SIP messages, such asINVITE, 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 responses across responsive nodes in a cluster, thus enabling SIP applications to meet the real-time demand for SIP services.
The Mobicents SIP load balancer implementation, its installation, configuration and an example application, are all detailed below.
Implementation of the Mobicents SIP Servlets Load Balancer
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. TheFailover section goes into more detail about this aspect of the load balancer; see: Section 4.4, “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.
SIP Message Flow
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 originating 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 will 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.
Example IP and Port Cluster Configuration, 192.168.1.1 Being the SIP Load Balancer
4.2.1. SIP Load Balancer: Installing, Configuring and Running
4.2.1.1. Pre-Install Requirements and Prerequisites
Software Prerequisites
- A SIP Servlet-Enabled JBoss Application Server or Tomcat Servlet Container
- 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 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.
- To install a SIP Servlet-enabled Tomcat Servlet Container, follow these instructions: Section 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”.
4.2.1.2. Downloading
You should ensure that you have downloaded the following files before installing and configuring:
- SIP load balancer executable JAR file
- First, you need to download the Mobicents SIP load balancer executable JAR file.
- SIP load balancer Configuration Properties 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.
4.2.1.3. Installing
Installation is simple: put the SIP load balancer executable JAR file anywhere you like.
4.2.1.4. Configuring
Configuring the SIP load balancer and the two SIP Servlets-enabled Server nodes is not difficult.
Procedure 4.3. 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.propertiesfile; descriptions of the important lines are provided beneath.1 host=127.0.0.1 internalPort=5065 externalPort=5060 #JSIP stack configuration 5 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 10 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 4.3. Complete Sample lb.properties File
- host
- This is the local IP address, or interface, on which the SIP load balancer will listen for incoming requests.
- externalPort
- This is the port on which the SIP load balancer will listen for incoming requests from SIP User Agents.
- internalPort
- 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 theSipStackandSipStackImplclasses for further information on them. - Configure the
server.xmlconfiguration files for all of your Servlet container nodes according to the following scheme. Pay special attention to the location of theserver.xmlconfiguration 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 theserver.xmlfile for the “all” Configuration Profile. This file is therefore located in theserver/all/deploy/jboss-web.deployerdirectory. 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 theserver.xmlfile inserver/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 4.3, “MSS for JBoss: Clustering Support”.- the
classNameattribute of theServiceelement should have the valueorg.mobicents.servlet.sip.startup.failover.SipStandardBalancerNodeServiceinstead oforg.mobicents.servlet.sip.startup.SipStandardService. - Add an attribute called “
balancers” to theServiceelement which has as its values the IP address (or addresses) of the SIP load balancer(s) to which it should send heartbeats.
4.2.1.5. Running
Procedure 4.4. 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.propertiesin 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.xmlconfiguration file [7], 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 theserver.xmlconfiguration file where you should change the value for each new node you add to the cluster:1 <!-- Define a SIP Connector --> 2 <Connector port="5080" 3
Example 4.4. Changing the SIP Connector Port for Servlet Server Nodes in server.xml
Finally, start all of your SIP load balancer client nodes.
4.2.1.6. Testing
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
4.2.1.7. Stopping
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
4.2.1.8. Uninstalling
To uninstall the SIP load balancer, simply delete the JAR file you installed.
4.3. MSS for JBoss: Clustering Support
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 Application Server 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.
4.3.1. SIP Servlets Server Cluster: Installing, Configuring and Running
4.3.1.1. Pre-Install Requirements and Prerequisites
Software Prerequisites
- A SIP Servlets-enabled JBoss Application Server
- 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.First, install your SIP Servlets Server with JBoss by following these instructions: Section 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”. Then proceed to Section 4.3.1.2, “Configuring” below.
4.3.1.2. Configuring
Once installed, the MSS for JBoss binary distribution requires only minor configuration in order to enable clustering. SIP and HTTP session state clustering are pre-configured 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 Must Use the all Server Configuration Profile
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:
1 <?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" 5 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 --> 10 <!-- 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! --> 15 <!-- 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/> 20 <context-param> <param-name>com.sun.faces.injectionProvider</param-name> <param-value>org.jboss.web.jsf.integration.injection.JBossInjectionProvider</param-value> </context-param>
Example 4.5. 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.
4.3.1.3. Running
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.
Running MSS for JBoss with the “all” Configuration Profile, on Linux
To run the server on Linux using the “all” Configuration Profile, start the server with the following command:mss-jboss-<version>]$ ./bin/run.sh -c all
Running MSS for JBoss with the “all” Configuration Profile, on Windows
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-<version>>bin\run.bat -c all
4.3.1.4. Stopping
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 4.2.1.7, “Stopping”
- Stopping MSS for JBoss: Section 2.1.9, “Stopping”
- Stopping MSS for Tomcat: Section 2.2.8, “Stopping”
4.3.1.5. Testing
To test your MSS for JBoss cluster setup for mid-call failover, refer to:
4.3.1.6. Uninstalling
Uninstalling a SIP Servlets Cluster would entail deleting the Mobicents SIP Servlets Servers directories, the SIP Load Balancer directory, and possibly unsetting the
JBOSS_HOME environment variable.
4.4. MSS for JBoss: Failover Support
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 4.5. Preparing for Clustering
- Modify the
JBOSS_HOMEenvironment variable in theprepare-jboss-server-for-clustering-failover-network.shshell script so that it points to the topmost directory of your MSS for JBoss installation (the one of whichbin/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”.
grep For The Win!
On the Linux command line, you can use thegrepcommand 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" *) &
4.4.1. MSS for JBoss Cluster: Installing, Configuring and Running
TBD
4.4.1.1. Pre-Install Requirements and Prerequisites
Software Prerequisites
4.4.1.2. Downloading
4.4.1.3. Installing
4.4.1.4. Configuring
4.4.1.5. Running
4.4.1.6. Using
4.4.1.7. Testing
4.4.1.8. Uninstalling
[7]
In the JBoss SIP Servlets Server binary distribution, this file is located inside the <topmost_directory>/server/all/deploy/jboss-web.deployer/ directory, and in the Tomcat binary distribution, it is located in the <topmost_directory>/conf/ directory.
Revision History
| Revision History | |||
|---|---|---|---|
| Revision 2.0 | Fri Mar 06 2009 | ||
| |||
Index
F
- feedback
- contact information for this manual, We Need Feedback!
JBoss Communications Platform 1.2.0
Media Server User Guide
The JBoss Communications Platform Media Server Gateway Guide
Edition 1.0
Legal Notice
Copyright © 2009 Red Hat Inc. This material may only be distributed subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License (which is presently available at http://creativecommons.org/licenses/by-nc-sa/3.0/).
Red Hat, the "Shadow Man" logo and JBoss are registered trademarks of Red Hat,
Inc. in the United States and other countries.
All other trademarks referenced herein are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072USAPhone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588Research Triangle Park, NC 27709USA
Abstract
JBCP, the JBoss Communications Platform, is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. JBCP serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes) by leveraging J2EE to enable the convergence of data and video in Next-Generation
Intelligent Network (NGIN) applications.
The JBoss Communications Platform enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration
and Presence-Sensing. Out-of-the-box monitoring and management of JBCP components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise
applications with end points such as the Web, Customer Relationship
Management (CRM) systems and Service-Oriented Architectures (SOAs). The JBoss Communications Platform is the natural choice for telecom Operations Support Systems
(OSSes) and Network Management Systems (NMSes).
In addition to telecom, JBCP is suitable for a variety of problem domains demanding an
Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial
trading, online gaming, (RFID) sensor network integration, and distributed control.
- Preface
- 1. Introduction to the Mobicents Media Server
- 2. Installing the Mobicents Media Server
- 3. Configuring the Mobicents Media Server
- 4. Controlling and Programming the Mobicents Media Server
- 5. MMS: Event Packages
- 6. MMS Demonstration Example
- 7. MMS: Best Practices
- A. Revision History
- Index
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:
To see the contents of the filemy_next_bestselling_novelin your current working directory, enter thecat my_next_bestselling_novelcommand at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.
Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:
Press Enter to execute the command.Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session.
The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in
Mono-spaced Bold. For example:
File-related classes includefilesystemfor file systems,filefor files, anddirfor directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).To insert a special character into a gedit file, choose from the main menu bar. Next, choose from the Character Map menu bar, type the name of the character in the Search field and click . The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the button. Now switch back to your document and choose from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.
Note the shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select from the sub-menu in the menu of the main menu bar' approach.
Mono-spaced Bold ItalicProportional Bold Italic
Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, typesshat a shell prompt. If the remote machine isusername@domain.nameexample.comand your username on that machine is john, typessh john@example.com.Themount -o remountcommand remounts the named file system. For example, to remount thefile-system/homefile system, the command ismount -o remount /home.To see the version of a currently installed package, use therpm -qcommand. It will return a result as follows:package.package-version-release
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.
1.2. Pull-quote Conventions
Two, commonly multi-line, data types are set off visually from the surrounding text.
Output sent to a terminal is set in
Mono-spaced Roman and presented thus:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in
Mono-spaced Roman but are presented and highlighted as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring Important boxes won't cause data loss but may cause irritation and frustration.
Warning
A Warning should not be ignored. Ignoring warnings will most likely cause data loss.
2. We Need Feedback!
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product JBoss Communications Platform.
When submitting a bug report, be sure to mention the manual's identifier: Media_Server_User_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
Chapter 1. Introduction to the Mobicents Media Server
1.1. Overview: the Reasoning and Need for Media Servers
Media Gateways Bridge Multiple Technologies
Today, all communications can be routed through computers. Widespread access to broadband Internet and the ubiquity of Internet Protocol (IP) enable the convergence of voice, data and video. Media gateways provide the ability to switch voice media between a network and its access point. Using Digital Subscriber Line (DSL) and fast-Internet cable technology, a media gateway converts, compresses and packetizes voice data for transmission back-and-forth across the Internet backbone for landline and wireless phones. Media gateways sit at the intersection of Public Switched Telephone Networks (PSTNs) and wireless or IP-based networks.The Justification for Media Gateways for VoIP
Multiple market demands are pushing companies to converge all of their media services using media gateways with Voice-over-IP (VoIP) capabilities. Companies have expectations for such architectures, which include:- Lowering initial costs
- Capital investment is decreased because low-cost commodity hardware can be used for multiple functions.
- Lowering development costs
- Open system hardware and software standards with well-defined applications reduce costs, and Application Programming Interfaces (APIs) accelerate development.
- Handling multiple media types
- Companies want VoIP solutions today, but also need to choose extensible solutions that will handle video in the near future.
- Lowering the costs of deployment and maintenance
- Standardized, modular systems reduce training costs and maintenance while simultaneously improving uptime.
- Enabling rapid time-to-market
- Early market entry hits the window of opportunity and maximizes revenue.
What Is the Mobicents Media Server?
The Mobicents Media Gateway is an open source Media Server aimed at:- Delivering competitive, complete, best-of-breed media gateway functionality of the highest quality.
- Meeting the demands of converged wireless and landline networks, DSL and cable broadband access, and fixed-mobile converged VoIP networks from a single—and singularly-capable—media gateway platform.
- Increasing flexibility with a media gateway that supports a wide variety of call control protocols, which possesses an architecture that can scale to meet the demands of small-carrier providers as well as large enterprises.
1.2. Mobicents Media Server Architecture
Media services have played an important role in the traditional Time Division Multiplexing (TDM)-based telephone network. As the network migrates to an Internet Protocol (IP)-based environment, media services are also moving to new environments.
One of the most exciting trends is the emergence and adoption of complementary modular standards that leverage the Internet to enable media services to be developed, deployed and updated more rapidly than before in a network architecture that supports the two concepts called provisioning-on-demand and scaling-on-demand.
1.2.1. Design Overview and Typical Deployment Scenario
General Design Overview
The Mobicents Media Server is developed on top of existing Java technologies. The Java platform is ideal for network computing. It offers a single, unified-and-unifying programming model that can connect all elements of a business infrastructure. The modularization effort is supported by the use of the Java Management Extension (JMX) API, and the industry-standard Service Logic Execution Environment (SLEE) container. Using JMX enables easy management of both the server's media components and the control modules hosted by the SLEE.
The Mobicents Media Server's high degree of modularity benefits the application developer in several ways. The already-tight code can be further trimmed down to support applications which require small footprints. For example, if PSTN interconnection is unnecessary in your application, then the D-channel feature can simply be removed from the Media Server. If you later decide to deploy the same application within a Signaling System 7 (SS7) network, then simply enable the appropriate endpoint. Another example is the freedom you have to drop your favorite media control protocol directly into the SLEE container.
The Media Server architecture assumes that call control intelligence lies outside of the Media Server and is handled by an external entity. The Media Server also assumes that call controllers will use control procedures such as MGCP, Mecago or MSML, among others. Each specific control module can be plugged in directly to the server as a standard SLEE deployable unit. Utilizing the SLEE container for the implementation of control protocol-specific communication logic allows for simple deployment, as well as facilitating deployment of such control modules. The developer does not need to mess with low-level transaction and state management details, multi-threading, connection-pooling and other similar complex, low-level details and APIs.
Note
The Mobicents Media Server uses SLEE for implementing its own communication capabilities. The SLEE container does not serve here as a call controller.
In addition to control protocol modules, the SLEE container is aimed at providing high-level features like Interactive Voice Response (IVR), the Drools business rule management system, and VoiceXML engines.
The modules deployed under SLEE control interact with the Media Server's Service Provider Interface (SPI) through the Media Server Control Resource Adapter, or MSC-RA. The MSC-RA follows the recommendations of JSR-309 and implements asynchronous interconnection with the Media Server SPI stack. This local implementation is restricted and does not use high-level abstractions like VoiceXML dialogs, etc..
Typical Deployment Scenario
The Mobicents Media Server offers a complete media gateway and server solution; here is a non-exhaustive list of the MMS's capabilities:- Digital Signal Processing to convert and compress TDB voice circuits into IP packets;
- announcement access points;
- conferencing;
- high-level Interactive Voice Response (IVR) engines;
The gateway is able to provide signaling conversation and can operate as a Session Border Controller at the boundaries of Local Access Networks (LANs). The Media Server is always controlled by an external JBoss Communications Platform application server, which implements the call control logic.
Typical Media Server Deployment Scenario
1.2.2. Endpoints
Endpoints
It is convenient to consider a media gateway as a collection of endpoints. An endpoint is a logical representation of a physical entity such as an analog phone or a channel in a trunk. Endpoints are sources or sinks of data and can be either physical or virtual. Physical endpoint creation requires hardware installation, while software is sufficient for creating virtual endpoints. An interface on a gateway that terminates at a trunk connected to a PTSN switch would be an example of a physical endpoint. An audio source in an audio content server would be an example of a virtual endpoint.
The type of the endpoint determines its functionality. Our analysis, so far, has led us to isolate the following basic endpoint types:
- digital signal 0 (DS0)
- analog line
- announcement server access point
- conference bridge acces point
- packet relay
- Asynchronous Transfer Mode (ATM) "trunk side" interface
This list is not final: other endpoint types may be defined in the future, such as test endpoints which could be used to check network quality, or frame-relay endpoints that could be used to manage audio channels multiplexed over a frame-relay virtual circuit.
Descriptions of Various Access Point Types
- Announcement Server Access Point
- An announcement server endpoint provides access, intuitively, to an announcement server. Upon receiving requests from the call agent, the announcement server “plays” a specified announcement. A given announcement endpoint is not expected to support more than one connection at a time. Connections to an announcement server are typically one-way; they are “half-duplex”: the announcement server is not expected to listen to audio signals from the connection. Announcement access points are capable of playing announcements; however, these endpoints do not have the capability of transcoding. To achieve transcoding, a Packet Relay must be used. Also note that the announcement server endpoint can generate tones, such as dual-tone multi-frequency (DTMF).
- Interactive Voice Response Access Point
- An Interactive Voice Response (IVR) endpoint provides access to an IVR service. Upon requests from the call agent, the IVR server “plays” announcements and tones, and “listens” for responses, such as (DTMF) input or voice messages, from the user. A given IVR endpoint is not expected to support more than one connection at a time. Similarly to announcement endpoints, IVR endpoints do not possess media-transcoding capabilities. IVR plays and records in the format in which the media was stored or received.
- Conference Bridge Access Point
- A conference bridge endpoint is used to provide access to a specific conference. Media gateways should be able to establish several connections between the endpoint and packet networks, or between the endpoint and other endpoints in the same gateway. The signals originating from these connections are mixed according to the connection “mode” (as specified later in this document). The precise number of connections that an endpoint supports is characteristic of the gateway, and may, in fact, vary according to the allocation of resources within the gateway.
- Packet Relay Endpoint
- A packet relay endpoint is a specific form of conference bridge that typically only supports two connections. Packet relays can be found in firewalls between a protected and an open network, or in transcoding servers used to provide interoperation between incompatible gateways, such as gateways which don't support compatible compression algorithms and gateways which operate over different transmission networks, such as IP or ATM.
- Echo Endpoint
- An echo—or loopback—endpoint is a test endpoint that is used for maintenance and/or continuity testing. The endpoint returns the incoming audio signal from the endpoint back to that same endpoint, thus creating an echo effect
Signal Generators (SGs) and Signal Detectors (SDs)
This endpoint contains a set of resources which provide media-processing functionality. It manages the interconnection of media streams between the resources, and arbitrates the flow of media stream data between them. Media services, also called commands, are invoked by a client application on the endpoint; that endpoint causes the resources to perform the desired services, and directs events sent by the resources to the appropriate client. A primary resource and zero or more secondary resources are included in the endpoint. The primary resource is typically connected to an external media stream, and provides the data from that stream to secondary resources. The secondary resources may process that stream (e.g. by recording it and/or performing automatic speech recognition on it), or may themselves generate generate media stream data (e.g., by playing a voice file) which is then transmitted to the primary resource.
A resource is statically prepared if the preparation takes place at the time of creation. A resource is dynamically prepared if preparation of a particular resource (and its associated media streams) does not occur until it is required by a media operation. Static preparation can lead to less efficient usage of the Media Server's resources, because those resources tend to be allocated for a longer time before use. However, once a resource has been prepared, it is guaranteed to be available for use. Dynamic preparation may utilize resources more efficiently because just-in-time (JIT) allocation algorithms may be used.
An endpoint is divided logically into a Service Provider Interface that is used to implement a specific endpoint, and a management interface, which is used to implement the manageable resources of that endpoint. All endpoints are plugged into the Mobicents SLEE server by registering with the MBean server. The kernel in that sense is only an aggregator, and not a source of actual functionality. The functionality is provided by the SPI implementation of the MBeans and, in fact, all major endpoints are manageable MBeans which are interconnected through the MBean server. The best way to add endpoints to a Media Server is to write a new JMX bean which provides an implementation of the endpoint's SPI.
The SPI layer is an abstraction that endpoint providers must implement in order to enable their media-processing features. An implementation of an SPI for an endpoint is referred to as an Endpoint Provider.
View the EndpointManagementMBean UML Diagram.
1.2.3. Endpoint Identifiers
An endpoint is identified by its local name. The syntax of the local name depends on the type of endpoint being named. However, the local name for each of these types is naturally hierarchical, beginning with a term that identifies the physical gateway containing the given endpoint, and ending with a term which specifies the individual endpoint concerned. With this in mind, the JNDI naming rules are applied to the endpoint identifiers.
1.2.4. Connections
Connections are created on the call agent on each endpoint that will be involved in the “call”. In the classic example of a connection between two “DS0” endpoints, EP1 and EP2, the call agents controlling the endpoints establish two connections (C1 and C2):
Media Server Connections
Each connection is designated locally by a connection identifier, and will be characterized by connection attributes.
Resources and Connection Attributes
Many types of resources can be associated with a connection, such as specific signal-processing functions or packetization functions. Generally, these resources fall in two categories:Two Types of Resources
- Externally-Visible Resources
- Externally-visible resources are ones which affect the format of “the bits on the network”, and must be communicated to the second endpoint involved in the connection.
- Internal Resources
- Internal resources are resources which determine which signal is being sent over the connection and how the received signals are processed by the endpoint.
The resources allocated to a connection or, more generally, to the handling of the connection, are chosen by the Media Server under instructions from the call agent. The call agent provides these instructions by sending two set of parameters to the Media Server:
- The local directives instruct the gateway on the choice of resources that should be used for a connection.
- When available, the session description is provided by the other end of the connection.
The local directives specify parameters such as the mode of the connection (e.g. send-only, or send-receive), preferred coding or packetization methods, the usage of echo-cancellation or silence suppression, etc. (A more comprehensive and detailed list can be found in the specification of the
LocalConnectionOptions parameter of the CreateConnection command.) For each of these parameters, the call agent can either specify a value, a range of values, or no value at all. This allow various implementations to implement various levels of control, from very tight control where the call agent specifies minute details of the connection-handling, to very loose control, where the call agent only specifies broad guidelines, such as the maximum bandwidth, and lets the gateway select the detailed values itself.
Based on the value of the local directives, the gateway determines the resources allocated to the connection. When this is possible, the gateway will choose values that are in line with the remote session description; however, there is no absolute requirement that the parameters will be exactly the same.
Once the resource have been allocated, the gateway will compose a session description that describes the way it intends to receive packets. Note that the session description may in some cases present a range of values. For example, if the gateway is ready to accept one of several compression algorithms, it can provide a list of these accepted algorithms.
Local Connections Are a Special Case
Large gateways include a large number of endpoints which are often of different types. In some networks, we may often have to set up connections between endpoints located within the same gateway. Examples of such connections may be:- connecting a trunk line to a wiretap device;
- connecting a call to an Interactive Voice-Response (IVR) unit;
- connecting a call to a conferencing unit; or,
- routing a call from one endpoint to another, something often described as a hairpin connection.
Local connections are much simpler to establish than network connections. In most cases, the connection will be established through a local interconnecting device, such as, for example, a TDM bus.
1.2.5. Events and Signals
The concept of events and signals is central to the Media Server. A Call Controller may ask to be notified about certain events occurring in an endpoint (for example: off-hook events) by passing an event identifier as a parameter to an endpoint's
subscribe() method.
A Call Controller may also request certain signals to be applied to an endpoint (for example: a dial-tone) by supplying the identifier of the event as an argument to the endpoint's
apply() method.
Events and signals are grouped in packages, within which they share the same namespace. which we will refer to as an event identifier. Event identifiers are integer constants. Some of the events may be parametrized with additional data such as with a DTMF mask.
Signals are divided into different types depending on their behavior:
Types of Signals
- On/off (OO)
- Once applied, these signals last until they are turned off. This can only happen as the result of a reboot/restart or a new signal request where the signal is explicitly turned off. Signals of type OO are defined to be idempotent; thus, multiple requests to turn a given OO signal on (or off) are perfectly valid. An On/Off signal could be a visual message-waiting indicator (VMWI). Once turned on, it must not be turned off until explicitly instructed to by the Call Agent, or as a result of an endpoint restart. In other words, these signals will not turn off as a result of the detection of a requested event.
- Time-out (TO)
- Once applied, these signals last until they are either cancelled (by the occurrence of an event or by explicit releasing of signal generator), or a signal-specific period of time has elapsed. A TO signal that times out will generate an operation complete event. If an event occurs prior to the allotted 180 seconds, the signal will, by default, be stopped (the keep signals active action can be used to override this behavior). If the signal is not stopped, the signal will time out, stop, and generate an operation complete event, about which the server controller may or may not have requested to be notified. A TO signal that fails after being started, but before having generated an operation complete event, will generate an operation failure event that includes the name of the signal that failed. Deletion of a connection with an active TO signal will result in such a failure.
- Brief (BR)
- The duration of these signals is normally so short that they stop on their own. If a signal stopping event occurs, or a new signal request is applied, a currently active BR signal will not stop. However, any pending BR signals not yet applied will be cancelled (a BR signal becomes pending if a signal request includes a BR signal, and there is already an active BR signal). As an example, a brief tone could be a DTMF digit. If the DTMF digit
1is currently being played, and a signal stopping event occurs, the1would play to completion. If a request to play DTMF digit2arrives before DTMF digit1finishes playing, DTMF digit2would become pending.
Signal(s) may be generated on endpoints or on connections. One or more actions such as the following are associated with each event:
- notify the event immediately, together with the accumulated list of observed events;
- accumulate the event in an event buffer, but do not yet notify;
- keep signal(s) active; or
- ignore the event.
Chapter 2. Installing the Mobicents Media Server
The Mobicents Media Server is a self-contained Java software stack consisting of multiple servers architecturally designed to work together. This server stack includes the JBoss Application Server and the Mobicents JAIN SLEE Server; both of these required servers are included in the Media Server distribution.
The Mobicents Media Server is available in both binary and source code distributions. The simplest way to get started with the Media Server is to download the ready-to-run binary distribution. Alternatively, the source code for the Mobicents Media Server can be obtained by checking it out from its repository using the Subversion version control system (VCS), and then built using the Maven build system. Whereas installing the binary distribution is recommended for most users, obtaining and building the source code is recommended for those who want access to the latest revisions and Media Server capabilities.
Installing the Java Development Kit
2.1. Java Development Kit: Installing, Configuring and Running
The JBoss Communications Platform is written in Java; therefore, before running any JBCP 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 JBCP must be version 5 or higher[8].
Should I Install the JRE or JDK?
Although you can run JBCP servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, JBCP-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?
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.
Downloading
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 JBCP in a production environment.
Installing
The following procedures detail how to install the Java Development Kit on both Linux and Windows.Procedure 2.1. Installing the JDK on Linux
- Regardless of which file you downloaded, you can install it on Linux by simply making sure the file is executable and then running it:
~]$ chmod +x "jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin" ~]$ ./"jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin"
You Installed Using the Non-RPM Installer, but Want the SysV Service Scripts
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/.
Important
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
Configuring your system for the JDK consists in two tasks: setting theJAVA_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.
- Setting the
JAVA_HOMEEnvironment Variable on Generic Linux - After installing the JDK, you must ensure that the
JAVA_HOMEenvironment variable exists and points to the location of your JDK installation.Setting the
You can determine whetherJAVA_HOMEEnvironment Variable on LinuxJAVA_HOMEis set on your system byechoing it on the command line:~]$ echo $JAVA_HOME
IfJAVA_HOMEis 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~/.bashrcconfiguration 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 JBCP (any environment variablesexported from~/.bashrcfiles are local to that user). - Setting
java,javacandjava_sdk_1.5.0Using thealternativescommand Selecting the Correct System JVM on Linux using
On systems with thealternativesalternativescommand, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as whichjavaandjavacexecutables should be run when called.As the root user, call/usr/sbin/alternativeswith the--config javaoption 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 thejavaexecutable. In thealternativesinformation printout above, a plus (+) next to a number indicates the one currently being used. As peralternatives' 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 thejavaccommand and thejava_sdk_1.5.0environment variable, as the root user:~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
- Setting the
JAVA_HOMEEnvironment Variable on Windows - For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
Testing
Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in yourPATH, run the java -version command in the terminal from your home directory:
~]$ java -version java version "1.5.0_16" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03) Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling
There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily usingalternatives, and/or by setting JAVA_HOME.
Uninstalling the JDK on Linux
On RPM-based systems, you can uninstall the JDK using theyum remove <jdk_rpm_name> command.
Uninstalling the JDK on Windows
On Windows systems, check the JDK entry in theStart menu for an uninstall command, or use Add/Remove Programs.
2.2. Binary Distribution: Installing, Configuring and Running
The Media Server distribution comes bundled with the JBoss Application Server, the latest version of the Mobicents JAIN SLEE Server, and all of the resource adapters required to run the various bundled examples.
2.2.1. Pre-Install Requirements and Prerequisites
You should ensure that a few requirements have been met before continuing with the install.
Hardware Requirements
- Sufficient Disk Space
- You must have sufficient disk space in order to install the Media Server binary release. Once unzipped, version 1.0.0 of the Media Server binary release requires at least 100 MB of free disk space. Keep in mind that disk space requirements may change from release to release.
- Anything Java Itself Will Run On
- The Mobicents Media Server and its bundled servers, JBoss and JAIN SLEE, are 100% Java. The Media Server will run on the same hardware that the JBoss Application Server runs on.
Software Prerequisites
- JDK 5 or Higher
- A working installation of the Java Development Kit (JDK) version 5 or higher is required in order to run the Mobicents Media Server. Note that the JBoss Application Server is a runtime dependency of the Media Server and, as mentioned, comes bundled with the binary distribution.
2.2.2. Downloading
You can download the latest version of the Media Server from http://www.mobicents.org/mms-downloads.html. The top row of the table holds the latest version. Click the
Download link on the right to start the download from Sourceforge.net.
2.2.3. Installing
Once the requirements and prerequisites have been met and you have downloaded the binary distribution zip file, you are ready to install the Media Server. Follow the instructions below for your platform, whether Linux or Windows.
Use Version Numbers Relevant to Your Installation!
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.3. Installing the Media Server Binary Distribution on Linux
- Assuming that you downloaded the binary distribution zip file to your home folder, create a subdirectory to unzip hte files to. 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 binary distribution you downloaded.
~]$ mkdir “ms-<version>” - Move the downloaded zip file into the directory you just created:
~]$ mv “mobicents-media-server-all-1.0.0.GA.zip” “ms-
<version>” - Move into that directory:
~]$ cd “ms-<version>” - Finally, use Java's
jarcommand to extract the contents of the zip file into the current directory, thus completing the install:-xvfms-
<version>]$ jar -xvf “mobicents-media-server-all-1.0.0.GA.zip”- Alternatively, if Linux's
unziputility is present on your system or is installable, you can use it in lieu of Java'sjarcommand:-xvfms-
<version>]$ unzip “mobicents-media-server-all-1.0.0.GA.zip”Note
You can also useunzip's-d<unzip_to_location>
- To free disk space, you may want to delete the zip file once you've extracted its contents:
ms-
<version>]$ rm “mobicents-media-server-all-1.0.0.GA.zip”
Procedure 2.4. Installing the Media Server Binary Distribution on Windows
- For this example, we'll assume that you downloaded the binary distribution zip file to the
My Downloadsfolder. First, using Windows Explorer, create a subfolder inMy Downloadsto extract the zip file's contents into. - 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
jarcommand to extract the binary distribution files from the zip archive. To use this method instead, first move the downloaded zip file from-xvfMy Downloadsto the folder that you just created to hold the Media Server files. - Then, open the Windows Command Prompt and navigate to the folder holding the archive using the
cdcommand:Opening the Command Prompt from Windows Explorer
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 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\ms-<version>” - Finally, use the
jarcommand to extract the archive contents into the current folder.-xvfC:\Users\Me\My Downloads\ms-
<version>>jar -xvf “mobicents-media-server-all-1.0.0.GA.zip”
- At this point, you may want to move the folder holding the Media Server binary files (in this example, the folder named
ms-) to another location. This step is not strictly necessary, but it is probably a good idea to move the Media Server folder from<version>My Downloadsto 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\ms-
<version>>delete “mobicents-media-server-all-1.0.0.GA.zip”
2.2.4. Configuring (and Setting JBOSS_HOME)
2.2.4.1. Setting the JBOSS_HOME Environment Variable
The JBoss Communications Platform (JBCP) is built on top of the JBoss Enterprise Application Platform (JBoss EAP). You do not need to set the
JBOSS_HOME environment variable to run any of the JBoss Communications Platform servers unless JBOSS_HOME is already set.
The best way to know for sure whether
JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.
Checking to See If JBOSS_HOME is Set on Linux
At the command line,echo$JBOSS_HOME to see if it is currently defined in your environment:
~]$ echo $JBOSS_HOME
Silence on the command line (a completely blank line) means that it is not set, in which case you can proceed with running the JBoss Communications Platform.
Checking to See if JBOSS_HOME is Set on Windows
For information on determining whether environment variables are set in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.
If
JBOSS_HOME is already set on your system, then you have three options:
unsetit, which only takes effect for the current session and is therefore not advised;- find where
JBOSS_HOMEis defined, such as in your local~/.bashrcstartup script in Linux, or, possibly, system-wide in/etc/bashrc, and remove it or comment it out; - or point it to the correct location, in which case you should refer to the following instructions on how to set
JBOSS_HOME.
Setting the JBOSS_HOME Environment Variable on Linux
TheJBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform that you installed. As another hint, this topmost directory contains a bin subdirectory.
Setting
JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Linux, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.
Procedure 2.5. To Set JBOSS_HOME on Linux...
- Open the
~/.bashrcstartup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:export JBOSS_HOME="/home/
<username>/<path>/<to>/<install_directory>" - Save and close the
.bashrcstartup script. - You should
sourcethe.bashrcscript to force your change to take effect, so thatJBOSS_HOMEbecomes set for the current session[9].~]$ source ~/.bashrc
- Finally, ensure that
JBOSS_HOMEis set in the current session, and actually points to the correct location:Note
The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output,JBOSS_HOMEhas been set correctly to thetopmost_directoryof the JBCP installation. Note that if you are installing one of the standalone JBCP servers (with JBoss AS bundled!), thenJBOSS_HOMEwould point to thetopmost_directoryof your server installation.~]$ echo $JBOSS_HOME /home/silas/jboss-eap-4.3/jboss-as
Setting the JBOSS_HOME Environment Variable on Windows
TheJBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform that you installed. As another hint, this topmost directory contains a bin subdirectory.
For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.
2.2.5. Running
Once installed, you can run the Mobicents Media Server by executing the one of the startup scripts in the
<topmost_directory>/jboss-4.2.3.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 Media 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 Media Server started successfully if the last line of output is similar to the following (ending with “Started in 23s:648ms”):
11:23:07,656 INFO [Server] JBoss (MX MicroKernel) [4.2.2.GA (build: SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 23s:648ms
Procedure 2.6. Running the Media Server on Linux
- Change your working directory to the Media Server's topmost directory (the one which you extracted the zip file's contents to):
~]$ cd “ms-<version>” - (Optional) Ensure that the
jboss-4.2.3.GA/bin/run.shstart script is executable:ms-
<version>]$ chmod +x “jboss-4.2.3.GA/bin/run.sh” - Finally, execute the
run.shBourne shell script:ms-
<version>]$ “./jboss-4.2.3.GA/bin/run.sh”- Instead of executing the Bourne shell script to start the server, you may alternatively run the
run.jarexecutable Java archive in thejboss-4.2.3.GA/bin/directory:ms-
<version>]$ java -jar “jboss-4.2.3.GA/bin/run.jar”
Procedure 2.7. Running the Media Server on Windows
- There are several different ways to start the Media 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.3.GA\bin\subfolder. - Although not the preferred way (see below), it is possible to start the Media Server by double-clicking on the
run.batexecutable batch file.- As mentioned above, the best way to start the Media 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
jboss-4.2.3.GA\bin\folder in Windows Explorer, or you can open the Command Prompt via the Start menu and navigate to the correct folder:C:\Users\Me\My Downloads>cd “ms-<version>” - Start the Media Server by running the executable
run.batbatch file:C:\Users\Me\My Downloads\ms-
<version>>jboss-4.2.3.GA\bin\run.bat- It is also possible to start the Media Server by running the
run.jarexecutable Java archive:C:\Users\Me\My Downloads\ms-
<version>>java -jar jboss-4.2.3.GA\bin\run.jar
2.2.6. Stopping
Detailed instructions for stopping the Media 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 2.8. Stopping the Media Server on Linux by Executing shutdown.sh or shutdown.jar
- You can shut down the Media Server by executing the
shutdown.shBourne shell script in thejboss-4.2.3.GA/bin/directory. To do so, first change your working directory to the Media Server's topmost directory (the one to which you extracted the downloaded zip file's contents):~]$ cd “ms-<version>” - (Optional) Ensure that the jboss-4.2.3.GA/bin/shutdown.sh start script is executable:
ms-
<version>]$ chmod +x “jboss-4.2.3.GA/bin/shutdown.sh” - Finally, run the
shutdown.shexecutable Bourne shell script, and remember to add the-Soption (which is the short option for “--shutdown”) as a command line argument:ms-
<version>]$ “./jboss-4.2.3.GA/bin/shutdown.sh” -S- Instead of executing the Bourne shell script to stop the server, you may alternatively run the
shutdown.jarexecutable Java archive to do so (and remembering, again, to add the-Scommand line argument):ms-
<version>]$ java -jar “jboss-4.2.3.GA/bin/shutdown.jar” -S
Procedure 2.9. Stopping the Media Server on Windows
- Stopping the Media Server on Windows consists in executing either the
shutdown.bator theshutdown.jarexecutable file in thejboss-4.2.3.GA\binsubfolder of the Media Server binary distribution. Make sure to add the-Soption (which is the short option for--shutdown) as a command line argument.C:\Users\Me\My Downloads\ms-
<version>>jboss-4.2.3.GA\bin\shutdown.bat -S- Alternatively, you can execute the
shutdown.jarJava archive by running thejavacommand, and remembering to add the-jar-Soption as a command line argument:C:\Users\Me\My Downloads\ms-
<version>>java -jar jboss-4.2.3.GA\bin\shutdown.jar -S
2.2.7. Using
2.2.8. Testing
For information on testing the Media Server, refer to Section 2.3, “Writing and Running Tests Against the Mobicents Media Server”.
2.2.9. Uninstalling
To uninstall the Media Server, simply delete the directory you decompressed the binary distribution archive into.
2.3. Writing and Running Tests Against the Mobicents Media Server
For information about the different kinds of tests that the Mobicents Media Server provides, refer to Writing and Running Tests Against MMS.
[8] At this point in time, it is possible to run most JBCP servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.
[9]
Note that any other terminals which were opened prior to your having altered .bashrc will need to source~/.bashrc as well should they require access to JBOSS_HOME.
Chapter 3. Configuring the Mobicents Media Server
All endpoints are plugged into the Mobicents JAIN SLEE server by registering with the MBean server. Note that if you have configured the servlet container, e.g. Tomcat, to service a different port, then you will need to supply a different port number in the URL.
3.1. RTPManager
RTPManager is responsible for managing the actual RTP Socket. The reference of RTPManager is passed to each endpoint (the endpoint does the look-up via JNDI) and endpoints leverage the RTPManagerRTPManger to create Connections and decide on supported codecs.
The configurable aspects of the RTPManager are:
- JndiName
- The Java Naming and Directory Interface (JNDI) name under which the endpoint is to be bound.
- BindAddress
- The IP address to which this endpoint is bound.
- Jitter
- The size of the jitter buffer in milliseconds.
- PacketizationPeriod
- The period of media stream packetization in milliseconds.
- PortRange
- The port range within which the RTP socket will be created. The first free port in the given range will be used.
- AudioFormats
- The Audio Formats supported by this instance of
RTPManger. - UseStun
- Whether the Mobicents Media Server is behind a NAT and a STUN setting is required. The STUN details are explained in Section 3.6, “MMS STUN Support”.
Supported RTP Formats
TheRTPManager is able to receive the following RTP media types:
| Media Type | PayLoad Number |
|---|---|
| Audio: G711 (A-law) 8bit, 8kHz | 8 |
| Audio: G711 (U-law) 8bit, 8kHz | 0 |
| telephone-event | 101 |
| Audio: GSM 8bit, 8kHz | 3 |
| Audio: G729 8bit, 8kHz | 18 |
| Audio: Speex 8bit, 8kHz | 97 |
Table 3.1. Supported RTP Formats
<mbean
code="org.mobicents.media.server.impl.jmx.rtp.RTPManager"
name="media.mobicents:service=RTPManager,QID=1">
<attribute
name="JndiName">java:media/mobicents/protocol/RTP</attribute>
<attribute
name="BindAddress">${jboss.bind.address}</attribute>
<attribute
name="Jitter">60</attribute>
<attribute
name="PacketizationPeriod">20</attribute>
<attribute
name="PortRange">1024-65535</attribute>
<attribute
name="AudioFormats">0 = ULAW, 8000, 8, 1; 3 = GSM, 8000, 8, 1; 8 = ALAW, 8000,
8, 1; 97 = SPEEX, 8000, 8, 1; 101 = telephone-event/8000</attribute>
</mbean>
Example 3.1. The RTPManager MBean
3.2. Announcement Server Access Points
An Announcement Server endpoint provides access to an announcement service. Upon requests from the call agent, an Announcement Server will “play” a specified announcement. A given announcement endpoint is not expected to support more than one connection at a time. Connections to an Announcement Server are typically one-way, i.e. “half-duplex”: the Announcement Server is not expected to listen to audio signals from the connection. Announcement endpoints do not transcode announced media; in order to achieve this, the application must use Packet Relay endpoints on the media path. Also note that the announcement server endpoint can generate a tone such as, for example, DTMF.
<mbean code="org.mobicents.media.server.impl.jmx.enp.ann.AnnEndpointManagement" name="media.mobicents:endpoint=announcement"> <attribute name="JndiName">media/trunk/Announcement</attribute> <attribute name="RtpFactoryName">java:media/mobicents/protocol/RTP</attribute> </mbean>
Example 3.2. The AnnEndpointManagement MBean
Configuration of an Announcement Server Access Point
The configurable attributes of the Announcement Server are as follows:- JndiName
- The Java Naming and Directory Interface (JNDI) name under which the endpoint is to be bound.
- RtpFactoryName
- The JNDI name of RTPManager.
Channels
Controls the number of announcement endpoints available in the server instance, in an endpoints pool. Endpoints are not created dynamically. At any given time, the number of endpoints in use cannot exceed theChannels value. It is not subject to change during runtime.
Supported Packages
The supported packages are as follows:org.mobicents.media.server.spi.events.Announcement
3.3. Interactive Voice Response
An Interactive Voice Response (IVR) endpoint provides access to an IVR service. Upon requests from the Call Agent, the IVR server “plays” announcements and tones, and “listens” to voice messages from the user. A given IVR endpoint is not expected to support more than one connection at a time. For example, if several connections were established to the same endpoint, then the same tones and announcements would be played simultaneously over all connections. IVR endpoints do not posses the capability of transcoding played or recorded media streams. IVRs record or play in the format that the data was delivered.
<mbean
code="org.mobicents.media.server.impl.jmx.enp.ivr.IVRTrunkManagement"
name="media.mobicents:endpoint=ivr">
<depends>media.mobicents:service=RTPManager,QID=1</depends>
<attribute
name="JndiName">media/trunk/IVR</attribute>
<attribute
name="RtpFactoryName">java:media/mobicents/protocol/RTP</attribute>
<attribute
name="MediaType">audio.x_wav</attribute>
<!-- DtmfMode can be either RFC2833 or INBAND or AUTO -->
<attribute
name="DtmfMode">AUTO</attribute>
<attribute
name="RecordDir">${jboss.server.data.dir}</attribute>
<attribute
name="Channels">24</attribute>
</mbean>
Example 3.3. The IVREndpointManagement MBean
Configuration of the Interactive Voice Response Endpoint
The configurable attributes of the Interactive Voice Response endpoint are as follows:- JndiName
- The Java Naming and Directory Interface (JNDI) name under which the endpoint is to be bound.
- RtpFactoryName
- The JNDI name of RTPManager.
- RecordDir
- The directory where the recorded files should be created and stored.
- Channels
- Controls the number of announcement endpoints available in the server instance , in an endpoints pool. Endpoints are not created dynamically. At any given time the number of endpoints in use can not exceed the
channelsvalue. It is not subject to change during runtime. - MediaType
- It currently defaults to WAV.
- DtmfMode
- Controls DTMF detection mode. Possible values are:
RFC2833,INBANDorAUTO.
Supported Media Types and Formats
The supported media types and formats are listed as follows:- WAVE (.wav)
- 16-bit mono/stereo linear
Record Directory Configuration
You can specify the common directory where all the recorded files should be stored, or simply omit this attribute, in which case the default directory is null, and the application needs to pass an absolute directory path to record to.Supported Packages
The supported packages are as follows:org.mobicents.media.server.spi.events.Announcementorg.mobicents.media.server.spi.events.Basicorg.mobicents.media.server.spi.events.AU
3.4. Packet Relay Endpoint
A packet relay endpoint is a specific form of conference bridge that typically only supports two connections. Packet relays can be found in firewalls between a protected and an open network, or in transcoding servers used to provide interoperation between incompatible gateways (for example, gateways which do not support compatible compression algorithms, or gateways which operate over different transmission networks such as IP or ATM).
<mbean code="org.mobicents.media.server.impl.jmx.enp.prl.PRTrunkManagement" name="media.mobicents:endpoint=packet-relay"> <depends>media.mobicents:service=RTPManager,QID=1</depends> <attribute name="JndiName">media/trunk/PacketRelay</attribute> <attribute name="RtpFactoryName">java:media/mobicents/protocol/RTP</attribute> <attribute name="Channels">10</attribute> </mbean>
Example 3.4. The PREndpointManagement MBean
Configuration of the Packet Relay Endpoint
The configurable attributes of the Packet Relay endpoint are as follows:- JndiName
- The JNDI name under which endpoint is to be bound.
- RtpFactoryName
- The JNDI name of
RTPManager. - Channels
- Controls the number of announcement endpoints available in the server instance , in an endpoints pool. Endpoints are not created dynamically. At any given time, the number of endpoints in use cannot exceed the
channelsvalue. It is not subject to change during runtime.
Supported Packages
The supported packages are as follows:org.mobicents.media.server.spi.events.Basic
3.5. Conference Bridge Endpoint
The Mobicents Media Server should be able to establish several connections between the endpoint and packet networks, or between the endpoint and other endpoints in the same gateway. The signals originating from these connections shall be mixed according to the connection “mode”. The precise number of connections an endpoint supports is a characteristic of the gateway, and may in fact vary according with the allocation of resources within the gateway. The conf endpoint can play an announcement directly on connections and hence only for the participant listening to an announcement, and can even detect DTMF for connection.
<mbean code="org.mobicents.media.server.impl.jmx.enp.cnf.ConfTrunkManagement" name="media.mobicents:endpoint=conf"> <depends>media.mobicents:service=RTPManager,QID=1</depends> <attribute name="JndiName">media/trunk/Conference</attribute> <attribute name="RtpFactoryName"> java:media/mobicents/protocol/RTP </attribute> <attribute name="Channels">10</attribute> </mbean>
Example 3.5. The ConfEndpointManagement MBean
Configuration of the Conference Bridge Endpoint
The configurable attributes of the Conference Bridge endpoint are as follows:- JndiName
- The JNDI name under which endpoint is to be bound.
- RtpFactoryName
- The JNDI name of
RTPManager. - Channels
- Controls the number of announcement endpoints available in the server instance, in an endpoints pool. Endpoints are not created dynamically. At any given time, the number of endpoints in use cannot exceed the
Channelsvalue. It is not subject to change during runtime.
Supported Packages
The supported packages are as follows:org.mobicents.media.server.spi.events.Basic
3.6. MMS STUN Support
When using Mobicents Media Server behind a routing device performing Network Address Translation, you may need to employ the Simple Traversal of User Datagram Protocol through Network Address Translators (abbreviated: STUN) protocol in order for the server to operate correctly. In general, it is recommended to avoid deploying the MMS behind a NAT, since doing so can incur significant performance penalties and failures. Nevertheless, the current MMS implementation does work with a static NAT, a.k.a. a one-to-one (1-1) NAT, in which no port-mapping occurs. Full Cone NAT should also work with Address-Restricted NAT.
For more informantion STUN NAT classification, refer to chapter 5 of RFC3489 - STUN - Simple Traversal of User Datagram Protocol (UDP).
MMS STUN Configuration
Each RTPManager in the Media Server can have its own STUN preferences. The STUN options are specified in thejboss-service.xml configuration file. Here is an example of an RTPManager MBean with static NAT configuration:
<mbean
code="org.mobicents.media.server.impl.jmx.rtp.RTPManager"
name="media.mobicents:service=RTPManager,QID=1">
<attribute
name="JndiName">java:media/mobicents/protocol/RTP</attribute>
<attribute
name="BindAddress">${jboss.bind.address}</attribute>
<attribute
name="Jitter">60</attribute>
<attribute
name="PacketizationPeriod">20</attribute>
<attribute
name="PortRange">1024-65535</attribute>
<attribute
name="AudioFormats">
8 = ALAW, 8000, 8, 1;
0 = ULAW, 8000, 8, 1;
101 = telephone-event
</attribute>
<attribute
name="UseStun">true</attribute>
<attribute
name="StunServerAddress">stun.ekiga.net</attribute>
<attribute
name="StunServerPort">3478</attribute>
<attribute
name="UsePortMapping">false</attribute>
</mbean>
Example 3.6. Static NAT configuration of an Announcement Endpoint in jboss-service.xml
There are four attributes related to STUN configuration:
- UseStun
- A boolean attribute which enables or disables STUN for the current endpoint.
- StunServerAddress
- A string attribute; the address of a STUN server. In the
jboss-service.xmlconfiguration file example, this attribute is set to stun.ekiga.net. - StunServerPort
- A string attribute representing the port number of the STUN server.
jboss-service.xmlconfiguration file example, 3478 is the port of the Ekiga server. - UsePortMapping
- A boolean attribute that specifies whether the NAT is mapping the port numbers. A NAT is mapping ports if the internal and external ports are not guaranteed to be the same for every connection through the NAT. In other words, if the client established a connection with the NAT at the hypothetical address 111.111.111.111, on port 1024, then the NAT will establish the second leg of the connection to some different (private) address, but on the same port, such as 192.168.1.1:1024. If these ports are the same (1024), then your NAT is not mapping the ports, and you can set this attribute to false, which improves the performance of the NAT traversal by doing the STUN lookup only once at boot-time, instead of doing it every time a new connection is established. NATs that don't map ports are also known as static NATs.
Chapter 4. Controlling and Programming the Mobicents Media Server
4.1. MMS Control Protocols
The Mobicents Media Server adopts a call control architecture where the call control “intelligence” is located outside of the Media Server itself, and is handled by external call control elements collectively known as Call State Control Function (CSCF).The media server assumes that these call control elements will synchronize with each other to send coherent commands and responses to the media servers under their control. Server Control Protocols is, in essence, an asynchronous master/slave protocol, where the Server Control Modules are expected to execute commands sent by CSCF. Each Server Control Module is implemented as a JSLEE application, and consists of a set of Service Building Blocks (SBB)s, which are in charge of communicating with media server endpoints via SPI. Such an architecture avoids difficulties with programming concurrency, low-level transaction and state-management details, connection-pooling and other complex APIs.
The MGCP Module
The MGCP module is included in default binary distribution. The Call Agent uses MGCP to tell the Media Server:- which events should be reported to the Call Agent;
- how endpoints should be connected; and,
- which signals should be played on which endpoints.
Configuring the MGCP Module
The default port for MGCP is 2728.4.2. MMS Control API
The main objective of the Media Server Control API is to provide multimedia application developers with a Media Server abstraction interface.
The JavaDoc for the MMS Control API
The JavaDoc documentation for the Mobicents Media Server Control API is available here: http://hudson.jboss.org/hudson/job/MobicentsDocumentation/lastSuccessfulBuild/artifact/msc-api/apidocs/index.html.
4.2.1. Basic Components of the MMS API
This section describes the basic objects of the API as well as some common design patterns.
The API components consist of a related set of interfaces, classes, operations, events, capabilities, and exceptions. The API provides seven key objects common to media servers, and more advanced packages. We provide a very brief description of the API in this overview document; the seven key objects are:
MsProvider- Represents the “window” through which an application views the call processing.
MsSession- Represents a call; this object is a dynamic collection of physical and logical entities that bring two or more endpoints together.
MsEndpoint- Represents a logical endpoint (e.g., an announcement access server, or an interactive voice response server).
MsConnection- Represents the dynamic relationship between an
MsSessionobject and a user agent. MsLink- Represent the dynamic relationship between two endpoints located on the same Media Server.
- MsRequestedEvent
- The application requests the detection of certain events like DTMF on an endpoint using this API.
- MsRequestedSignal
- The application requests the application of signals on endpoints, such as the Play-on-Announcement endpoint, using this API.
The purpose of an
MsConnection object is to describe the relationship between an MsSession object and a user agent. An MsConnection object exists if the user agent is part of the media session. MsConnection objects are immutable in terms of their MsSession and user agent references. In other words, the MsSession and user agent object references do not change throughout the lifetime of the MsConnection object instance. The same MsConnection object may not be used in another MsSession.
Interface Diagram of the MMS API
MsProvider can be used to create the MsSession object and to create the instance of MsEventFactory.
MsSession is a transient association of zero or more connections for the purposes of engaging in a real-time communication exchange. The session and its associated connection objects describe the control and media flows taking place in a communication network. Applications create instances of an MsSession object with the MsProvider.createSession() method, which returns an MsSession object that has zero connections and is in the IDLE state. The MsProvider object instance does not change throughout the lifetime of the MsSession object. The MsProvider object associated with an MsSession object is obtained via the getProvider() method.
Applications create instances of
MsConnection objects with the MsSession.createNetworkConnection(String endpointName) method. At this stage MsConnection is in the IDLE state. The Application calls MsConnection.modify(String localDesc, String remoteDesc) passing the local SDP and remote SDP. MsConnection at this time will find out the corresponding EndPoint, using JNDI, and using the endPointName passed to it. It will then call createConnection(int mode) to create an instance of Connection. This Connection creates an instance of RtpSocketAdaptorImpl, which opens up the socket for RTP data transfer. However, the transfer of data does not yet begin, and the state of MsConnection is HALF_OPEN. At this stage, Connection can only accept RTP packets as it has no knowledge of a peer to which to send RTP packets. If remoteDesc is not null, at this stage it will be applied to Connection, and now the state of MsConnection is OPEN as it knows peer SDP, and can receive as well as send RTP packets. Once MsConnection.release() is called, all of the resources of MsConnection are released and it transforms to the CLOSED state. MsConnection is unusable in the CLOSED state and gets garbage-collected.
Applications create instances of
MsLink objects with the MsSession.createLink(MsLinkMode mode) method. At this stage, MsLink is in the IDLE state. The application calls the MsLink.join(String endpointName1, String endpointName2), passing the endpoint names of the two local endpoints to be joined. At this point, the MsLink object will find out the corresponding EndPoints, using JNDI, and by using the endPointName passed to it. It will then call createConnection(int mode) to create an instance of the Connection object. The connections are local connections and hence no network resources are acquired (Sockets). As soon as Connections are created for both EndPoints, setOtherParty(Connection other) is called on each Connection passing the other Connection, which starts the data transfer between the two Connections. At this stage, MsLink changes to the CONNECTED state. As soon as the application calls MsLink.release(), release() is called on the connection of respective endpoints. As soon as both of the connections are released, MsLink changes to DISCONNECTED and becomes unusable. Soon after this, MsLink gets garbage-collected.
The application may ask to be notified about certain events occurring in an endpoint (e.g., DTMF), or the application may also request certain signals to be applied to an endpoint (e.g., Play an Announcement). To achieve this, the application needs to get an instance of
MsEventFactory by calling MsProvider.getEventFactory() and create an instance of MsRequestedEvent to request for the notification of events or to create an instance of MsRequestedEvent to apply signals at endpoints. The application needs to pass the corresponding MsEventIdentifier as a parameter to MsEventFactory.createRequestedEvent(MsEventIdentifier eventID) or MsEventFactory.createRequestedSignal(MsEventIdentifier eventID). The examples below will clarify this
4.2.2. Basic API Patterns: Listeners
The basic programming pattern of the API is that applications (which reside “above” the API) make synchronous calls to API methods. The platform or network element implementing the API can inform the application of underlying events (for example, the arrival of incoming calls) by means of Java events. The application provides
Listener objects corresponding to the events it is interested in obtaining.
Listeners
MsSessionListener- Applications which are interested in receiving events for changes in state of the
MsSessionobject should implementMsSessionListener. MsConnectionListener- Applications which are interested in receiving events for changes of state in
MsConnectionshould implementMsConnectionListener. MsLinkListener- Applications which are interested in receiving events for changes in state of MsLink should implement MsLinkListener.
MsResourceListener- Applications interested in receiving events for changes in state of
MsSignalDetectororMsSignalGeneratorshould implementMsResourceListener.
4.2.3. Events
Each of the listeners defined above listen to different types of events fired by the server.
Events related to MsSession
MsSessionListener is listening for MsSessionEvent, which carries the MsSessionEventID representing an MsSession state change. The following table shows the different types of MsSessionEventID, when these events are fired, and the corresponding methods of MsSessionListener that will be called.
MsSessionEventID
| Description |
MsSessionListener Method Called
|
|---|---|---|
SESSION_CREATED
|
Fired when MsProvider.createSession() is called and a new MsSession is created
|
public void sessionCreated(
|
SESSION_ACTIVE
|
When the MsConnection or MsLink is created on MsSession for the first time, it transitions to ACTIVE state and SESSION_ACTIVE is fired. Afterwards, this the state remains ACTIVE even if the application creates more MsConnections or MsLinks.
|
public void sessionActive(
|
SESSION_INVALID
|
When all the MsConnection or MsLink objects are disassociated from MsSession, it transitions to INVALID state and SESSION_INVALID is fired
|
public void sessionInvalid(
|
Events Related to MsConnection
MsConnectionListener listens for an MsConnectionEvent, which carries the MsConnectionEventID that represents an MsConnection state change. The following table shows the different types of MsConnectionEventID, when these events would be fired, and the corresponding methods of MsConnectionListener that will be called.
MsConnectionEventID
| Description |
MsConnectionListener Method Called
|
|---|---|---|
CONNECTION_CREATED
|
Fired as soon as the creation of MsConnection is successful. MsConnection is not holding any resources yet.
|
public void connectionCreated(
|
CONNECTION_HALF_OPEN
|
Fired as soon as the modification of MsConnection is successful. At this stage the RTP socket is open in the Media Server to receive a stream, but has no idea about remote SDP. The application may call MsConnection.modify(localDesc, null), passing null for remote SDP if the remote SDP is not known yet, and then later call modify again with the actual SDP once its known
| |
CONNECTION_MODIFIED
|
As soon as MsConnection is successfully modified, by calling MsConnection.modify(String localDesc, String remoteDesc), CONNECTION_MODIFIED is fired. When modify() is called, MsConnection checks to see whether there is an endpoint associated it and, if so, then this means it is a modification request.
|
public void connectionHalfOpen(MsConnectionEvent event);
|
CONNECTION_OPEN
|
Fired as soon as the modification of MsConnection is successful and the SDP passed by the Call Agent is successfully applied to an RTP Connection. At this stage, there is a flow of RTP packets from the User Agent to the Media Server and vice versa. Its possible that the application may call MsConnection.modify(localDesc, remoteDesc), passing the remoteDesc(remote SDP)
|
public void connectionOpen(MsConnectionEvent event);
|
CONNECTION_DISCONNECTED
|
As soon as MsConnection is successfully released, MsConnection.release()CONNECTION_DISCONNECTED is fired.
|
public void connectionDisconnected(MsConnectionEvent event);
|
CONNECTION_FAILED
|
Fired as soon as the creation of MsConnection fails for reasons specified in MsConnectionEventCause. Immediately after CONNECTION_FAILED, CONNECTION_DISCONNECTED will be fired, giving the lister a chance to perform clean up.
|
public void connectionFailed(MsConnectionEvent event);
|
Events Related to MsLink
MsLinkListener listens for an MsLinkEvent which carries the MsLinkEventID that represents an MsLink state change. The following table shows the different types of MsLinkEventID, when these events are fired, and the corresponding methods of MsLinkListener that are called.
MsLinkEventID
| Description |
MsLinkListener method called
|
|---|---|---|
LINK_CREATED
|
As soon as a new MsLink is created by calling MsSession.createLink(MsLinkMode mode), LINK_CREATED is fired.
|
public void linkCreated(MsLinkEvent evt)
|
LINK_CONNECTED
|
Fired as soon as the join(String a, String b) operation of MsLink is successful.
|
public void linkConnected(MsLinkEvent evt);
|
LINK_DISCONNECTED
|
Fired as soon as the release() operation of MsLink is successful.
|
public void linkDisconnected(MsLinkEvent evt);
|
LINK_FAILED
|
Fired as soon as the join(String a, String b) operation of MsLink fails.
|
public void linkFailed(MsLinkEvent evt)
|
4.2.4. MSC API Objects: Finite State Machines
MsSessionState Finite State Machine
The behavior of MsSession is specified in terms of Finite State Machines (FSMs) represented by MsSessionState, shown below:
IDLE- This state indicates that the session has zero connections or links.
ACTIVE- This state indicates that the session has one or more connections or links.
INVALID- This state indicates the session has lost all of its connections or links.
MsConnection Finite State Machine
MsConnection state is represented by the MsConnectionState enum:
IDLE- This state indicates that the
MsConnectionhas only been created and has no resources attached to it. HALF_OPEN- This state indicates that the
MsConnectionhas created the RTP socket, but doesn't yet have any information about Remote SDP to send the RTP Packets.MsConnectionis still usable inHALF_OPENstate if it is only receiving the RTP Packets but doesn't have to send any. OPEN- This state indicates that the
MsConnectionnow has information about remote SDP and can send RTP Packates to the remote IP (for example, to a remote user agent). FAILED- This state indicates that the creation or modification of
MsConnectionfailed, and that theMsConnectionobject isn't reusable anymore. CLOSED- This state indicates that
MsConnectionhas released all its resources and closed the RTP sockets. It is not usable any more.
MsLink Finite State Machine
MsLink state is represented by the MsLinkState enum:
IDLE- This state indicates that the
MsLinkhas been created and has no endpoints associated with it. CONNECTED- This state indicates that the connections from both endpoints have been created and that data transfer has started.
FAILED- This state indicates that the creation of
MsLinkfailed and is not usable anymore. DISCONNECTED- This state indicates that
MsLinkhas closed the connections of both endpoints and is not usable anymore.
4.2.5. API Methods and Usage
So far we have specified the key objects as well as their Finite State Machines (FSMs). To understand operationally how these objects are used and the methods they provide, we can look at the UML sequence diagram examples. The following call flow depicts a simple announcement.
Click to see the Announcement call flow diagram.
/**
* This is just a psuedocode to show how to use the MSC Api. This example uses
* the Announcement Endpoint to play an announcement
*
* user agent <----> RTP Connection <--- Announcement Endpoint
*
* @author amit bhayani
*
*/
public class AnnouncementExample implements MsSessionListener, MsConnectionListener {
private MsProvider msProvider;
private MsSession msSession;
public void startMedia(String remoteDesc) {
// Creating the provider
MsProvider provider = new MsProviderImpl();
// Registering the Listeners
provider.addSessionListener(this);
provider.addConnectionListener(this);
// Creating the Session
msSession = provider.createSession();
// Creating the connection passing the Endpoint Name. Here we are
// creating Announcement Endpoint which will be connected to User Agent
// (remoteDesc is SDP of remote end)
MsConnection msCOnnection = msSession.createNetworkConnection("media/trunk/Announcement/$");
// Get the Remote SDP here and pass it to connection. If creation of
// connection is successful connectionCreated method will be called
msCOnnection.modify("$", remoteDesc);
}
public void sessionActive(MsSessionEvent evt) {
// TODO Auto-generated method stub
}
public void sessionCreated(MsSessionEvent evt) {
// TODO Auto-generated method stub
}
public void sessionInvalid(MsSessionEvent evt) {
// TODO Auto-generated method stub
}
public void connectionCreated(MsConnectionEvent event) {
MsConnection connection = event.getConnection();
MsEndpoint endpoint = connection.getEndpoint();
// This is the actualname, could be something like
// 'media/trunk/Announcement/enp-1'
String endpointName = endpoint.getLocalName();
// URL to play audio file.
String url= "http://something/mobicents.wav";
MsEventFactory eventFactory = msProvider.getEventFactory();
MsPlayRequestedSignal play = null;
play = (MsPlayRequestedSignal) eventFactory.createRequestedSignal(MsAnnouncement.PLAY);
play.setURL(url);
// Let us request for Announcement Complete event or Failure in case
// if it happens
MsRequestedEvent onCompleted = null;
MsRequestedEvent onFailed = null;
onCompleted = eventFactory.createRequestedEvent(MsAnnouncement.COMPLETED);
onCompleted.setEventAction(MsEventAction.NOTIFY);
onFailed = eventFactory.createRequestedEvent(MsAnnouncement.FAILED);
onFailed.setEventAction(MsEventAction.NOTIFY);
MsRequestedSignal[] requestedSignals = new MsRequestedSignal[] { play };
MsRequestedEvent[] requestedEvents = new MsRequestedEvent[] { onCompleted, onFailed };
endpoint.execute(requestedSignals, requestedEvents, connection);
}
public void connectionDisconnected(MsConnectionEvent event) {
// TODO Auto-generated method stub
}
public void connectionFailed(MsConnectionEvent event) {
// TODO Auto-generated method stub
}
public void connectionHalfOpen(MsConnectionEvent event) {
// TODO Auto-generated method stub
}
public void connectionOpen(MsConnectionEvent event) {
// TODO Auto-generated method stub
}
}
Example 1.1. Example Code
Example 2
Example that shows how to listen for DTMF. For simplicity removed all imports and other code
public class IVRExample implements MsSessionListener, MsConnectionListener, MsNotificationListener {
...
public void startMedia(String remoteDesc) {
// Creating the provider
MsProvider provider = new MsProviderImpl();
// Registering the Listeners
provider.addSessionListener(this);
provider.addConnectionListener(this);
provider.addNotificationListener(this);
// Creating the Session
msSession = provider.createSession();
// Creating the connection passing the Endpoint Name. Here we are
// creating Announcement Endpoint which will be connected to User Agent
// (remoteDesc is SDP of remote end)
MsConnection msConnection = msSession.createNetworkConnection("media/trunk/IVR/$");
// Get the Remote SDP here and pass it to connection. If creation of
// connection is successful connectionCreated method will be called
msConnection.modify("$", remoteDesc);
}
..
..
.....
public void connectionCreated(MsConnectionEvent event) {
MsConnection connection = event.getConnection();
MsEndpoint endpoint = connection.getEndpoint();
// This is the actualname, could be something like
// 'media/trunk/Announcement/enp-1'
String endpointName = endpoint.getLocalName();
MsEventFactory factory = msProvider.getEventFactory();
MsDtmfRequestedEvent dtmf = (MsDtmfRequestedEvent) factory.createRequestedEvent(DTMF.TONE);
MsRequestedSignal[] signals = new MsRequestedSignal[] {};
MsRequestedEvent[] events = new MsRequestedEvent[] { dtmf };
endpoint.execute(signals, events, connection);
}
..
.......
public void update(MsNotifyEvent evt) {
MsEventIdentifier identifier = evt.getEventID();
if (identifier.equals(DTMF.TONE)) {
MsDtmfNotifyEvent event = (MsDtmfNotifyEvent) evt;
String seq = event.getSequence();
if (seq.equals("0")) {
} else if (seq.equals("1")) {
} else if (seq.equals("2")) {
} else if (seq.equals("3")) {
} else if (seq.equals("4")) {
} else if (seq.equals("5")) {
} else if (seq.equals("6")) {
} else if (seq.equals("7")) {
} else if (seq.equals("8")) {
} else if (seq.equals("9")) {
}
}
}
}
Example 3
Example that shows how DTMF signal can be applied to Endpoint
MsEventFactory eventFactory = msProvider.getEventFactory();
MsRequestedSignal dtmf = eventFactory.createRequestedSignal(DTMF.TONE);
dtmf.setTone("1");
MsRequestedSignal[] signals = new MsRequestedSignal[] { dtmf };
MsRequestedEvent[] events = new MsRequestedEvent[];
msEndpoint.execute(signals, events, connection);
Example 4
Example that shows how to begin recording and listen for FAILED event
String RECORDER = "file://home/user/recordedfile.wav";
MsEventFactory eventFactory = msProvider.getEventFactory();
MsRecordRequestedSignal record = (MsRecordRequestedSignal) eventFactory.createRequestedSignal(MsAudio.RECORD);
record.setFile(RECORDER);
MsRequestedEvent onFailed = eventFactory.createRequestedEvent(MsAudio.FAILED);
onFailed.setEventAction(MsEventAction.NOTIFY);
MsRequestedSignal[] requestedSignals = new MsRequestedSignal[] { record };
MsRequestedEvent[] requestedEvents = new MsRequestedEvent[] { onFailed };
endpoint.execute(requestedSignals, requestedEvents, connection);
Note that passing empty MsRequestedSignal[] and MsRequestedEvent[] will nullify all previous MsRequestedSignal and MsRequestedEvent
Example 4.1. Example Code
Chapter 5. MMS: Event Packages
The Basic Package
Package name:org.mobicents.media.server.spi.events.Basic
| Event ID | Description | Type | Duration |
|---|---|---|---|
org.mobicents.media.server.spi.events.Basic.DTMF
| DTMF Event | BR |
The Announcement Package
Package name:org.mobicents.media.server.spi.event.Announcement
| Event ID | Description | Type | Duration |
|---|---|---|---|
org.mobicents.media.server.spi.event.Announcement.PLAY
| play an announcement | TO | variable |
org.mobicents.media.server.spi.event.Announcement.COMPLETED
| |||
org.mobicents.media.server.spi.event.Announcement.FAILED
|
Announcement actions are qualified by URLs and by sets of initial parameters. The “operation completed” (
COMPLETED) event will be detected once an announcement has finished playing. If the announcement cannot be played in its entirety, an “operation failure” (FAILED) event can be returned. The failure can also be explained with a commentary.
The Advanced Audio Package
Package name:org.mobicents.media.server.spi.events.AU
| Event ID | Description | Type | Duration |
|---|---|---|---|
org.mobicents.media.server.spi.event.AU.PLAY_RECORD
| play a prompt (optional) and then record some speech | TO | variable |
org.mobicents.media.server.spi.event.AU.PROMPT_AND_COLLECT
| |||
org.mobicents.media.server.spi.event.Announcement.FAILED
|
The function of
PLAY_RECORD is to play a prompt and record the user's speech. If the user does not speak, the user may be re-prompted and given another chance to record. By default, PLAY_RECORD does not play an initial prompt, makes only one attempt to record, and therefore functions as a simple record operation
Chapter 6. MMS Demonstration Example
The motive of this example is to demonstrate the capabilities of new Media Server (MS) and Media Server Resource Adapters (MSC-RA).
The example demonstrates usage of
- the Announcement Endpoint
- the Packet Relay Endpoint
- The Loop Endpoint
- The Conference Endpoint
- The IVR Endpoint
For more information on each of these types of endpoints, refer to Section 1.2, “Mobicents Media Server Architecture”.
Where is the Code?
Check out the 'mms-demo' example from http://code.google.com/p/mobicents/source/browse/#svn/branches/servers/media/1.x.y/examples/mms-demo.Install and Run
Start the Mobicents Server (this will also start Media Server). Make sure you haveserver/default/deploy/mobicents.sar and server/default/deploy/mediaserver.sar in your Mobicents Server
From Binary
Go to/examples/mms-demo and call 'ant deploy-all'. This will deploy the SIP RA, MSC RA, the mms-demo example and also mms-demo-audio.war. The war file contains the audio *.wav files that are used by mms-demo example.
From Source Code
If you are deploying from source code, you may deploy each of the resource adapters individually- make sure
JBOSS_HOMEis set and the server is running. - Call mvn install from
servers/jain-slee/resources/sipto deploy SIP RA - Call mvn install from
servers/media/controllers/mscto deploy media RA - Call mvn install from
servers/media/examples/mms-demoto deploy example
Once the example is deployed, make a call from your SIP Phone to TBD.
1010: Loop Endpoint Usage Demonstration
As soon as the call is established CallSbb creates a Connection using PREndpointImpl. PREndpointImpl has two Connections, one connected to calling UA by calling msConnection.modify("$", sdp). Once the connection is established CallSbb creates child LoopDemoSbb and calls startDemo() on it passing the PREndpoint name as argument. LoopDemoSbb creates child AnnouncementSbb which uses the AnnEndpointImpl to make an announcement. The other Connection of PREndpointImpl is connected to Connection from AnnEndpointImpl using the MsLink.MsLink link = session.createLink(MsLink.MODE_FULL_DUPLEX); .... ... link.join(userEndpoint, ANNOUNCEMENT_ENDPOINT);
Once the link is created (look at onLinkConnected() )
AnnouncementSbb creates the instance of MsPlayRequestedSignal and sets the path of audio url. AnnouncementSbb also creates an instance of MsRequestedEvent for MsAnnouncement.COMPLETED and MsAnnouncement.FAILED such that the Media resource adapter fires respective events and the SBB has a handler for the org.mobicents.media.events.announcement.COMPLETED event to handle Announcement Complete.
MsEventFactory eventFactory = msProvider.getEventFactory();
MsPlayRequestedSignal play = null;
play = (MsPlayRequestedSignal) eventFactory.createRequestedSignal(MsAnnouncement.PLAY);
play.setURL(url);
MsRequestedEvent onCompleted = null;
MsRequestedEvent onFailed = null;
onCompleted = eventFactory.createRequestedEvent(MsAnnouncement.COMPLETED);
onCompleted.setEventAction(MsEventAction.NOTIFY);
onFailed = eventFactory.createRequestedEvent(MsAnnouncement.FAILED);
onFailed.setEventAction(MsEventAction.NOTIFY);
MsRequestedSignal[] requestedSignals = new MsRequestedSignal[]{play};
MsRequestedEvent[] requestedEvents = new MsRequestedEvent[]{onCompleted, onFailed};
link.getEndpoints()[1].execute(requestedSignals, requestedEvents, link);
As soon as the announcement is over
LoopDemoSbb creates child LoopbackSbb and calls startConversation() on it, passing the PREndpoint name as argument. LoopbackSbb uses MsLink to associate the other connection of PREndpointImpl to LoopEndpointImpl. LoopEndpointImpl simply forwards the voice packet received from caller back to caller.
MsLink link = session.createLink(MsLink.MODE_FULL_DUPLEX); ....... ... link.join(endpointName, LOOP_ENDPOINT);
The SBB Child Relation Diagram
1011: DTMF Usage Demonstration
As soon as the call is established CallSbb creates a Connection using PREndpointImpl. PREndpointImpl has two Connections, one connected to calling UA by calling msConnection.modify("$", sdp). Once the connection is established CallSbb creates child DtmfDemoSbb and calls startDemo() on it passing the PREndpoint name as argument. DtmfDemoSbb creates child AnnouncementSbb which uses the AnnEndpointImpl to make an announcement. The other Connection of PREndpointImpl is connected to Connection from AnnEndpointImpl using the MsLink..... MsLink link = session.createLink(MsLink.MODE_FULL_DUPLEX); .... ... link.join(userEndpoint, ANNOUNCEMENT_ENDPOINT);
Once the link is created the flow is the same as that of 1010 to play the announcement.
As soon as announcement is over DtmfDemoSbb creates instance of MsDtmfRequestedEvent and applies it on IVREndpoint. Look at onAnnouncementComplete() method of DtmfDemoSbb
MsLink link = (MsLink) evt.getSource();
MsEndpoint ivr = link.getEndpoints()[1];
MsEventFactory factory = msProvider.getEventFactory();
MsDtmfRequestedEvent dtmf = (MsDtmfRequestedEvent) factory.createRequestedEvent(DTMF.TONE);
MsRequestedSignal[] signals = new MsRequestedSignal[]{};
MsRequestedEvent[] events = new MsRequestedEvent[]{dtmf};
ivr.execute(signals, events, link);
On every DTMF received DtmfDemoSbb plays corresponding WAV file using the AnnouncementSbb as explained above.
The SBB Child Relation Diagram
1012: ConfEndpointImpl Usage Demonstration
As soon as the call is established CallSbb creates a Connection using PREndpointImpl. PREndpointImpl has two Connections, one connected to calling UA by calling msConnection.modify("$", sdp). Once the connection is established CallSbb creates child ConfDemoSbb and calls startDemo() on it passing the PREndpoint name as argument. ConfDemoSbb creates child AnnouncementSbb which uses the AnnEndpointImpl to make an announcement. The other Connection of PREndpointImpl is connected to Connection from AnnEndpointImpl using the MsLink..... MsLink link = session.createLink(MsLink.MODE_FULL_DUPLEX); .... ... link.join(userEndpoint, ANNOUNCEMENT_ENDPOINT);
Once the link is created the flow is the same as that of 1010 to play the announcement.
As soon as announcement is over ConfDemoSbb creates child ForestSbb and calls enter() on it passing the PREndpoint name as argument. ForestSbb uses MsLink to associate the other Connection of PREndpointImpl to ConfEndpointImpl:
MsLink link = session.createLink(MsLink.MODE_FULL_DUPLEX); link.join(endpointName, CNF_ENDPOINT);
Once the link is established (Look at onConfBridgeCreated() ) ForestSbb creates many child AnnouncementSbb each responsible for unique announcement (in this case playing crickets.wav and mocking.wav). So now UA is actually listening to many announcements at same go.
The SBB Child Relation Diagram
Recording Usage Demonstration
As soon as the call is established,CallSbb creates a Connection using PREndpointImpl. PREndpointImpl has two Connections, one connection to the calling User Agent by calling msConnection.modify("$", sdp). Once the connection is established, CallSbb creates child RecorderDemoSbb and calls startDemo() on it, passing the PREndpoint name as an argument. RecorderDemoSbb creates child AnnouncementSbb which uses the AnnEndpointImpl to make an announcement. The other Connection of PREndpointImpl is connected to Connection from AnnEndpointImpl using the MsLink.
Chapter 7. MMS: Best Practices
7.1. Mobicents Media Server Best Practices
Note: these best practices apply to Mobicents Media Server version 1.0.0.CR6 and later
7.1.1. DTMF Detection Mode: RFC2833 versus Inband versus Auto
The Mobicents Media Server will block the resource depending on the DTMF detection mode configured in jboss-service.xml at start-up time. Inband is highly resource-intensive and must perform many more calculations in order to detect DTMF when compared to RFC2833. So if your application already knows that User Agents (UAs) support RFC2833, it is always better to configure DTMF mode as RFC2833 rather than as Inband or Auto. Also, please note that Auto is even more resource-intensive because it does not know beforehand whether DTMF would be Inband or RFC2833, and hence both detection methods must be started. The default detection mode is RFC2833.
All of the Conference, Packet Relay and IVR endpoints have DTMF detection enabled; the mode can be configured using jboss-service.xml. We advise retaining the same mode for all three, but this is not a necessity.
7.1.2. Transcoding Is CPU-Intensive
Digital Signal Processing (DSP) is very costly and should be avoided as much as possible. By default, Announcement endpoints and IVR endpoints do not have DSP enabled. What this means is that your application needs to know beforehand which codecs are supported by your UA; you can then ask Announcement or IVR to play an audio file which has been pre-encoded in one of these formats. The onus of deciding which pre-encoded file to play lies with the application. For example, if I am writing a simple announcement application that would only play announcements to the end user, and I know that my end users have one of either the PCMU or GSM codecs, then I would make sure to have pre-encoded audio files such as helloworld-pcmu.wav and helloworld-gsm.gsm. Then, when the UA attempts to connect to the Media Server, my application knows which codecs the UA supports and can ask the Media Server to play the respective file.
This strategy will work fine because, most of the time in the telecommunications world, applications have a known set of supported codecs, .However if this is not true, or if you are writing a simple demo application and need or want all codecs to be supported, you can put a Packet Relay endpoint in front of Announcement or IVR endpoint. This way, the Packet Relay will do all necessary digital signal processing, and your application need not bother about which audio file to play. The audio file in this case will be encoded in Linear format, and all UAs, irrespective of whether they support PCMU, PCMA, Speex, G729 or GSM codecs, would be able to hear the announcement.
7.1.3. Conference Endpoints block the Number of Connections at Start Time
The Conference endpoint starts all of the connections at boot time. This means that Conference blocks all the necessary resources at start time even if UAs are not yet connected. In our experience, this is required because resource allocation at runtime causes jitter for the other participants. Due to this, there is cap on the maximum number of connections a conference can handle which takes effect at start time. By default, this number is set to five in jboss-service.xml:
<attribute name="MaxConnections">5</attribute>
If your requirements are such that your application will have conferences ranging from five to ten simultaneous users, it is best to define two or more ConfTrunkManagementMBeans, and allow your application to use the correct Conference endpoint rather than changing the value of MaxConnections to "10" for all. For example:
<mbean
code="org.mobicents.media.server.impl.jmx.enp.cnf.ConfTrunkManagement"
name="media.mobicents:endpoint=conf">
<depends>media.mobicents:service=RTPManager,QID=1</depends>
<attribute
name="JndiName">media/trunk/Conference5</attribute>
<attribute
name="RtpFactoryName">java:media/mobicents/protocol/RTP</attribute>
<attribute
name="Channels">1</attribute>
<attribute
name="DtmfMode">RFC2833</attribute>
<!--MaxConnections represents the maximum number of participants who can join a conference.
Use judiciously: this blocks resources at MMS startup-->
<attribute
name="MaxConnections">5</attribute>
</mbean>
<mbean
code="org.mobicents.media.server.impl.jmx.enp.cnf.ConfTrunkManagement"
name="media.mobicents:endpoint=conf">
<depends>media.mobicents:service=RTPManager,QID=1</depends>
<attribute
name="JndiName">media/trunk/Conference7</attribute>
<attribute
name="RtpFactoryName">java:media/mobicents/protocol/RTP</attribute>
<attribute
name="Channels">1</attribute>
<attribute
name="DtmfMode">RFC2833</attribute>
<!--MaxConnections represents the maximum number of participants who can join a conference.
Use judiciously: this blocks resources at MMS startup-->
<attribute
name="MaxConnections">7</attribute>
</mbean>
<mbean
code="org.mobicents.media.server.impl.jmx.enp.cnf.ConfTrunkManagement"
name="media.mobicents:endpoint=conf">
<depends>media.mobicents:service=RTPManager,QID=1</depends>
<attribute
name="JndiName">media/trunk/Conference10</attribute>
<attribute
name="RtpFactoryName">java:media/mobicents/protocol/RTP</attribute>
<attribute
name="Channels">1</attribute>
<attribute
name="DtmfMode">RFC2833</attribute>
<!--MaxConnections represents the maximum number of participants who can join a conference.
Use judiciously: this blocks resources at MMS startup-->
<attribute
name="MaxConnections">10</attribute>
</mbean>
Finally, ensure that you configure Channels carefully: this represents the number of conferences that can occur concurrently.
Revision History
| Revision History | |||
|---|---|---|---|
| Revision 2.0 | Fri Mar 06 2009 | ||
| |||
| Revision 1.0 | Tue Jan 20 2009 | ||
| |||
Index
F
- feedback
- contact information for this manual, We Need Feedback!
JBoss Communications Platform 1.2.0
SIP Presence Service User Guide
The Guide to the SIP Presence and XML Document Management Servers
Edition 1.0
Legal Notice
Copyright © 2009 Red Hat Inc. This material may only be distributed subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License (which is presently available at http://creativecommons.org/licenses/by-nc-sa/3.0/).
Red Hat, the "Shadow Man" logo and JBoss are registered trademarks of Red Hat,
Inc. in the United States and other countries.
All other trademarks referenced herein are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072USAPhone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588Research Triangle Park, NC 27709USA
Abstract
JBCP, the JBoss Communications Platform, is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. JBCP serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes) by leveraging J2EE to enable the convergence of data and video in Next-Generation
Intelligent Network (NGIN) applications.
The JBoss Communications Platform enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration
and Presence-Sensing. Out-of-the-box monitoring and management of JBCP components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise
applications with end points such as the Web, Customer Relationship
Management (CRM) systems and Service-Oriented Architectures (SOAs). The JBoss Communications Platform is the natural choice for telecom Operations Support Systems
(OSSes) and Network Management Systems (NMSes).
In addition to telecom, JBCP is suitable for a variety of problem domains demanding an
Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial
trading, online gaming, (RFID) sensor network integration, and distributed control.
- Preface
- 1. Introduction to the Mobicents SIP Presence Service
- 2. Installing the SIP Presence Service
- 3. Mobicents SIP Presence Server
- 4. Mobicents XML Document Management Server
- 5. Mobicents Resource List Server
- A. Revision History
- Index
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:
To see the contents of the filemy_next_bestselling_novelin your current working directory, enter thecat my_next_bestselling_novelcommand at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.
Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:
Press Enter to execute the command.Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session.
The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in
Mono-spaced Bold. For example:
File-related classes includefilesystemfor file systems,filefor files, anddirfor directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).To insert a special character into a gedit file, choose from the main menu bar. Next, choose from the Character Map menu bar, type the name of the character in the Search field and click . The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the button. Now switch back to your document and choose from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.
Note the shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select from the sub-menu in the menu of the main menu bar' approach.
Mono-spaced Bold ItalicProportional Bold Italic
Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, typesshat a shell prompt. If the remote machine isusername@domain.nameexample.comand your username on that machine is john, typessh john@example.com.Themount -o remountcommand remounts the named file system. For example, to remount thefile-system/homefile system, the command ismount -o remount /home.To see the version of a currently installed package, use therpm -qcommand. It will return a result as follows:package.package-version-release
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.
1.2. Pull-quote Conventions
Two, commonly multi-line, data types are set off visually from the surrounding text.
Output sent to a terminal is set in
Mono-spaced Roman and presented thus:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in
Mono-spaced Roman but are presented and highlighted as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring Important boxes won't cause data loss but may cause irritation and frustration.
Warning
A Warning should not be ignored. Ignoring warnings will most likely cause data loss.
2. We Need Feedback!
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product JBoss Communications Platform.
When submitting a bug report, be sure to mention the manual's identifier: SIP_Presence_Service_User_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
Chapter 1. Introduction to the Mobicents SIP Presence Service
The JBCP SIP Presence Service provides presence functionalities to SIP-based networks using standards developed by the Internet Engineering Task Force (IETF), the Open Mobile Alliance (OMA), the 3rd Generation Partnership Project (3GPP) and the European Telecommunications Standards Institute (ETSI).
1.1. Architecture of the Mobicents SIP Presence Service
The SIP Presence Service is comprised of three separate but interrelated servers.
The Three Servers Comprising the SIP Presence Service
- The SIP Presence Server
- The JBCP SIP Presence Server is an entity that accepts, stores and distributes Presence Information. The SIP Presence Server performs the following functions:
- It manages publications from one or multiple presence source(s) of a certain presentity. This includes refreshing presence information, replacing existing presence information with newly-published information, or removing presence information.
- It manages subscriptions from watchers to presence information and generates notifications about presence information state changes, retrieving the presence authorization rules from the XDM Server.
- It manages subscriptions from watcher information subscribers to watcher information and generates notifications about watcher information state changes.
- The XML Document Management Server
- The XML Document Management Server (XDM Server) is a functional element of next-generation IP communications networks is responsible for handling the management of user XML documents stored on the network side, such as presence authorization rules, static presence information, contact and group lists (also known as “resource lists”), policy data, and many others.
- The Resource List Server
- The Resource List Server (RLS) handles subscriptions to presence lists. It creates and manages back-end subscriptions to all resources in the presence list. The list content is retrieved from the XDM Server.
A major advantage of the SIP Presence Service is that, depending on your needs, each server can be deployed separately, or all servers can be integrated on the same host. In addition, there are JAIN SLEE internal client interfaces available for each server, which distinguishes the JBCP SIP Presence Service from other presence services.
For documentation on each server proceed to links under this page Resources section.
Resources and Further Information about the Mobicents Presence Service
For further information on the Mobicents Presence Service, here is a list of additional resources:- Issue tracker
- Forums
Chapter 2. Installing the SIP Presence Service
2.1. Mobicents SIP Presence Service: Installing, Configuring and Running
There are multiple distributions of the Mobicents SIP Presence Service.
Description of the Different SIP Presence Service Distributions
- The zipped-up source distribution
- This distribution is source only, and its installation is not covered in this guide. Be careful you don't accidentally download this distribution when wanting one of the binary distributions (this one has
.srcin its file name). - The all-included integrated SIP Presence Service binary distribution with JBoss
- These installation instructions detail the installation, running and configuring of the all-included integrated binary SIP Presence Service distribution. In addition to the XML Document and SIP Presence Servers, this distribution bundles the JBoss Application Server, the latest version of the Mobicents JAIN SLEE Server, and the SIP and HTTP Servlet resource adapters.
- The integrated SIP Presence Service binary distribution without JBoss
- Users who have already installed and set up a separate Mobicents JAIN SLEE Server installation may want to install this the integrated distribution without JBoss. If you install this distribution, keep in mind that the
JBOSS_HOMEenvironment variable must be set to the correct location. - The XML Document Management Server binary distribution with JBoss
- Users who wish to deploy the XML Document Server on a different host or who do not require the SIP Presence Server should install the standalone XDM Server binary distribution. The following installation, running and configuring instructions provide parallel instructions specific to the XDM Server.
Installing the Java Development Kit
2.1.1. Java Development Kit: Installing, Configuring and Running
The JBoss Communications Platform is written in Java; therefore, before running any JBCP 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 JBCP must be version 5 or higher[10].
Should I Install the JRE or JDK?
Although you can run JBCP servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, JBCP-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?
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.
Downloading
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 JBCP in a production environment.
Installing
The following procedures detail how to install the Java Development Kit on both Linux and Windows.Procedure 2.1. Installing the JDK on Linux
- Regardless of which file you downloaded, you can install it on Linux by simply making sure the file is executable and then running it:
~]$ chmod +x "jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin" ~]$ ./"jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin"
You Installed Using the Non-RPM Installer, but Want the SysV Service Scripts
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/.
Important
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
Configuring your system for the JDK consists in two tasks: setting theJAVA_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.
- Setting the
JAVA_HOMEEnvironment Variable on Generic Linux - After installing the JDK, you must ensure that the
JAVA_HOMEenvironment variable exists and points to the location of your JDK installation.Setting the
You can determine whetherJAVA_HOMEEnvironment Variable on LinuxJAVA_HOMEis set on your system byechoing it on the command line:~]$ echo $JAVA_HOME
IfJAVA_HOMEis 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~/.bashrcconfiguration 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 JBCP (any environment variablesexported from~/.bashrcfiles are local to that user). - Setting
java,javacandjava_sdk_1.5.0Using thealternativescommand Selecting the Correct System JVM on Linux using
On systems with thealternativesalternativescommand, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as whichjavaandjavacexecutables should be run when called.As the root user, call/usr/sbin/alternativeswith the--config javaoption 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 thejavaexecutable. In thealternativesinformation printout above, a plus (+) next to a number indicates the one currently being used. As peralternatives' 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 thejavaccommand and thejava_sdk_1.5.0environment variable, as the root user:~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
- Setting the
JAVA_HOMEEnvironment Variable on Windows - For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
Testing
Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in yourPATH, run the java -version command in the terminal from your home directory:
~]$ java -version java version "1.5.0_16" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03) Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling
There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily usingalternatives, and/or by setting JAVA_HOME.
Uninstalling the JDK on Linux
On RPM-based systems, you can uninstall the JDK using theyum remove <jdk_rpm_name> command.
Uninstalling the JDK on Windows
On Windows systems, check the JDK entry in theStart menu for an uninstall command, or use Add/Remove Programs.
2.1.2. Pre-Install Requirements and Prerequisites
You should ensure that a few requirements have been met before continuing with the install.
Hardware Requirements
- Sufficient Disk Space
- You must have sufficient disk space in order to install the integrated SIP Presence Service binary release. Once unzipped, version 1.0.0 BETA4 of the integrated SIP Presence Service binary release requires at least 90 MB of free disk space. Version 1.0.0 BETA4 CP1 of the XDM Server binary release requires at least 90 MB of disk space. Keep in mind that disk space requirements may change from release to release.
- Anything Java Itself Will Run On
- The Mobicents SIP Presence Service and its bundled servers, JBoss and JAIN SLEE, are all 100% Java. SIP Presence Service will run on the same hardware that the JBoss Application Server runs on.
Software Prerequisites
- JDK 5 or Higher
- A working installation of the Java Development Kit (JDK) version 5 or higher is required in order to run the Mobicents SIP Presence Service. Note that the JBoss Application Server is a runtime dependency of the SIP Presence Service and, as mentioned, comes bundled with the main binary distribution.
2.1.3. Downloading
You can download the latest version of the SIP Presence Service distribution you need from the Mobicents
Downloads page at http://sourceforge.net/project/showfiles.php?group_id=102670. Click on the Mobicents SIP Presence Service link to view all available distributions and downloads. The latest releases are nearer the top.
If you are unsure which distribution zip file to download, refer to Description of the Different SIP Presence Service Distributions, and then to the following list of release binaries.
SIP Presence Service Binary Distribution Zip Files
- mobicents-sip-presence-integrated-1.0.0.BETA4-CP1.zip
- Download this zip file to obtain the integrated SIP Presence Service binary distribution, which includes the SIP Presence Server, the XDM Server, and the JBoss Application Server as well as all required resource adapters.
- mobicents-sip-presence-xdms-1.0.0.BETA4-CP1.zip
- Download this zip file to obtain the XML Document Management Server binary distribution, which bundles the JBoss Application Server and the Mobicents JAIN SLEE Server.
2.1.4. Installing
Once the requirements and prerequisites have been met, and you have downloaded the correct zip file for the binary distribution you need, you are ready to install the SIP Presence Service (or XDM Server). Follow the instructions below for your platform, whether Linux or Windows.
Use Version Numbers Relevant to Your Installation!
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.3. Installing the SIP Presence Service Binary Distribution on Linux
- Assuming that you downloaded the binary distribution zip file to your home folder, create a subdirectory to unzip the files to. 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 binary distribution you downloaded.
Integrated SIP Presence Service:
~]$ mkdir "sps-
<version>"XDM Server:
~]$ mkdir "xdms-
<version>" - Move the downloaded zip file into the directory you just created:
Integrated SIP Presence Service:
~]$ mv "mobicents-sip-presence-integrated-1.0.0.BETA4-CP1.zip" "sps-
<version>"XDM Server:
~]$ mv "mobicents-sip-presence-xdms-1.0.0.BETA4-CP1.zip" "xdms-
<version>" - Move into the directory:
~]$ cd "sps-
<version>"Or...~]$ cd "xdms-
<version>" - Finally, use Java's
jarcommand to extract the contents of the zip file into the current directory, thus completing the install:-xvfIntegrated SIP Presence Service:
sps-
<version>]$ jar -xvf "mobicents-sip-presence-integrated-1.0.0.BETA4-CP1.zip"XDM Server:
xdms-
<version>]$ jar -xvf "mobicents-sip-presence-xdms-1.0.0.BETA4-CP1.zip" - To free disk space, you may want to delete the zip file once you've extracted its contents:
sps-
<version>]$ rm "mobicents-sip-presence-integrated-1.0.0.BETA4-CP1.zip"xdms-
<version>]$ rm "mobicents-sip-presence-xdms-1.0.0.BETA4-CP1.zip"
Procedure 2.4. Installing the SIP Presence Service Binary Distribution on Windows
- For this example, we'll assume that you downloaded the binary distribution zip file to the
My Downloadsfolder. First, using Windows Explorer, create a subfolder inMy Downloadsto 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 SIP Presence Service or XDM Server binary distribution you downloaded. In these instructions, we will refer to this folder assps-or<version>xdms-.<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
jarcommand to extract the binary distribution files from the zip archive. To use this method instead, first move the downloaded zip file from-xvfMy Downloadsto the folder that you just created to hold the server's files. - Then, open the Windows Command Prompt and navigate to the folder holding the archive using the
cdcommand:Opening the Command Prompt from Windows Explorer
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 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\sps-
<version>"Or...C:\Users\Me>cd "My Downloads\xdms-
<version>" - Finally, use the
jarcommand to extract the archive contents into the current folder.-xvfIntegrated SIP Presence Service:
C:\Users\Me\My Downloads\sps-
<version>>jar -xvf "mobicents-sip-presence-integrated-1.0.0.BETA4-CP1.zip"XDM Server:
C:\Users\Me\My Downloads\xdms-
<version>>jar -xvf "mobicents-sip-presence-xdms-1.0.0.BETA4-CP1.zip"
- At this point, you may want to move the folder holding the SIP Presence Service or XDM Server binary files (in this example, the folder named
sps-or<version>xdms-) to another location. This step is not strictly necessary, but it is probably a good idea to move the server's folder from<version>My Downloadsto 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\sps-
<version>>delete "mobicents-sip-presence-integrated-1.0.0.BETA4-CP1.zip"C:\Users\Me\My Downloads\xdms-
<version>>delete "mobicents-sip-presence-xdms-1.0.0.BETA4-CP1.zip"
2.1.5. Running
Once installed, you can run the SIP Presence Service or XDM Server by executing the one of the startup scripts in the
<install_directory>/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 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 server started successfully if the last line of output is similar to the following (ending with “Started in 23s:648ms”):
11:23:07,656 INFO [Server] JBoss (MX MicroKernel) [4.2.3.GA (build: SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 23s:648ms
Detailed instructions are given below, arranged by platform.
Procedure 2.5. Running the SIP Presence Service on Linux
- Change your working directory to the SIP Presence Service's or XDM Server's install directory:
~]$ cd "sps-
<version>"Or...~]$ cd "xdms-
<version>" - (Optional) Ensure that the
bin/run.shstart script is executable:Integrated SIP Presence Service:
sps-
<version>]$ chmod +x "bin/run.sh"XDM Server:
xdms-
<version>]$ chmod +x "bin/run.sh" - Finally, execute the
run.shBourne shell script:Integrated SIP Presence Service:
sps-
<version>]$ "./bin/run.sh"XDM Server:
xdms-
<version>]$ "./bin/run.sh"- Instead of executing the Bourne shell script to start the server, you may alternatively run the
run.jarexecutable Java archive in thebin/directory:Integrated SIP Presence Service:
sps-
<version>]$ java -jar "bin/run.jar"XDM Server:
xdms-
<version>]$ java -jar "bin/run.jar"
Procedure 2.6. Running the SIP Presence Service on Windows
- There are several different ways to start the SIP Presence Service or XDM 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
bin\subfolder. - Although not the preferred way (see below), it is possible to start the server by double-clicking on the
run.batexecutable batch file.- As mentioned above, the best way to start the SIP Presence Service or XDM Serveris 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
<install_directory>\bin\folder in Windows Explorer, or you can open the Command Prompt via the Start menu and navigate to the correct folder:C:\Users\Me\My Downloads> cd "sps-
<version>"Or...C:\Users\Me\My Downloads> cd "xdms-
<version>" - Start the server by running the executable
run.batbatch file:C:\Users\Me\My Downloads\sps-
<version>>bin\run.batC:\Users\Me\My Downloads\xdms-
<version>>bin\run.bat- It is also possible to start the SIP Presence Service (or XDM Server) by running the
run.jarexecutable Java archive:Integrated SIP Presence Service:
C:\Users\Me\My Downloads\sps-
<version>>java -jar "bin\run.jar"XDM Server:
C:\Users\Me\My Downloads\xdms-
<version>>java -jar "bin\run.jar"
2.1.6. Stopping
Detailed instructions for stopping the SIP Presence Service and XDM 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 2.7. Stopping the SIP Presence Service on Linux by Executing shutdown.sh or shutdown.jar
- You can shut down the server by executing the
shutdown.shBourne shell script in the<install_directory>/bin/directory. To do so, first change your working directory to the SIP Presence Service's (or XDM Server's) install directory:~]$ cd "sps-
<version>"Or...~]$ cd "xdms-
<version>" - (Optional) Ensure that the
shutdown.shstart script is executable:Integrated SIP Presence Service:
sps-
<version>]$ chmod +x "bin/shutdown.sh"XDM Server:
xdms-
<version>]$ chmod +x "bin/shutdown.sh" - Finally, run the
shutdown.shexecutable Bourne shell script, and remember to add the-Soption (which is the short option for--shutdown) as a command line argument:Integrated SIP Presence Service:
sps-
<version>]$ "./bin/shutdown.sh" -SXDM Server:
xdms-
<version>]$ "./bin/shutdown.sh" -S- Instead of executing the Bourne shell script to stop the server, you may alternatively run the
shutdown.jarexecutable Java archive to do so (and remembering, again, to add the-Scommand line argument):Integrated SIP Presence Service:
sps-
<version>]$ java -jar "bin/shutdown.jar" -SXDM Server:
xdms-
<version>]$ java -jar "bin/shutdown.jar" -S
Procedure 2.8. Stopping the SIP Presence Service on Windows
- Stopping the SIP Presence Service (or XDM Server) on Windows consists in executing either the
shutdown.bator theshutdown.jarexecutable file in thebin/subfolder of the SIP Presence Service/XDM Server binary distribution. Make sure to add the-Soption (which is the short option for--shutdown) as a command line argument.Integrated SIP Presence Service:
C:\Users\Me\My Downloads\sps-
<version>>bin\shutdown.bat -SXDM Server:
C:\Users\Me\My Downloads\xdms-
<version>>bin\shutdown.bat -S- Alternatively, you can execute the
shutdown.jarJava archive by running thejavacommand, and remembering to add the-jar-Soption as a command line argument:Integrated SIP Presence Service:
C:\Users\Me\My Downloads\sps-
<version>>java -jar "bin\shutdown.jar" -SXDM Server:
C:\Users\Me\My Downloads\sps-
<version>>java -jar "bin\shutdown.jar" -S
2.1.7. Configuring (and Setting JBOSS_HOME)
2.1.7.1. Setting the JBOSS_HOME Environment Variable
The JBoss Communications Platform (JBCP) is built on top of the JBoss Enterprise Application Platform (JBoss EAP). You do not need to set the
JBOSS_HOME environment variable to run any of the JBoss Communications Platform servers unless JBOSS_HOME is already set.
The best way to know for sure whether
JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.
Checking to See If JBOSS_HOME is Set on Linux
At the command line,echo$JBOSS_HOME to see if it is currently defined in your environment:
~]$ echo $JBOSS_HOME
Silence on the command line (a completely blank line) means that it is not set, in which case you can proceed with running the JBoss Communications Platform.
Checking to See if JBOSS_HOME is Set on Windows
For information on determining whether environment variables are set in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.
If
JBOSS_HOME is already set on your system, then you have three options:
unsetit, which only takes effect for the current session and is therefore not advised;- find where
JBOSS_HOMEis defined, such as in your local~/.bashrcstartup script in Linux, or, possibly, system-wide in/etc/bashrc, and remove it or comment it out; - or point it to the correct location, in which case you should refer to the following instructions on how to set
JBOSS_HOME.
Setting the JBOSS_HOME Environment Variable on Linux
TheJBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform that you installed. As another hint, this topmost directory contains a bin subdirectory.
Setting
JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Linux, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.
Procedure 2.9. To Set JBOSS_HOME on Linux...
- Open the
~/.bashrcstartup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:export JBOSS_HOME="/home/
<username>/<path>/<to>/<install_directory>" - Save and close the
.bashrcstartup script. - You should
sourcethe.bashrcscript to force your change to take effect, so thatJBOSS_HOMEbecomes set for the current session[11].~]$ source ~/.bashrc
- Finally, ensure that
JBOSS_HOMEis set in the current session, and actually points to the correct location:Note
The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output,JBOSS_HOMEhas been set correctly to thetopmost_directoryof the JBCP installation. Note that if you are installing one of the standalone JBCP servers (with JBoss AS bundled!), thenJBOSS_HOMEwould point to thetopmost_directoryof your server installation.~]$ echo $JBOSS_HOME /home/silas/jboss-eap-4.3/jboss-as
Setting the JBOSS_HOME Environment Variable on Windows
TheJBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform that you installed. As another hint, this topmost directory contains a bin subdirectory.
For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.
2.1.8. Testing
2.1.9. Uninstalling
To uninstall the SIP Presence Service or XDM Server, simply delete the directory you decompressed the binary distribution archive into.
[10] At this point in time, it is possible to run most JBCP servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.
[11]
Note that any other terminals which were opened prior to your having altered .bashrc will need to source~/.bashrc as well should they require access to JBOSS_HOME.
Chapter 3. Mobicents SIP Presence Server
The Mobicents SIP Presence Server is a free and open source implementation of a SIP Presence Server, as defined by the Internet Engineering Task Force (IETF), the Open Mobile Alliance (OMA), the 3rd Generation Partnership Project (3GPP) and the European Telecommunications Standards Institute (ETSI).
The SIP Presence Server is an entity that accepts, stores and distributes SIP presence information.
3.1. Functional Architecture of the SIP Presence Server
Functional Diagram of the Mobicents SIP Presence Server
The SIP Presence Server is comprised of the following functional elements:
- Presence Publication Control
- This functional element manages the publication of presence events, which includes not only the handling of new publications, but also the refreshing, modification or removal of, already-published information.Because the presence resource, which is also called a presentity, can have multiple publications simultaneously, such as some state published by a user agent or device, and some location data published by a Presence Network Agent (on behalf of the presentity), this element is also responsible for composing all of the different publications for the same resource.In some presence networks, it may be of interest to allow resources to have a static presence state which is stored in the XDM Server. In cases like these, Presence Publication Control may need to interface with the XDM Server to retrieve and subscribe to (learn about changes to) that information, and use it when composing the final presence information document.
- Presence Subscription Control
- This functional element handles subscriptions to presence events or to the list of subscribers (watchers), for any specific resource. It is, of course, responsible for emitting notifications related to those subscriptions.Presence authorization rules, which define if a subscription is allowed or rejected and, if allowed, define which transformations to the original presence events are needed, are stored on the XDM Server by the user. Thus, Presence Subscription Control needs to retrieve and subscribe to that information.
- XDM Client Control
- This last element is responsible for interfacing with the XDM Server that manages the user's XML documents, and is related to the main functions of the presence server. It is capable not only of retrieving a document or part of one, but also of subscribing to either updates of a single, specific document, or to a full collection of documents of a specific type or application.
3.1.1. Implementation Architecture of the Mobicents SIP Presence Server
Implementation Architecture of the Mobicents SIP Presence Server
The implementation of the Mobicents SIP Presence Server comprises the following functional elements:
The Two Services Which Compose the SIP Presence Server
- Presence Publication Control Service
- This JAIN SLEE service includes the root Service Building Block (SBB),
PresencePublicationControlSbb, which is the implementation of the abstract SIP eventPublicationControlSbb. It handles publications on the presence event package.ThePresencePublicationControlSbbprovides the following capabilities:- It provides the logic to authorize a publication; however, it only authorizes
PUBLISHrequests when the request URI matches the PIDF document “entity” attribute. - It provides JAXB unmarshellers to validate and parse the PIDF document for the abstract
PublicationControlSbb. - It demands that notifying subscribers occur through a child relation to the root SBB of the Presence Subscription Control Service.
- Finally, it also provides an
SbbLocalObjectinterface that can be used, in JAIN SLEE child relations, to obtain the composed presence information for a specific resource.
- Presence Subscription Control Service.
- This JAIN SLEE service includes the root SBB
PresenceSubscriptionControlSbb, which is the implementation of the abstract SIP EventSubscriptionControlSbb. It handles subscriptions on the “presence” event package.The standout SBB logic item is the usage of presence-rules documents, obtained through the XDM Client SBB child relation, in order to authorize subscriptions and transform the content notified[12]. It also defines a child relation to the root SBB ofPresencePublicationServiceto retrieve the composed PIDF document for the subscription's notifier.The SBB also provides anSbbLocalObjectinterface that can be used, in JAIN SLEE child relations, to make the presence event known to the subscribers of a specific resource.
The implementation architecture of the SIP Presence Server also contains client-side components:
- Presence Client SBB
Not Yet Available
This SBB is not yet available.ThePresenceClientSBBis the interface to a JAIN SLEE SBB intended to be used as a client for the Mobicents SIP Presence Server (and other servers compliant with same standards), in JAIN SLEE child relations.Two implementations of this interface are provided: theInternalPresenceClientSBBthat is used with applications running in the Mobicents SIP Presence Server JAIN SLEE container, and theExternalPresenceClientSBB, used with applications running in a different JAIN SLEE container than the Mobicents SIP Presence Server.
3.2. Resources and Further Information about the SIP Presence Server
For further information on the Mobicents SIP Presence Server, see the following list of additional resources:
Chapter 4. Mobicents XML Document Management Server
The Mobicents XML Document Management Server (XDM Server) is part of the Mobicents SIP Presence Service; it is the first free and open source implementation of an XML Document Management Server as defined in the Open Mobile Alliance (OMA) XML Document Management v1.1 specification. This functional element of next-generation IP communication networks is responsible for handling the management of user 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.
4.1. Functional Architecture of the XDM Server
The Mobicents XDM Server includes the following XCAP application usages:
The SIP interface partially implements the XCAP Diff Event IETF draft, version 3. Subscriptions to a single document or usage by an entire application are supported. However, these differing usages do not extend to the single-XML element or attribute value level. Regarding the notifications, the diff-processing subscription parameter, if present, is ignored, and patching of content is not available at the moment, which means that only the document etags, new and/or old, will be provided.
The XDM Server comprises the following functional elements:
Functional Elements of the XDM Server
- Data Source
- The XDM Server data source is where all user XML documents are stored. Information related to the server itself is also stored in this element along with the user's provisioned dataThe data source also handles subscriptions to updates on specific documents, or complete XCAP application usages.
- Aggregation Proxy
- The aggregation proxy is responsible for handling an XDM client's XCAP requests, which includes authentication and authorization of the requester.
- Request Processor
- This element includes the XCAP Server logic to process an XCAP request and return a proper response.
- XDM Event Subscription Control
- This element, using the SIP protocol, is responsible for handling subscriptions to documents managed by the XDM. Its functions include the authentication and authorization of a subscription, attachment to update events on specific documents or application usages, and the sending of notifications when documents change.
Implementation Architecture of the Mobicents XML Document Management Server
The XDM Server is built on top of the Mobicents JAIN SLEE container. This figure depicts the architecture of the XDM Server implementation.
View the diagram of the XDM Server Implementation.
The Functional Elements of the XML Document Management Server
- Data Source Resource Adapter
- This resource adapter implements the Data Source functional element.The
RA Typedefines two activities objects,DocumentActivityandAppUsageActivity, both of which are used to fire events that signal that a document, element or attribute was updated.TheRA Typealso defines a Service Building Block (SBB) RA interface to manage the users and documents stored in the XDM Server, and create activities, where events will be fired. The resource adapter will only fire events on activities that exist; that is, the RA won't create activities implicitly if a document is updated.TheRA Typealso provides a base abstract implementation of the resource adapter, making it very simple to change the underlying resource used to store information, which is by default the internal JDBC datasource of the JBoss Application Server. - AppUsage Cache Resource Adaptor
- This resource adapter stores the XCAP application usages installed in the server.Each
AppUsageis an object that includes the logic to validate XCAP documents that result from XCAP requests and are expensive to create; this resource adapter thus provides caching of AppUsages, using a pool model.The resource adapter doesn't possess events or activities. - AppUsage Service
- XCAP Application Usages are installed through a JAIN SLEE service, making it possible to add and/or remove application usages while the server is running.
- Aggregation Proxy Service
- This JAIN SLEE service implements the aggregation proxy functional element. It handles events fired by the Mobicents HTTP Servlet resource adapter and then uses two child SBBs: the
User Profile Enabler SBBto retrieve information regarding the user needed for authentication/authorization of the XCAP request, and theRequest Processor SBB, which handles the XCAP request. - Request Processor SBB
- The
Request Processor SBBimplements the request processor functional element, providing a synchronous SBB interface to process XCAP requests. It uses theAppUsage Cacheresource adapter to borrow AppUsage objects, and the Data Source resource adapter to retrieve or set documents stored in the server's data source. - User Profile Enabler SBB (TBD: not available yet)
- This SBB provides a synchronous SBB interface used in JAIN SLEE child relations in order to retrieve user information. Two different implementations of the interface are provided: the first considers whether the information is stored in the XDM Data Source, another interfaces with a Diameter Sh Server, such as IMS HSS.
- XCAP Diff Subscription Control Service
- This JAIN SLEE Service extends the abstract SIP Event Subscription Control component to handle SIP subscriptions on the xcap-diff event package.
The implementation architecture figure also contains client-side components:
Client-Side Components of the XML Document Management Server
- XCAP Client
- The XCAP client is a simple API to interact with an XCAP Server that internally uses the Apache HTTP Client.
- XCAP Client Resource Adaptor
- The XCAP Client Resource Adapter adapts the XCAP Client API into the JAIN SLEE domain. It provides methods to interact with the XCAP server in both synchronous and asynchronous ways.The RA Type description and code snippets using the RA can be found here.
- XDM Client SBB
- The XDMClientSBB is an interface of a JAIN SLEE SBB to be used as a client to the Mobicents XDM Server (and others compliant with same standards), in JAIN SLEE child relations.Two implementations of this interface are provided:
InternalXDMClientSBBis intended to be used on applications running in the Mobicents XDM Server JAIN SLEE container, andExternalXDMClientSBB, which is intended to be used on applications in a different JAIN SLEE container than the Mobicents XDM Server.
4.2. Resources and Further Information about the XDM Server
For further information on the Mobicents XDM Server, here is a list of additional resources:
Chapter 5. Mobicents Resource List Server
Resource List Server
The Mobicents Resource List Server is not yet fully-implemented.
Revision History
| Revision History | |||
|---|---|---|---|
| Revision 2.0 | Fri Mar 06 2009 | ||
| |||
| Revision 1.0 | Tue Jan 20 2009 | ||
| |||
Index
F
- feedback
- contact information for this manual, We Need Feedback!