com.sun.im.service
Interface PresenceSession

All Superinterfaces:
CollaborationSession

public interface PresenceSession
extends CollaborationSession

presence service session. A PresenceSession is use to access and advertise presence information. A presence information access unit or user agent, is called a presentity. Actual presence information is accessed by performing actions on a presentity. A presentity is identified by an address, whose format is defined in RFC 822 (addr-spec). Example:

The Presence information format is defined in a iCAPI's pseudo-DTD.


Field Summary
static java.lang.String STATUS_AWAY
          user agent online / user unavailable
static java.lang.String STATUS_BUSY
          user agent online / user involved in other tasks and of limited availability
static java.lang.String STATUS_CLOSED
          user agent offline / user unreachable
static java.lang.String STATUS_FORWARDED
          user agent offline / one-way messages forwarded to other delivery mechanism
static java.lang.String STATUS_IDLE
          Extended status to signify that the user is away.
static java.lang.String STATUS_OPEN
          user agent online / user available to communicate
static java.lang.String STATUS_OTHER
          other status
 
Method Summary
 void addAccessRule(PresenceAccessRule rule)
          Deprecated. Instead use setPrivacyList
 void cancel(java.lang.String presentity)
          cancels the previously granted subscription approval.
 java.lang.String fetch(java.lang.String presentity)
          retrieves presence information from the presence store synchronously
 java.lang.String[] fetch(java.lang.String[] presentity)
          retrieves presence information from the presence store synchronously
 void fetch(java.lang.String[] presentity, PresenceInfoListener listener)
          retrieves presence information from the presence store asynchronously about multiple presentities
 void fetch(java.lang.String presentity, PresenceInfoListener listener)
          retrieves presence information from the presence store asynchronously
 java.util.Collection getAccessRules(java.lang.String presentity)
          Deprecated. Instead use getPrivacyList
 void publish(java.lang.String presenceInfo)
          Update a unit of presence information in the relevant presence stores.
 void saveAccessRules()
          Deprecated. Instead use setPrivacyList
 PresenceSubscription subscribe(java.lang.String[] presentity, PresenceInfoListener listener)
          Subscribe to multiple presentities at once.
 PresenceSubscription subscribe(java.lang.String[] presentity, PresenceInfoListener listener, java.util.Date expires)
          Subscribe to multiple presentities at once, i.e. ask to be notified of any presence information update pertaining to any of these presentities.
 PresenceSubscription subscribe(java.lang.String presentity, PresenceInfoListener listener)
          subscribe to a presentity.
 PresenceSubscription subscribe(java.lang.String presentity, PresenceInfoListener listener, java.util.Date expires)
          subscribe to a presentity, i.e. ask to be notified of any presence information update pertaining to this presentity.
 void unsubscribe(java.lang.String presentity)
          Cancels any subscription made for a presentity.
 void unsubscribe(java.lang.String[] presentity)
          Cancels any subscription made to the specified presentities.
 
Methods inherited from interface com.sun.im.service.CollaborationSession
accessService, addPrivacyList, addSessionListener, changePassword, createPrincipal, createPrincipal, createPrivacyList, getActivePrivacyListName, getConferenceService, getDefaultPrivacyListName, getMediaService, getNewsService, getNotificationService, getPersonalStoreService, getPresenceService, getPrincipal, getPrivacyList, getStreamingService, listPrivacyLists, logout, removePrivacyList, removeSessionListener, setActivePrivacyListName, setDefaultPrivacyListName, setSessionListener, unregister
 

Field Detail

STATUS_OPEN

public static final java.lang.String STATUS_OPEN
user agent online / user available to communicate

See Also:
Constant Field Values

STATUS_CLOSED

public static final java.lang.String STATUS_CLOSED
user agent offline / user unreachable

See Also:
Constant Field Values

STATUS_AWAY

public static final java.lang.String STATUS_AWAY
user agent online / user unavailable

See Also:
Constant Field Values

STATUS_IDLE

public static final java.lang.String STATUS_IDLE
Extended status to signify that the user is away. user agent online / user idle and probably unresponsive

See Also:
Constant Field Values

STATUS_BUSY

public static final java.lang.String STATUS_BUSY
user agent online / user involved in other tasks and of limited availability

See Also:
Constant Field Values

STATUS_FORWARDED

public static final java.lang.String STATUS_FORWARDED
user agent offline / one-way messages forwarded to other delivery mechanism

See Also:
Constant Field Values

STATUS_OTHER

public static final java.lang.String STATUS_OTHER
other status

See Also:
Constant Field Values
Method Detail

subscribe

public PresenceSubscription subscribe(java.lang.String presentity,
                                      PresenceInfoListener listener)
                               throws CollaborationException
