JBoss.orgCommunity Documentation
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();
}
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
endActivity()
method:Ends the activity and its related Activity Context.
There are three events fired by XCAP Client Resource Adaptor, which represents a response to each type of request, received in a specific AsyncActivity
instance.
Table 2.1. Events fired on the AsyncActivity
Name | Vendor | Version | Event Class | Description |
---|---|---|---|---|
GetResponse Event | org.mobicents | 2.0 | org.mobicents. slee.resource. xcapclient. ResponseEvent | A response to a XCAP GET request. |
PutResponse Event | org.mobicents | 2.0 | org.mobicents. slee.resource. xcapclient. ResponseEvent | A response to a XCAP PUT request. |
DeleteResponse Event | org.mobicents | 2.0 | org.mobicents. slee.resource. xcapclient. ResponseEvent | A response to a XCAP DELETE request. |
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;
}
createActivity()
method:Creates a new AsyncActivity
instance.
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;
}
setAuthenticationCredentials(Credentials)
method:Sets default authentication credentials to be used on XCAP requests, when those do not provide specific authentication credentials.
unsetAuthenticationCredentials()
method:Unsets default authentication credentials.
shutdown()
method:Unsupported operation.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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();
}
}