9 OCMS Parlay X Presence Web Services

This chapter describes OCMS support for the Parlay X 2.1 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"
"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 Presence 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 Presence 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 Presence Web Services, Part 14, Presence ETSI ES 202 391-14.

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.

Presence Web Services Interface Descriptions

The Presence Web Services consist of the following interfaces:

PresenceConsumer: The watchers use these methods to obtain presence data (Table 9-1).
PresenceNotification: The presence consumer interface uses the client callback defined in this interface to send notifications. (Table 9-2).
PresenceNotificationListener: This is a thin Java wrapper layer on top of the Parlay X PresenceNotification interface. An Oracle extension provides the user context if available. The client application should implement this interface and register it using the addPresenceNotificationListener() method from PresenceNotificationListenerManager. Once registered with the manager, it will be called if there is incoming notification. The end client can register multiple listeners. All listeners will be called on every incoming notification. The user context in the form of a SIP address is passed in the context parameter. This class is included in the presencewsnotification-10.1.3.4.war.
PresenceSupplier: The presentity uses these methods to supply presence data and manage access to the data by its watchers (Table 9-3).

Table 9-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	Indicates that the watcher want to receive notifications for a user presence status.
endPresenceNotification	Indicates that the watcher does not want further notifications for a specific notification request (identified by the correlator).

Table 9-2 PresenceNotification Interface (used by PresenceNotificationListener)

Operation	Description
statusChanged	The asynchronous operation is called by the Web Service when an attribute for which notifications were requested changes.
statusEnd	The notifications have ended. This message will not be delivered in the case of an error ending the notifications or deliberate ending of the notifications (using endPresenceNotification operation).
notifySubscription	This asynchronous operation is called by the Web Service to notify the watcher (application) that the subscription has terminated. Typical reasons are a timeout of the underlying SIP soft state subscription or the decision of the presentity to block further presence information to that watcher.
subscriptionEnded	This asynchronous method notifies the watcher that the server or the presentity handled the pending subscription.

Table 9-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("unique_correlator");
sr.setInterfaceName("PresenceNotification");
sr.setEndpoint(new URI ("http://127.0.0.1:8088/presencenotification/PresenceNotification"));
 
// Calling the web service
consumer.subscribePresence (new URI
("sip.presentity@test.example.com") , pat, "webcenter", 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: PresenceConsumer, Operation: startPresenceNotification

This operation indicates that the watcher want to receive notifications for a user presence status.

Code Example

SimpleReference sr = getNotificationReference(presentity);
 
TimeMetric freq = new TimeMetric();
freq.setMetric(TimeMetrics.Minute);
TimeMetric duration = new TimeMetric();
duration.setMetric(TimeMetrics.Minute);
 
PresenceAttributeType pa = PresenceAttributeType.Activity;
PresenceAttributeType[] pat = new PresenceAttributeType[] { pa };
mConsumer.startPresenceNotification(new URI(presentity), pat, sr, freq, duration, 0, false);

Interface: PresenceConsumer, Operation: endPresenceNotification

This operation indicates that the watcher does not want further notifications for a specific notification request (identified by the correlator).

Code Example

// Pass in the correlator used in startPresenceNotification.
mConsumer.endPresenceNotification(correlator);

Interface PresenceSupplier, Operation: publish and Oracle Specific Remove Presence

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.

Presence 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);

// 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 9-4 and Table 9-5 describe the error codes and their associated error message.

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

Error Code	Error Message
SDP20201	Watcher is on the block, polite-block or pending list.
SDP20202	Subscription is pending.

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

Error Code	Error Message
SDP20101	Invalid result from XDMS server.
SDP20102	Invalid HTTP session data.
SDP20103	Invalid URI.
SDP20104	Peer unavailable.
SDP20105	Unknownhost.
SDP20106	Service not available.
SDP20107	Internal error.
SDP20108	User unauthenticated.