JBoss.orgCommunity Documentation

JAIN SLEE User Guide


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Provide feedback to the authors!
1. Introduction to Mobicents JAIN SLEE
2. Installing Mobicents JAIN SLEE
2.1. Pre-Install Requirements and Prerequisites
2.1.1. Hardware Requirements
2.1.2. Software Prerequisites
2.2. Install Alternatives
2.2.1. Binary Release
2.2.2. Binary Release Snapshot
2.2.3. Release Source Building
2.2.4. Trunk Source Building
2.3. Uninstall Mobicents JAIN SLEE
3. Configuring and Running Mobicents JAIN SLEE
3.1. Server Profiles
3.2. Running Mobicents JAIN SLEE
3.2.1. Starting
3.2.2. Stopping
3.3. Configuring Mobicents JAIN SLEE
3.3.1. Event Router Statistics and Configuration
3.3.2. Timer Facility Configuration
3.3.3. Configuring JAIN SLEE Profiles
3.3.4. Other Configurations
3.3.5. Logging Configuration
3.3.6. Congestion Control Configuration
4. Managing Mobicents JAIN SLEE
4.1. JAIN SLEE JMX Agent
4.2. SNMP Agent
4.3. Managing JAIN SLEE Components
4.3.1. Persistent Deployable Unit Management
4.3.2. Ant Tasks
4.4. Management Consoles
4.4.1. JMX Console
4.4.2. Jopr Console
4.4.3. TWIDDLE CLI
5. Logging, Traces and Alarms
5.1. Log4j Logging Service
5.1.1. Simplified Global Log4j Configuration
5.2. Alarm Facility
5.3. Trace Facility
5.3.1. JAIN SLEE Tracers and Log4j
6. Mobicents JAIN SLEE Clustering
6.1. High Availability and Fault Tolerance
6.1.1. High Availability Mode
6.1.2. Fault Tolerant Mode
6.2. Component Redundancy in Fault Tolerant Clusters
6.2.1. Internal Component Redundancy
6.2.2. External Component Redundancy
6.3. Managing Components in Mobicents JAIN SLEE Cluster
6.4. Fault Tolerant Resource Adaptor API
6.4.1. The Fault Tolerant Resource Adaptor Object
6.4.2. The Fault Tolerant Resource Adaptor Context
6.5. Resource Adaptor Activity Replication
7. Firing Events from Java EE Applications
7.1. SLEE Connection Factory
7.1.1. Local SLEE Connection Factory
7.1.2. Remote SLEE Connection Factory
7.1.3. Using SLEE Connection Factory
8. JAIN SLEE 1.1 Extensions
8.1. SbbContext Extension
8.2. ChildRelation Extension
8.3. SbbLocalObject Extension
8.4. ProfileContext Extension
8.5. ActivityContextInterface Extension
8.6. Library References Extension
8.6.1. Extended Library Jar XML Descriptor DTD
8.6.2. Extended Library Jar XML Descriptor Example
9. Advanced Topics
9.1. Class Loading
9.2. Congestion Control
9.2.1. Congestion Control Configuration
9.3. JAIN SLEE 1.1 Profiles JPA Mapping
9.3.1. Profile Specification JPA Tables And columns
9.3.2. Profile Specification JPA Datasource
9.4. Testing the JAIN SLEE 1.1 TCK
9.5. Setting JAIN SLEE Source Code Projects in Eclipse IDE
A. Java Development Kit (JDK): Installing, Configuring and Running
B. Setting the JBOSS_HOME Environment Variable
C. Fault Tolerant Clustering - A Concrete Example
C.1. Example Overview
C.2. Creating Sbb entities
C.3. Relaying the Message
D. Revision History
Index

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

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:

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:

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:

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:

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:

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:

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, 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.

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.


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 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.


