JBoss.orgCommunity Documentation

Mobicents SIP Presence Service User Guide

by Douglas Silas, Eduardo Martins, Ivelin Ivanov, and Jared Morgan

Abstract

The Mobicents Platform is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. Mobicents serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSes) by leveraging J2EE to enable the convergence of data and video in Next-Generation Intelligent Network (NGIN) applications.

The Mobicents SIP Presence Service, provides presence functionalities to SIP-based networks, and is built upon Mobicents JAIN SLEE.


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 Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product SIP Presence Service, or contact the authors.

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

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

The Mobicents SIP Presence Service provides presence functionalities to SIP-based networks using standards developed by the Internet Engineering Task Force (IETF), the Open Mobile Alliance (OMA), the 3rd Generation Partnership Project (3GPP) and the European Telecommunications Standards Institute (ETSI).

The SIP Presence Service is comprised of three separate but interrelated servers.

A major advantage of the Mobicents SIP Presence Service is that, depending on your needs, each server can be deployed separately, or all servers can be integrated on the same host.

The Mobicents SIP Presence Service is built on top of Mobicents JAIN SLEE, a high performance and scalable Application Server and uses many additional Java Enterprise (JEE) technologies, such as Java Persistence API (JPA) to manage data.

In addition, there are JAIN SLEE internal client interfaces available for interaction with each server, which distinguishes the Mobicents SIP Presence Service from other presence services.

Resources and Further Information about the Mobicents SIP Presence Service

For further information on the Mobicents SIP Presence Service, here is a list of additional resources:

There are multiple binary distributions of the Mobicents SIP Presence Service.

The Mobicents Platform (Mobicents) is built on top of the JBoss Application Server (JBoss AS). 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 AS). 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 AS 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 AS 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 AS, yet requires it to run, then you should install JBoss AS 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 2.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[1].

    ~]$ 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/
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.



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

The Mobicents XML Document Management Server (XDM Server) is part of the Mobicents SIP Presence Service; it is the first free and open source implementation of an XML Document Management Server as defined in the Open Mobile Alliance (OMA) XML Document Management v1.1 specification. This functional element of next-generation IP communication networks is responsible for handling the management of user XML documents stored on the network side, such as presence authorization rules, contact and group lists (also known as resource lists), static presence information, and much more.

The Mobicents XDM Server includes the following XCAP application usages:

The SIP interface partially implements the XCAP Diff Event IETF draft, version 3. Subscriptions to a single document or usage by an entire application are supported. However, these differing usages do not extend to the single-XML element or attribute value level. Regarding the notifications, the diff-processing subscription parameter, if present, is ignored, and patching of content is not available at the moment, which means that only the document etags, new and/or old, will be provided.

The XDM Server comprises the following functional elements:

Implementation Architecture of the Mobicents XML Document Management Server

The XDM Server is built on top of the Mobicents JAIN SLEE container. This figure depicts the architecture of the XDM Server implementation.

The Functional Elements of the XML Document Management Server

Data Source Resource Adapter

This resource adapter implements the Data Source functional element.

The RA Type defines two activities objects, DocumentActivity and AppUsageActivity, both of which are used to fire events that signal that a document, element or attribute was updated.

The RA Type also defines a Service Building Block (SBB) RA interface to manage the users and documents stored in the XDM Server, and create activities, where events will be fired. The resource adapter will only fire events on activities that exist; that is, the RA won't create activities implicitly if a document is updated.

The RA Type also provides a base abstract implementation of the resource adapter, making it very simple to change the underlying resource used to store information, which is by default the internal JDBC datasource of the JBoss Application Server.

AppUsage Cache Resource Adaptor

This resource adapter stores the XCAP application usages installed in the server.

Each AppUsage is an object that includes the logic to validate XCAP documents that result from XCAP requests and are expensive to create; this resource adapter thus provides caching of AppUsages, using a pool model.

The resource adapter doesn't possess events or activities.

AppUsage Service

XCAP Application Usages are installed through a JAIN SLEE service, making it possible to add and/or remove application usages while the server is running.

Aggregation Proxy Service

This JAIN SLEE service implements the aggregation proxy functional element. It handles events fired by the Mobicents HTTP Servlet resource adapter and then uses two child SBBs: the User Profile Enabler SBB to retrieve information regarding the user needed for authentication/authorization of the XCAP request, and the Request Processor SBB, which handles the XCAP request.

Request Processor SBB

The Request Processor SBB implements the request processor functional element, providing a synchronous SBB interface to process XCAP requests. It uses the AppUsage Cache resource adapter to borrow AppUsage objects, and the Data Source resource adapter to retrieve or set documents stored in the server's data source.

User Profile Enabler SBB

