6 OCMS Parlay X Web Services

This chapter describes OCMS support for the Parlay X 2.0 Presence Web services interfaces for developing applications. The Web service functions as a Presence Network Agent which can publish, subscribe, and listen to notifies on behalf of the users of the Web service. This chapter contains the following sections:

"Introduction"
"Installing the Web Services"
"Installing the Aggregation Proxy"
"Configuring Web Services with the Aggregation Proxy"
"Presence Web Services Interface Descriptions"
"Using the Presence Web Services Interfaces"
"OCMS Parlay X Presence Custom Error Codes"

Introduction

OCMS provides support for Part 14 of the Parlay X Presence Web Service as defined in the Open Service Access, Parlay X Web Services, Part 14, Presence ETSI ES 202 391-14 specification. The OCMS Parlay X Web service maps the Parlay X Web service to a SIP/IMS network according to the Open Service Access, Mapping of Parlay X Web Services to Parlay/OSA APIs, Part 14, Presence Mapping, Subpart 2, Mapping to SIP/IMS Networks, ETSI TR 102 397-14-2 specification.

Note:

Due to the synchronous nature of the Web service, to receive a callback from the Web service the client must implement the Web service callback interface. For presence, the required interface is the PresenceNotification interface described in Open Service Access, Parlay X Web Services, Part 14, Presence ETSI ES 202 391-14.

Because this implementation is not common or practical for most Web service architectures, the PresenceNotification interface is not currently supported.

The presence Web service communicates directly with IMS presence network elements using the SIP/SIMPLE protocol interface, and uses the JSR-32 UAC framework to communicate with the SIP network.

The HTTP server that hosts the presence Web service is a Presence Network Agent or a Parlay X to SIP gateway.

Installing the Web Services

The Web services are packaged as a standard .ear file and can be deployed the same as any other Web services through Enterprise Manager. The .ear file contains two .war files that implement the two interfaces. If the Web services are deployed on the same server as the presence server, they must be a child application of the Presence server.

Installing the Aggregation Proxy

The aggregation proxy is packaged as a standard .ear file and can be deployed through Enterprise Manager. There are two requirements:

The application name must be "aggregationproxyear".
The parent application must be "subscriberdataservices". The aggregation proxy uses the authentication functions of subscriberdataservices to authenticate Web services.

Configuring Web Services with the Aggregation Proxy

The Web services operate within a trusted domain where another entity performs authentication. To authenticate Web services and identify the user of the services, OCMS uses the aggregation proxy to insert the HTTP X-3GPP-ASSERTED-IDENTITY header as defined in 3GPP TS 33.222 Generic Authentication Architecture (GAA); Access to network application functions using Hypertext Transfer Protocol over Transport Layer Security (HTTPS).

To define a Web services deployment server:

Open the Enterprise Manager page for the aggregation proxy.
Configure the WebServiceHost and WebServicePort to the host and port of the Web services deployment server.
Configure the XCAPHost, XCAPPort, and XCAPRoot to the location and parameters of the XDMS.

Presence Web Services Interface Descriptions

The presence Web services consist of three interfaces:

PresenceConsumer: The watchers use these methods to obtain presence data (Table 6-1).
PresenceNotification: The presence consumer interface uses the client callback defined in this interface to send notifications. OCMS does not currently support PresenceNotification (Table 6-2).
PresenceSupplier: The presentity uses these methods to supply presence data and manage access to the data by its watchers (Table 6-3).

Table 6-1 PresenceConsumer Interface

Operation	Description
subscribePresence	The Web Services send a SUBSCRIBE to the presence server.
getUserPresence	Returns the cached presence status because the status changes of the presentity are asynchronously sent to the Web services through a SIP NOTIFY. The Web services actually have the subscription, not the Web services client.
startPresenceNotification	Not supported.
endPresenceNotification	Not supported.

Table 6-2 PresenceNotification Interface

Operation	Description
statusChanged	Not supported.
statusEnd	Not supported.
notifySubscription	Not supported.
subscriptionEnded	Not supported.

Table 6-3 PresenceSupplier Interface