Mobicents JAIN SLEE can also be complemented with Mobicents SIP Servlets and Mobicents Media Server, providing unique value and integration features not found elsewhere.

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.5.0.FINAL.zip to the /mobicents directory.

    				    [usr]$ cd /mobicents
    				    [usr]$ jar -xvf mobicents-jainslee-2.5.0.FINAL.zip
    					
  2. Setting up JBOSS_HOME Environment Variable

    You should now have a directory called mobicents-jainslee-2.5.0.FINAL. Next you need to set your JBOSS_HOME environment variables. This is discussed in Appendix B, Setting the JBOSS_HOME Environment Variable.

  1. Downloading the source code

    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.5.0.FINAL.

    [usr]$ svn co http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/core/2.5.0.FINAL mobicents-slee-core-2.5.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.5.0.FINAL/release
    				    [usr]$ ant
    				    

    Once the process finishes you should have a mobicents-jainslee-2.5.0.FINAL.zip file, installation is the same as for Section 2.2.1, “Binary Release”.

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.

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.

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 Mappers. The default one takes into account the hashcode of the activity handle when distributing, while the alternative uses a round robin algorithm.

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.

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>
            

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.

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>
</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>
            

To switch the active configuration simply change the parameter injected in the bean named Mobicents.JAINSLEE.Container.

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,
        registerDirectly=true)</annotation>
    <property name="entitiesRemovalDelay">1</property>
    <property name="timerThreads">8</property>
    <property name="loadClassesFirstFromAS">true</property>
</bean>
            

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”.

JAIN SLEE provides a file deployer that greatly simplifies the management of JAIN SLEE deployable unit jars. The deployer:

All operations are persistent, which means that unlike management done through JMX, these survive server shutdowns.

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:

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">
  <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>
        


<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.

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">
        <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.

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}">
    <!-- sub-tasks -->
</slee-management>
        

The attributes have the same meaning as the properties listed in the script code to import the tasks here: Section 4.3.2, “Ant Tasks”.

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:

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.

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.

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"> 
    <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.

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:

The available management operations are:

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.

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.

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.

For further information on how to use JAIN SLEE Trace Facility and receive JMX notifications refer to the JAIN SLEE 1.1 Specification.

JAIN SLEE supports clustering, whether it is simple high availability (HA) or complete fault tolerance (FT) support. This is achieved through the replication of the container state. The Mobicents JAIN SLEE implementation also exposes a clustering extension API for Resource Adaptors components, which live outside the container.

The fault tolerant clustering mode provides clustering for most of the JAIN SLEE components. JAIN SLEE components can be divided into internal and external components. Internal components are logically contained by the JAIN SLEE container, and external components are at least partly outside the container.

For a concrete example of how the container behaves in FT mode, see Appendix C, Fault Tolerant Clustering - A Concrete Example.

Internal SLEE components are components that are completely inside the JAIN SLEE container. This group of components include SBB entities, internal activities, events and timers. With the exception of events, all internal components will be fully redundant in a FT JAIN SLEE configuration.

SBB entities are fully replicated. SBB entities are always serialized and saved by the container, regardless of the clustering profile. In an FT environment the container will replicate this serialized state to other nodes in the cluster so that it can be retrieved if the node fails or if the SBB entity is processed in another node. All SBB entities will hence be accessible by any node in the cluster at any given time.

Timers are fully replicated. Timers created in a given node will be executed in that same node. If the node leaves the cluster, all active timers from that node are recreated and run in another node.

Activity context interfaces (ACI), as well as activity handles are fully replicated. The ACIs for all activities are replicated within a fault tolerant cluster. However, the activity object is not replicated by default and needs to be handled by the resource adaptor that owns the activity in question if replication is required. The activity objects for all internal activities, e.g. null activities, profile table activities and service activities, are fully replicated.

Events are not replicated because of performance constraints. Hence, all events fired in a node is routed only in that node. However, if an event is fired in one node, and an SBB entity created in another node has attached to that ACI, the SBB entity will be retrieved in the node that fired the event and the event will be delivered to it. Hence, even though the event is fired in a single node, the effects will be cluster-wide. Because the events are not replicated, any event currently being routed in a node that fails, will be lost.

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. However, it misses an API for clustering, which is critical for a RA deployed in a clustered JAIN SLEE environment. The JAIN SLEE 1.1 contract does not define any fault tolerant data source nor cluster state callbacks.

