24 Using the XCAP Interfaces

Oracle Communications Converged Application Server provides APIs that let you access an XML Document Management Server (XDMS). The XDMS handles the management of user-generated XML documents stored on the network, such as authorization rules and contact and group lists (also referred to as resource lists).

The XML Configuration Access Protocol Server (XCAP server), provides an interface that allows for the manipulation of service-related data stored as XML documents within the XDMS. The XCAP specification defines how an HTTP address (or URI) can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted.

Each XCAP resource on a XCAP server has an associated application. For the associated application to use the XCAP resources, the application must have the following information:

An Application Unique ID (AUID), which uniquely identifies the application usage, must be created.
The XML schema must be defined.
The default namespace binding, which maps the namespace prefixes to the namespace URIs, must be set.
The MIME type of the document must be defined.
The XCAP server must be able to validate the content of each XCAP document that is being modified.
The data in the XML document must have a well defined semantic.
Naming conventions for XCAP client URIs must be set.
Resource interdependencies, how changes to one resource will effect other resources, has to be determined.

The following operations are supported using XCAP:

Retrieve an item
Delete an item
Modify an item
Add an item

The XCAP addressing mechanism is based on XML Path Language (XPath), a query language for selecting nodes in XML documents. The operations above can be executed on XML documents and elements. Operations to XML attributes are not supported, however, attributes can be handled indirectly by modifying the elements that contain them.

About XCAP and VoLTE

Converged Application Server provides two levels of XCAP support: Access to the XDMS using a base XCAP API that is not specific to any schema, and a high level API providing support for GSMA IR.92 supplementary services using VoLTE as supported by the Service Foundation Toolkit (SFT). The VoLTE version of the XCAP API supports the following supplementary services:

3GPP TS 24.611 Communications Diversion
3GPP TS 24.604 Communication Barring
3GPP TS 24.607 Originating Identification Presentation and Originating Identification Restriction
3GPP TS 24.608 Terminating Identification Presentation and Terminating Identification Restriction
3GPP TS 24.615 Communication Waiting

The supported RFC 4825 functions are:

Partial operations (adding and removing XML elements)
Data validation
Support for 409 XCAP error responses as defined in Section 11 of RFC 4825

Creating and Accessing an XCAP Client

XCAPClient is the main Java class for accessing an XDMS with XCAP. The XCAPClient class functions as a gateway to create XCAP connections, documents, and the XCAP root of the requesting URI. Any Java class that has access to the CommunicationService can obtain an instance of XCAPClient and establish a connection to an XDMS.

Example 24-1 illustrates the usage of XCAPClient.

Example 24-1 Creating an XCAP Connection Using XCAPClient

@CommunicationBean
public class MyCommunicationBean {
 
  @Context CommunicationService service;
 
  @CommunicationEvent(type = CommunicationEvent.Type.INITIALIZATION, communicationType = 
  Conversation.class)
  public void init() throws NamingException {
     XCAPClient client = service.getXcapClient();
     XcapRoot root = client.createXcapRoot("http://example.com/xcap");
     XcapConnection connection = client.createConnection(root);
  }

In this example the CommunicationService calls getXcapClient(), which returns a reference via the client object variable. XCAPClient is the starting point from which to create XCAP connections.

XCAPClient client = service.getXcapClient();

The createXcapRoot() method creates the XCAP root of the requesting URI.

XcapRoot root = client.createXcapRoot("http://example.com/xcap");

To create an HTTP connection to an XDMS, use an instance of XCAPConnection. You can use XCAPConnection to send a request to the XDMS, and perform the following functions:

Authenticate the request with the XDMS.
Send the request to the XDMS.
Receive the response from the XDMS.

To create the connection, use the createConnection(root) method. The example below returns the XCAP root to XCapConnection via the connection object reference variable.

XcapConnection connection = client.createConnection(root);

Fetching, Creating, and Deleting Resources With XCAP

The following examples fetch, remove, and modify the simservs XML document, which contains data associated with one or more supplementary services (SimservTypes). You can also perform these actions on the simserv XML document's elements.

XCAP resources are analogous to HTTP resources, and can be XML documents, an element in an XML document, or an attribute of an element. You use the HTTP GET, PUT, and DELETE methods to fetch, create, or replace and remove XCAP resources. The following sections describe the steps required to create, fetch, or delete a resource from an XDMS using XCAP:

Fetching Documents from the XDMS
Creating or Replacing Documents in the XDMS
Deleting a Document from the XDMS

Fetching Documents from the XDMS

To fetch (or retrieve) an XCAP resource:

Create the XCAP URI of the resource.

The URI must identify the XCAP resource.
Authenticate the XCAP request against the XDMS.
Create the HTTP GET request.
Send the XCAP request to the XDMS.
Process the HTTP response from the XDMS.

The request is successfully processed when it returns a HTTP status code of 200.

Example 24-2 shows the code to fetch a document from an XDMS.

Example 24-2 Fetching XDMS Document

...
  @CommunicationEvent(type = CommunicationEvent.Type.INITIALIZATION, communicationType = 
  Conversation.class)
  public void init() throws NamingException {
     XCAPClient client = service.getXcapClient();
     XcapDocumentSelector selector = client.createDocumentSelector(AUID, XUI, documentName);
     SimServsDocument document = client.createDocument(selector, contentType);
     XcapRequest request = client.createRequest(document, XcapRequest.Operation.FETCH);
     XcapConnection conn = client.createConnection(client.createXcapRoot(XCAP_ROOT));
     XcapResponse resp = conn.send(request);        
     if (resp.getStatus() == 200) {
     }
  }
...

The method in this example performs the following actions:

The client object reference variable—which refers to the XCapClient class—makes a series of method calls to createDocumentSelector(), createDocument(), createRequest(), and createConnection(), and returns arguments as shown. Of these statements, the following fetches the XDMS document via the XcapRequest object's Operation.FETCH, which fetches the resource.

XcapRequest request = client.createRequest(document, XcapRequest.Operation.FETCH);

If the request is successful, the response data populates XCAPDocument, and the FETCH operation retrieves the specified XML document.

Creating or Replacing Documents in the XDMS

The process to create an XDMS document is similar to the fetch operation shown in Example 24-2. The difference is that you use the Operation.SYNC argument to create or replace the simserv document in the XDMS.

To create or replace a document:

Create a local representation of the XCAP resource, including a representation of the XML content, an XCAP URI, and the content type.
Authenticate the XCAP request against the XDMS.
Create the HTTP PUT request.
Send the XCAP request to the XDMS.
Process the HTTP response from the XDMS.

Example 24-3 creates a document in the XDMS by converting an XML input stream.

Example 24-3 Creating or Replacing XCAP Documents

...
@CommunicationEvent(type = CommunicationEvent.Type.INITIALIZATION, communicationType = 
Conversation.class)
public void createDocument() throws XcapException, IOException {
    XCAPClient client = service.getXcapClient();
    XcapDocumentSelector selector = client.createDocumentSelector(AUID, XUI, documentName);
    SimServsDocument document = client.createDocument(selector, contentType);
    XcapRequest request = client.createRequest(document, XcapRequest.Operation.SYNC);
    XcapConnection conn = client.createConnection(client.createXcapRoot(XCAP_ROOT));
    XcapResponse resp = conn.send(request);        
    if (resp.getStatus() == 201) {
    }
 }

Example 24-4 creates a simserv document of the specified MIME type (Internet media type).

Example 24-4 Creating XCAP Documents Using the XCAP API

public void createByApi() throws XcapException, IOException { String XUI = 
"sip:bob@oracle.com";
  XCAPClient  client = service.getXcapClient(); 
  XcapDocumentSelector selector = client.createDocumentSelector( SimServsDocument.AUID, XUI,
  SimServsDocument.FILENAME); 
  SimServsDocument document = xcapClient.createDocument(Selector, SimServsDocument.MIMETYPE);
...

Deleting a Document from the XDMS

To delete a simserv document you construct an XCAP URI identifying its location in the XDMS. To delete a simserv document from the XDMS:

Create the XCAP URI of the resource.

The URI must identify the XCAP resource.
Authenticate the XCAP request against the XDMS.
Create the HTTP DELETE request.
Send the XCAP request to the XDMS.
Process the HTTP response from the XDMS.

The request is successfully processed when it returns a HTTP status code of 2xx or 4xx.

Example 24-5 removes the element from the XML document stored in the XDMS using the XcapRequest class's Operation.DELETE argument.

Example 24-5 Deleting Documents From the XDMS

...
XcapRequest request = client.createRequest(rule, XcapRequest.Operation.DELETE);
XcapConnection conn = client.createConnection(client.createXcapRoot(XCAP_ROOT));
XcapResponse resp = conn.send(request);
...

Using XCAP for IR.92 Supplementary Services

The 3GPP TS 24.623 specification defines usage of the XCAP protocol for the manipulation of XML data related to the following IR.92 supplementary services:

3GPP TS 24.604: Communication Diversion

3GPP TS 24.607: Originating Identification Presentation and Originating Identification Restriction
3GPP TS 24.608: Terminating Identification Presentation and Terminating Identification Restriction
3GPP TS 24.611: Anonymous Communication Rejection and Communication Barring.
3GPP TS 24.615: Communication Waiting

The 3GPP TS 24.623 specification defines the above supplementary services are as sub-trees of the simservs XML document. XCAP maps XML document sub-trees and element attributes to HTTP URIs so that these components can be directly accessed by clients using the HTTP protocol. In order to maintain synchronization with the network elements and other terminals that the user might be using, the UE subscribes to changes in the XCAP simserv documents.

The following examples illustrate the sub-trees defining the supplementary services in the simserv XML document schema.

3GPP TS 24.607 Originating Identity

Example 24-6 illustrates the Originating Identity sub-tree of the simservs XML document defined by the 3GPP TS 24.623 specification.

Example 24-6 Originating Identity Sub-Tree

<?xml version="1.0" encoding="UTF-8"?>
<simservs xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
 
   <originating-identity-presentation active="true"/>
 
   <originating-identity-presentation-restriction active="true">
       <default-behaviour>presentation-restricted</default-behaviour>
   </originating-identity-presentation-restriction>
 
</simservs>

3GPP TS 24.608: Terminating Identification Presentation and Restriction

Example 24-7 illustrates the Terminating Identification Presentation and Restriction sub-tree of the simservs XML document defined by the 3GPP TS 24.623 specification.

Example 24-7 Terminating Identification Presentation and Restriction Sub-Tree

<?xml version="1.0" encoding="UTF-8"?>
<simservs xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
 
   <terminating-identity-presentation active="true"/>
 
   <terminating-identity-presentation-restriction active="true">
       <default-behaviour>presentation-restricted</default-behaviour>
   </terminating-identity-presentation-restriction>
 
</simservs>

3GPP TS 24.615 Communication Waiting

Example 24-8 illustrates the Communication Waiting sub-tree of the simservs XML document defined by the 3GPP TS 24.623 specification.

Example 24-8 Communication Waiting Sub-Tree

<?xml version="1.0" encoding="UTF-8"?>
<simservs xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <communication-waiting active="true"/>
</simservs>

XCAP Supplementary Service APIs

Table 24-1 lists the supplementary service Java classes available in the com.oracle.sft.xcap.client.simservs package. Refer to the Converged Application Server API Reference to learn more about these Java classes and their usage.

Table 24-1 Java Classes To Create Supplementary Service Rules

Class	Description
CommunicationDiversion	Describes a ruleset and no-reply timer for communication diversion.
CommunicationWaiting	Describes a ruleset for the communication waiting service.
IncomingCommunicationBarring	Describes a ruleset for barring of incoming communication.
OriginatingIdentityPresentation	Describes a ruleset for barring of originating requests.
OriginatingIdentityPresentationRestriction	Describes a ruleset for restriction of originating identity presentation.
OutgoingCommunicationBarring	Describes a ruleset for barring of outgoing communication.
TerminatingIdentityPresentation	Describes a ruleset for terminating identity presentation.
TerminatingIdentityPresentationRestriction	Describes a ruleset for restriction of terminating identity presentation.

Creating Supplementary Service Rules

To create or modify a supplementary service's sub-tree in the simserv XML, use the appropriate supplementary service Java class in combination with the SimServs class's createAbsService() method.

Example 24-9 disables the Communication Waiting service. In this example the simServs.createAbsService() returns a CommunicationWaiting instance object. The object is assigned to the cw variable. The SimServ object's setActive(false) method disables the service.

Example 24-9 Creating a CommunicationWaiting Service

CommunicationWaiting cw = simServs.createAbsService(CommunicationWaiting.class);
cw.setActive(false);

Example 24-10 implements the following services:

Communication Waiting is set to false, disabling the service.
Originating Identification Presentation is enabled.
Originating Identification Restriction uses its default behavior, which does not restrict the presentation of the caller's identity.
Terminating Identity Presentation allows the callee (the terminating identity) to receive the caller's (the originating identity) identification.

Example 24-10 Implementing Supplementary Service Rules with XCAP

...
//Disable the Communication Waiting service
CommunicationWaiting cw = simServs.createAbsService(CommunicationWaiting.class);
cw.setActive(false);

//Enable Originating Identity Presentation
OriginatingIdentityPresentation oip = simServs.createAbsService(OriginatingIdentityPresentation.class);
oip.setActive(true);

//The caller's ID is not restricted
OriginatingIdentityPresentationRestriction oipr = 
simServs.createAbsService(OriginatingIdentityPresentationRestriction.class);
oipr.setDefaultBehaviour(DefaultBehaviour.PRESENTATION_NOT_RESTRICTED);

//Enable the calling party to receive identification information
TerminatingIdentityPresentation tip = simServs.createAbsService(TerminatingIdentityPresentation.class);
TerminatingIdentityPresentationRestriction tipr = 
simServs.createAbsService(TerminatingIdentityPresentationRestriction.class);
...

Adding and Editing Elements

XCAP maps XML document sub-trees and elements to HTTP URIs so that these components can be directly accessed by clients using the HTTP protocol. You can perform get, fetch, and delete operations on XML elements containing the specified attributes. The com.oracle.sft.xcap.client.Attributable interface identifies an element as having attributes.

Example 24-11 illustrates the use of the setByAttrName() method to set the name of an XML attribute's predicate. A predicate is similar to an If/Then statement. If the predicate is TRUE, the element is selected. If the predicate is FALSE, it is excluded. The result of the predicate is only valid if the result is unique, and the uniqueness must be enforced. Element selection without predicates returns a list.

In this example two Communication Diversion rules are stored in the XDMS, and are identified using the IDs rule66 and rule88. The code shown in Example 24-11 creates a Communication Diversion rule using the rule66 identifier, which it stores in the r1 variable. The r1 variable is then used to call the setByAttrName() method, to set the attribute using the rule66 identifier. The example code then performs a FETCH operation using the XcapRequest interface to retrieve the element whose ID is labelled rule66 from the XDMS.

Example 24-11 Fetching a Specific Element From the XDMS

XcapDocumentSelector ds = client.createDocumentSelector(SimServsDocument.AUID,
XUI, SimServsDocument.FILENAME);
SimServsDocument d = client.createDocument(ds, SimServsDocument.MIMETYPE);
SimServs ss = d.getSimservs();
CommunicationDiversion cd1 = ss.createAbsService(CommunicationDiversion.class);
RuleSet rs1 = cd1.createRuleset();
Rule r1 = rs1.createRule("rule66");

// Set attribute tester
r1.setByAttrName("id");
XcapRequest req1 = client.createRequest(r1, XcapRequest.Operation.FETCH);
XcapConnection conn1 = client.createConnection(client.createXcapRoot(XCAP_ROOT));
XcapResponse resp1 = null;
    try 
{
  resp1 = conn1.send(req1);
} catch (XcapException e) {
  e.printStackTrace();
  fail("Exception when send FETCH request: " + req1.getResource().getUrl());
}
assertThat(resp1, notNullValue());
assertThat(resp1.getStatus(), is(200));
assertThat(r1.getId(), is("rule66"));
assertThat(r1.getConditions(), notNullValue());
assertThat(r1.getConditions().getConditions(Identity.class).size(), is(1));
Condition cccc = r1.getConditions().getConditions(Identity.class).iterator().next();
assertThat(cccc, instanceOf(Identity.class));
List<One> theOnesss = ((Identity) cccc).getOnes();
assertThat(theOnesss.get(0).getId(), is("sip:bob@example.com"));
assertThat(rs1.getRules().size(), is(1));
assertThat(rs1.getRule("rule88"), nullValue());

// Fetch from Busy
rs1 = cd1.createRuleset();
r1 = rs1.createRule("rule66");
r1.setByAttrName("id");
Busy b = null;
try {
      b = r1.createConditions().createCondition(Busy.class);
    } catch (XcapException e) {
      e.printStackTrace();
      fail("Exception");
    }
    req1 = client.createRequest(b, FETCH);
    try {
      resp1 = conn1.send(req1);
    } catch (XcapException e) {
      e.printStackTrace();
      fail("Exception when send FETCH request: " + req1.getResource().getUrl());
    }
    assertThat(resp1.getStatus(), is(200));
  }

Validating Data

Proper URI generation and XML data validation are key to working with XCAP documents. When a client performs an XCAP operation, it must use the proper HTTP request. In the case of document/node creation or updates, the client should ensure that the resulting document remains consistent with the data constraints imposed by the application. An XCAP server must not allow any modification that breaks any data constraint, and an XCAP client must not make any modification that will lead to issues with the application-defined schema. While data validation sent and received using XCAP is optional, it is strongly recommended that you use data validation to ensure that the resulting XCAP documents retain their integrity.

Note:

The XCAP API does not cache any data fetched from the XCAP server. Validation is only performed using related schemas. When validating data, the entire XML document is validated even if only a single element is being fetched or updated.

Example 24-12 creates the AllMedia, NoMedia and Media elements, however, only one of them can legally exist in the XCAP document. The code below illustrates the use of an exception which, when validation fails, prevents the creation or modification of the XML file in the XDMS. Example 24-13 illustrates the XML document containing the AllMedia, NoMedia and Media sub-elements.

Example 24-12 Create and Validate the AllMedia, NoMedia, and Media Elements

. . .
SupportedMediaType smt = mc.getMediaType(); 
smt.setAllMedia(); 
smt.setNoMedia(); 
smt.createMedia().setValue("audio"); 
smt.createMedia().setValue("video"); 
 
XcapRequest reqCC = client.createRequest(cc, XcapRequest.Operation.SYNC); 
XcapConnection connCC = client.createConnection(client.createXcapRoot(XCAP_ROOT)); 
 
/** 
* Set to validate. If there are no validation errors, the XCAP connection
* requestis made, and a new document is created.
*/
connCC.setValidation(true); 
 
XcapResponse respCC = null; 
try { 
    respCC = connCC.send(reqCC); 
    fail("Exception when send SYNC request: " + reqCC.getResource().getUrl());
} catch (XcapException e) { 
    e.printStackTrace(); 
}
. . .

Example 24-13 Simserv Supported-Media-Type Element

. . .
<xs:complexType name="supported-media-type">
     <xs:choice>
          <xs:element name="all-media" type="ss:empty-element-type" />
          <xs:element name="no-media" type="ss:empty-element-type" />
          <xs:sequence maxOccurs="unbounded">
               <xs:element name="media" type="ss:media-type" />
          </xs:sequence>
<xs:any namespace="##other" processContents="lax" />
     </xs:choice>
</xs:complexType>
. . .

XCAP Authentication and Authorization

Authentication consists of determining whether a user wishing to perform certain operations is who he or she claims to be. Authorization consists of determining whether an authenticated user is allowed to perform the requested operation. User authorization is performed by the relevant XDMS the processes requests coming from authenticated users. XCAP user authentication uses XCAP User Identity (XUI) to perform authentication. The XUI typically takes the form of a TEL URI or SIP URI.

Using Digest Authentication

The XCAP APIs provide support for both Basic and Digest authentication (as defined in RFC 2617). Digest authentication uses a simple challenge-response mechanism to verify the identity of a user over SIP or HTTP, and requires a user name and password. Clients must implement digest authentication, assuring interoperability with servers that challenge the client.

Table 24-2 lists the method to create a an XCAP connection using Basic/Digest authentication available via com.oracle.sft.xcap.client.XcapConnection.

Table 24-2 XCAP Basic/Digest Authentication in XcapConnection Interface

Method	Description
`setCredentials(String userName, String password)`	Sets the user name and password for Basic/Digest authentication.

Example 24-14 illustrates the use of the Basic/Digest authentication APIs.

Example 24-14 Basic/Digest Authentication

...
XCAPClient xcapClient = new XcapClientImpl();
XcapRequest request = xcapClient.createRequest(document,
                                               XcapRequest.Operation.SYNC);
XcapConnection conn = xcapClient.createConnection(xcapClient
String userName = "alice";
String password = "myPassword";
conn.setCredentials(userName, password);
XcapResponse resp = conn.send(request);
...

Using Transport Layer Security

Section 14 of RFC 4825 specifies that XCAP clients must implement Transport Layer Security (TLS), ensuring interoperability with servers that challenge the client. TLS is a cryptographic protocol that provides communication security over the Internet. TLS encrypts segments of network connections at the Application Layer for the Transport Layer, using asymmetric cryptography for key exchange, symmetric encryption for privacy, and message authentication codes for message integrity.

To implement TLS, refer to the chapter on configuring Secure Sockets Layer (SSL) in Oracle Fusion Middleware Securing Oracle WebLogic Server for more information.

Using X-3GPP-Asserted-Identity Header Authentication

The X-3GPP-Asserted-Identity header functions for HTTP requests in the same manner that the P-Asserted-Identity header functions for SIP requests. When the XCAP server receives an incoming HTTP request having a X-3GPP-Asserted-Identity header, it first verifies that the request was received from a trusted host. If the host was trusted, the server asserts the user's identity using the information in the header, authenticates the user, and logs the user in if that user is authorized to access the requested resource.

To insert X-3GPP-Asserted-Identity headers into the HTTP request, use the addHeader() or addHeaders() methods. X-3GPP-Asserted-Identity headers are sent to the XCAP server, and, if authenticated, are put into effect. If the X-3GPP-Asserted-Identity header fails to authenticate the request, the XCAP request may revert to Digest authentication if the XCAP server is configured to do so.

To use X-3GPP-Asserted-Identity authentication you must configure Converged Application Server to handle this header type for authentication. To learn more, see the chapter on configuring 3GPP HTTP authentication assertion providers in Converged Application Server Security Guide.

Note:

In order to use X-3GPP-Asserted-Identity header authentication, the XCAP server must also support the use of this header type. If you enable X-3GPP-Asserted-Identity header authentication, and the XCAP server is unable to use it, the header is ignored.

Table 24-3 lists the methods to insert X-3GPP-Asserted-Identity headers into an HTTP via com.oracle.sft.xcap.client.XcapRequest. The value used is the XCAP User Identifier (XUI), such as sip:bob@example.com. Refer to the Converged Application Server API Reference to learn more about these methods and their usage.

Table 24-3 Methods to Insert 3GPP-Asserted-Identity Authentication Headers

Method	Description
`addHeader(String name, String value)`	Inserts a single header containing a single value into the HTTP request.
`addHeader(String name, <List>String values)`	Inserts a single header containing a list of values into the HTTP request.
`addHeaders(Map<String, List<String> aHeaders)`	Inserts a series of headers containing a list of values into the HTTP request.
`Map<String, List<String>> getHeaders()`	Returns an unmodifiable map of the headers for the request. The map keys are strings that represent the request-header field names. Each map value is a unmodifiable list of strings that represents the corresponding header field values.
`removeHeader(String aHeaderName)`	Removes the header whose name you supply using the string argument.