JBoss.orgCommunity Documentation

Chapter 2. Resource Adaptor Type

2.1. Activities
2.2. Events
2.3. Activity Context Interface Factory
2.4. Resource Adaptor Interface
2.5. Restrictions
2.6. Sbb Code Examples
2.6.1. Synchronous Operations
2.6.2. Asynchronous Operations

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.

There is a single events fired by XCAP Client Resource Adaptor, which represents a response to a request, received in a specific AsyncActivity instance.


Important

Spaces where introduced in Event Class column values, to correctly render the table. Please remove them when using copy/paste.

The Resource Adaptor's Activity Context Interface Factory is of type org.mobicents.slee.resource.xcapclient.XCAPClientActivityContextInterfaceFactory, it allows the SBB to retrieve the ActivityContextInterface related with a specific AsyncActivity instance. The interface is defined as follows:



        
package org.mobicents.slee.resource.xcapclient;
import javax.slee.ActivityContextInterface;
import javax.slee.FactoryException;
import javax.slee.UnrecognizedActivityException;
public interface XCAPClientActivityContextInterfaceFactory {
    public ActivityContextInterface getActivityContextInterface(
            AsyncActivity activity) throws NullPointerException,
            UnrecognizedActivityException, FactoryException;
}
     

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 shutdown() method exposed by the XCAP Client Resource Adaptor SBB Interface underlying XcapClient, throws a UnsupportedOperationException if invoked.

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 onResponseEvent(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();
        }
        
    }