The Fault Tolerant RA API extends the JAIN SLEE 1.1 RA API , providing missing features related to clustering. An effort has been made keep the API similar to the standard RA contract, so that anyone who has developed a JAIN SLEE 1.1 RA is able to easily use the proprietary API extension.

The clustered RA context follows the contract of JAIN SLEE 1.1 specification interface javax.slee.resource.ResourceAdaptorContext . It gives access to facilities that the RA may use when run in a 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.

The standard Resource Adaptor Context provides a java.util.Timer, which can be used by the Resource Adaptor to schedule the execution of tasks, the Fault Tolerant Resource Adaptor Context provides org.mobicents.slee.resource.cluster.FaultTolerantTimer, an alternative scheduler which is able to fail over tasks scheduled.

The Fault Tolerant Timer has an interface that resembles the JDK's ScheduledExecutorService, with two fundamental changes to allow a proper interaction in a cluster environment:

The Fault Tolerant Timer interface:

cancel(Serializable taskID)

Requests the cancellation of the FT Timer Task with the specified ID.

configure(FaultTolerantTimerTaskFactory taskFactory, int threads)

Configures the fault tolerant timer, specifying the timer task factory and the number of threads the timer uses to execute tasks.

isConfigured()

Indicates if the timer is configured.

schedule(FaultTolerantTimerTask task, long delay, TimeUnit unit)

Creates and executes a one-shot action that becomes enabled after the given delay.

scheduleAtFixedRate(FaultTolerantTimerTask task, long initialDelay, long period, TimeUnit unit)

Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period; that is executions will commence after initialDelay then initialDelay+period, then initialDelay + 2 * period, and so on. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor. If any execution of this task takes longer than its period, then subsequent executions may start late, but will not concurrently execute.

scheduleWithFixedDelay(FaultTolerantTimerTask task, long initialDelay, long delay, TimeUnit unit)

Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given delay between the termination of one execution and the commencement of the next. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.

A simple example for the usage of the Faul Tolerant Timer Task:



            // data, task and factory implementation
            
package org.mobicents.slee.resource.sip11;
import java.io.Serializable;
import org.mobicents.slee.resource.cluster.FaultTolerantTimerTaskData;
public class FaultTolerantTimerTaskDataImpl implements
        FaultTolerantTimerTaskData {
    private final String taskID;
    public FaultTolerantTimerTaskDataImpl(String taskID) {
        this.taskID = taskID;
    }
    @Override
    public Serializable getTaskID() {
        return taskID;
    }
}
package org.mobicents.slee.resource.sip11;
import org.mobicents.slee.resource.cluster.FaultTolerantTimerTask;
import org.mobicents.slee.resource.cluster.FaultTolerantTimerTaskData;
import org.mobicents.slee.resource.cluster.FaultTolerantTimerTaskFactory;
public class FaultTolerantTimerTaskFactoryImpl implements
        FaultTolerantTimerTaskFactory {
    private final SipResourceAdaptor ra;
    public FaultTolerantTimerTaskFactoryImpl(SipResourceAdaptor ra) {
        this.ra = ra;
    }
    @Override
    public FaultTolerantTimerTask getTask(FaultTolerantTimerTaskData data) {
        return new FaultTolerantTimerTaskImpl(ra, data);
    }
}
package org.mobicents.slee.resource.sip11;
import org.mobicents.slee.resource.cluster.FaultTolerantTimerTask;
import org.mobicents.slee.resource.cluster.FaultTolerantTimerTaskData;
public class FaultTolerantTimerTaskImpl implements FaultTolerantTimerTask {
    private final SipResourceAdaptor ra;
    private final FaultTolerantTimerTaskData data;
    public FaultTolerantTimerTaskImpl(SipResourceAdaptor ra,
            FaultTolerantTimerTaskData data) {
        this.ra = ra;
        this.data = data;
    }
    @Override
    public void run() {
        ra.getTracer("FaultTolerantTimerTaskImpl").info("Timer executed.");
    }
    @Override
    public FaultTolerantTimerTaskData getTaskData() {
        return data;
    }
}
// ra code retrieving the timer, configuring it and submiting a task
public void setFaultTolerantResourceAdaptorContext(
        FaultTolerantResourceAdaptorContext<SipActivityHandle, String> context) {
    this.ftRaContext = context;
    FaultTolerantTimer timer = context.getFaultTolerantTimer();
    timer.config(new FaultTolerantTimerTaskFactoryImpl(this), 4);
    FaultTolerantTimerTaskDataImpl data = new FaultTolerantTimerTaskDataImpl("xyz");
    FaultTolerantTimerTaskImpl task = new FaultTolerantTimerTaskImpl(this,
            data);
    timer.schedule(task, 30, TimeUnit.SECONDS);
}
        

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.

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/

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 {
    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 SbbLocalObjectExt getSbbLocalObject()
            throws TransactionRequiredLocalException, IllegalStateException,
            SLEEException;
            
    public ServiceActivityContextInterfaceFactory getServiceActivityContextInterfaceFactory();
    public ServiceActivityFactory getServiceActivityFactory();
    public TimerFacility getTimerFacility();
}
    

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.

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



