JBoss.orgCommunity Documentation

Mobicents JAIN SLEE SIP Subscription Client Enabler User Guide


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 the Issue Tracker, against the product Mobicents JAIN SLEE SIP Subscription Client Enabler, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: JAIN_SLEE_ENABLER_SIPSubscriptionClient_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.

This section provides instructions on how to obtain and build the SIP Subscription Client Enabler from source code.

  1. Downloading the source code

    Use SVN to checkout a specific release source, the base URL is http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/enablers/sip-subscription-client, then add the specific release version, lets consider 1.0.0.BETA2.

    [usr]$ svn co http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/enablers/sip-subscription-client/1.0.0.BETA2 slee-enabler-sip-subscription-client-1.0.0.BETA2
  2. Building the source code

    Important

    Maven 2.0.9 (or higher) is used to build the release. Instructions for using Maven2, including install, can be found at http://maven.apache.org

    Use Maven to build the deployable unit binary.

    				    [usr]$ cd slee-enabler-sip-subscription-client-1.0.0.BETA2
    				    [usr]$ mvn install
    				    

    Once the process finishes you should have the deployable-unit jar file in the target directory, if Mobicents JAIN SLEE is installed and environment variable JBOSS_HOME is pointing to its underlying JBoss Application Server directory, then the deployable unit jar will also be deployed in the container.

    Important

    This procedure does not install the Enabler's dependencies

Similar process as for Section 2.2.1, “Release Source Code Building”, the only change is the SVN source code URL, which is http://mobicents.googlecode.com/svn/trunk/servers/jain-slee/enablers/sip-subscription-client.

This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.

In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.

Important

The Service's Sbb will be referred as the Parent Sbb in the following sections.

Relation betweeen Parent Sbb, Enabler instance and subscriptions to Presence Server, look as follows:

JAIN SLEE SIP Subscription Client Enabler design

The Mobicents JAIN SLEE SIP Subscription Client Enabler Sbb provides synchronous callbacks to the Parent's Sbb, and that can only be achieved if the Parent's SbbLocalObject extends a specific Java interface, deployed also by the Enabler, and provides it's SbbLocalObject to the Enabler's Sbb, through a specific method exposed by the latter interface. The Enabler stores the Parent's SbbLocalObject and uses it when a callback to the Parent's Sbb is needed.

The SbbLocalObject which must be used or extended by the Parent's Sbb is named org.mobicents.slee.enabler.sip.SubscriptionClientParentSbbLocalObject , which extends the javax.slee.SbbLocalObject and org.mobicents.slee.enabler.sip.SubscriptionClientParent interfaces, the latter declares the callbacks which must be implemented in the Parent's Sbb Abstract Class:



package org.mobicents.slee.enabler.sip;
public interface SubscriptionClientParent {
    public void subscribeSucceed(int responseCode, 
        SubscriptionClientChildLocalObject enabler);
    public void unsubscribeSucceed(int responseCode, 
        SubscriptionClientChildLocalObject enabler);
    public void onNotify(Notify notify, 
        SubscriptionClientChildLocalObject enabler);
    public void subscribeFailed(int responseCode, S
        ubscriptionClientChildLocalObject sbbLocalObject);
    public void resubscribeFailed(int responseCode, 
        SubscriptionClientChildLocalObject sbbLocalObject);
    public void unsubscribeFailed(int responseCode, 
        SubscriptionClientChildLocalObject sbbLocalObject);
}
        
        

The Parent Sbb must define following information in its descriptor

child reference

A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:



            <sbb-ref>
                <sbb-name>SipSubscriptionClientChildSbb</sbb-name>
                <sbb-vendor>org.mobicents</sbb-vendor>
                <sbb-version>1.0</sbb-version>
                <sbb-alias>sipSubClientChildSbb</sbb-alias>
            </sbb-ref>
            
            
child relation method

The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:



                <get-child-relation-method>                 
                    <sbb-alias-ref>sipSubClientChildSbb</sbb-alias-ref>
                    <get-child-relation-method-name>getSipSubscriptionClientChildRelation</get-child-relation-method-name>
                    <default-priority>0</default-priority>
                </get-child-relation-method>
                
                
Sbb Local Object

After the sbb-abstract-class element the Parent's SbbLocalObject interface name is defined:



        <sbb-local-interface>
            <sbb-local-interface-name>...</sbb-local-interface-name>
        </sbb-local-interface>
        
        

