com.ibm.soa.parlayx21.presence
Interface PresenceConsumer

All Superinterfaces:
java.rmi.Remote
All Known Subinterfaces:
PresenceConsumer_RI
All Known Implementing Classes:
PresenceConsumerBindingStub, PresenceConsumerProxy

public interface PresenceConsumer
extends java.rmi.Remote

The interface contains the operations for the presence consumer.

Client role: watcher.

This set of methods is used by the watcher to obtain presence data. After the subscription to presence data, the watcher can select between a polling mode or a notification mode in order to receive presence data.


Method Summary
 void endPresenceNotification(java.lang.String correlator)
          Indicates that the watcher does not want further notifications for a specific notification request (identified by the correlator).
 PresenceAttribute[] getUserPresence(java.net.URI presentity, PresenceAttributeType[] attributes)
          Returns the aggregated presence data of a presentity.
 java.net.URI[] startPresenceNotification(java.net.URI presentity, PresenceAttributeType[] attributes, SimpleReference reference, TimeMetric frequency, TimeMetric duration, java.lang.Integer count, boolean checkImmediate)
          The notification pattern with correlation is used in order to be able to correlate the notification events with the request.
 void subscribePresence(java.net.URI presentity, PresenceAttributeType[] attributes, java.lang.String application, SimpleReference reference)
          We assume that the watcher has been previously authenticated, so that his identity is known and can be associated with the subscription at the server.
 

Method Detail

subscribePresence

void subscribePresence(java.net.URI presentity,
                       PresenceAttributeType[] attributes,
                       java.lang.String application,
                       SimpleReference reference)
                       throws java.rmi.RemoteException,
                              PolicyException,
                              ServiceException

We assume that the watcher has been previously authenticated, so that his identity is known and can be associated with the subscription at the server.

The presentity is contacted and requested to authorize the watcher. As this process generally involves user interaction there cannot be an immediate response. The watcher is notified with notifySubscription(). If the presentity is a group, every member of the group will be contacted for authorization. The watcher will get one notification for each member.

Only after the subscription is completed (and the presentity has allowed access to attributes) may the watcher will get information when he uses getUserPresence() or startPresenceNotification().

Note that the SimpleReference contains the correlator string used in subsequent messages to the notification interface.

At this interface level, the subscription has no expiration, although at can be ended from the presentity of or the underlying layers (see subscriptionEnded operation).

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses - if the presentity address does not exist.

PolicyException from ES 202 391-1 [3]:
  * POL0006: Groups not allowed.
  * POL0007: Nested groups not allowed.

Parameters:
presentity - xsd:anyURI

A presentity or a group of presentities whose attributes the watcher wants to monitor.

attributes - PresenceAttributeType [0..unbounded]

The attributes the watcher wants to access. (the same for all the group members). An empty array means subscription of all attributes.

application - xsd:string

Describes the application the watcher needs the data for.

reference - common:SimpleReference

The notification interface.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

getUserPresence

PresenceAttribute[] getUserPresence(java.net.URI presentity,
                                    PresenceAttributeType[] attributes)
                                    throws java.rmi.RemoteException,
                                           PolicyException,
                                           ServiceException

Returns the aggregated presence data of a presentity. Only the attributes which the watcher is entitled to see will be returned. This method does not support group identities.

Before getting these attributes, the watcher has to subscribe to them (see above). The presentity needs not be informed of the access, as he has already consented when the watcher called subscribePresence().

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses - if the presentity address does not exist.

PolicyException from ES 202 391-1 [3]. The presentity has the possibility to cancel or block a subscription by manipulating the policy rules. The exception informs the watcher about this status change.
  * POL0002: Privacy error - if the watcher is not subscribed to the requested data.
  * POL0006: Groups not allowed.

Parameters:
presentity - xsd:anyURI

The presentity whose data the watcher wants to see.

attributes - PresenceAttributeType [0..unbounded]

The attributes the watcher wants to see. An empty array means all attributes.

Returns:
result PresenceAttribute [0..unbounded]

The actual presence data.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

startPresenceNotification

java.net.URI[] startPresenceNotification(java.net.URI presentity,
                                         PresenceAttributeType[] attributes,
                                         SimpleReference reference,
                                         TimeMetric frequency,
                                         TimeMetric duration,
                                         java.lang.Integer count,
                                         boolean checkImmediate)
                                         throws java.rmi.RemoteException,
                                                PolicyException,
                                                ServiceException

The notification pattern with correlation is used in order to be able to correlate the notification events with the request. The attributes represent a subset of the attributes subscribed and can be used as filter.

The watcher sets a notification trigger on certain user presence attribute changes. If the list of attributes is empty, the watcher wants to be notified on all subscribed attributes.

In case the presentity is a group the watcher will receive notifications for every single member of the group. The watcher will only get notifications for those attributes and presentities he subscribed successfully prior to the call. The service will return a list of presentities where the notifications could not be set up.

The presentity needs not be informed of the access, as he has already consented when the watcher called subscribePresence().

Note that the SimpleReference contains the correlator string used in subsequent messages to the notification interface.

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses - if the presentity URI does not exist.
  * SVC0005: Duplicate correlator.

PolicyException from ES 202 391-1 [3]. The presentity has the possibility to cancel or block a subscription by manipulating the policy rules. The exception informs the watcher about this status change.
  * POL0001: Policy error.
  * POL0004: Unlimited notifications not supported.
  * POL0005: Too many notifications requested.
  * POL0006: Groups not allowed.
  * POL0007: Nested groups not allowed.

Parameters:
presentity - xsd:anyURI

The presentity or group whose attributes the watcher wants to monitor.

attributes - PresenceAttributeType [0..unbounded]

The attributes the watcher wants to see.

reference - common:SimpleReference

The notification interface.

frequency - common:TimeMetric

Maximum frequency of notifications (can also be considered minimum time between notifications). In case of a group subscription the service must make sure this frequency is not violated by notifications for various members of the group, especially in combination with checkImmediate.

duration - common:TimeMetric

Length of time notifications occur for, do not specify to use default notification time defined by service policy.

count - xsd:int

Maximum number of notifications.For no maximum, either do not specify this part or specify a value of zero.

checkImmediate - xsd:boolean

Whether to check status immediately after establishing notification.

Returns:
result xsd:anyURI [0..unbounded]

The presentities whose attributes the watcher did not subscribe. Empty if all went fine.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

endPresenceNotification

void endPresenceNotification(java.lang.String correlator)
                             throws java.rmi.RemoteException,
                                    PolicyException,
                                    ServiceException

Indicates that the watcher does not want further notifications for a specific notification request (identified by the correlator). Note that the subscription to presence data stays active; the caller of this method remains a watcher and can still use getUserPresence() or reactivate the notifications.

Referenced faults

ServiceException from ES 202 391-1 [3]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.

PolicyException from ES 202 391-1 [3]:
  * POL0001: Policy error.

Parameters:
correlator - xsd:string

The notification the watcher wants to cancel.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException


Copyright © 2003 IBM Corp. All Rights Reserved.