Operation	Description
publish	Maps directly to a SIP PUBLISH.
getOpenSubscriptions	Called by the presentity (supplier) to check if any watcher wants to subscribe to its presence data. No SIP message maps to this method. Returns pending subscriptions currently in the Web services server.
updateSubscriptionAuthorization	The supplier uses this method to answer any open pending subscriptions. An XCAP PUT message is sent to the XDMS server to update the presence-rule document.
getMyWatchers	Retrieves the local list of watchers from the Web services server.
getSubscribedAttributes	Retrieves the local list of subscribed attributes from the Web services server. Currently, only returns Activity.
blockSubscription	Causes the Web services server to end a watcher subscription by modifying the XCAP document on the XDMS server (i.e., putting the watcher on the block list).

Using the Presence Web Services Interfaces

This section describes how to use each of the operations in the interfaces, and includes code examples.

Interface: PresenceConsumer, Operation: subscribePresence

This is the first operation the application must call before using another operation in this interface. It serves two purposes:

It allows the Web services to associate the current HTTP session with a user.
It provides a context for all the other operations in this interface by subscribing to at least one presentity (SUBSCRIBE presence event).

Code Example

// Setting the attribute to activity
PresenceAttributeType pa = PresenceAttributeType.Activity;
PresenceAttributeType[] pat = new PresenceAttributeType[]{pa};

// These inputs are required but not used.
SimpleReference sr = new SimpleReference();
sr.setCorrelator("unused_correlator");
sr.setInterfaceName("unused_interfacename");
sr.setEndpoint(new URI ("http://unused.com"));

// Calling the web service
consumer.subscribePresence (new URI
("sip.presentity@test.example.com") , pat, "unused", sr);

Interface: PresenceConsumer, Operation: getUserPresence

Call this operation to retrieve a subscribed presentity presence. If the person is offline, it returns ActivityNone and the hardstate note will be written to PresenceAttribute.note. If it returns ActivityOther, the description of the activity is returned in the OtherValue field.

If the Name field is equal to "ServiceAndDeviceNote", OtherValue is a combination of the service note and the device note. Note that there can be more than one "ServiceAndDeviceNote" when the presentity is logged into multiple clients.

Code Example

PresenceAttributeType pat = new
  PresenceAttributeType(){PresenceAttributeType.Activity};
PresenceAttribute[] resultPA =
  consumer.getUserPresence(new URI(presentity),pat);
for (int i = 0; i < resultPA.length; i++){
  PresenceAttribute pa = resultPA[i];
  // Check to see if it is an activity type.
  if (pa.getTypeAndValue().getUnionElement() ==
              PresenceAttributeType.Activity){
     // Get the presence status.
     System.out.println("Activity: " +
         pa.getTypeAndValue().getActivity().toString());
     // Get the customized presence note.
     if (pa.getNote().length() > 0){
        System.out.println("Note: " + pa1.getNote());
    }
  }
  // If this is of type Other, then we need to extract
  // different type of information.
  if (pa.getTypeAndValue().getUnionElement() ==
              PresenceAttributeType.Other){
    // This is "ActivityOther", a custom presence status.
    if (pa.getTypeAndValue().getOther()
             .getName().compareToIgnoreCase("ActivityOther") == 0){
   System.out.println("Other Activity->" + 
          pa.getTypeAndValue().getOther().getValue() + "\n");
 } else {
    // Currently, the only other value beside ActivityOther is
    // "ServiceAndDeviceNote" which is the service note + 
    // device note.
    System.out.println("Combined Note->" +
        pa.getTypeAndValue().getOther().getValue() + "\n");
    }
  }
}

Interface PresenceSupplier, Operation: publish and Oracle Specific "Unpublish"

This is the first operation the application must call before using another operation in this interface. It serves three purposes:

It allows the Web services to associate the current HTTP session with a user.
It publishes the user's presence status.
It subscribes to watcher-info so that the Web services can keep track of any watcher requests.

There are three attributes that are of interest when performing a PUBLISH. These attributes can be set in a PresenceAttribute structure and passed into the PUBLISH method.

Presense status with a customized note: this is the customized note configured in the My Presence text box in Oracle Communicator. The <note> element is contained in the <person> element of the Presence Information Data Format (PIDF) XML file.
Device note: implicitly inserted by Oracle Communicator, or inserted from a Web service. The <note> element is contained in the <device> element of the Presence Information Data Format (PIDF) XML file.
Service note: configured in the Presence tab in the Oracle Communicator preferences. The <note> element is contained in the <tuple> element of the Presence Information Data Format (PIDF) XML file.

Code Example