subscribe to a presentity. i.e. ask to be notified of any presence information update pertaining to this presentity. The subscription is valid until cancelled.

Parameters:
presentity - presentity url
listener - callback object used to notify the caller whenever a relevant presence update happens.
Returns:
presence subscription handle.
Throws:
CollaborationException - failure to register the subscription in the pub/sub subsystem.

subscribe

public PresenceSubscription subscribe(java.lang.String[] presentity,
                                      PresenceInfoListener listener)
                               throws CollaborationException
Subscribe to multiple presentities at once. i.e. ask to be notified of any presence information update pertaining to any of these presentities. The subscription is valid until cancelled.

Parameters:
presentity - array of presentity url
listener - callback object used to notify the caller whenever a relevant presence update happens.
Returns:
presence subscription handle.
Throws:
CollaborationException - failure to register the subscription in the pub/sub subsystem.

subscribe

public PresenceSubscription subscribe(java.lang.String presentity,
                                      PresenceInfoListener listener,
                                      java.util.Date expires)
                               throws CollaborationException
subscribe to a presentity, i.e. ask to be notified of any presence information update pertaining to this presentity. The subscription expires autaomatically after the specified expiration date is reached.

Parameters:
presentity - presentity url
listener - callback object used to notify the caller whenever a relevant presence update happens.
expires - expiration date for this subscription.
Returns:
presence subscription handle.
Throws:
failure - to register the subscription in the pub/sub subsystem.
CollaborationException

subscribe

public PresenceSubscription subscribe(java.lang.String[] presentity,
                                      PresenceInfoListener listener,
                                      java.util.Date expires)
                               throws CollaborationException
Subscribe to multiple presentities at once, i.e. ask to be notified of any presence information update pertaining to any of these presentities. The subscription expires autaomatically after the specified expiration date is reached.

Parameters:
presentity - array of presentity urls
listener - callback object used to notify the caller whenever a relevant presence update happens.
expires - expiration date for this subscription.
Returns:
presence subscription handle.
Throws:
failure - to register the subscription in the pub/sub subsystem.
CollaborationException

unsubscribe

public void unsubscribe(java.lang.String presentity)
                 throws CollaborationException
Cancels any subscription made for a presentity.

Parameters:
presentity - presentity url
Throws:
CollaborationException

unsubscribe

public void unsubscribe(java.lang.String[] presentity)
                 throws CollaborationException
Cancels any subscription made to the specified presentities.

Parameters:
presentity - array of presentity urls
Throws:
CollaborationException

publish

public void publish(java.lang.String presenceInfo)
             throws CollaborationException
Update a unit of presence information in the relevant presence stores.

Parameters:
presenceInfo - Presence information in XML format
Throws:
CollaborationException

fetch

public void fetch(java.lang.String presentity,
                  PresenceInfoListener listener)
           throws CollaborationException
retrieves presence information from the presence store asynchronously

Parameters:
presentity - presentity reference
listener - callback object used by the provider to return search results asynchronously.
Throws:
CollaborationException

fetch

public void fetch(java.lang.String[] presentity,
                  PresenceInfoListener listener)
           throws CollaborationException
retrieves presence information from the presence store asynchronously about multiple presentities

Parameters:
presentity - array of presentity references
listener - callback object used by the provider to return search results asynchronously.
Throws:
CollaborationException

fetch

public java.lang.String fetch(java.lang.String presentity)
                       throws CollaborationException
retrieves presence information from the presence store synchronously

Parameters:
presentity - presentity url
Returns:
an xml document containing the presence information.
Throws:
CollaborationException

fetch

public java.lang.String[] fetch(java.lang.String[] presentity)
                         throws CollaborationException
retrieves presence information from the presence store synchronously

Parameters:
presentity - presentity url
Returns:
an array of xml documents, each containing the presence information related to one presentity.
Throws:
CollaborationException

cancel

public void cancel(java.lang.String presentity)
            throws CollaborationException
cancels the previously granted subscription approval.

Parameters:
presentity - presentity url
Throws:
CollaborationException

addAccessRule

public void addAccessRule(PresenceAccessRule rule)
                   throws CollaborationException
Deprecated. Instead use setPrivacyList

create or modify access to a presentity for an identified user or set of users

Parameters:
rule - access rule
Throws:
CollaborationException

getAccessRules

public java.util.Collection getAccessRules(java.lang.String presentity)
                                    throws CollaborationException
Deprecated. Instead use getPrivacyList

get access rules protecting a presentity.

Parameters:
presentity - address of the protected presentity
Returns:
a Collection of PresenceAccessRule objects.
Throws:
CollaborationException

saveAccessRules

public void saveAccessRules()
                     throws CollaborationException
Deprecated. Instead use setPrivacyList

commits access rules to the server

Throws:
CollaborationException