This SBB provides a synchronous SBB interface used in JAIN SLEE child relations in order to retrieve user information, to be used on user authentication. Two different implementations of the interface are provided: the first considers whether the information is stored in the XDM Data Source, another interfaces with a Diameter Sh Server, such as IMS HSS.

XCAP Diff Subscription Control Service

This JAIN SLEE Service extends the abstract SIP Event Subscription Control component to handle SIP subscriptions on the xcap-diff event package.

The implementation architecture figure also contains client-side components:

The Mobicents SIP Presence Server is a free and open source implementation of a SIP Presence Server, as defined by the Internet Engineering Task Force (IETF), the Open Mobile Alliance (OMA), the 3rd Generation Partnership Project (3GPP) and the European Telecommunications Standards Institute (ETSI).

The SIP Presence Server is an entity that accepts, stores and distributes SIP presence information.

The SIP Presence Server is comprised of the following functional elements:

Presence Publication Control

This functional element manages the publication of presence events, which includes not only the handling of new publications, but also the refreshing, modification or removal of, already-published information.

Because the presence resource, which is also called a presentity, can have multiple publications simultaneously, such as some state published by a user agent or device, and some location data published by a Presence Network Agent (on behalf of the presentity), this element is also responsible for composing all of the different publications for the same resource.

In some presence networks, it may be of interest to allow resources to have a static presence state which is stored in the XDM Server. In cases like these, Presence Publication Control may need to interface with the XDM Server to retrieve and subscribe to (learn about changes to) that information, and use it when composing the final presence information document.

Presence Subscription Control

This functional element handles subscriptions to presence events or to the list of subscribers (watchers), for any specific resource. It is, of course, responsible for emitting notifications related to those subscriptions.

Presence authorization rules, which define if a subscription is allowed or rejected and, if allowed, define which transformations to the original presence events are needed, are stored on the XDM Server by the user. Thus, Presence Subscription Control needs to retrieve and subscribe to that information.

XDM Client Control

This last element is responsible for interfacing with the XDM Server that manages the user's XML documents, and is related to the main functions of the presence server. It is capable not only of retrieving a document or part of one, but also of subscribing to either updates of a single, specific document, or to a full collection of documents of a specific type or application.

The implementation of the Mobicents SIP Presence Server comprises the following functional elements:

The Two Services Which Compose the SIP Presence Server

Presence Publication Control Service

This JAIN SLEE service includes the root Service Building Block (SBB), PresencePublicationControlSbb, which is the implementation of the abstract SIP event PublicationControlSbb. It handles publications on the presence event package.

The PresencePublicationControlSbb provides the following capabilities:

  • It provides the logic to authorize a publication; however, it only authorizes PUBLISH requests when the request URI matches the PIDF document “entity” attribute.

  • It provides JAXB unmarshallers to validate and parse the PIDF document for the abstract PublicationControlSbb.

  • It demands that notifying subscribers occur through a child relation to the root SBB of the Presence Subscription Control Service.

  • Finally, it also provides an SbbLocalObject interface that can be used, in JAIN SLEE child relations, to obtain the composed presence information for a specific resource.

Presence Subscription Control Service.

This JAIN SLEE service includes the root SBB PresenceSubscriptionControlSbb, which is the implementation of the abstract SIP Event SubscriptionControlSbb. It handles subscriptions on the “presence” event package.

The standout SBB logic item is the usage of presence-rules documents, obtained through the XDM Client SBB child relation, in order to authorize subscriptions and transform the content notified[2]. It also defines a child relation to the root SBB of PresencePublicationService to retrieve the composed PIDF document for the subscription's notifier.

The SBB also provides an SbbLocalObject interface that can be used, in JAIN SLEE child relations, to make the presence event known to the subscribers of a specific resource.

The implementation architecture of the SIP Presence Server also contains client-side components:

Presence Client SBB

The PresenceClientSBB is the interface to a JAIN SLEE SBB intended to be used as a client for the Mobicents SIP Presence Server (and other servers compliant with same standards), in JAIN SLEE child relations.

Two implementations of this interface are provided: the InternalPresenceClientSBB that is used with applications running in the Mobicents SIP Presence Server JAIN SLEE container, and the ExternalPresenceClientSBB, used with applications running in a different JAIN SLEE container than the Mobicents SIP Presence Server.



[2] Note that this feature is not yet used.

Revision History
Revision 3.0Fri Jul 10 2009Eduardo Martins
Major update to include XDM Server authentication and authorization, creation of XCAP Application Usages, SIP Client configuration examples and Resource List Server.
Revision 2.0Fri Mar 06 2009Douglas Silas
First release of the "parameterized" and much-improved Mobicents documentation.
Revision 1.0Tue Jan 20 2009Douglas Silas
Creation of the Mobicents SIP Presence User Guide separate from the Mobicents Platform User Guide.