// PresenceAttribute contains presence status and note.
typeValue.setUnionElement(PresenceAttributeType.Activity);
typeValue.setActivity(activity);
paActivity.setTypeAndValue(typeValue);
// Setting the customized note here.
paActivity.setNote(activityNote);
paActivity.setLastChange(dateTime);

// Create the PresenceAttribute containing device note.
AttributeTypeAndValue typeValueOther = createATV();
PresenceAttribute paOther = new PresenceAttribute();
// Device note is carried in a PresenceAttributeType.Other
typeValueOther.setUnionElement(PresenceAttributeType.Other);
// Set the name to "DeviceNote" to indicate the value
// should be used as device note.
other.setName("DeviceNote");
other.setValue(deviceName);
typeValueOther.setOther(other);
paOther.setTypeAndValue(typeValueOther);
// The note is not used. Can be anything.
paOther.setNote("OracleExtension");
paOther.setLastChange(dateTime);

// Create the PresenceAttribute containing service note.
AttributeTypeAndValue typeValueOther1 = createATV();
PresenceAttribute paOther1 = new PresenceAttribute();
// Service note is carried in another
// PresenceAttributeType.Other
typeValueOther1.setUnionElement(PresenceAttributeType.Other);
OtherValue other1 = new OtherValue();
// Set the name to "ServiceNote" to indicate the value
// should be used as device note.
other1.setName("ServiceNote");
other1.setValue(serviceName);
typeValueOther1.setOther(other1);
paOther1.setTypeAndValue(typeValueOther1);
// The note is not used. Can be anything.
paOther1.setNote("OracleExtension");
paOther1.setLastChange(dateTime);

//Unpublish Functionality Implemented by OCMS
//To perform an "Unpublish", set OtherValue to (Expires, 0)
//OtherValue other = new OtherValue();
//other.setName("Expires");
//other.setValue(0);
//typeValue.setOther (other);
//typeValue.setUnionElement(PresenceAttributeTypeOther);

paArray = new PresenceAttribute[]{paActivity,paOther,paOther1};

// Calling the publish method by passing the PresenceAttribute
// array containing the presence status, device note and service
// note.
publish(paArray);

Interface: PresenceSupplier, Operation: getOpenSubscriptions

This operation retrieves a list of new requests to be on your watcher list.

Code Example

SubscriptionRequest[] srArray = getOpenSubscriptions();
for (SubscriptionRequest sr:srArray) {
    System.out.println(sr.getWatcher() .toString());
}

Interface: PresenceSupplier, Operation: updateSubscriptionAuthorization

This operation allows you to place a watcher on either the block or allow list.

Code Example

//You always pass in Activity
pp.set.PresenceAttribute(PresenceAttributeType.Activity);
updateSubscriptionAuthorization(new URI("sip:allow@test.example.com"),
new PresencePermission[]{pp});
PresencePermission pp = new PresencePermission();
pp.setDecision(true);
//Put the user on the allow list

Interface: PresenceSupplier, Operation: getMyWatchers

This operation retrieves the list of watchers in your allow list.

Code Example

URI[] uris;
uris = getMyWatchers();
for (URI uri:uris)
    System.out.println(uri.toString());

Interface: PresenceSupplier, Operation: getSubscribedAttributes

This operation returns only a single item of PresenceTypeAttribute.Activity. An exception will be thrown if there is no existing subscription.

Code Example

PresenceAttributeType[] pat =
getSubscriberdAttributes("sip:watcher@test.example.com");

Interface: PresenceSupplier, Operation: blockSubscription

This operation places a watcher into the block list.

Code Example

blockSubscription(new URI("sip:block.this.watcher@test.example.com"));

OCMS Parlay X Presence Custom Error Codes

OCMS introduces two extensions to the Parlay X standard exceptions:

PresencePolicyException extends PolicyException, and
PresenceServiceException extends ServiceException

Table 6-4 and Table 6-5 describe the error codes and their associated error message.

Table 6-4 OCMS Parlay X Presence Custom Error Codes: PresencePolicyException

Error Code	Error Message
OPOL0001	Watcher is on the block, polite-block or pending list.

Table 6-5 OCMS Parlay X Presence Custom Error Codes: PresenceServiceException

Error Code	Error Message
PRES0001	Invalid result from XDMS server.
PRES0002	Invalid HTTP session data.
PRES0003	Invalid URI.
PRES0004	Peer unavailable.
PRES0005	Unknown host.
PRES0006	Service unavailable.
PRES0007	Internal error.
PRES0008	User unauthenticated.