In the last chapter we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this chapter it is explained how to use the Enabler's Sbb, the Child Sbb.

Enabler performs following tasks:

manage subscription

send subscription events on behalf of Parent Sbb

automatic refresh

based on values exchanged between Enabler and Server, Enabler keeps track of subscription life time(expiration) and issues refresh requests to Server

JAIN SLEE SIP Subscription Client Enabler control flow

The Mobicents JAIN SLEE SIP Subscription Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.enabler.sip.SubscriptionClientChildSbbLocalObject , which extends the javax.slee.SbbLocalObject and org.mobicents.slee.enabler.sip.SubscriptionClientChild interfaces, the latter declares the methods which can be used to interact with the SIP Event Server:



package org.mobicents.slee.enabler.sip;
    public void setParentSbb(SubscriptionClientParentSbbLocalObject parent);
    public String getSubscriber();
    public String getEventPackage();
    public String getNotifier();
    public void subscribe(String subscriber, String subscriberdisplayName, String notifier, 
        int expires, String eventPackage, Map<String, String> eventsParameters, 
        String acceptedContentType, String acceptedContentSubtype) throws SubscriptionException;
    public void subscribe(String subscriber, String subscriberdisplayName, String notifier, 
        int expires, String eventPackage, Map<String, String> eventParameters, 
        String acceptedContentType, String acceptedContentSubtype, String contentType, 
        String contentSubType, String content) throws SubscriptionException;
    public void unsubscribe() throws SubscriptionException;
        
        
The setParentSbb(SubscriptionClientParentLocalObject parent); method:

Passes the Parent's SbbLocalObject, which will be used by the Child Sbb to provide async results. If not invoked after the child creation the Enabler won't be able to callback the Parent Sbb.

The getSubscriber(); method:

returns subscriber used for subscription in Server.

The getNotifier(); method:

returns notifier used as target for subscription.

The getEventPackage(); method:

returns event package used in subscrption, ie. presence or presence.winfo

The public void subscribe(String subscriber, String subscriberdisplayName, String notifier, int expires, String eventPackage, Map<String, String> eventsParameters , String acceptedContentType, String acceptedContentSubtype) throws SubscriptionException; method:

this method should be called to subscribe enabler to certain document in Server, optionally user may pass eventsParameters. Event Parameters are sent with each SUBSCRIBE. Accepted content type arguments indicate type of expected content generated by Presence Server. It throws exception in case of transport error or wrong arguments.

The public void subscribe(String subscriber, String subscriberdisplayName, String notifier, int expires, String eventPackage, Map<String, String> eventParameters, String acceptedContentType, String acceptedContentSubtype, String contentType, String contentSubType, String content) throws SubscriptionException; method:

this method is similar to previously defined method. In addition, this method allows to pass filter document in each SUBSCRIBE sent to Presence Server. This is useful, for instance in case of subscribtion to RLS service in XDM server. Content type arguments must match type of document passed to Presence Server.

The unsubscribe() throws SubscriptionException; method:

this method should be called to explicitly unsubscribe from publication. If enabler is refreshing, when this method is called, it will throw exception.

The Child Relation in the Parent Sbb Abstract Class is used to create and retrieve the Child Sbb, it is important to not forget to pass the Parent's SbbLocalObject to the Child after creation:



public SubscriptionClientChildLocalObject getPublicationClientChildSbb() {
    final ChildRelation childRelation = getSipPublicationClientChildRelation();
    if (childRelation.isEmpty()) {
        try {
            // creates new instance
            SubscriptionClientChildLocalObject sbb = 
                (SubscriptionClientChildLocalObject) childRelation.create();
            // passes the parent sbb local object to the child
            sbb.setParentSbb((SubscriptionClientParentLocalObject) 
                sbbContext.getSbbLocalObject());
            return sbb;
        } catch (Exception e) {
            tracer.severe("Failed to create child sbb", e);
            return null;
        }
    }
    else {
        return (SubscriptionClientChildLocalObject) 
            childRelation.iterator().next();
    }
}
        
        

The SbbLocalObject of the Child could also be stored in a CMP Field for the simplest retrieval, but unless you are going to reuse each instance several times it's better to have less state, specially in clustered environments.

Revision History
Revision 1.0Tue Oct 26 2010Eduardo Martins
Creation of the Mobicents JAIN SLEE SIP Subscription Client Enabler User Guide.