|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface PresenceConsumer
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 |
---|
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).
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.
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.
java.rmi.RemoteException
PolicyException
ServiceException
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().
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.
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.
The actual presence data.
java.rmi.RemoteException
PolicyException
ServiceException
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.
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.
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.
The presentities whose attributes the watcher did not subscribe. Empty if all went fine.
java.rmi.RemoteException
PolicyException
ServiceException
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.
ServiceException from ES 202 391-1 [3]:
* SVC0001: Service error.
* SVC0002: Invalid input value.
PolicyException from ES 202 391-1 [3]:
* POL0001: Policy error.
correlator
- xsd:string
The notification the watcher wants to cancel.
java.rmi.RemoteException
PolicyException
ServiceException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |