JBoss.orgCommunity Documentation

Mobicents JAIN SLEE XCAP Client Resource Adaptor 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 XCAP Client Resource Adaptor, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: JAIN_SLEE_XCAPClient_RA_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 Resource Adaptor Type is the interface which defines the contract between the RA implementations, the SLEE container, and the Applications running in it.

The name of the RA Type is XCAPClientResourceAdaptorType, its vendor is org.mobicents and its version is 2.0.

The RA Type uses its own XCAP Client API, with an implementation built on top of Apache HTTP Client 4.x, for further information about the Apache API refer to its website at http://hc.apache.org/httpcomponents-client/index.html.

The single activity object for XCAP Client Resource Adaptor is the org.mobicents.slee.resource.xcapclient.AsyncActivity interface. Through the activity an SBB can send multiple XCAP requests, and receive the related responses asynchronously. Due to the nature of SLEE activities, this RA activity acts like a queue of requests, allowing the processing of their responses - the events- in a serialized way

An activity starts on demand by an SBB, through the RA SBB Interface, and it ends when an SBB invokes its endActivity() method.

The AsyncActivity interface is defined as follows:



        
package org.mobicents.slee.resource.xcapclient;
import java.net.URI;
import org.mobicents.xcap.client.auth.Credentials;
import org.mobicents.xcap.client.header.Header;
public interface AsyncActivity {
    public void get(URI uri, Header[] additionalRequestHeaders,
            Credentials credentials);
    public void put(URI uri, String mimetype, String content,
            Header[] additionalRequestHeaders, Credentials credentials);
    public void put(URI uri, String mimetype, byte[] content,
            Header[] additionalRequestHeaders, Credentials credentials);
    public void putIfMatch(URI uri, String eTag, String mimetype,
            String content, Header[] additionalRequestHeaders,
            Credentials credentials);
    public void putIfMatch(URI uri, String eTag, String mimetype,
            byte[] content, Header[] additionalRequestHeaders,
            Credentials credentials);
    public void putIfNoneMatch(URI uri, String eTag, String mimetype,
            String content, Header[] additionalRequestHeaders,
            Credentials credentials);
    public void putIfNoneMatch(URI uri, String eTag, String mimetype,
            byte[] content, Header[] additionalRequestHeaders,
            Credentials credentials);
    public void delete(URI uri, Header[] additionalRequestHeaders,
            Credentials credentials);
    public void deleteIfMatch(URI uri, String eTag,
            Header[] additionalRequestHeaders, Credentials credentials);
    public void deleteIfNoneMatch(URI uri, String eTag,
            Header[] additionalRequestHeaders, Credentials credentials);
    public void endActivity();
}
     
The get(URI, Header[], Credentials) method:

Retrieves the XCAP resource specified by the URI parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The put(URI, String, String, Header[], Credentials) method:

Puts the provided XML content, in String format, in the XCAP resource specified by the URI parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The put(URI, String, byte[], Header[], Credentials) method:

Puts the provided XML content, in byte[] format, in the XCAP resource specified by the URI parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The putIfMatch(URI, String, String, String, Header[], Credentials) method:

Conditional put of the provided XML content, in String format, in the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag matches the provided eTag parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The putIfMatch(URI, String, String, byte[], Header[], Credentials) method:

Conditional put of the provided XML content, in byte[] format, in the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag matches the provided eTag parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The putIfNoneMatch(URI, String, String, String, Header[], Credentials) method:

Conditional put of the provided XML content, in String format, in the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag doesn't match the provided eTag parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The putIfNoneMatch(URI, String, String, byte[], Header[], Credentials) method:

Conditional put of the provided XML content, in byte[] format, in the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag doesn't match the provided eTag parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The delete(URI, Header[], Credentials) method:

Deletes the XCAP resource specified by the URI parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The deleteIfMatch(URI, String, Header[], Credentials) method:

Conditional delete of the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag matches the provided eTag parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The deleteIfNoneMatch(URI, String, Header[], Credentials) method:

Conditional delete of the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag doesn't match the provided eTag parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The endActivity() method:

Ends the activity and its related Activity Context.

