JBoss.org Community Documentation
User Guide
Copyright ©
Abstract
Mobicents is a highly scalable event-driven application server with a robust component model. Mobicents is the first and only Open Source Platform certified for JSLEE 1.0 compliance. It complements J2EE to enable the convergence of voice, video and data in next-generation intelligent applications. Web and SIP can be combined together to achieve more sophisticated and natural user experience.
- Preface
- 1. Introduction
- 2. Installation of the Mobicents Converged Application Server
- 3. Working with the Mobicents Management Console
- 4. Resource Adapters
-
- 4.1. Resource Adapters
- 4.2. SIP Resource Adapter
- 4.3. The XMPP and Google Talk Resource Adapter
- 4.4. Asterisk Resource Adapter
- 4.5. J2EE and CA Resource Adapter
- 4.6. Diameter Resource Adapter
- 4.7. Media Resource Adapter
- 4.8. SMPP Resource Adapter
- 4.9. Media Gateway Resource Adapter
- 4.10. JCC INAP Resource Adapter
- 4.11. HTTP Servlet Resource Adapter
- 4.12. The HTTP Client Resource Adapter
- 4.13. Persistence Resource Adapter
- 4.14. XCAP Client Resource Adapter
- 4.15. Rules Resource Adapter
- 4.16. TTS Resource Adapter
- 4.17. SAP Resource Adapter
- 4.18. Third-Party Resource Adapters
- 5. Mobicents Examples
- 6. Mobicents SIP Servlets Server
- 7. Mobicents SIP Presence Service
- 8. Mobicents Media Server
- A. Revision History
Certain words in this manual are represented in different fonts, styles, and weights. This highlighting indicates that the word is part of a specific category. The categories include the following:
-
Courier font -
Courier font represents
commands,file names and paths, andprompts.When shown as below, it indicates computer output:
Desktop about.html logs paulwesterberg.png Mail backupfiles mail reports
-
bold Courier font -
Bold Courier font represents text that you are to type, such as:
service jonas startIf you have to run a command as root, the root prompt (
#) precedes the command:#gconftool-2 -
italic Courier font -
Italic Courier font represents a variable, such as an installation directory:
install_dir/bin/ - bold font
-
Bold font represents application programs and text found on a graphical interface .
When shown like this: OK , it indicates a button on a graphical application interface.
Additionally, the manual uses different strategies to draw your attention to pieces of information. In order of how critical the information is to you, these items are marked as follows:
Note
A note is typically information that you need to understand the behavior of the system.
Tip
A tip is typically an alternative way of performing a task.
Important
Important information is necessary, but possibly unexpected, such as a configuration change that will not persist after a reboot.
Caution
A caution indicates an act that would violate your support agreement, such as recompiling the kernel.
Warning
A warning indicates potential data loss, as may happen when tuning hardware for maximum performance.
The Mobicents Communication Platform is the best architecture for creating, deploying and managing services and applications integrating voice, video and data across a range of IP and communications networks. The Mobicents Communication Platform drives convergence by leveraging the following four core capabilities.
Core Capabilities of the Mobicents Converged Application Server
- Mobicents JAIN SLEE
-
Mobicents JAIN SLEE provides a highly-scalable event-driven application server with a robust component model and a fault-tolerant execution environment. Mobicents JAIN SLEE is the first and only Open Source Platform certified for JSLEE 1.0 compliance. It complements J2EE to enable the convergence of voice, video and data in next-generation intelligent applications. Web and SIP can be combined together to achieve more sophisticated and natural user experience.
- Mobicents Media Server
-
The Mobicents Media Server is an open sourced server based on the Java Media Framework implementation, and aimed to:
Aims of the Mobicents Media Server
-
Deliver a competitive, complete, best-of-breed media gateway functionality of the highest quality.
-
Meet the demands of converged wireless, wireline, cable broadband access and fixed-mobile converged VoIP networks from a single media gateway platform.
-
Increase flexibility with a media gateway that supports a wide variety of call control protocols, and which scales down to meet the demands of enterprises and small carrier providers.
-
React quickly to dynamic market requirements.
-
- Mobicents Presence (XDM) Server
-
The first free and open source implementation of an XML Document Management (XDM) server, as defined in the Open Mobile Alliance (OMA) specifications. This functional element of next-generation IP communication networks is responsible for handling the management of users' XML documents stored on the network side, such as presence authorization rules, contact and group lists (also known as resource lists), static presence information, and much more.
- The JBoss Microcontainer
-
The JBoss Microcontainer is the state-of-the-art hosting environment in which higher-level containers reside. It provides service registration, configuration and dependency management, classloading isolation control, package versioning, deployment, thread pooling and many other fundamental building blocks necessary for highly-scalable, fault-tolerant middleware servers.
In the scope of telecommunications' Next Generation Intelligent Networks (NGINs), Mobicents fits in as a high-performance core engine for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes).
Mobicents enables the composition of Service Building Blocks (SBBs) such as call control, billing, user-provisioning, administration, and presence-sensing features. The JAIN SLEE [1] specification allows popular protocol stacks such as SIP to be plugged in as resource adapters. The SLEE Service Building Blocks have many similarities to Enterprise Java Beans (EJBs), and naturally accommodate integration with enterprise applications, the Web, Customer Relationship Management (CRM) and Service-Oriented Architecture (SOA) end points.
Out-of-the-box monitoring and management of Mobicents components is achieved via SLEE standard-based Java Management Extensions (JMXes) and Simple Network Management Profile (SNMP) interfaces.
Beyond telecommunications, Mobicents is applicable to a wider variety of problems demanding high-volume, low-latency signaling. Examples include financial trading, online gaming, RFID sensor network integration, and distributed control.
The Mobicents Converged Application Server has a wide variety of use cases, including all of the following domains:
VoIP Call Control Services
Voice-over-Internet Protocol (VoIP) services are some of the primary use cases for Mobicents. Examples of VoIP services include call routing, forwarding, termination, voice mailbox, conferencing and user provisioning.
Instant Messaging Services
Online Multi-Player Games
SLEE is a great platform for Massively Multi-Player (MMP games. The following are some of the principle requirements for MMP servers, provided by the leader of Java.net Games community:
-
Worst-case latencies from end-to-end in the back-end system, including all database operations, of no more than 100 ms.
-
A programming model that allows the game programmer to program simple persistent objects, with no more work than any other standard Java object, and have them execute on data events coming into the system. These objects must be "real objects" in the simulation sense of the term.
-
A programming model that is optimistically parallel while appearing to the programmer as a single-threaded event-driven model. Each event has to be ACID-transactional (Atomicity, Consistency, Isolation, Durability), and atomic unto itself. The programmer cannot be required to be aware in any way of multiple threads, database access, or locking. It must be inherently and transparently race-condition-proof and deadlock-proof.
-
It must scale to massive numbers of simultaneous users (5-to-6 figures) online simultaneously accessing the same database of objects.
-
It needs to provide failover, fault-tolerance and efficient load-balancing. The last is critical. Game applications are cost-sensitive. Without the ability to load-balance the potentially heavy loads of multiple apps over banks of low-cost computers used to maximal efficiency, the economic model falls apart.
If you are familiar with SLEE, then you have already noticed that these requirements closely track the fundamental SLEE design principles.
Here are some pointers to books, blogs and papers on the subject of Massive Multi-Player games:
Financial Day Trading
Financial trading is a well-understood problem domain demanding highly-available, fast-response technology to serve billions of trading calls per day. Each trading call is a concise message identifying the trader, ticker and price. Day trading applications fit nicely on top of event-driven containers.
First Responder Communication Networks
We live in an unsafe world. Project P25 is focused on public safety communications digital radio interoperability. It is spurred on by growing concern which has driven many countries' governmentsincluding the US Federal Governmentto reorganize in order to create focused positions to address homeland security. The National Institute of Standards and Technology (NIST) is building a test system for Radio-Frequency subsystem interoperability Standard, which is based on these three protocols: the Session Initiation Protocol (SIP), the Service Discovery Protocol (SDP), and the Real-time Transport Protocol (RTP). The reference implementation and test system will be built as SLEE services.
Sensor Network Integration and RFID
Gartner predicts that sensor technologies will be part of our everyday life by the year 2015. Sensors will be everywhere: as RFID tags on consumer products, devices monitoring tire pressure, location-tracking tags carried by workers in sensitive or hazardous environments, etc. In addition, all enterprise activities will be monitored using enterprise tools connected to the network; by 2010 these, as embedded Internet devices, will represent 95% of all Internet-connected systems.
Pervasive sensor technologies will transform the objective of IT from providing support for fundamentally manual processes to automating the execution of tasks in response to a continuously-changing environment monitored by sensors. This requires a new kind of architecture capable of delivering extreme transaction processing.
[1] JAIN SLEE stands for Java API for Intelligent Network Service Logic and Execution Environment architecture. JSLEE (Java Service Logic Execution Environment) is a short synonym for JAIN SLEE.
The Mobicents Converged Application Server can be installed by downloading the ready-to-go binary distribution, or, alterately, the source code can be obtained using the Subversion version control system (VCS) and then Mobicents can be built from source. Installing the binary distribution is recommended for most users, and obtaining and building the source code distribution is recommended for those who want access to the latest revisions and capabilities.
Mobicents is written in Java; therefore, before running any Mobicents server, you must have a working Java Runtime Environment (JRE) or Java Development Kit (JDK) installed on your system. In addition, the JRE or JDK you are using to run Mobicents must be version 5 or higher[2].
Should I Install the JRE or JDK?
Although you can run the Mobicents servers using the Java Runtime Environment, we assume that most Mobicents users are developers interested in developing Java-based, Mobicents-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.
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 Mobicents in a production environment.
Installing
Procedure 2.1. Installing the JDK on Linux
-
Regardless of which file you downloaded, you can install it on Linux by moving into the directory you downloaded the installer to, making sure the file is executable, and then running it:
~]$ cd downloads downloads]$ chmod +x “jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin” downloads]$ ./“jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin”
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 the JAVA_HOME environment variable, and ensuring that the system is using the proper JDK (or JRE) using the alternatives command. Setting JAVA_HOME usually overrides the values for java, javac and java_sdk_1.5.0 in alternatives, but we will set them all just to be safe and consistent.
-
Setting the
JAVA_HOMEEnvironment Variable -
After installing the JDK, you must ensure that the
JAVA_HOMEenvironment variable exists and points to the location of your JDK installation.Setting the
JAVA_HOMEEnvironment Variable on LinuxYou can determine whether
JAVA_HOMEis set on your system byechoing it on the command line:~]$ echo $JAVA_HOME
If
JAVA_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 Mobicents (any environment variables
exported from~/.bashrcfiles are local to that user).Setting the
JAVA_HOMEEnvironment Variable on Windows -
Setting
java,javacandjava_sdk_1.5.0Usingalternatives -
Selecting the Correct System JVM on Linux
On systems with the
alternativescommand, 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 the
javaexecutable. 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 the
javaccommand 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
Testing
Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in your PATH, run the java command in the terminal from your home directory:-version
~]$ java -version java version "1.5.0_16" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03) Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling
There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily using alternatives, and/or by setting JAVA_HOME.
Uninstalling the JDK on Linux
On RPM-based systems, you can uninstall the JDK using the yum command.remove <jdk_rpm_name>
Uninstalling the JDK on Windows
On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.
The Mobicents JAIN SLEE Server binary distribution is comprised of—and comes bundled with—all of the following components:
-
the JBoss Application Server, version 4.2.2 GA
-
the Mobicents JAIN SLEE Server
-
the Mobicents Media Server
-
the Mobicents SIP Servlets Server
-
the Mobicents SIP Presence Service
-
a large number of resource adapters
-
multiple demonstration examples
You should ensure that a few requirements have been met before continuing with the install.
Hardware Requirements
- Sufficient Disk Space
-
You must have sufficient disk space in order to install the Mobicents binary release. Once unzipped, version 1.2.0 of the Mobicents binary release requires at least 100 MB of free disk space. Keep in mind that disk space requirements may change from release to release.
- Anything Java Itself Will Run On
-
The Mobicents JAIN SLEE Server is 100% Java, along with all of its bundled servers, resource adapters and demonstration examples. Therefore, the Mobicents JAIN SLEE Server will run on the same hardware that the JBoss Application Server runs on.
Software Prerequisites
- 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 JAIN SLEE Server. Note that the JBoss Application Server is a runtime dependency of Mobicents and, as mentioned, comes bundled with the binary distribution.
For instructions on how to install the JDK, refer to Chapter 2, Installation of the Mobicents Converged Application Server .
When you download the Mobicents JAIN SLEE Server binary distribution, you can also choose to verify the integrity of the zip file you download, which is both preferred and safer. If you are setting up Mobicents in a production environment (as opposed to, say, merely playing around with Mobicents' capabilities on your personal machine), we recommend verifying the integrity of the downloaded distribution. The first procedure following shows you how to simply download the Mobicents JAIN SLEE Server binary distribution, while the second procedure following details how to download and verify the installation zip file.
Procedure 2.3. Downloading Without Verifying
-
You can download the latest version of the Mobicents JAIN SLEE Server from http://www.mobicents.org/jainsleedownload.html. The top row of the table hold the latest version. Click the
Downloadlink on the right to start the download from Sourceforge.net.
Procedure 2.4. Downloading and Verifying
-
The preferred—and safer—way to obtain the JAIN SLEE Server binary distribution is to download the binary zip file as well as its corresponding sha1 file, and use the sha1 file to verify the integrity of the zip file. To do this, first go to http://www.mobicents.org/jainsleedownload.html and, at the top of the page, click on the
herein “Browse all fileshere” link. The most recent releases are located near the top. Download both the zip file and its attendant sha1 file. For example, if you wanted to download the Mobicents JAIN SLEE Server version 1.20 Release Candidate 1, you would download both of the following files:-
mobicents-all-1.2.0.CR1-jboss-4.2.2.GA.zip
-
mobicents-all-1.2.0.CR1-jboss-4.2.2.GA.zip.sha1.asc
-
-
Next, verify the integrity of the zip file with the sha1 file, which contains a checksum which is used to do precisely this, and which can alert you if the file has been changed since it was uploaded, or if it was corrupted upon download.
On a Linux system you can use the
sha1sumcommand to verify the integrity of the binary distribution zip file.On a Windows system you will need to download a sha1sum-generating program such as the
sha1sum.exeprogram. This program will generate a checksum that you can compare with the sum in the sha1 file.If the two checksums are identical, then the downloaded binary distribution zip file's integrity is assured, and it is safe to proceed with installation.
Beware of a Corrupted or Compromised Zip File!
If the two checksums are not identical, it means that the downloaded zip file was corrupted upon download, or has been changed since it was last uploaded to the server. In this case, you should first re-download the two files (the zip file and the sha1 file) and compare once more. If this second comparison fails, it could indicate a problem with the install file, and you should contact the Mobicents team by email to alert them to the conflict.
Once the requirements and prerequisites have been met and you have downloaded the binary distribution zip file, you are ready to install Mobicents. Follow the instructions below for your platform, whether Linux or Windows.
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.5. Installing the Mobicents Binary Distribution on Linux
-
First, move to the directory to which you downloaded the binary distribution zip file. For this example, we'll assume you're currently in your home directory, and that you downloaded the zip file to a subdirectory of it, referred to as
<downloads>.~]# cd <downloads>
-
In
<downloads>, create a subdirectory to hold the unzipped Mobicents files. It is good practice to include the version number in this directory name; if you do so, remember to correctly match it with the version of the Mobicents binary distribution you downloaded.<downloads>]$ mkdir "mobicents-<version>"
-
Move the downloaded zip file into the directory you just created:
<downloads>]$ mv "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip" "mobicents-<version>"
-
Move into that directory:
<downloads>]$ cd "mobicents-<version>"
-
Finally, use Java's
jarcommand to extract the contents of the zip file into the current directory, thus completing the install:-xvfmobicents-<version>]$ jar -xvf "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
-
Alternatively, if Linux's
unziputility is present on your system or is installable, you can use it in lieu of Java'sjarcommand:-xvfmobicents-<version>]$ unzip "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
Tip
You can also use
unzip's-d<unzip_to_location>
-
-
To free disk space, you may want to delete the zip file once you've extracted its contents:
mobicents-<version>]$ rm "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
Procedure 2.6. Installing the Mobicents Binary Distribution on Windows
-
For this example, we'll assume that you downloaded the binary distribution zip file to the
My 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 Mobicents binary distribution you downloaded. In these instructions, we will refer to this folder asmobicents-<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 Mobicents 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 Open Command Window Here context menu item to appear, which can be used to open the Command Prompt with the current working directory set to either the folder you opened, or opened it from.
C:\Users\Me>cd "My Downloads\mobicents-<version>"
-
Finally, use the
jarcommand to extract the archive contents into the current folder.-xvfC:\Users\Me\My Downloads\mobicents-<version>>jar -xvf "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
-
-
At this point, you may want to move the folder holding the Mobicents binary files (in this example, the folder named
mobicents-<version>) to another location. This step is not strictly necessary, but it is probably a good idea to move the Mobicents folder fromMy 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\mobicents-<version>delete "mobicents-jainslee-server-1.2.0.CR2-jboss-4.2.2.GA.zip"
Configuring the Mobicents JAIN SLEE Server consists in setting the JBOSS_HOME environment variable.
Before running the Mobicents server you are installing, you should consider if you need to set the JBOSS_HOME environment variable. Setting it (or re-setting it to the new value) will always work. Whether or not you
need
to set JBOSS_HOME depends on the following factors:
-
If you are installing a binary Mobicents server and
JBOSS_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
JBOSS_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 JBoss Application Server, then you must set
JBOSS_HOME.
The following instructions detail how to set JBOSS_HOME on both Linux and Windows.
Procedure 2.7. Setting the JBOSS_HOME Environment Variable on Linux
-
The
JBOSS_HOMEenvironment variable must point to the location of your JBoss installation. Any Mobicents server which runs on top of the JBoss Application Server has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, abindirectory.JBOSS_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 JBOSS_HOME="/home/<username>/<path>/<to>/<mobicents_server>"
Save and close
.bashrc. -
You can—and should—
sourceyour.bashrcfile to make your change take effect (so thatJBOSS_HOMEis set) for the current session:~]$ source ~/.bashrc
-
Finally, make sure that
JBOSS_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 by
JBOSS_HOME:~]$ echo $JBOSS_HOME
To be absolutely sure, change your directory to the one pointed to by
JBOSS_HOME:~]$ cd $JBOSS_HOME && pwd
Procedure 2.8. Setting the JBOSS_HOME Environment Variable on Windows
-
The
JBOSS_HOMEenvironment variable must point to the location of your JBoss installation. Any Mobicents server which runs on top of the JBoss Application Server has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, abindirectory.JBOSS_HOMEmust be set to the topmost directory of your Mobicents server installation.If you are planning on running the JBoss Application Server as the Administrator, then you should, of course, set the
JBOSS_HOMEenvironment variable as the administrator , and if you planning to run Tomcat as a normal user, then setJBOSS_HOMEas a user environment variable.For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
Once installed, you can run the Mobicents JAIN SLEE Server by executing the one of the startup scripts in the <topmost_directory>/jboss-4.2.2.GA/bin directory (on Linux or Windows), or by double-clicking the run.bat executable batch file in that same directory (on Windows only). However, we suggest always starting the JAIN SLEE Server using the terminal or Command Prompt because you are then able to read—and act upon—any startup messages, and possibly debug any problems that might arise. In the Linux terminal or Command Prompt, you will be able to tell that the JAIN SLEE Server started successfully if the last line of output is similar to the following (ending with “Started in 25s:527ms”):
16:29:15,442 INFO [ManagementConsole] Mobicents Management Console initialized 16:29:15,551 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080 16:29:15,586 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009 16:29:15,622 INFO [Server] JBoss (MX MicroKernel) [4.2.2.GA (build: SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 25s:527ms
Detailed instructions are given below, arranged by platform.
Procedure 2.9. Running the JAIN SLEE Server on Linux
-
Change your working directory to the JAIN SLEE Server's topmost directory (the one which you extracted the zip file's contents to):
downloads]$ cd "mobicents-<version>"
-
(Optional) Ensure that the
jboss-4.2.2.GA/bin/run.shstart script is executable:mobicents-<version>]$ chmod +x jboss-4.2.2.GA/bin/run.sh
-
Finally, execute the
run.shBourne shell script:mobicents-<version>]$ ./jboss-4.2.2.GA/bin/run.sh
-
Instead of executing the Bourne shell script to start the server, you may alternatively run the
run.jarexecutable Java archive in thejboss-4.2.2.GA/bindirectory:mobicents-<version>]$ java -jar jboss-4.2.2.GA/bin/run.jar
-
Procedure 2.10. Running the JAIN SLEE Server on Windows
-
There are several different ways to start the JAIN SLEE Server on Windows. All of the following methods accomplish the same task.
Using Windows Explorer, change your folder to the one in which you unzipped the downloaded zip file, and then to the
jboss-4.2.2.GA\binsubfolder. -
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
<topmost_directory>\jboss-4.2.2.GA\binfolder in Windows Explorer (see Opening the Command Prompt from Windows Explorer for details), or you can open the Command Prompt via the Start menu and navigate to the correct folder:C:\Users\Me\My Downloads> cd "mobicents<version>"
-
Start the JAIN SLEE Server by running the executable
run.batbatch file:C:\Users\Me\My Downloads\mobicents<version>>jboss-4.2.2.GA\bin\run.bat
-
It is also possible to start the JAIN SLEE Server by running the
run.jarexecutable Java archive:C:\Users\Me\My Downloads\mobicents<version>>java -jar jboss-4.2.2.GA\bin\run.jar
-
-
The JAIN SLEE Server can be observed and controlled using the Mobicents Management Console, which is started along with the server. For information on configuring the JAIN SLEE Server with the Management Console, refer to Chapter 3, Working with the Mobicents Management Console .
Just as there are multiple ways to run the JAIN SLEE Server, there are multiple ways to stop it. Detailed instructions for stopping the JAIN SLEE Server are given below, arranged by platform. Note that if you properly stop the server, you will see the following three lines as the last output in the Linux terminal or Command Prompt:
16:44:29,745 INFO [Server] Shutdown complete Shutdown complete Halting VM
Procedure 2.11. Stopping the JAIN SLEE Server on Linux by Issuing a Control Code
-
Assuming that you started the JAIN SLEE Server as a foreground process in the terminal, the easiest way to stop it is by pressing the Ctrl + c key combination in the same terminal in which you started it.
Procedure 2.12. Stopping the JAIN SLEE Server on Linux by Executing shutdown.sh or shutdown.jar
-
Another way to shut down the JAIN SLEE Server is by executing the
shutdown.shBourne shell script in the<topmost_directory>/jboss-4.2.2.GA/bindirectory. To do so, first change your working directory to the JAIN SLEE Server's topmost directory (the one to which you extracted the downloaded zip file's contents):downloads]$ cd "mobicents-<version>"
-
(Optional) Ensure that the jboss-4.2.2.GA/bin/shutdown.sh start script is executable:
mobicents-<version>]$ chmod +x jboss-4.2.2.GA/bin/shutdown.sh
-
Finally, run the
shutdown.shexecutable Bourne shell script, and remember to add the-Soption (which is the short option for--shutdown) as a command line argument:mobicents-<version>]$ ./jboss-4.2.2.GA/bin/shutdown.sh -S
-
Instead of executing the Bourne shell script to stop the server, you may alternatively run the
shutdown.jarexecutable Java archive to do so (and remembering, again, to add the-Scommand line argument):mobicents-<version>]$ java -jar jboss-4.2.2.GA/bin/shutdown.jar -S
-
Procedure 2.13. Stopping the JAIN SLEE Server on Windows
-
Stopping the JAIN SLEE Server on Windows consists in executing either the
shutdown.bator theshutdown.jarexecutable file in thejboss-4.2.2.GA\binsubfolder of the JAIN SLEE 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\mobicents-<version>>jboss-4.2.2.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\mobicents-<version>>java -jar jboss-4.2.2.GA\bin\shutdown.jar -S
-
[2] At this point in time, it is possible to run most Mobicents servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the Mobicents XML Document Management Server does not. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the Mobicents XML Document Management Server with Java 6.
Once Mobicents is running, you can access the management console by pointing your browser to
http://localhost:8080/management-console/
. If you are working with a remote machine, replace
localhost
with the name of the remote machine's host, and
8080
with the correct port.
The management console screen has the following components:
-
The
Main Menu, on the left. -
The
Current View, on the right. -
The
Log Console, on the bottom.
New views my be selected by clicking on the Main Menu items. The Log Console displays important and relevant notifications when operations are executed, such as error and status messages.
The initial management console view, which can also be accessed by clicking on SLEE at the top of the Main Menu, displays a status message indicating whether Mobicents is currently running or not, and provides controls to start, stop, and shut down the Mobicents Converged Application Server.
Deployable Units
This view can be selected by clicking on Deployable Units from the Main Menu, and shows a list of all deployable units that can be deployed with the Mobicents Converged Application Server.
A tab bar at the top of the view allows one to browse, search for, and install deployable units.
Components
The next view on the Main Menu is the Components view, which displays a list of component types, such as services, SBBs, resource adapters, etc., and their current count. Clicking on a component type will cause the management console to show a list of components for that type. From there, you can click on the different components to see their details.
Services
The Services view shows the list of available services, their state, whether ACTIVE or INACTIVE, and all currently possible actions for that resource adapter, such as activate, deactivate or remove.