<!--
The library element defines a library.  It contains an optional description
about the library, the name, vendor, and version of the library being defined,
zero or more references to any other components that this library
depends on, and information about zero or more jar files that contain
prepackaged classes and resources to be included with the library.

The classes and resources for a library are the sum total of the classes and
resources contained in:
- the library component jar itself (if any)
- the library jars specified by the jar elements (if any)

All these classes are loaded by the same classloader.

Used in: library-jar
-->
<!ELEMENT library (description?, library-namelibrary-vendorlibrary-version,
 event-type-ref*, library-ref*, profile-spec-ref*, resource-adaptor-type-ref*,
 sbb-ref*, jar*)>

<!--
The event-type-ref element identifies an event type that the library classes depend.
It contains the name, vendor,and version of the event type.

Used in: library
-->
<!ELEMENT event-type-ref (event-type-nameevent-type-vendor
          event-type-version)>

<!--
The event-type-name element contains the name of an event type referred by
the library.

Used in: event-type-ref

Example:
    <event-type-name>
        javax.csapi.cc.jcc.JccCallEvent.CALL_CREATED
    </event-type-name>
-->
<!ELEMENT event-type-name (#PCDATA)>

<!--
The event-type-vendor element contains the vendor of an event type referred by
the library

Used in: event-type-ref

Example:
    <event-type-vendor>javax.csapi.cc.jcc</event-type-vendor>
-->
<!ELEMENT event-type-vendor (#PCDATA)>

<!--
The event-type-version element contains the version of an event type referred by
the library

Used in: event-type-ref

Example:
    <event-type-version>1.1</event-type-version>
-->
<!ELEMENT event-type-version (#PCDATA)>

<!--
The profile-spec-ref element identifies an profile specification that the library
classes depend. It contains an optional description about the reference, and the
name, vendor, and version of the referenced profile specification.

Used in: library
-->
<!ELEMENT profile-spec-ref (description?, profile-spec-name,
          profile-spec-vendorprofile-spec-version)>

<!--
The profile-spec-name element contains the name of a profile specification
component.

Used in: profile-spec-ref

Example:
    <profile-spec-name>AddressProfileSpec</profile-spec-name>
-->
<!ELEMENT profile-spec-name (#PCDATA)>

<!--
The profile-spec-vendor element contains the vendor of a profile specification
component.

Used in: profile-spec-ref

Example:
    <profile-spec-name>javax.slee</profile-spec-name>
-->
<!ELEMENT profile-spec-vendor (#PCDATA)>

<!--
The profile-spec-version element contains the version of a profile
specification component.

Used in: profile-spec-ref

Example:
    <profile-spec-version>1.0</profile-spec-version>
-->
<!ELEMENT profile-spec-version (#PCDATA)>
          
<!--
The resource-adaptor-type-ref element identifies an resource adaptor type that the
library classes depend. It contains the name, vendor,and version of the RA type.

Used in: library
-->
<!ELEMENT resource-adaptor-type-ref (resource-adaptor-type-name,
          resource-adaptor-type-vendorresource-adaptor-type-version)>

<!--
The resource-adaptor-type-name element contains the name of a resource
adaptor type component referred by the library.

Used in: resource-adaptor-type-ref

Example:
    <resource-adaptor-type-name>JCC</resource-adaptor-type-name>
-->
<!ELEMENT resource-adaptor-type-name (#PCDATA)>

<!--
The resource-adaptor-type-vendor element contains the vendor of a resource
adaptor type component referred by the library.

Used in: resource-adaptor-type-ref

Example:
    <resource-adaptor-type-vendor>
        javax.csapi.cc.jcc
    </resource-adaptor-type-vendor>
-->
<!ELEMENT resource-adaptor-type-vendor (#PCDATA)>

<!--
The resource-adaptor-type-version element contains the version of a resource
adaptor type component referred by the library.

Used in: resource-adaptor-type-ref

Example:
    <resource-adaptor-type-version>1.1</resource-adaptor-type-version>
-->
<!ELEMENT resource-adaptor-type-version (#PCDATA)>

<!--
The sbb-ref element identifies an SBB that the library classes depend.
It contains the name, vendor,and version of the SBB.

Used in: library
-->
<!ELEMENT sbb-ref (sbb-namesbb-vendor
          sbb-version)>

<!--
The sbb-name element contains the name of a SBB component referred
 by the library.


Used in: sbb-ref

Example: 
    <sbb-name>MySbb</sbb-name>
-->
<!ELEMENT sbb-name (#PCDATA)>

<!--
The sbb-vendor element contains the vendor of a SBB component referred
 by the library.

Used in: sbb-ref

Example: 
    <sbb-vendor>My Company, Inc.</sbb-vendor>
-->
<!ELEMENT sbb-vendor (#PCDATA)>

<!--
The sbb-version element contains the version of a SBB component referred
 by the library.

Used in: sbb-ref

Example: 
    <sbb-version>1.0</sbb-version>
-->
<!ELEMENT sbb-version (#PCDATA)>

<!-- 
The ID mechanism is to allow tools that produce additional deployment
information (ie. information beyond that contained by the standard SLEE
deployment descriptors) to store the non-standard information in a separate
file, and easily refer from those tools-specific files to the information in
the standard deployment descriptor.  The SLEE architecture does not allow the
tools to add the non-standard information into the SLEE-defined deployment
descriptors.
-->
<!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>
<!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

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>
        </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>


        

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.


  • 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.

  • 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.

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.

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.

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.

The configuration is exposed a JBoss Microcontainer Bean:



<bean name="Mobicents.JAINSLEE.CongestionControlConfiguration"
    class="org.mobicents.slee.container.management.jmx.CongestionControlConfiguration">
    <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name=
        "org.mobicents.slee:name=CongestionControlConfiguration",exposedInterface=
        org.mobicents.slee.container.management.jmx.CongestionControlConfigurationMBean.class,
        registerDirectly=true)</annotation>
    <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>
            

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.

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.

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 5 or higher[1].

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 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.

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.

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


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.



[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.

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

You DO NOT NEED to set JBOSS_HOME if...

You MUST set JBOSS_HOME if...

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 becomes set for the current session[2].

    ~]$ source ~/.bashrc
  4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct location:

    Note

    The command line usage below is based upon a binary installation of the 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/<path>/<to>/<install_directory>
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.



[2] Note that any other terminals which were opened prior to your having altered .bashrc will need to source ~/.bashrc as well should they require access to JBOSS_HOME.

In order to highlight the behavior of the Mobicents JAIN SLEE server when run in fault tolerant clustering mode, a concrete situation is described below.

Revision History
Revision 1.0Tue Dec 22 2009Eduardo Martins
Creation of the Mobicents JAIN SLEE 2.x User Guide.
Revision 1.1Fri Mar 25 2011Carl-Magnus Björkell
Clarifications to the clustering section. Added a clustering example to the appendix.