org.glassfish.cafe.api
Interface PresenceWatcher

All Superinterfaces:

UserProcedure

public interface PresenceWatcher
extends UserProcedure

The Presence Watcher is an entity that requests presence information about a list of presentities (i.e. presence list) from the presence service. User specific presence lists are defined in a Group.

Presence Watcher is a UserProcedure. Each invocation of the update() method results in sending a SUBSCRIBE method in the network, subscribing to the presence information for a specific group. The expiration time of the User procedure defines the period the subscription is active.

Events received after invoking the update() method indicate whether the subscription is accepted or not. If the subscription was accepted, a PresenceMessage can be received containing presence information changes of any of the users in the presence list.

In order to limit the network load generated by the sending of notification messages it is possible to define an associated PresenceWatcherFilterSet in which both events and information to be included can be selected. The default filter set is empty. A newly defined filter set is included in a SUBSCRIBE method to the network if the update() method is invoked.

A special meaning is assigned to invoking the update() method with the expiration time set to a time in the past. If such a request is received by the remote side, it will send immediately a notification with the requested status and will terminate the procedure.

Example code of how to subscribe with an PresenceWatcher:

                CommunicationService service = CommunicationService.getInstance();
                Map map = new HashMap();
                map.put("Bob@example.com","Bob"); 
                Group buddies = service.createGroup("Friends",
                                        "me@example.com",
                                map);
                PresenceWatcher watcher = buddies.startWatching(communicationSession);
 

Or, instead of the last line, for example if it is necessary to define a filter on the PresenceWatcher before initiating it.

                PresenceWatcher watcher = 
                        communicationSession.createPresenceWatcher(buddies);
                watcher.update();
 

The watcher procedures are described in [RFC3265] and [RFC3856]. The event notification filtering is described in [RFC4660].

Nested Class Summary

Nested classes/interfaces inherited from interface org.glassfish.cafe.api.UserProcedure

UserProcedure.State

Method Summary

PresenceWatcherFilterSet	createFilterSet() Creates a Filter Set instance associated with this watcher.
String	getEvent() Returns the event package corresponding to this Subscription.
PresenceWatcherFilterSet	getFilterSet() Gets the Filter Set instance associated with this watcher.
Group	getGroup() Returns the group that this presence watcher is subscribed to.
Map<String,PeerPresentity>	getPeerPresentities() Provides the accumulated presence information for all the presentities this watcher has subscribed to.
PeerPresentity	getPeerPresentity(String presentityURI) Provides the presence information for a certain presentity the watcher has subscribed to.
void	removeFilterSet() Removes the Filter Set instance associated with this watcher.

Methods inherited from interface org.glassfish.cafe.api.UserProcedure

addAgent, end, getAgent, getAgents, getExpirationTime, getMessage, getState, getUserId, removeAgent, setExpirationTime, update

Method Detail

getEvent

String getEvent()

Returns the event package corresponding to this Subscription.

Returns:

the event package name.

getGroup

Group getGroup()

Returns the group that this presence watcher is subscribed to.

Returns:

the group this watcher was created with.

getPeerPresentities

Map<String,PeerPresentity> getPeerPresentities()

Provides the accumulated presence information for all the presentities this watcher has subscribed to.

Returns:

map with key the URI of the peer presentity and the value its presence information.

getPeerPresentity

PeerPresentity getPeerPresentity(String presentityURI)

Provides the presence information for a certain presentity the watcher has subscribed to.

Parameters:

presentityURI - the URI of the peer presentity.

Returns:

the presence information of this peer presentity. In case no presence information with regard to this presentity is available, null is returned.

createFilterSet

PresenceWatcherFilterSet createFilterSet()

Creates a Filter Set instance associated with this watcher.

removeFilterSet

void removeFilterSet()

Removes the Filter Set instance associated with this watcher.

getFilterSet

PresenceWatcherFilterSet getFilterSet()

Gets the Filter Set instance associated with this watcher.

Returns:

a PresenceWatcherFilterSet instance.