The XCAP Client Resource Adaptor interface, of type org.mobicents.slee.resource.xcapclient.XCAPClientResourceAdaptorSbbInterface, which an SBB uses to create new AsyncActivity instances or send synchronous requests, its interface is defined as follows:



        
package org.mobicents.slee.resource.xcapclient;
import javax.slee.resource.ActivityAlreadyExistsException;
import javax.slee.resource.StartActivityException;
import org.mobicents.xcap.client.XcapClient;
public interface XCAPClientResourceAdaptorSbbInterface extends XcapClient {
    public AsyncActivity createActivity()
            throws ActivityAlreadyExistsException, StartActivityException;
}
    

The XCAP Client Resource Adaptor interface extends type org.mobicents.xcap.client.XcapClient, its interface is defined as follows:



        
package org.mobicents.xcap.client;
import java.io.IOException;
import java.net.URI;
import org.mobicents.xcap.client.auth.Credentials;
import org.mobicents.xcap.client.header.Header;
public interface XcapClient {
    public void setAuthenticationCredentials(Credentials credentials);
    public void unsetAuthenticationCredentials();
    public void shutdown();
    public XcapResponse get(URI uri, Header[] additionalRequestHeaders,
            Credentials credentials) throws IOException;
    public XcapResponse put(URI uri, String mimetype, String content,
            Header[] additionalRequestHeaders, Credentials credentials)
            throws IOException;
    public XcapResponse put(URI uri, String mimetype, byte[] content,
            Header[] additionalRequestHeaders, Credentials credentials)
            throws IOException;
    public XcapResponse putIfMatch(URI uri, String eTag, String mimetype,
            String content, Header[] additionalRequestHeaders,
            Credentials credentials) throws IOException;
    public XcapResponse putIfMatch(URI uri, String eTag, String mimetype,
            byte[] content, Header[] additionalRequestHeaders,
            Credentials credentials) throws IOException;
    public XcapResponse putIfNoneMatch(URI uri, String eTag, String mimetype,
            String content, Header[] additionalRequestHeaders,
            Credentials credentials) throws IOException;
    public XcapResponse putIfNoneMatch(URI uri, String eTag, String mimetype,
            byte[] content, Header[] additionalRequestHeaders,
            Credentials credentials) throws IOException;
    public XcapResponse delete(URI uri, Header[] additionalRequestHeaders,
            Credentials credentials) throws IOException;
    public XcapResponse deleteIfMatch(URI uri, String eTag,
            Header[] additionalRequestHeaders, Credentials credentials)
            throws IOException;
    public XcapResponse deleteIfNoneMatch(URI uri, String eTag,
            Header[] additionalRequestHeaders, Credentials credentials)
            throws IOException;
}
    
The setAuthenticationCredentials(Credentials) method:

Sets default authentication credentials to be used on XCAP requests, when those do not provide specific authentication credentials.

The unsetAuthenticationCredentials() method:

Unsets default authentication credentials.

The shutdown() method:

Unsupported operation.

The get(URI, Header[], Credentials) method:

Retrieves the XCAP resource specified by the URI parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The get(URI, Header[], Credentials) method:

Retrieves the XCAP resource specified by the URI parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The put(URI, String, String, Header[], Credentials) method:

Puts the provided XML content, in String format, in the XCAP resource specified by the URI parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The put(URI, String, byte[], Header[], Credentials) method:

Puts the provided XML content, in byte[] format, in the XCAP resource specified by the URI parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The putIfMatch(URI, String, String, String, Header[], Credentials) method:

Conditional put of the provided XML content, in String format, in the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag matches the provided eTag parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The putIfMatch(URI, String, String, byte[], Header[], Credentials) method:

Conditional put of the provided XML content, in byte[] format, in the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag matches the provided eTag parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The putIfNoneMatch(URI, String, String, String, Header[], Credentials) method:

Conditional put of the provided XML content, in String format, in the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag doesn't match the provided eTag parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The putIfNoneMatch(URI, String, String, byte[], Header[], Credentials) method:

Conditional put of the provided XML content, in byte[] format, in the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag doesn't match the provided eTag parameter. The request mimetype needs to be provided, according to the content type to be put. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The delete(URI, Header[], Credentials) method:

Deletes the XCAP resource specified by the URI parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The deleteIfMatch(URI, String, Header[], Credentials) method:

Conditional delete of the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag matches the provided eTag parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The deleteIfNoneMatch(URI, String, Header[], Credentials) method:

Conditional delete of the XCAP resource specified by the URI parameter. The request only succeeds if the XCAP resource entity tag doesn't match the provided eTag parameter. Additional HTTP headers, to be added in the XCAP request, and authentication credentials can be specified too.

The following code examples shows how to use the Resource Adaptor Type for common functionalities

The following code examples the usage of the RA's SBB Interface to send synchronous XCAP requests:



            
        // create auth credentials
        Credentials credentials = ra.getCredentialsFactory().getHttpDigestCredentials(username,password);
            
        // create doc uri       
        String documentSelector = DocumentSelectorBuilder.getUserDocumentSelectorBuilder("resource-lists", userName, documentName).toPercentEncodedString(); 
        UriBuilder uriBuilder = new UriBuilder()
            .setSchemeAndAuthority("http://127.0.0.1:8080")
            .setXcapRoot("/mobicents")
            .setDocumentSelector(documentSelector);
        URI documentURI = uriBuilder.toURI();
        
        // the doc to put
        String initialDocument =
            "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
            "<resource-lists xmlns=\"urn:ietf:params:xml:ns:resource-lists\">" +
                "<list name=\"friends\"/>" +
            "</resource-lists>";                        
        
        // put the document and get sync response
        XcapResponse response = ra.put(documentURI,"application/resource-lists+xml",initialDocument,null,credentials);
        
        // check put response
        if (response != null) {
            if(response.getCode() == 200 || response.getCode() == 201) {
                log.info("document created in xcap server...");
            } else {
                log.severe("bad response from xcap server: "+response.toString());
            }
        } else {
            log.severe("unable to create document in xcap server...");
        }
                    
        // let's create an uri selecting an element
        // create uri
        String elementSelector = new ElementSelectorBuilder()
            .appendStepByName("resource-lists")
            .appendStepByAttr("list","name","friends")
            .appendStepByAttr("entry","uri","sip:alice@example.com")
            .toPercentEncodedString();
        URI elementURI = uriBuilder.setElementSelector(elementSelector).toURI();
        
        // put an element and get sync response
        String element = "<entry uri=\"sip:alice@example.com\" xmlns=\"urn:ietf:params:xml:ns:resource-lists\"/>";
        response = ra.put(elementURI,ElementResource.MIMETYPE,element,null,credentials);
        
        // check put response
        if (response != null) {
            if(response.getCode() == 201) {
                log.info("element created in xcap server...");
            } else {
                log.severe("bad response from xcap server: "+response.toString());
            }
        } else {
            log.severe("unable to create element in xcap server...");
        }
                
        // get the document and check content is ok
        response = ra.get(documentURI,null,credentials);
        
        // check get response       
        if (response != null) {
            if(response.getCode() == 200) {
                log.info("document successfully retreived in xcap server.");
                // delete the document
                ra.delete(documentURI,null,credentials);        
            } else {
                log.severe("bad response from xcap server: "+response.toString());
            }
        } else {
            log.severe("unable to retreive document in xcap server...");
        }
        

The following code examples the usage of the AsyncActivity to send async XCAP requests, the optimal way to use the RA, since it doesn't block the SLEE container event routing threads:



            
        // now we will use JAXB marshalling and unmarshalling too
                        
        // let's create a list containing  someone
        ObjectFactory of = new ObjectFactory();
        ListType listType = of.createListType();
        listType.setName("enemies");
        EntryType entry = of.createEntryType();
        entry.setUri("sip:winniethepooh@disney.com");
        listType.getListOrExternalOrEntry().add(entry);
        
        // create the uri selecting the new element
        String elementSelector = new ElementSelectorBuilder()
            .appendStepByName("resource-lists")
            .appendStepByAttr("list","name","enemies")
            .toPercentEncodedString();
        String documentSelector = DocumentSelectorBuilder.getUserDocumentSelectorBuilder("resource-lists", userName, documentName).toPercentEncodedString();
        UriBuilder uriBuilder = new UriBuilder()
        .setSchemeAndAuthority("http://127.0.0.1:8080")
        .setXcapRoot("/mobicents")
        .setDocumentSelector(documentSelector)
        .setElementSelector(elementSelector);
        URI uri = uriBuilder.toURI();
        
        // marshall content to byte array
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        jAXBContext.createMarshaller().marshal(listType, baos);
        
        // lets put the element using the sync interface
        XcapResponse response = ra.put(uri,ElementResource.MIMETYPE,
            baos.toByteArray(),null,credentials);
        // check put response
        if (response != null) {
            if(response.getCode() == 201) {
                log.info("list element created in xcap server...");
            } else {
                log.severe("bad response from xcap server: "+response.toString());
            }
        } else {
            log.severe("unable to create list element in xcap server...");
        }
        
        // now lets get it using the async interface
        
        // get a async request activity from the xcap client ra
        AsyncActivity activity = ra.createActivity();
        
        // attach this sbb entity to the activity's related aci 
        ActivityContextInterface aci = acif.getActivityContextInterface(activity);
        aci.attach(sbbContext.getSbbLocalObject());
        
        // send request
        activity.get(uri,null,credentials);
        

And the next code snippet examples the handling of the ResponseEvent, and the ending of the activity instance:



            
    public void onGetResponseEvent(ResponseEvent event, ActivityContextInterface aci) {
                
        // check put response
        XcapResponse response = event.getResponse();
        if (response != null) {
            if(response.getCode() == 200) {
                log.info("list element retreived from xcap server...");
            } else {
                log.severe("bad response from xcap server: "+response.toString());
            }
        } else {
            log.severe("unable to create list element in xcap server...");
        }
                        
        // end the activity
        AsyncActivity activity = (AsyncActivity)aci.getActivity();
        if (activity != null) {
            activity.endActivity();
        }
        
    }
        

This chapter documents the XCAP Client Resource Adaptor Implementation details, such as the configuration properties, the default Resource Adaptor entities, and the JAIN SLEE 1.1 Tracers and Alarms used.

The name of the RA is XCAPClientResourceAdaptor, its vendor is org.mobicents and its version is 2.0.

There is a single Resource Adaptor Entity created when deploying the Resource Adaptor, named XCAPClientRA.

The XCAPClientRA entity is also bound to Resource Adaptor Link Name XCAPClientRA, to use it in an Sbb add the following XML to its descriptor:



        <resource-adaptor-type-binding>
            <resource-adaptor-type-ref>
                <resource-adaptor-type-name>
                    XCAPClientResourceAdaptorType
                </resource-adaptor-type-name>
                <resource-adaptor-type-vendor>
                    org.mobicents
                </resource-adaptor-type-vendor>
                <resource-adaptor-type-version>
                    2.0
                </resource-adaptor-type-version>
            </resource-adaptor-type-ref>
            <activity-context-interface-factory-name>
                slee/resources/xcapclient/2.0/acif
            </activity-context-interface-factory-name>
            <resource-adaptor-entity-binding>
                <resource-adaptor-object-name>
                    slee/resources/xcapclient/2.0/sbbrainterface
                </resource-adaptor-object-name>
                <resource-adaptor-entity-link>
                    XCAPClientRA
                </resource-adaptor-entity-link>
            </resource-adaptor-entity-binding>
        </resource-adaptor-type-binding>
    

  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/resources/xcap-client, then add the specific release version, lets consider 2.4.1.FINAL.

    [usr]$ svn co http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/resources/xcap-client/2.4.1.FINAL slee-ra-xcap-client-2.4.1.FINAL
  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-ra-xcap-client-2.4.1.FINAL
    				    [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.

Similar process as for Section 4.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/resources/xcap-client.

Revision History
Revision 1.0Tue Dec 30 2009Eduardo Martins
Creation of the Mobicents JAIN SLEE XCAP Client RA User Guide.