Mobicents SLEE Container User Guide

Mobicents JAIN SLEE User Guide
by Alexandre Mendonça, Amit Bhayani, Bartosz Baranowski,

Douglas Silas, Eduardo Martins, Ivelin Ivanov, and Jared Morgan
Preface ............................................................................................................................. v
1. Document Conventions .......................................................................................... v
1.1. Typographic Conventions ............................................................................ v
1.2. Pull-quote Conventions .............................................................................. vii
1.3. Notes and Warnings .................................................................................. vii
2. Provide feedback to the authors! .......................................................................... viii
1. Introduction to Mobicents JAIN SLEE ......................................................................... 1
2. Installing Mobicents JAIN SLEE .................................................................................. 3
2.1. Pre-Install Requirements and Prerequisites .......................................................... 3
2.1.1. Hardware Requirements ........................................................................... 3
2.1.2. Software Prerequisites .............................................................................. 3
2.2. Install Alternatives ............................................................................................... 3
2.2.1. Binary Release ........................................................................................ 4
2.2.2. Binary Release Snapshot ......................................................................... 4
2.2.3. Release Source Building .......................................................................... 4
2.2.4. Trunk Source Building .............................................................................. 5
2.3. Uninstall Mobicents JAIN SLEE ........................................................................... 5
3. Configuring and Running Mobicents JAIN SLEE ......................................................... 7
3.1. Server Profiles .................................................................................................... 7
3.2. Running Mobicents JAIN SLEE ........................................................................... 7
3.2.1. Starting .................................................................................................... 7
3.2.2. Stopping .................................................................................................. 8
3.3. Configuring Mobicents JAIN SLEE ....................................................................... 8
3.3.1. Event Router Statistics and Configuration .................................................. 8
3.3.2. Timer Facility Configuration ..................................................................... 10
3.3.3. Configuring JAIN SLEE Profiles .............................................................. 11
3.3.4. Configuring JAIN SLEE Usage Params ................................................... 12
3.3.5. Other Configurations .............................................................................. 13
3.3.6. Logging Configuration ............................................................................. 14
3.3.7. Congestion Control Configuration ............................................................ 14
4. Managing Mobicents JAIN SLEE ............................................................................... 15
4.1. JAIN SLEE JMX Agent ..................................................................................... 15
4.2. SNMP Agent .................................................................................................... 15
4.3. Managing JAIN SLEE Components .................................................................... 15
4.3.1. Persistent Deployable Unit Management .................................................. 15
4.3.2. Ant Tasks .............................................................................................. 18
4.4. Management Consoles ...................................................................................... 23
4.4.1. JMX Console ......................................................................................... 23
4.4.2. Jopr Console ......................................................................................... 23
4.4.3. TWIDDLE CLI ........................................................................................ 24
5. Logging, Traces and Alarms ..................................................................................... 25
5.1. Log4j Logging Service ....................................................................................... 25
5.1.1. Simplified Global Log4j Configuration ...................................................... 26
5.2. Alarm Facility .................................................................................................... 27
iii
Mobicents JAIN SLEE User Guide
5.3. Trace Facility .................................................................................................... 27

5.3.1. JAIN SLEE Tracers and Log4j ................................................................ 28
6. High Availability abd Fault Tolerance ........................................................................ 31
6.1. Mobicents JAIN SLEE Cluster ........................................................................... 31
6.1.1. Managing Components in Mobicents JAIN SLEE Cluster .......................... 31
6.2. Fault Tolerant Resource Adaptor API ................................................................. 32
6.2.1. The Fault Tolerant Resource Adaptor Object ............................................ 32
6.2.2. The Fault Tolerant Resource Adaptor Context And Replicated Data
Sources ........................................................................................................... 33
6.3. Resource Adaptor Activity Replication ................................................................ 33
7. Firing Events from Java EE Applications .................................................................. 35
7.1. SLEE Connection Factory ................................................................................. 35
7.1.1. Local SLEE Connection Factory .............................................................. 35
7.1.2. Remote SLEE Connection Factory .......................................................... 35
7.1.3. Using SLEE Connection Factory ............................................................. 35
8. JAIN SLEE 1.1 Extensions ......................................................................................... 37
8.1. SbbContext Extension ....................................................................................... 37
8.2. ProfileContext Extension ................................................................................... 39
8.3. ActivityContextInterface Extension ...................................................................... 39
8.4. Library References Extension ............................................................................ 40
8.4.1. Extended Library Jar XML Descriptor DTD ............................................... 40
8.4.2. Extended Library Jar XML Descriptor Example ......................................... 46
9. Advanced Topics ....................................................................................................... 49
9.1. Class Loading ................................................................................................... 49
9.2. Congestion Control ........................................................................................... 50
9.2.1. Congestion Control Configuration ............................................................ 50
9.3. JAIN SLEE 1.1 Profiles JPA Mapping ................................................................ 52
9.3.1. Profile Specification JPA Tables And columns .......................................... 52
9.3.2. Profile Specification JPA Datasource ....................................................... 53
9.4. Testing the JAIN SLEE 1.1 TCK ........................................................................ 53
9.5. Setting JAIN SLEE Source Code Projects in Eclipse IDE ..................................... 54
A. Java Development Kit (JDK): Installing, Configuring and Running ................................... 55
B. Setting the JBOSS_HOME Environment Variable .......................................................... 59
C. Revision History .......................................................................................................... 63
Index ............................................................................................................................... 65
iv
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 [https://
fedorahosted.org/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 file my_next_bestselling_novel in your current

working directory, enter the cat my_next_bestselling_novel command 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 include filesystem for file systems, file for files, and dir
for 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:
v
Preface
Choose System > Preferences > Mouse from the main menu bar to launch
Mouse Preferences. In the Buttons tab, click the Left-handed mouse check
box and click Close 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 Applications >

Accessories > Character Map from the main menu bar. Next, choose Search
> Find from the Character Map menu bar, type the name of the character in the
Search field and click Next. 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 Copy button. Now switch back to your document
and choose Edit > Paste 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 Mouse from the Preferences sub-menu in the System menu
of the main menu bar' approach.
Mono-spaced Bold Italic or Proportional 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, type ssh [email protected]

at a shell prompt. If the remote machine is example.com and your username on
that machine is john, type ssh [email protected].
The mount -o remount file-system command remounts the named file

system. For example, to remount the /home file system, the command is mount
-o remount /home.
To see the version of a currently installed package, use the rpm -q package
command. It will return a result as follows: 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
vi
Pull-quote Conventions
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.
vii
Preface
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. Provide feedback to the authors!

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 the Issue Tracker [http://
code.google.com/p/mobicents/issues/list], against the product Mobicents JAIN SLEE, or contact
the authors.
When submitting a bug report, be sure to mention the manual's identifier:

JAIN_SLEE_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.
viii
Chapter 1.
Introduction to Mobicents JAIN

SLEE
JAIN SLEE is the specification for a Java Service Logic and Execution Environment (SLEE)
architecture, created in the Java Community Process (JCP) by several individuals and companies,
including Red Hat. A SLEE is an application server, or service container, which defines a
component model for structuring the logic of communications services as a collection of reusable
components, and for combining these components into even more sophisticated services. This
model was designed and optimized for event-driven applications.
In addition to the service component model, the SLEE also defines management interfaces used
to administer the container and the service components executing within, and a set of standard
facilities, which provide common features, such as timers, traces and alarms, to JAIN SLEE
components.
Mobicents JAIN SLEE is the first and only open source platform certified for JAIN SLEE 1.1
compliance, providing a highly scalable, event-driven application server with a robust component
model and a fault tolerant execution environment.
Figure 1.1. Overview of JAIN SLEE
Mobicents JAIN SLEE is built on top of the open source award winning JBoss Application Server,
which means that Mobicents JAIN SLEE complements JAIN SLEE with Java Enterprise (JEE) 5
1
Chapter 1. Introduction to Mo...
container features, allowing strong convergence of different application models, for even feature
richer communication services, for instance, the Web and SIP can be combined to achieve a more
sophisticated and natural user experience. Mobicents JAIN SLEE inherits quality management
features and tools from JBoss Application Server, such as the JMX Console, Jopr Plugins and
SNMP Adaptor.
Figure 1.2. Mobicents Platform
Mobicents JAIN SLEE can also be complemented with Mobicents SIP Servlets and Mobicents
Media Server, providing unique value and integration features not found elsewhere.
2
Chapter 2.
Installing Mobicents JAIN SLEE

2.1. Pre-Install Requirements and Prerequisites
Ensure that the following requirements have been met before continuing with the install.
2.1.1. Hardware Requirements
Sufficient Disk Space

Once unzipped, the JAIN SLEE binary release requires at least 300MB 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 container, and bundled JAIN SLEE components are 100% java.
The JAIN SLEE will run on the same hardware that the JBoss Application Server runs on, but
it is recommended at least 2GB or 4GB of RAM memory, for 32 or 64 bit Operating Systems.
2.1.2. Software Prerequisites
JDK 6
A working installation of the Java Development Kit (JDK) version 6 is required in order to run
the Mobicents JAIN SLEE. Note that the JBoss Application Server is a runtime dependency,
but comes bundled with the binary distribution.
For instructions on how to install the JDK, refer to Appendix A, Java Development Kit (JDK):
Installing, Configuring and Running.
2.2. Install Alternatives
Binary Release
The binary release is a zip file containing an already built binary release of Mobicents JAIN
SLEE
Release Source Building

As an alternative to the binary release, it is possible to download a specific release source
code and build a binary from it.
Trunk Source Building

Similar as the Release Source Building, but done on the trunk (current development) source
code.
Binary Release Snapshot

The binary release snapshot is a build of the trunk source code done daily and upoaded to
a public web site.
3
Chapter 2. Installing Mobicen...
2.2.1. Binary Release

You can download the Binary zip files from http://sourceforge.net/projects/mobicents/files/
Mobicents JAIN SLEE Server.
In this form of installation, simply unzip the downloaded zip file to the directory of your choice on
any operating system that supports the zip format.
1. Unzip the release file
Unzip the file to extract the archive contents into the location of your choice. You can do
this using the JDK jar tool (or any other ZIP extraction tool). In the example below we are
assuming you downloaded the zip file was named mobicents-jainslee-2.3.0.FINAL.zip to the /
mobicents directory.
[usr]$ cd /mobicents
[usr]$ jar -xvf mobicents-jainslee-2.3.0.FINAL.zip
2. Setting up JBOSS_HOME Environment Variable
You should now have a directory called mobicents-jainslee-2.3.0.FINAL. Next you need to
set your JBOSS_HOME environment variables. This is discussed in Appendix B, Setting the
JBOSS_HOME Environment Variable.
2.2.2. Binary Release Snapshot

You can download the Binary Snapshot zip files from http://hudson.jboss.org/hudson/view/
Mobicents/job/Mobicents-Slee-2.x-Release/. The installation is similar to the Section 2.2.1, “Binary
Release” one.
2.2.3. Release Source Building
1. Downloading the source code
Important
Subversion is used to manage its source code. Instructions for using
Suversion, including install, can be found at http://svnbook.red-bean.com
Use SVN to checkout the specific release source, the base URL is http://
mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/core/ , then add the specific
release version, lets consider 2.3.0.FINAL.
4
Trunk Source Building
[usr]$ svn co http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/

core/2.3.0.FINAL mobicents-slee-core-2.3.0.FINAL
2. Building the source code
Important
Apache Ant 1.6 (or higher) and Maven 2.0.9 (or higher) is used to build the
release. Instructions for using Ant and Maven2, including install, can be found
at http://ant.apache.org and http://maven.apache.org
Use Ant to build the binary.
[usr]$ cd mobicents-slee-core-2.3.0.FINAL/release
[usr]$ ant
Once the process finishes you should have a mobicents-jainslee-2.3.0.FINAL.zip file,

installation is the same as for Section 2.2.1, “Binary Release”.
2.2.4. Trunk Source Building

Similar process as for Section 2.2.3, “Release Source Building”, the only change is the SVN source
code URL, which is http://mobicents.googlecode.com/svn/trunk/servers/jain-slee.
2.3. Uninstall Mobicents JAIN SLEE

To uninstall simply delete the directory containing Mobicents JAIN SLEE.
5
6
Chapter 3.
Configuring and Running Mobicents

JAIN SLEE
3.1. Server Profiles
Mobicents JAIN SLEE reuses JBoss Application Server server profiles to expose different
configurations for different needs:
Default Profile
The default profile is proper for standalone or pure high availability. It provides the best
performance per cluster node, with linear scaling, but there is no state replication in the cluster,
which means that there is no support for failover, neither there is any kind of state gravitation
(one node sending state so another node continues its work.
All Profile
The all profile is proper for more flexible high availability and failover support. Performance
per node decreases but the cluster does state replication or gravitation.
Profiles can be selected when starting the server, see Section 3.2, “Running Mobicents JAIN
SLEE” for detailed instructions.
3.2. Running Mobicents JAIN SLEE

Starting or stopping Mobicents JAIN SLEE is no different than starting or stopping JBoss
Application Server
3.2.1. Starting
Once installed, you can run server(s) by executing the run.sh (Unix) or run.bat (Microsoft Windows)
startup scripts in the <install_directory>/bin directory (on Unix or Windows).
3.2.1.1. Starting Parameters
Server Profile
To specify the server profile use -c profile_name, for instance, to use the all profile then
start the server with -c all
Important
If not specified the default profile is used.
7
Chapter 3. Configuring and Ru...
IP / Host
To specify the IP/Host which the server binds, use -b IP, for instance, to use the 192.168.0.1
IP then start the server with -b 192.168.0.1
Important
If not specified then 127.0.0.1 is used.
3.2.2. Stopping
You can shut down the server(s) you can run server(s) by executing the shutdown.sh -s (Unix)
or shutdown.bat -s (Microsoft Windows) scripts in the <install_directory>/bin directory (on
Unix or Windows). Note that if you properly stop the server, you will see the following three lines
as the last output in the Unix terminal or Command Prompt:
[Server] Shutdown complete

Shutdown complete
Halting VM
3.3. Configuring Mobicents JAIN SLEE

JAIN SLEE is configured through an XML descriptor for each Section 3.1, “Server Profiles”. The
XML file is named jboss-beans.xml and is located at $JBOSS_HOME/server/profile_name/
deploy/mobicents-slee/META-INF, where profile_name is the server profile name.
Warning
This configuration greatly affects performance or correctness of the container

behavior. This is for advanced users that know the internals of the container.
3.3.1. Event Router Statistics and Configuration

The JAIN SLEE Event Router is the module responsible for creating new service instances and
delivering events to all interested parties. It is capable of doing the routing of several events in
parallel, through the usage of multiple executors, each bound to a different thread.
The Event Router is also able to account performance and load statistics, indicating the number of
activities being assigned or several timings regarding event routing, globally or for each individual
executor/thread. Statistics are turned on by default and may be retrieved through the JMX MBean
org.mobicents.slee:name=EventRouterStatistics.
An important sub-module of the Event Router is the Executor Mapper, which is responsible
for assigning activities to the available executors. JAIN SLEE includes two different Executor
8
Event Router Statistics and Configuration
Mappers. The default one takes into account the hashcode of the activity handle when distributing,
while the alternative uses a round robin algorithm.
Note
In the case of advanced performance tuning, it is advised to try the different

implementations available, or even provide a custom one.
The Executor Mapper is nothing more than an interface:

org.mobicents.slee.container.eventrouter.EventRouterExecutorMapper. To deploy a
custom implementation, drop the implementation class or classes, packed in a jar file, in the server
profile /deploy directory.
The whole Event Router is a critical component with respect to the container's performance. Its
configuration can be tuned, through an XML file and a JMX MBean.
3.3.1.1. Event Router Persistent Configuration
Configuration is done through an XML descriptor for each Section 3.1, “Server Profiles”. The XML
file is named jboss-beans.xml and is located at $JBOSS_HOME/server/profile_name/deploy/
mobicents-slee/META-INF, where profile_name is the server profile name.
The configuration is exposed a JBoss Microcontainer Bean:
<bean name="Mobicents.JAINSLEE.EventRouterConfiguration"
class="org.mobicents.slee.container.management.jmx.EventRouterConfiguration">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name=
"org.mobicents.slee:name=EventRouterConfiguration", exposedInterface=
org.mobicents.slee.container.management.jmx.EventRouterConfigurationMBean.class,
registerDirectly=true)</annotation>
<property name="eventRouterThreads">8</property>
<property name="collectStats">true</property>
<property name="executorMapperClassName">
org.mobicents.slee.runtime.eventrouter.mapping.ActivityHashingEventRouterExecutorMapper
</property>
</bean>
9
Table 3.1. JAIN SLEE Event Router Bean Configuration
Property Name Property Type Description

eventRouterThreads int defines how many executors
should be used by the Event
Router, each bounds to a
different thread
collectStats boolean defines if performance and
load statistics should be
collected, turning this feature
off will increase performance
executorMapperClassName Class This property defines the
implementation class of
Executor Mapper used by the
Event Router, the one above
and default uses the activity
handle hashcode to do the
mapping, an alternative is
org.mobicents.slee.runtime.eventrouter.map
which uses Round Robin
algorithm.
3.3.1.2. Event Router JMX Configuration
Through JMX, the Event Router module configuration can be changed while the container is
running. These configuration changes are not persisted.
The JMX MBean that can be used to change the Event Router configuration is named
org.mobicents.slee:name=EventRouterConfiguration, and provides getters and setters to
change each property defined in the persistent configuration. See Section 4.4.1, “JMX Console”
for how the JMX Console can be used to use this MBean.
3.3.2. Timer Facility Configuration

The JAIN SLEE Timer Facility is the module responsible for managing SLEE timers, and the
number of threads it uses is configurable.
The Timer Facility configuration can be changed through an XML file and a JMX MBean.
3.3.2.1. Timer Facility Persistent Configuration
Configuration is done through an XML descriptor for each Mobicents Cluster. The XML file is
named jboss-beans.xml and is located at {JBOSS_HOME}/server/{profile_name}/deploy/
mobicents-slee/META-INF
10
Configuring JAIN SLEE Profiles
<bean name="Mobicents.JAINSLEE.TimerFacilityConfiguration"
class="org.mobicents.slee.container.management.jmx.TimerFacilityConfiguration">
"org.mobicents.slee:name=TimerFacilityConfiguration",exposedInterface=
org.mobicents.slee.container.management.jmx.TimerFacilityConfigurationMBean.class,
<property name="timerThreads">4</property>
</bean>
Table 3.2. JAIN SLEE Timer Facility Bean Configuration

timerThreads int defines how many threads
should be used by the Timer
Facility
3.3.2.2. Timer Facility JMX Configuration

Through JMX the Timer Facility module configuration can be changed with the container running.
Note that such configuration changes are not persisted.
The JMX MBean which can be used to change the Timer Facility configuration is named
org.mobicents.slee:name=TimerFacilityConfiguration, and provides getters and setters to
change each property defined in the persistent configuration. The JMX Console can be used to
use this MBean, see Section 4.4.1, “JMX Console”.
3.3.3. Configuring JAIN SLEE Profiles

JAIN SLEE Profiles is a component used to store data, usually related with a user and/or service
profile. JAIN SLEE maps JAIN SLEE Profiles to a Java Persistence API (JPA) Datasource, through
Hibernate.
There are two configurations for JAIN SLEE Profiles provided as JBoss Microcontainer Beans:
<bean name="Mobicents.JAINSLEE.Profiles.JPA.HSQLDBConfig"
class="org.mobicents.slee.container.deployment.profile.jpa.Configuration">
<property name="persistProfiles">true</property>
<property name="clusteredProfiles">false</property>
<property name="hibernateDatasource">java:/DefaultDS</property>
<property name="hibernateDialect">org.hibernate.dialect.HSQLDialect</property>
<depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
11
</bean>
<bean name="Mobicents.JAINSLEE.Profiles.JPA.PostgreSQLConfig"
class="org.mobicents.slee.container.deployment.profile.jpa.Configuration">
<property name="persistProfiles">true</property>
<property name="clusteredProfiles">true</property>
<property name="hibernateDatasource">java:/PostgresDS</property>
<property name="hibernateDialect">org.hibernate.dialect.PostgreSQLDialect</property>
</bean>
Important
Configurations can be changed, or new ones can be added. For new ones, ensure
that the name attribute of the bean element is unique.
Table 3.3. JAIN SLEE Profiles Bean Configuration

persistProfiles boolean If true, profile changes are
persisted into the data source.
clusteredProfiles boolean If true, then the container is
aware there is a shared data
source and that updates may
be done by other nodes (for
example, deletion of a JAIN
SLEE profile table).
hibernateDatasource String The name of the Java
Datasource deployed in the
JBoss Application Server.
hibernateDialect String The java class name of
the hibernate dialect to use,
related with the selected
datasource.
To switch the active configuration simply change the parameter injected in the bean named
Mobicents.JAINSLEE.Container.
3.3.4. Configuring JAIN SLEE Usage Params

JAIN SLEE Usage Params are usage statistics of several JAIN SLEE concepts, such as the SBB,
Service, Resource Adaptor or Profile Table. Configuration for JAIN SLEE Usage Params is done
through a JBoss Microcontainer Bean:
12
Other Configurations
<bean name="Mobicents.JAINSLEE.UsageMbeans.Config"
class="org.mobicents.slee.runtime.usage.UsageMBeansConfiguration">
<property name="clusteredUsageMBeans">false</property>
</bean>
There is a single property to configure, named clusteredUsageMBeans, with a boolean value. Set
this property to true if the usage param values should be shared by all cluster nodes. This option
means a significant performance penalty, but makes it possible to learn the current values for the
whole cluster by checking a single node. Use this only if there is no other solution, such as a
management client, that gets the value of each node and then does the appropriate calculations.
3.3.5. Other Configurations

Other JAIN SLEE runtime configuration is done through the following JBoss Microcontainer Bean:
<bean name="Mobicents.JAINSLEE.MobicentsManagement"
class="org.mobicents.slee.container.management.jmx.MobicentsManagement">
<annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(
name="org.mobicents.slee:service=MobicentsManagement",
exposedInterface=org.mobicents.slee.container.management.
jmx.MobicentsManagementMBean.class,
<property name="entitiesRemovalDelay">1</property>
<property name="timerThreads">8</property>
<property name="loadClassesFirstFromAS">true</property>
</bean>
Table 3.4. Other JAIN SLEE Configurations

entitiesRemovalDelay int The number of minutes before
the container forces the
ending of SBB entities from a
service being deactivated.
timerThreads int The number of threads used
by the timer facility.
loadClassesFirstFromAS boolean If true, a classloader
always looks for classes
13

first in the container's own
classloader, which shares and
imports classes from JBoss
Application Server.
This configuration can be changed with the container running with JMX. Note that such
configuration changes are not persisted.
To change the configuraton, use the JMX MBean named

org.mobicents.slee:service=MobicentsManagement, which provides getters and setters to
change each property defined in the persistent configuration that is configurable with the container
running. The JMX Console can be used to use this MBean, as described in Section 4.4.1, “JMX
Console”.
3.3.6. Logging Configuration

Logging configuration is documented in section Section 5.1.1, “Simplified Global Log4j
Configuration”
3.3.7. Congestion Control Configuration

Congesture Control feature configuration is documented in section Section 9.2.1, “Congestion
Control Configuration”
14
Chapter 4.
Managing Mobicents JAIN SLEE

4.1. JAIN SLEE JMX Agent
The JMX Agent exposes all MBeans running in the server, including the ones mandated by the
JAIN SLEE 1.1 specification.
Important
The operations done through the JMX Agent are not kept once the server is
shutdown. For instance, if a deployable unit is installed through JMX, and the
server is shutdown, once the server is started again the deployable unit will not
be installed.
Important
By default, the JMX Agent listens to port 1099, and is only available at the host/
ip which the server is bound.
4.2. SNMP Agent

JBoss Application Server provides an SNMP Agent, which can be used to ...
Important
TODO
4.3. Managing JAIN SLEE Components
4.3.1. Persistent Deployable Unit Management

JAIN SLEE provides a file deployer that greatly simplifies the management of JAIN SLEE
deployable unit jars. The deployer:
• Handles the installation of enclosed JAIN SLEE components.
• Automatically activates and deactivates services contained.
• Handles the creation, removal, activation, deactivation, link binding and link unbinding of all
Resource Adapter Entities.
15
Chapter 4. Managing Mobicents...
All operations are persistent, which means that unlike management done through JMX, these
survive server shutdowns.
4.3.1.1. Persistent Deployable Unit Install

To install a deployable unit jar simply copy the file to $JBOSS_HOME/server/profile_name/
deploy/, where profile_name is the server profile name. Child directories can be used.
4.3.1.2. Persistent Deployable Unit Uninstall

To uninstall a deployable unit jar simply delete the file.
4.3.1.3. Beyond Deployable Unit (Un)Install

The file deployer provides additional behavior then simply (un)install deployable unit jars, as done
through the JAIN SLEE 1.1 DeploymentMBean:
Service (De)Activation
All services contained in the deployable unit jar are activated after the install, and deactivated
prior to uninstall, or server shutdown.
Dependencies Management
The deployer puts the installation process on hold until all of the component's dependencies
are installed and activated. When uninstalling, it waits for all of the components which depend
on components inside the deployable unit to be uninstalled. After an install or uninstall, the
deployer evaluates all operations on hold.
4.3.1.4. Deploy-Config Extension

A deployable unit jar may include a deploy-config.xml file in its META-INF/ directory. This file
provides additional management actions for persistent install/uninstall operations:
Resource Adaptor Entity Management

It is possible to specify RA entities, and the container will create and activate the RA entities
after the deployable unit is installed. During the uninstall process, the container will deactivate
and remove those RA entities.
Resource Adaptor Links Management

It is possible to specify RA links, and the container will bind those after the deployable unit is
installed. When uninstalled, the container will unbind those RA links as well. The links are set
for resource adapter entities created in the deploy-config.xml file.
This file should comply with the following schema:
<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
16
Persistent Deployable Unit Management
<xs:element name="deploy-config">
<xs:complexType>
<xs:sequence>
<xs:element ref="ra-entity" maxOccurs="unbounded" minOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="property">
<xs:complexType>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="type" type="xs:string" use="required" />
<xs:attribute name="value" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:element name="properties">
<xs:complexType>
<xs:sequence>
<xs:element ref="property" maxOccurs="unbounded" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="file" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
<xs:element name="ra-entity">
<xs:complexType>
<xs:sequence>
<xs:element ref="properties" maxOccurs="1" minOccurs="0"/>
<xs:element ref="ra-link" maxOccurs="unbounded" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="resource-adaptor-id" type="xs:string" use="required" />
<xs:attribute name="entity-name" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
<xs:element name="ra-link">
<xs:complexType>
<xs:attribute name="name" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
</xs:schema>
17
<ra-entity
resource-adaptor-
id="ResourceAdaptorID[name=JainSipResourceAdaptor,vendor=net.java.slee.sip,version=1.2]"
entity-name="SipRA">
<properties>
<property name="javax.sip.PORT" type="java.lang.Integer" value="5060" />
</properties>
<ra-link name="SipRA" />
</ra-entity>
The deploy-config.xml example above defines a resource adaptor entity named SipRa, to be
created for the resource adaptor with id ResourceAdaptorID[name=JainSipResourceAdaptor,
vendor=net.java.slee.sip, version=1.2], and with a single config property named
javax.sip.PORT of type java.lang.Integer and with value 5060. Additionally, a resource
adaptor link named SipRa should be bound to the resource adaptor entity.
After the deployable unit is installed, the resource adaptor entity is created, activated and the
resource adaptor link is bound. Before the deployable unit is uninstalled, or the server is shutdown,
the link is unbound, then the resource adaptor entity is deactivated, and finally the same resource
adaptor entity is removed.
4.3.2. Ant Tasks
JAIN SLEE includes some tasks for Apache Ant, which can be used for common management
tasks done through JMX, when the container is running. The tasks come bundled in $JBOSS_HOME/
server/default/deploy/mobicents-slee/lib/ant-tasks.jar. To use these, the Ant script
must include the following code:
<property environment="system" />

<property name="node" value="default" />
<property name="jboss.deploy" value="${system.JBOSS_HOME}/server/default/deploy" />
<path id="project.classpath">
<fileset dir="${jboss.deploy}/mobicents-slee/lib">
<include name="*.jar" />
</fileset>
<fileset dir="${system.JBOSS_HOME}/client">
18
Ant Tasks
<include name="*.jar" />

</fileset>
</path>
<property name="project.classpath" refid="project.classpath" />
<property name="jnpHost" value="127.0.0.1" />

<property name="jnpPort" value="1099" />
<taskdef name="slee-management"
classname="org.mobicents.ant.MobicentsManagementAntTask"
classpath="${project.classpath}" />
It is important to understand some properties set by the code above:
node
This property defines the server configuration profile to be used, for further information about
those refer to Section 3.1, “Server Profiles”.
jnpHost
The host/ip which Mobicents JAIN SLEE is bound.
jnpPort
The port which the JMX Agent is listening.
Important
The property values can be overridden when invoking the Ant script. To do this, use
the parameter -DpropertyName=propertyValue. For example, the server profile
can be changed from default to all using -Dnode=all.
4.3.2.1. SLEE Management Task
The slee-management task allows a script to manage JAIN SLEE deployable units, services and
resource adapters. The operations, or sub-tasks, are done through JMX.
<slee-management jnpport="${jnpPort}" host="${jnpHost}">


</slee-management>
19
The attributes have the same meaning as the properties Section 4.3.2, “Ant Tasks” in the script
code to import the tasks.
4.3.2.1.1. Install Deployable Unit Sub-Task
The install sub-task installs JAIN SLEE the deployable unit jar pointed by the value of attribute
url. Example of usage:

<install url="file:///tmp/my-deployable-unit.jar" />
</slee-management>
4.3.2.1.2. Uninstall Deployable Unit Sub-Task
The uninstall sub-task uninstalls JAIN SLEE the deployable unit jar which was installed from
the value of attribute url. Example of usage:

<uninstall url="file:///tmp/my-deployable-unit.jar" />
</slee-management>
4.3.2.1.3. Activate Service Sub-Task
The activateservice sub-task activates an already installed JAIN SLEE service, with the id
specified by the value of attribute componentid. Example of usage:
<slee-management host="${jnpHost}" jnpport="${jnpPort}">

<activateservice
componentid="ServiceID[name=FooService,vendor=org.mobicents,version=1.0]" />
</slee-management>
4.3.2.1.4. Deactivate Service Sub-Task
The deactivateservice sub-task deactivates an already installed JAIN SLEE service, with the
id specified by the value of attribute componentid. Example of usage:
20
Ant Tasks

<deactivateservice
componentid="ServiceID[name=FooService,vendor=org.mobicents,version=1.0]" />
</slee-management>
4.3.2.1.5. Create Resource Adaptor Entity Sub-Task
The createraentity sub-task creates the resource adaptor entity with the name specified by the
value of attribute entityname, for an already installed JAIN SLEE resource adaptor, with the id
specified by the value of attribute componentid. Example of usage:

<createraentity
componentid="ResourceAdaptorID[name=FooRA,vendor=org.mobicents,version=1.0]"
entityname="FooRA" />
</slee-management>
4.3.2.1.6. Remove Resource Adaptor Entity Sub-Task
The removeraentity sub-task removes the resource adaptor entity with the name specified by
the value of attribute entityname. Example of usage:

<removeraentity entityname="FooRA" />
</slee-management>
4.3.2.1.7. Activate Resource Adaptor Entity Sub-Task
The activateraentity sub-task activates the resource adaptor entity with the name specified
by the value of attribute entityname. Example of usage:

<activateraentity entityname="FooRA" />
21
</slee-management>
4.3.2.1.8. Deactivate Resource Adaptor Entity Sub-Task
The deactivateraentity sub-task deactivates the resource adaptor entity with the name
specified by the value of attribute entityname. Example of usage:

<deactivateraentity entityname="FooRA" />
</slee-management>
4.3.2.1.9. Bind Resource Adaptor Link Sub-Task
The bindralinkname sub-task binds the resource adaptor link with the name specified by the
value of attribute linkname, for an already active JAIN SLEE resource adaptor entity, with the
name specified by the value of attribute entityname. Example of usage:

<bindralinkname entityname="FooRA"
linkname="FooRA" />
</slee-management>
4.3.2.1.10. Unbind Resource Adaptor Link Sub-Task
The unbindralinkname sub-task unbinds the resource adaptor link with the name specified by
the value of attribute linkname. Example of usage:

<unbindralinkname linkname="FooRA" />
</slee-management>
22
Management Consoles
4.4. Management Consoles
4.4.1. JMX Console

JBoss Application Server provides a simple web console that gives quick access to all MBeans
registered in the server, which includes the ones defined by the JAIN SLEE 1.1 specification.
To access the JMX console once the server is running, point a web browser to http://ip:8080/
jmx-console, where ip is the IP/Host the container is bound. Unless set during start up, the IP/
Host will be 127.0.0.1/localhost by default.
MBeans in the domain javax.slee are all standard JAIN SLEE 1.1 MBeans, while the ones in
the domain org.mobicents.slee are proprietary to Mobicents JAIN SLEE. The following ones
are of particular interest:
org.mobicents.slee:service=MobicentsManagement
the MBean which can be used to make non persistent changes to the server configuration, in
runtime. The operation dumpContainerState displays a textual snapshot of the server's state,
which can be used to quickly look for memory leaks or other debug/profiling related tasks.
org.mobicents.slee:name=DeployerMBean
the MBean allows interaction with the persistent deployable unit deployer. The operation
showStatus displays a textual snapshot of the deployers's state, which can be used to quickly
find out if there is any deployable unit deployment pending, for instance, due to missing
dependencies.
org.mobicents.slee:name=CongestionControlConfiguration
the MBean allows changing or retrieving the Congestion Control feature, with the container
running. Details are provided in section Section 9.2.1, “Congestion Control Configuration”.
Important
For further information about JAIN SLEE 1.1 MBeans and their operations refer to
the JAIN SLEE 1.1 Specification, all are covered with great detail.
4.4.2. Jopr Console

The JMX Console is simple but the MBeans operations were made considering its invocation
by management clients, not people using browsers. Jopr was developed to become Red Hat's
Middleware Administration Tool, providing an unified interface and extensible model, to be used
to control, monitor and manage servers individually, and clusters.
Mobicents JAIN SLEE binary release includes a Jopr Console in tools/management-console,

with standalone documentation.
23
4.4.3. TWIDDLE CLI

Both, JMX Console and Jopr Console, are graphic(web) based tools. Some deployments may
require command line access to Mobicents SLEE. To aid such cases, Mobicents offers TWIDDLE
based CLI. It allows to manage single instance (remote or local) of Mobicents SLEE server.
Mobicents JAIN SLEE binary release includes a TWIDDLE CLI in tools/twiddle, with standalone
documentation.
24
Chapter 5.
Logging, Traces and Alarms

5.1. Log4j Logging Service
In Mobicents JAIN SLEE Apache log4j is used for logging. If you are not familiar with the log4j
package and would like to use it in your applications, you can read more about it at the Jakarta
web site [http://jakarta.apache.org/log4j/].
Logging is controlled from a central conf/jboss-log4j.xml file, in each server configuration

profile. This file defines a set of appenders specifying the log files, what categories of messages
should go there, the message format and the level of filtering. By default, in Mobicents produces
output to both the console and a log file (log/server.log).
There are 6 basic log levels used: TRACE, DEBUG, INFO, WARN, ERROR and FATAL.
Logging is organized in categories and appenders. Appenders control destination of log entries.
Different appenders differ in configuration, however each supports threshold. Threshold filters log
entries based on their level. Threshold set to WARN will allow log entry to pass into appender if its
level is WARN, ERROR or FATAL, other entries will be discarded. For more details on appender
configuration please refer to its documentation or java doc.
The logging threshold on the console is INFO, by default. In contrast, there is no threshold set for
the server.log file, so all generated logging messages are logged there.
Categories control level for loggers and its children, for details please refer to log4j manual.
By default Mobicents JAIN SLEE inherits level of INFO from root logger. To make platform add
more detailed logs, file conf/jboss-log4j.xml has to be altered. Explicit category definition for
Mobicents JAIN SLEE looks like:
<category name="org.mobicents.slee">
<priority value="INFO"/>
</category>
This limits the level of logging to INFO for all Mobicents JAIN SLEE classes. It is possible to
declare more categories with different level, to provide logs with greater detail.
For instance, to provide detailed information on Mobicents JAIN SLEE transaction engine in
separate log file(txmanager.log), file conf/jboss-log4j.xml should contain entries as follows:
<appender name="TXMANAGER" class="org.jboss.logging.appender.RollingFileAppender">
25
Chapter 5. Logging, Traces an...
<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
<param name="File" value="${jboss.server.home.dir}/log/txmanager.log"/>
<param name="Append" value="false"/>
<param name="MaxFileSize" value="500KB"/>
<param name="MaxBackupIndex" value="1"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
</layout>
</appender>
<category name="org.mobicents.slee.runtime.transaction">
<priority value="DEBUG" />
<appender-ref ref="TXMANAGER"/>
</category>
This creates a new file appender and specifies that it should be used by the logger (or category)
for the package org.mobicents.slee.runtime.transaction.
The file appender is set up to produce a new log file every day rather than producing a new
one every time you restart the server or writing to a single file indefinitely. The current log file is
txmanager.log. Older files have the date they were written added to their filenames.
5.1.1. Simplified Global Log4j Configuration

Besides manual logging configuration, described previously, Mobicents JAIN SLEE also exposes
management operations that greatly simplify such configuration, allowing the administrator to
select through predefined and complete logging configuration presets. Such operations are
available in MBean named org.mobicents.slee%3Aservice%3DMobicentsManagement, and the
available presets are:
Level
• DEFAULT: Regular logging, at INFO level, displaying most user-related messages;
• DEBUG: More verbose logging, mostly using DEBUG/TRACE level, displaying message
of interest for developers;
• PRODUCTION: Low verbosity and async logging, mostly in WARN level, for systems in
production so that logging does impact performance.
The available management operations are:
JMX Operation
• getLoggingConfiguration: retrieves what is the current logging configuration;
26
Alarm Facility
• switchLoggingConfiguration: allows switching to a different configuration preset;
• setLoggingConfiguration: used to upload a complete logging configuration.
Custom presets can be easily deployed in the application server too. Simply name the
configuration file as jboss-log4j.xml.PRESET_NAME, where PRESET_NAME should be unique
preset name, and copy it to directory $JBOSS_HOME/server/profile_name/deploy/mobicents-
slee/log4j-templates, where profile_name is the server profile name.
Note
These procedures changes the whole JBoss Application Server Platform logging
configuration, so it will affect also logging for other running applications besides
the JAIN SLEE container.
5.2. Alarm Facility

The JAIN SLEE Alarm Facility is used by SBBs, Resource Adaptors, and Profiles to request the
SLEE to raise or clear alarms. If a request is made to raise an alarm and the identified alarm has
not already been raised, the alarm is raised and a corresponding alarm notification is generated by
the AlarmMBean. If a request is made to clear an alarm and the identified alarm is currently raised,
the alarm is cleared and a corresponding alarm notification is generated by the AlarmMBean.
Alarm notifications are intended for consumption by management clients external to the SLEE.
The management client is responsible for registering to receive alarm notifications generated
by the Alarm Facility through the external management interface of the Alarm Facility. The
management client may optionally provide notification filters so that only the alarm notifications
that the management client would like to receive are transmitted to the management client.
For further information on how to use JAIN SLEE Alarm Facility and receive JMX notifications
refer to the JAIN SLEE 1.1 Specification.
5.3. Trace Facility

Notification sources such as SBBs, Resource Adaptors, Profiles, and SLEE internal components
can use the Trace Facility to generate trace messages intended for consumption by external
management clients. Management clients register to receive trace messages generated by the
Trace Facility through the external management interface (MBean). Filters can be applied, in
a similar way as in case of Alarms.
Within the SLEE, notification sources use a tracer to emit trace messages. A tracer is a named
entity. Tracer names are case-sensitive and follow the Java hierarchical naming conventions. A
tracer is considered to be an ancestor of another tracer if its name followed by a dot is a prefix
of the descendant tracer’s name. A tracer is considered to be a parent of a tracer if there are no
ancestors between itself and the descendant tracer. For example, the tracer named com is the
parent tracer of the tracer named com.foo and an ancestor of the tracer named com.foo.bar.
27
Chapter 5. Logging, Traces an...
All tracers are implicitly associated with a notification source, which identifies the object in the
SLEE that is emitting the trace message and is included in trace notifications generated by the
Trace MBean on behalf of the tracer. For instance, an SBB notification source is composed by
the SBB id and the Service id.
Important
Multiple notification sources may have tracers with same name in SLEE.
Comparing with common logging frameworks, this would mean that the notification
source would be part of the log category or name.
For further information on how to use JAIN SLEE Trace Facility and receive JMX notifications
refer to the JAIN SLEE 1.1 Specification.
5.3.1. JAIN SLEE Tracers and Log4j
Mobicents JAIN SLEE Tracers additionally log messages to Apache Log4j, being the log4j
category, for notification source X, defined as javax.slee. concatenated with the X.toString().
For instance, the full log4j logger name for tracer named GoogleTalkBotSbb, of sbb
notification source with SbbID[name=GoogleTalkBotSbb,vendor=mobicents,version=1.0]
and ServiceID[name=GoogleTalkBotService,vendor=mobicents,version=1.0], would be
javax.slee.SbbNotification[service=ServiceID[name=GoogleTalkBotService,
vendor=mobicents,version=0.1],
sbb=SbbID[name=GoogleTalkBotSbb,vendor=mobicents,
version=0.1]].GoogleTalkBotSbb (without the spaces or breaks), which means a log4j
category defining its level as DEBUG could be:
<category
name="javax.slee.SbbNotification[service=ServiceID[name=GoogleTalkBotService,
vendor=mobicents,version=0.1],sbb=SbbID[name=GoogleTalkBotSbb,
vendor=mobicents,version=0.1]]">
<priority value="DEBUG" />
</category>
The relation of JAIN SLEE tracers and log4j loggers goes beyond log4j showing tracer's
messages, changing the tracer's log4j logger effective level changes the tracer level in SLEE,
and vice-versa. Since JAIN SLEE tracer levels differ from log4j logger levels a mapping is needed:
28
JAIN SLEE Tracers and Log4j
Table 5.1. Mapping JAIN SLEE Tracer Levels with Apache Log4j Logger
Levels
Tracer Level Logger Level

OFF OFF
SEVERE ERROR
WARNING WARN
INFO INFO
CONFIG INFO
FINE DEBUG
FINER DEBUG
FINEST TRACE
29
30
Chapter 6.
High Availability abd Fault Tolerance

JAIN SLEE supports clustering, whether it is simple high availability or complete fault tolerance
support. This is achieved through the replication of the container state. It also exposes a clustering
API for JAIN SLEE Resource Adaptors components, which live outside the container.
6.1. Mobicents JAIN SLEE Cluster

JAIN SLEE clustering is defined by the server profile selected:
default
This configuration provides no state replication. It is best used for pure high availability cluster
setups.
all
This configuration provides state replication, and is useful for fault tolerance cluster setups.
All activity context and SBB entity data is replicated across the cluster.
Timers are failed over. All timers running in a node that leaves the cluster, or fails, are
recreated in another node.
Events are not failed over due to performance restraints. This means that an event fired will
be lost if its cluster node fails before it is routed.
Important
JAIN SLEE reuses the JBoss Application Server clustering framework, and if all
nodes of a cluster are in the same network then the underlying JBoss Application
Server clustering will automatically handle the discovery of new cluster nodes
and join these to the cluster. For more complicated setups, refer to the JBoss
Application Server clustering documentation.
6.1.1. Managing Components in Mobicents JAIN SLEE Cluster

JAIN SLEE clustering does not require special components management. Components can be
deployed and undeployed in all cluster modes, including fault tolerance setups, and the cluster
will handle the operation correctly. However, there are certain behaviours in fault tolerance setups
to be aware of:
Service Activation
JAIN SLEE Service started events are only fired on the first cluster node started.
Service Deactivation
Only the last node will force the removal of the service's SBB entities.
31
Chapter 6. High Availability ...
Resource Adaptor Entity Deactivation

Only the last node will force the removal of all its activities.
6.2. Fault Tolerant Resource Adaptor API

JAIN SLEE Resource Adaptors exist on the boundary between the container
and the underlying protocol. The specification contract requires the RA object to
implement the javax.slee.resource.ResourceAdaptor interface. This interface defines
callbacks, which SLEE uses to interact with the RA, including one to provide the
javax.slee.resource.ResourceAdaptorContext object. The Resource Adaptor Context
provides RA object facilities to interact with SLEE.
The JAIN SLEE 1.1 RA API is a major milestone, standardizing RA and JSLEE contract.
Unfortunately it is not enough, it misses an API for clustering, and that is critical for a RA working
with a clustered JAIN SLEE. Contarct does not define any fault tolerant data source nor callbacks
to inform on cluster state.
The Fault Tolerant RA API extends the JAIN SLEE 1.1 RA API, providing missing features related
to clustering, and it does it in a very familiar way, anyone who develops a JAIN SLEE 1.1 RA
easily uses our proprietary API.
6.2.1. The Fault Tolerant Resource Adaptor Object

The core of the Fault Tolerant RA isAPI the
org.mobicents.slee.resource.cluster.FaultTolerantResourceAdaptor interface. It is
intended to be used instead of the javax.slee.resource.ResourceAdaptor interface from the
JAIN SLEE 1.1 Specification.
The FaultTolerant interface provides three new callback methods used by the container:
setFaultTolerantResourceAdaptorContext(FaultTolerantResourceAdaptorContext
context)
This method provides the RA with the
org.mobicents.slee.resource.cluster.FaultTolerantResourceAdaptorContext
object, which gives access to facilities related with the cluster. This method is invoked by SLEE
right after invoking setResourceAdaptorContext( ResourceAdaptorContext context)
from JAIN SLEE 1.1 specs.
unsetFaultTolerantResourceAdaptorContext()
This method indicates that the RA should remove any references it has to the
FaultTolerantResourceAdaptorContext, as it is not valid anymore. The method is invoked by
SLEE before invoking unsetResourceAdaptorContext() from JAIN SLEE 1.1 specs.
failOver(K key)
Callback from SLEE when the local RA was selected to recover the state for a replicated data
key, which was owned by a cluster member that failed. The RA may then restore any runtime
resources associated with such data.
32
The Fault Tolerant Resource Adaptor Context And Replicated Data Sources
dataRemoved(K key)
Optional callback from SLEE when the replicated data key was removed from the cluster, this
may be helpful when the local RA maintains local state.
6.2.2. The Fault Tolerant Resource Adaptor Context And

Replicated Data Sources
Cluster RA context follows the contract of JAIN SLEE 1.1 specification interface
javax.slee.resource.ResourceAdaptorContext. It gives access to facilities for RA to run in
clustered environment.
The cluster contract is defined in:

org.mobicents.slee.resource.cluster.FaultTolerantResourceAdaptorContext. It
provides critical information, such as if SLEE is running in local mode (not clustered), if it is the
head/master member of the cluster, and what the members of the cluster are.
It also provides two data sources to replicate data in cluster:
ReplicatedData
A container for serializable data, which is replicated in the SLEE cluster, but don't require any
failover.
ReplicatedDataWithFailover
A ReplicatedData which requires fail over callbacks, this means, that for all data stored
here, when a cluster member goes down, the SLEE in another cluster member will invoke the
failOver(Key k) callback in the Fault Tolerant RA object.
When retrieved from the context through a boolean parameter, both types of ReplicatedData
can activate the callback on the FaultTolerantResourceAdaptor which indicates that a specific
data was removed from the cluster remotely.
6.3. Resource Adaptor Activity Replication

The Resource Adaptor API includes an optional component named
javax.slee.resource.Marshaler, which is responsible, besides other functions, for converting
Activity Handles to byte arrays and vice-versa. Also relevant, the Resource Adaptor, when starting
activities, may provide a flag indicating that the container may marshall the activity (using the
Marshaler). In case of a container cluster with data replication, if an activity is to be replicated then
the Marshaler must be provided and the activity flags must activate the flag MAY_MARSHALL,
otherwise the activity is not replicated and if a node fails all its activities are removed from the
container cluster.
Note
The activity replication doesn't mean that the activity object is replicated by any
means, only the related Activity Handle. The Resource Adaptor must use the Fault
33
Chapter 6. High Availability ...
Tolerant RA API or its own means to replicate any additional data to support that
presence of the activity in all nodes of the cluster. Usage of the Fault Tolerant RA
API is recommended since it reuses the clustering setup of the container.
34
Chapter 7.
Firing Events from Java EE

Applications
7.1. SLEE Connection Factory
The JAIN SLEE specification includes an API for interaction with JAIN SLEE container, with
the interface javax.slee.connection.SleeConnectionFactory upfront, which allows external
applications, such as an EJB, to create connections to a specific JAIN SLEE instance, and use
that to fire events.
JAIN SLEE provides two different implementations of the API, one for access in the same JVM,
another for remote access. Both implementations expose the SLEE Connection Factory in the
local JNDI tree, thus the same code is used by the application independently of the implementation
used.
7.1.1. Local SLEE Connection Factory
JAIN SLEE container instances always expose the local SLEE Connection Factory in its JVM,
which means that an external application running in the same JVM doesn't need any additional
tools or setup to use it.
7.1.2. Remote SLEE Connection Factory
JAIN SLEE includes a tool, named Remote SLEE Connection Tool, which is a JCA connector
that can be deployed in any Java EE application server. Once deployed this connector installs the
factory into JNDI, which communicates with the remote SLEE container through RMI.
Mobicents Remote SLEE Connection Tool is bundled in all Mobicents JAIN SLEE releases, in the
tools/remote-slee-connection directory, including its own documentation.
7.1.3. Using SLEE Connection Factory
Below is example code which retrieves the SLEE Connection Factory and uses it to fire an event
into the JAIN SLEE container. The code is the same whether the SLEE container is in the same
JVM or not.
// retrieves JNDI context

InitialContext context = new InitialContext();
// retrieves the connection factory from JNDI
35
Chapter 7. Firing Events from...
SleeConnectionFactory factory = (SleeConnectionFactory) context.lookup("java:/

MobicentsConnectionFactory");
// creates a connection to the SLEE container

SleeConnection connection = factory.getConnection();
// creates the activity handle which will be used to fire the event
ExternalActivityHandle handle = connection.createActivityHandle();
// retrieves the event type ID

EventTypeID eventTypeID = connection.getEventTypeID("CustomEvent", "...", "1.0");
// creates the event object

CustomEvent eventObject = new CustomEvent();
// fires the event in the remote SLEE container

connection.fireEvent(eventObject, eventTypeID, handle, null);
// closes the connection

connection.close();
36
Chapter 8.
JAIN SLEE 1.1 Extensions

Mobicents JAIN SLEE exposes proprietary extensions to the JAIN SLEE 1.1 specification, to allow
the development of easier or more powerful application code.
The extensions were discussed among multiple JAIN SLEE vendors, and should become part of
the standard in next revision, but there is no guarantee that portability won't be lost when using
those.
The extensions source code is available in the Mobicents Community

SVN, specifically at http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/api/
extensions/1.0.0.BETA1. The setup for the source project in Eclipse IDE is similar to the container
core, as seen in Section 9.5, “Setting JAIN SLEE Source Code Projects in Eclipse IDE”.
Java archives (JARs) with compiled classes, javadocs and sources are available in
the JBoss Maven Repository at http://repository.jboss.org/nexus/content/groups/public/org/
mobicents/servers/jainslee/api/jain-slee-11-ext/1.0.0.BETA1/
8.1. SbbContext Extension

This extension to JAIN SLEE 1.1 introduces org.mobicents.slee.SbbContextExt interface,
which extends javax.slee.SbbContext with methods to retrieve SLEE factories and facilities,
avoiding the usage of JNDI context.
package org.mobicents.slee;
import javax.slee.ActivityContextInterface;
import javax.slee.Sbb;
import javax.slee.SbbContext;
import javax.slee.facilities.ActivityContextNamingFacility;
import javax.slee.facilities.AlarmFacility;
import javax.slee.facilities.TimerFacility;
import javax.slee.nullactivity.NullActivityContextInterfaceFactory;
import javax.slee.nullactivity.NullActivityFactory;
import javax.slee.profile.ProfileFacility;
import javax.slee.profile.ProfileTableActivityContextInterfaceFactory;
import javax.slee.resource.ResourceAdaptorTypeID;
import javax.slee.serviceactivity.ServiceActivityContextInterfaceFactory;
import javax.slee.serviceactivity.ServiceActivityFactory;
public interface SbbContextExt extends SbbContext {
37
Chapter 8. JAIN SLEE 1.1 Exte...
public Object getActivityContextInterfaceFactory(

ResourceAdaptorTypeID raTypeID) throws NullPointerException,
IllegalArgumentException;
public ActivityContextNamingFacility getActivityContextNamingFacility();
public AlarmFacility getAlarmFacility();
public NullActivityContextInterfaceFactory getNullActivityContextInterfaceFactory();
public NullActivityFactory getNullActivityFactory();
public ProfileFacility getProfileFacility();
public ProfileTableActivityContextInterfaceFactory getProfileTableActivityContextInterfaceFactory();
public Object getResourceAdaptorInterface(ResourceAdaptorTypeID raTypeID,

String raEntityLink) throws NullPointerException,
IllegalArgumentException;
public ServiceActivityContextInterfaceFactory getServiceActivityContextInterfaceFactory();
public ServiceActivityFactory getServiceActivityFactory();
public TimerFacility getTimerFacility();

}
The getActivityContextInterfaceFactory(ResourceAdaptorTypeID) method:

Retrieves the ActivityContextInterface factory for the Resource Adaptor Type with the
specified ID.
The getActivityContextNamingFacility() method:

Retrieves the Activity Context Naming Facility.
The getAlarmFacility() method:

Retrieves the Alarm Facility.
The getNullActivityContextInterfaceFactory() method:

Retrieves the Null Activity Context Interface Factory.
The getNullActivityFactory() method:

Retrieves the Null Activity Factor.
The getProfileFacility() method:

Retrieves the Profile Facility.
38
ProfileContext Extension
The getProfileTableActivityContextInterfaceFactory() method:

Retrieves the Profile Table Activity Context Interface Factory.
The getResourceAdaptorInterface(ResourceAdaptorTypeID,String) method:

Retrieves the interface to interact with a specific Resource Adaptor entity, identified by both
the entity link name and the Resource Adaptor Type ID.
The getServiceActivityContextInterfaceFactory() method:

Retrieves the Service Activity Context Interface Factory.
The getServiceActivityFactory() method:

Retrieves the Service Activity Factory.
The getTimerFacility() method:

Retrieves the Timer Facility.
8.2. ProfileContext Extension

This extension to JAIN SLEE 1.1 introduces org.mobicents.slee.ProfileContextExt
interface, which extends javax.slee.ProfileContext with methods to retrieve SLEE alarm
facility, avoiding the usage of JNDI context.
import javax.slee.facilities.AlarmFacility;
import javax.slee.profile.Profile;
import javax.slee.profile.ProfileContext;
public interface ProfileContextExt extends ProfileContext {
public AlarmFacility getAlarmFacility();
The getAlarmFacility() method:

Retrieves the Alarm Facility.
8.3. ActivityContextInterface Extension

This simple extension to JAINSLEE 1.1 introduces
org.mobicents.slee.ActivityContextInterfaceExt interface, which extends
javax.slee.ActivityContextInterface with methods to retrieve the timers and names bound
to the ACI.
39
import javax.slee.ActivityContextInterface;
import javax.slee.facilities.TimerID;
public interface ActivityContextInterfaceExt extends ActivityContextInterface {
public TimerID[] getTimers();
public String[] getNamesBound();
The getTimers() method:

Retrieves the IDs of timers currently set which are related to the ACI.
The getNamesBound() method:

Retrieves the names currently bound to the ACI.
8.4. Library References Extension

JAIN SLEE 1.1 standard introduced the Library component, a wrapper for a set of jars and/or
classes to be referenced and used by other components types, such as SBBs.
The usage of the standard Library component is very limited, each Library can only refer other
Library components. Due to this limitation a developer may not be able to include classes in a
Library that depend, just as example, on Resource Adaptor Type interfaces, unless of course
those interfaces are in a Library too.
This extension allows libraries to reference other component types, which the developer should
use when the classes in the Library need to use classes from that component, by simply extending
the JAIN SLEE 1.1 Library Jar XML descriptor.
8.4.1. Extended Library Jar XML Descriptor DTD

The DTD document changes for the extended library jar XML descriptor:

<!ELEMENT library (description?, library-name, library-vendor, library-version,
event-type-ref*, library-ref*, profile-spec-ref*, resource-adaptor-type-ref*,
sbb-ref*, jar*)>

<!ELEMENT event-type-ref (event-type-name, event-type-vendor,
event-type-version)>

<!ELEMENT event-type-name (#PCDATA)>

<!ELEMENT event-type-vendor (#PCDATA)>

<!ELEMENT event-type-version (#PCDATA)>

<!ELEMENT profile-spec-ref (description?, profile-spec-name,
profile-spec-vendor, profile-spec-version)>

<!ELEMENT profile-spec-name (#PCDATA)>

<!ELEMENT profile-spec-vendor (#PCDATA)>

<!ELEMENT profile-spec-version (#PCDATA)>

<!ELEMENT resource-adaptor-type-ref (resource-adaptor-type-name,
resource-adaptor-type-vendor, resource-adaptor-type-version)>

<!ELEMENT resource-adaptor-type-name (#PCDATA)>

<!ELEMENT resource-adaptor-type-vendor (#PCDATA)>

<!ELEMENT resource-adaptor-type-version (#PCDATA)>

<!ELEMENT sbb-ref (sbb-name, sbb-vendor,
sbb-version)>

<!ELEMENT sbb-name (#PCDATA)>

<!ELEMENT sbb-vendor (#PCDATA)>

<!ELEMENT sbb-version (#PCDATA)>

<!ATTLIST library-jar id ID #IMPLIED>
<!ATTLIST description id ID #IMPLIED>
<!ATTLIST library id ID #IMPLIED>
<!ATTLIST library-name id ID #IMPLIED>
<!ATTLIST library-vendor id ID #IMPLIED>
<!ATTLIST library-version id ID #IMPLIED>
<!ATTLIST event-type-ref id ID #IMPLIED>
<!ATTLIST event-type-name id ID #IMPLIED>
<!ATTLIST event-type-vendor id ID #IMPLIED>
<!ATTLIST event-type-version id ID #IMPLIED>
<!ATTLIST library-ref id ID #IMPLIED>
<!ATTLIST profile-spec-ref id ID #IMPLIED>
<!ATTLIST profile-spec-name id ID #IMPLIED>
<!ATTLIST profile-spec-vendor id ID #IMPLIED>
<!ATTLIST profile-spec-version id ID #IMPLIED>
<!ATTLIST resource-adaptor-type-ref id ID #IMPLIED>
<!ATTLIST resource-adaptor-type-name id ID #IMPLIED>
<!ATTLIST resource-adaptor-type-vendor id ID #IMPLIED>
<!ATTLIST resource-adaptor-type-version id ID #IMPLIED>
<!ATTLIST sbb-ref id ID #IMPLIED>
<!ATTLIST sbb-name id ID #IMPLIED>
45
<!ATTLIST sbb-vendor id ID #IMPLIED>

<!ATTLIST sbb-version id ID #IMPLIED>
<!ATTLIST jar id ID #IMPLIED>
<!ATTLIST jar-name id ID #IMPLIED>
<!ATTLIST security-permissions id ID #IMPLIED>
<!ATTLIST security-permission-spec id ID #IMPLIED>
This full DTD is available at http://mobicents.org/slee/dtd/slee-library-jar_1_1-ext.dtd
8.4.2. Extended Library Jar XML Descriptor Example

The following XML descriptor examples the definition of references to JAIN SLEE 1.1 Component
types other than Library
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE library-jar PUBLIC
"-//Sun Microsystems, Inc.//DTD JAIN SLEE Ext Library 1.1//EN"
"http://mobicents.org/slee/dtd/slee-library-jar_1_1-ext.dtd">
<library-jar>
<library>
<library-name>extended-library-example</library-name>
<library-vendor>com.redhat</library-vendor>
<library-version>1.0</library-version>
<event-type-ref>
<event-type-name>ExampleX</event-type-name>
<event-type-vendor>com.redhat</event-type-vendor>
<event-type-version>1.0</event-type-version>
</event-type-ref>
<library-ref>
<library-name>LibraryX</library-name>
<library-vendor>com.redhat</library-vendor>
<library-version>1.0</library-version>
</library-ref>
<profile-spec-ref>
<profile-spec-name>ProfileX</profile-spec-name>
<profile-spec-vendor>com.redhat</profile-spec-vendor>
<profile-spec-version>1.0</profile-spec-version>
46
Extended Library Jar XML Descriptor Example
</profile-spec-ref>
<resource-adaptor-type-ref>
<resource-adaptor-type-name>ResourceAdaptorTypeX</resource-adaptor-type-name>
<resource-adaptor-type-vendor>com.redhat</resource-adaptor-type-vendor>
<resource-adaptor-type-version>1.0</resource-adaptor-type-version>
</resource-adaptor-type-ref>
<sbb-ref>
<sbb-name>SbbX</sbb-name>
<sbb-vendor>com.redhat</sbb-vendor>
<sbb-version>1.0</sbb-version>
</sbb-ref>
</library>
</library-jar>
Important
Note how the DOCTYPE element is set to the extended DTD instead of the
standard one.
47
48
Chapter 9.
Advanced Topics
9.1. Class Loading
Each JAIN SLEE Component has its own classloader (ComponentClassLoader) in the
package named org.mobicents.slee.container.component.deployment.classloading.
This classloader sees the component classes contained in the component jar
(URLClassLoaderDomain) by declaring it as the parent classloader, and adding the classes seen
by each component it refers. It does not see classes from a component that it does not depend on.
JAIN SLEE defines a class loading domain with the APIs required in the JAIN SLEE 1.1
container (for example, JAIN SLEE, JBDC and JMX). This domain (JBoss Microcontainer
ClassLoadingDomain) imports all classes shared in the JBoss Application Server, and acts like
the parent domain for all URLClassLoaderDomains, which means that a class imported by a SLEE
classloading domain will always be used first.
Figure 9.1. Classloading example in Mobicents JAIN SLEE
• The SIP INVITE Event component refers to the JAIN SIP Library in its XML descriptor, and
its classloader domain depends on the classloader domain of the JAIN SIP Library.
49
Chapter 9. Advanced Topics
• The SIP RA Type component refers to all Events in the SIP RA Event jar in its XML descriptor,
and its classloader domain depends on the classloader domain of the SIP Event JAR and
inherits its dependencies, including the JAIN SIP library classloading domain.
• The SIP RA component refers to the SIP RA Type component in its XML descriptor, and its
classloader domain depends on the classloader domain of the SIP RA Type Component jar,
and inherits its dependencies. This includes the SIP Event jar and JAIN SIP library classloading
domains.
• The SBB component refers to the SIP RA Type component and SIP INVITE Event in its
XML descriptor. Its classloader domain depends on the class loader domain of the SIP RA
Type Component jar, and inherits its dependencies; the SIP Event jar and the JAIN SIP library
classloading domains. It also depends on the classloader domain of the SIP Event jar.
Important
JBoss Application Server does not see the classes of deployed JAIN SLEE
components. This means that if it exports its classes for components that are
complemented with Java EE components, the common classes must be deployed
on JBoss Application Server, either directly or included in the Java EE component.
9.2. Congestion Control

JAIN SLEE can monitor the memory available in the JVM. In case it drops to a certain level
(percentage), new events and/or activity startups are rejected, and at the same time a JAIN SLEE
Alarm (which can send JMX notifications) is raised. This feature is called Congestion Control, and
the container will turn it off automatically once another available memory level is reached.
If Congestion Control rejects an operation, a javax.slee.SleeException is thrown. This means

that if the feature is to be used, the Resource Adaptors and Applications need to handle such use
case, and behave properly.
The type of JAIN SLEE Alarm raised is org.mobicents.slee.management.alarm.congestion.
Congestion Control is turned off by default.
9.2.1. Congestion Control Configuration

The Congestion Control feature is configured through an XML file or through a JMX MBean.
Changes applied through JMX are not persisted, and once the container is restarted the
configuration will revert to the one in the XML file.
9.2.1.1. Congestion Control Persistent Configuration

Configuration is done through a XML descriptor for each Section 3.1, “Server Profiles”. The XML
file is named jboss-beans.xml and is located at $JBOSS_HOME/server/profile_name/deploy/
mobicents-slee/META-INF, where profile_name is the server profile name.
50
Congestion Control Configuration
<bean name="Mobicents.JAINSLEE.CongestionControlConfiguration"
class="org.mobicents.slee.container.management.jmx.CongestionControlConfiguration">
"org.mobicents.slee:name=CongestionControlConfiguration",exposedInterface=
org.mobicents.slee.container.management.jmx.CongestionControlConfigurationMBean.class,
<property name="periodBetweenChecks">0</property>
<property name="minFreeMemoryToTurnOn">10</property>
<property name="minFreeMemoryToTurnOff">20</property>
<property name="refuseStartActivity">true</property>
<property name="refuseFireEvent">false</property>
</bean>
Table 9.1. JAIN SLEE Congestion Control Bean Configuration

periodBetweenChecks int The available memory level
is checked periodically, this
property defines the period,
in seconds, between these
checks, and if set to 0 turns
off the Congestion Control
feature.
minFreeMemoryToTurnOn int This property defines the
minimum free memory
percentage, which if reached
turns ON the Congestion
Control feature.
minFreeMemoryToTurnOff int This property defines the
minimum free memory
percentage, which if
reached turns OFF the
Congestion Control feature.
This value should be
considerably higher than
minFreeMemoryToTurnOn,
51

otherwise the feature may be
turning on and off all the time.
refuseStartActivity boolean If true and the Congestion
Control feature is ON,
the container rejects activity
startups, no matter it's a
request from a Resource
Adaptor or SBB.
refuseFireEvent boolean If true and the Congestion
Control feature is ON, the
container rejects the firing of
events, no matter it's a request
from a Resource Adaptor or
SBB.
9.2.1.2. Congestion Control JMX Configuration

Through JMX, the Congestion Control feature configuration can be changed with the container
running. These configuration changes are not persisted.
The JMX MBean which can be used to change the Congestion Control configuration is
named org.mobicents.slee:name=CongestionControlConfiguration, and provides getters
and setters to change each property defined in the persistent configuration. The JMX Console can
be used to use this MBean, see Section 4.4.1, “JMX Console”.
9.3. JAIN SLEE 1.1 Profiles JPA Mapping

As mentioned in the containers configuration section, Mobicents JAIN SLEE uses JPA to store
all JAIN SLEE 1.1 Profiles, and in mentioned section it was explained how to define which JPA /
Hibernate data source. In this section more details are provided about how JAIN SLEE 1.1 Profiles
are mapped to a JPA datasource schema.
9.3.1. Profile Specification JPA Tables And columns

For each Profile Specification, at least one JPA Table is created, and is named
SLEE_PE_ concatenated with the Profile CMP interface simple name (obtained as
java.lang.Class.getSimpleName()), then _, and finally the absolute value of the hashCode()
method of the javax.slee.ComponentID of the Profile Specification.
This table has a primary key composed by the profile name and profile table name, and a column
for each attribute of the Profile Specification CMP, except for those of array type. Those columns
are named C, concatenated with the cmp attribute name.
For each Profile CMP attribute of array type, a join table is created, and is named
SLEE_PEAAV_ concatenated with the Profile CMP interface simple name (obtained as
52
Profile Specification JPA Datasource
java.lang.Class.getSimpleName()), then _, then the absolute value of hashCode() method of

the javax.slee.ComponentID of the Profile Specification, and finally the CMP attribute name. This
table has a generated primary key column named ID, the foreign key, and two columns to store
the CMP attribute value:
SERIALIZABLE
Used to store the value if its type does not allow it to be converted to a String.
STRING
Used when the CMP attribute type can be converted to a java.lang.String, for instance
an Integer.
9.3.2. Profile Specification JPA Datasource

Unless configured manually, Mobicents JAIN SLEE uses the default datasource of JBoss
Application Server. Please refer to its documentation to learn about it.
9.4. Testing the JAIN SLEE 1.1 TCK

To run the JAIN SLEE 1.1 TCK:
1. Checkout and build the container source code as explained in Chapter 2, Installing Mobicents
JAIN SLEE.
2. Install the TCK Resource Adaptor and Plugin:
cd tck/jain-slee-1.1
mvn install
3. Setup JAVA_OPTS environment variable to include -XX:MaxPermSize=128M

-Djboss.defined.home=/Volumes/2/jboss-5.1.0.GA -Djava.security.manager=default -
Djava.security.policy=file:///Volumes/2/workspace/mobicents-jainslee-2/tck/jain-
slee-1.1/tck-security.policy, replacing the absolute paths with $JBOSS_HOME and the path
of the svn checkout.
4. Unzip and run the JAIN SLEE 1.1 TCK distribution:
unzip testsuite.zip
cd testsuite
ant
Important
No test should fail.
53
9.5. Setting JAIN SLEE Source Code Projects in Eclipse

IDE
The JAIN SLEE Core, each RA, and each example, are worked out with separated Eclipse IDE
Projects.
There are two alternatives to set up a specific project:
Procedure 9.1. Via Command Line
1. In the checked out directory of the project, and with Eclipse IDE closed, open a terminal.
2. Run the following:
]mvn mobicents:eclipse
mvn -Declipse.workspace=YOUR_RELATIVE_PATH_TO_ECLIPSE_WORKSPACE
eclipse:add-maven-repo
3. Install M2Eclipse if you want to do maven builds within Eclipse.
Procedure 9.2. With Eclipse IDE
• Install the M2Eclipse plugin and use "Import..." and subselect the "Maven Projects" feature.
Important
Ensure the "Resolve Workspace projects" and "Separate projects for

modules" in the "Advanced" options on the bottom of the window are turned
off. If the project is large, such as the JAIN SLEE Core, M2Eclipse may
be a considerable slower option, due to dynamic Maven2 Dependency
Management.
54
Appendix A. Java Development Kit
(JDK): Installing, Configuring and
Running
The Mobicents Platform 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
1
5 or higher .
Should I Install the JRE or JDK? Although you can run Mobicents servers using the Java
Runtime Environment, we assume that most 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
1
At this point in time, it is possible to run most Mobicents servers, such as the JAIN SLEE, 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.
55
Appendix A. Java Development ...
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. The following procedures detail how to install the Java Development Kit on both
Linux and Windows.
Procedure A.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 A.2. Installing the JDK on Windows
• Using Explorer, simply double-click the downloaded self-extracting installer and follow the
instructions to install the JDK.
56
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_HOME Environment Variable on Generic Linux

After installing the JDK, you must ensure that the JAVA_HOME environment variable exists and
points to the location of your JDK installation.
Setting the JAVA_HOME Environment Variable on Linux. You can determine whether
JAVA_HOME is set on your system by echoing it on the command line:
~]$ echo $JAVA_HOME
If JAVA_HOME is not set already, then you must set its value to the location of the JDK installation
on your system. You can do this by adding two lines to your personal ~/.bashrc configuration
file. Open ~/.bashrc (or create it if it doesn't exist) and add a line similar to the following one
anywhere inside the file:
export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"
You should also set this environment variable for any other users who will be running
Mobicents (any environment variables exported from ~/.bashrc files are local to that user).
Setting java, javac and java_sdk_1.5.0 Using the alternatives command

Selecting the Correct System JVM on Linux using alternatives . On systems with
the alternatives command, including Red Hat Enterprise Linux and Fedora, you can easily
choose which JDK (or JRE) installation you wish to use, as well as which java and javac
executables should be run when called.
As the root user, call /usr/sbin/alternatives with the --config java option to select
between JDKs and JREs installed on your system:
root@localhost ~]$ /usr/sbin/alternatives --config java
There are 3 programs which provide 'java'.
Selection Command
-----------------------------------------------
1 /usr/lib/jvm/jre-1.5.0-gcj/bin/java
2 /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 3 /usr/lib/jvm/jre-1.5.0-sun/bin/java
57
Appendix A. Java Development ...
Enter to keep the current selection[+], or type selection number:
In our case, we want to use the Sun JDK, version 5, that we downloaded and installed, to
run the java executable. In the alternatives information printout above, a plus (+) next to a
number indicates the one currently being used. As per alternatives' instructions, pressing
Enter will simply keep the current JVM, or you can enter the number corresponding to the
JVM you would prefer to use.
Repeat the procedure above for the javac command and the java_sdk_1.5.0 environment
variable, as the root user:
~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
Setting the JAVA_HOME Environment 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 your PATH, run the java -version command in the terminal
from your home directory:
~]$ java -version

java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03)
Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling. There is usually no reason (other than space concerns) to remove a particular
JDK from your system, given that you can switch between JDKs and JREs easily using
alternatives, and/or by setting JAVA_HOME.
Uninstalling the JDK on Linux. On RPM-based systems, you can uninstall the JDK using the
yum remove <jdk_rpm_name> command.
Uninstalling the JDK on Windows. On Windows systems, check the JDK entry in the Start
menu for an uninstall command, or use Add/Remove Programs.
58
Appendix B. Setting the
JBOSS_HOME Environment Variable
The Mobicents Platform (Mobicents) is built on top of the JBoss Application Server. You
do not need to set the JBOSS_HOME environment variable to run any of the Mobicents 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 Unix. At the command line, echo $JBOSS_HOME
to see if it is currently defined in your environment:
~]$ echo $JBOSS_HOME
The Mobicents Platform and most Mobicents servers are built on top of the JBoss Application
Server (JBoss Application Server). When the Mobicents Platform or Mobicents servers are
built from source, then JBOSS_HOME must be set, because the Mobicents files are installed into (or
“over top of” if you prefer) a clean JBoss Application Server installation, and the build process
assumes that the location pointed to by the JBOSS_HOME environment variable at the time of
building is the JBoss Application Server installation into which you want it to install the Mobicents
files.
This guide does not detail building the Mobicents Platform or any Mobicents servers from source.
It is nevertheless useful to understand the role played by JBoss AS and JBOSS_HOME in the
Mobicents ecosystem.
The immediately-following section considers whether you need to set JBOSS_HOME at all and, if
so, when. The subsequent sections detail how to set JBOSS_HOME on Unix and Windows
Important
Even if you fall into the category below of not needing to set JBOSS_HOME, you may
want to for various reasons anyway. Also, even if you are instructed that you do
not need to set JBOSS_HOME, it is good practice nonetheless to check and make
sure that JBOSS_HOME actually isn't set or defined on your system for some reason.
This can save you both time and frustration.
You DO NOT NEED to set JBOSS_HOME if...
• ...you have installed the Mobicents Platform binary distribution.
59
Appendix B. Setting the JBOSS...
• ...you have installed a Mobicents server binary distribution which bundles JBoss Application
Server.
You MUST set JBOSS_HOME if...
• ...you are installing the Mobicents Platform or any of the Mobicents servers from source.
• ...you are installing the Mobicents Platform binary distribution, or one of the Mobicents server
binary distributions, which do not bundle JBoss Application Server.
Naturally, if you installed the Mobicents Platform or one of the Mobicents server binary releases
which do not bundle JBoss Application Server, yet requires it to run, then you should install
before setting JBOSS_HOME or proceeding with anything else.
Setting the JBOSS_HOME Environment Variable on Unix. The JBOSS_HOME environment

variable must point to the directory which contains all of the files for the Mobicents Platform or
individual Mobicents server 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 Unix, 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 B.1. To Set JBOSS_HOME on Unix...
1. Open the ~/.bashrc startup 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>"
2. Save and close the .bashrc startup script.
3. You should source the .bashrc script to force your change to take effect, so that JBOSS_HOME
1
becomes set for the current session .
~]$ source ~/.bashrc
4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct
location:
1
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.
60
You MUST set JBOSS_HOME if...
Note
The command line usage below is based upon a binary installation of

the Mobicents Platform. In this sample output, JBOSS_HOME has been set
correctly to the topmost_directory of the Mobicents installation. Note that
if you are installing one of the standalone Mobicents servers (with JBoss AS
bundled!), then JBOSS_HOME would point to the topmost_directory of your
server installation.
~]$ echo $JBOSS_HOME

/home/silas/
Setting the JBOSS_HOME Environment Variable on Windows. The JBOSS_HOME

environment variable must point to the directory which contains all of the files for the Mobicents
Platform or individual Mobicents server 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.
61
62
Appendix C. Revision History
Revision History
Revision 1.0 Tue Dec 22 2009 EduardoMartins
Creation of the Mobicents JAIN SLEE 2.x User Guide.
63
64
Index
F
feedback, viii
65
66

Mobicents SLEE Container User Guide

Uploaded by

Copyright:

Available Formats

Mobicents SLEE Container User Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Mobicents SLEE Container User Guide

Uploaded by

Copyright:

Available Formats

Mobicents JAIN SLEE User Guide

by Alexandre Mendonça, Amit Bhayani, Bartosz Baranowski,

5.3. Trace Facility .................................................................................................... 27

1.1. Typographic Conventions

To see the contents of the file my_next_bestselling_novel in your current

Press Enter to execute the command.

Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to

To insert a special character into a gedit file, choose Applications >

Mono-spaced Bold Italic or Proportional Bold Italic

To connect to a remote machine using ssh, type ssh [email protected]

The mount -o remount file-system command remounts the named file

1.2. Pull-quote Conventions

Output sent to a terminal is set in Mono-spaced Roman and presented thus:

books Desktop documentation drafts mss photos stuff svn

public class ExClient

System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));

1.3. Notes and Warnings

A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a

2. Provide feedback to the authors!

When submitting a bug report, be sure to mention the manual's identifier:

Introduction to Mobicents JAIN

Figure 1.1. Overview of JAIN SLEE

Figure 1.2. Mobicents Platform

Installing Mobicents JAIN SLEE

2.1.1. Hardware Requirements

Sufficient Disk Space

Anything Java Itself Will Run On

2.1.2. Software Prerequisites

2.2. Install Alternatives

Release Source Building

Trunk Source Building

Binary Release Snapshot

2.2.1. Binary Release

1. Unzip the release file

2. Setting up JBOSS_HOME Environment Variable

2.2.2. Binary Release Snapshot

2.2.3. Release Source Building

1. Downloading the source code

[usr]$ svn co http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/

2. Building the source code

Use Ant to build the binary.

Once the process finishes you should have a mobicents-jainslee-2.3.0.FINAL.zip file,

2.2.4. Trunk Source Building

2.3. Uninstall Mobicents JAIN SLEE

Configuring and Running Mobicents

3.2. Running Mobicents JAIN SLEE

3.2.1.1. Starting Parameters

If not specified the default profile is used.

If not specified then 127.0.0.1 is used.

[Server] Shutdown complete

3.3. Configuring Mobicents JAIN SLEE

This configuration greatly affects performance or correctness of the container

3.3.1. Event Router Statistics and Configuration

In the case of advanced performance tuning, it is advised to try the different

The Executor Mapper is nothing more than an interface:

3.3.1.1. Event Router Persistent Configuration

The configuration is exposed a JBoss Microcontainer Bean:

Table 3.1. JAIN SLEE Event Router Bean Configuration

Property Name Property Type Description