oracle.sdp.presence.integration
Interface BuddyListManager

public interface BuddyListManager

A BuddyListManager is a manager for a particular user's buddy list information. For example, Alice will create her own BuddyListManager via the BuddyListManagerFactory.createBuddyListManager(URI, java.util.Map) method in order to manipulate her buddy list and presence rules information. Similarly, Bob will have to create his own instance of a BuddyListManager in order to be able to manipulate his buddy list and presence rules information.

Method Summary

void	allowWatcher(java.lang.String watcher) Allow the specified watcher to view the indicated user's presence (i.e.
void	allowWatchers(List<java.lang.String> watchers) Allow all the watchers on the list to view the indicated user's presence.
void	blockWatcher(java.lang.String watcher) Moves the watcher over to the blocked rule.
void	blockWatchers(List<java.lang.String> watchers) Moves all the watchers over to the blocked rule.
Buddy	createBuddy(java.net.URI uri) Creates a new Buddy with the specified URI.
List<Buddy>	getBuddies() Fetch all the buddies from the buddy list recursively.
ResourceList	getDefaultResourceList() Get the default resource list for this entity - NOT IMPLEMENTED.
ResourceListDocument	getResourceListDocument() Get the immutable resource list document that contains all the resource lists for this entity - NOT IMPLEMENTED.
java.net.URI	getUser() The user who this manager is acting on the behalf of.
void	removeBuddies(List<Buddy> buddies) Removes all the buddies from the user's default buddy list.
void	removeBuddies(List<Buddy> buddies, java.lang.String listName) Removes all the buddies from the named list - NOT IMPLEMENTED.
void	removeBuddy(Buddy buddy) Removes a buddy from the user's default buddy list.
void	removeBuddy(Buddy buddy, java.lang.String listName) Removes a buddy from the named list - NOT IMPLEMENTED.
void	removeWatcher(java.lang.String watcher) Remove the watcher from the presence rules document.
void	removeWatchers(List<java.lang.String> watchers) Remove the watchers from the presence rules document.
void	updateBuddies(List<Buddy> buddies) Updates all the buddies in the passed in list of buddies in the default list.
void	updateBuddies(List<Buddy> buddies, java.lang.String listName) Updates all the buddies in the passed in list of buddies into the named list - NOT IMPLEMENTED.
void	updateBuddy(Buddy buddy) Updates or adds a new buddy on the default buddy list.
void	updateBuddy(Buddy buddy, java.lang.String listName) Updates or adds a new buddy on the named list - NOT IMPLEMENTED.

Method Detail

allowWatcher

void allowWatcher(java.lang.String watcher)
                  throws java.lang.IllegalArgumentException,
                         DocumentConflictException,
                         XDMException,
                         PresenceRulesException,
                         BuddyListException

Allow the specified watcher to view the indicated user's presence (i.e. the user that "owns" this BuddyListManager)

If the user did not have a presence rules document on the remote server a new one will be created and this watcher will be put on the allow list.

Parameters:

watcher - the watcher to allow

Throws:

java.lang.IllegalArgumentException - in case the watcher is not a sip or a tel-uri

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

PresenceRulesException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

allowWatchers

void allowWatchers(List<java.lang.String> watchers)
                   throws java.lang.IllegalArgumentException,
                          DocumentConflictException,
                          XDMException,
                          PresenceRulesException,
                          BuddyListException

Allow all the watchers on the list to view the indicated user's presence.

If the user did not have a presence rules document on the remote server a new one will be created and these watchers will be put on the allow list.

Parameters:

watchers - the list of watchers to allow

Throws:

java.lang.IllegalArgumentException - in case any of the watchers are not a sip or a tel-uri

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

PresenceRulesException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

blockWatcher

void blockWatcher(java.lang.String watcher)
                  throws java.lang.IllegalArgumentException,
                         DocumentConflictException,
                         XDMException,
                         PresenceRulesException,
                         BuddyListException

Moves the watcher over to the blocked rule. I.e., this watcher will not be allowed to view the presence information of this user (i.e. the user who this BuddyListManager is acting on the behalf of. See getUser())

If the user did not have a presence rules document on the remote server a new one will be created and this watcher will be put on the block list.

Parameters:

watcher - the watcher to block

Throws:

java.lang.IllegalArgumentException - in case the watcher is not a sip or a tel-uri

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

PresenceRulesException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

blockWatchers

void blockWatchers(List<java.lang.String> watchers)
                   throws java.lang.IllegalArgumentException,
                          DocumentConflictException,
                          XDMException,
                          PresenceRulesException,
                          BuddyListException

Moves all the watchers over to the blocked rule. If any of the passed in watchers are not a sip- or a tel-uri then no one of the watchers will be moved over to the blocked rule.

If the user did not have a presence rules document on the remote server a new one will be created and these watchers will be put on the block list.

Parameters:

watchers - the list of watchers to block

Throws:

java.lang.IllegalArgumentException - in case any of the watchers are not a sip or a tel-uri

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

PresenceRulesException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

createBuddy

Buddy createBuddy(java.net.URI uri)
                  throws java.lang.IllegalArgumentException

Creates a new Buddy with the specified URI.

Parameters:

uri - the uri of the buddy

Returns:

the buddy with the specified URI

Throws:

java.lang.IllegalArgumentException - in case the uri is null or not a sip or a tel-uri

getBuddies

List<Buddy> getBuddies()
                       throws XDMException,
                              ResourceListException,
                              BuddyListException

Fetch all the buddies from the buddy list recursively. This method recurses into all the sublists of this entities resource list document, so that the list of buddies returned includes all the buddies in all the lists/sublists. If there are no buddies on the buddy list then an empty list will be returned.

Returns:

a list of buddies

Throws:

XDMException - if the connection with the XDM Enabler failes for any reason

ResourceListException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

getDefaultResourceList

ResourceList getDefaultResourceList()
                                    throws java.lang.Exception

Get the default resource list for this entity - NOT IMPLEMENTED.

Returns:

the default resource list

Throws:

BuddyListException - Currently, this will always be thrown.

java.lang.Exception

getResourceListDocument

ResourceListDocument getResourceListDocument()
                                             throws java.lang.Exception

Get the immutable resource list document that contains all the resource lists for this entity - NOT IMPLEMENTED. This object is read-only and has a limited lifetime, since operations that change this entity's buddy list on the server (whether via this manager or otherwise ) will cause this document to be out of sync with the resource list server. Users should call this method again whenever they need a document that is in sync with the server at that point in time.

Returns:

this entity's resource list document.

Throws:

BuddyListException - Currently, this will always be thrown.

java.lang.Exception

getUser

java.net.URI getUser()

The user who this manager is acting on the behalf of. This is the user that was passed in when creating this BuddyListManager

Returns:

a clone of the user (hence, changing the returned URI will not change the URI stored within the BuddyListManager)

removeBuddies

void removeBuddies(List<Buddy> buddies)
                   throws DocumentConflictException,
                          XDMException,
                          ResourceListException,
                          BuddyListException

Removes all the buddies from the user's default buddy list. If any of the buddies in the passed in list did not exist in the buddy list they will be silently ignored. If the user did not even have a buddy list, this method will also return silently.

Parameters:

buddies - the list of buddies to remove

Throws:

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

ResourceListException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

removeBuddies

void removeBuddies(List<Buddy> buddies,
                   java.lang.String listName)
                   throws DocumentConflictException,
                          XDMException,
                          ResourceListException,
                          BuddyListException

Removes all the buddies from the named list - NOT IMPLEMENTED. If any of the buddies in the passed in list did not exist in the named list they will be silently ignored. If the user did not even have the named list, this method will also return silently.

Parameters:

buddies - the list of buddies to remove

listName - the list on which to operate, in path-separated format (eg "friends/close" )

Throws:

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

ResourceListException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation. Currently, this will always be thrown.

removeBuddy

void removeBuddy(Buddy buddy)
                 throws DocumentConflictException,
                        XDMException,
                        ResourceListException,
                        BuddyListException

Removes a buddy from the user's default buddy list. If the buddy did not exist in the buddy list, the method will return silently. If the user did not even have a buddy list, this method will also return silently.

Parameters:

buddy - the buddy to be removed

Throws:

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

ResourceListException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

removeBuddy

void removeBuddy(Buddy buddy,
                 java.lang.String listName)
                 throws DocumentConflictException,
                        XDMException,
                        ResourceListException,
                        BuddyListException

Removes a buddy from the named list - NOT IMPLEMENTED. If the buddy did not exist in the named list, the method will return silently. If the user did not even have a list with the given name, this method will also return silently.

Parameters:

buddy - the buddy to be removed

listName - the list on which to operate, in path-separated format (eg "friends/close" )

Throws:

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

ResourceListException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation. Currently, this will always be thrown.

removeWatcher

void removeWatcher(java.lang.String watcher)
                   throws java.lang.IllegalArgumentException,
                          DocumentConflictException,
                          XDMException,
                          PresenceRulesException,
                          BuddyListException

Remove the watcher from the presence rules document. If the watcher did not exist on the presence rules document, this method will silently return. If the user did not even have a presence rules document on the remote server, this method will silently return.

Parameters:

watcher - the watcher to remove

Throws:

java.lang.IllegalArgumentException - in case the watcher is not a sip or a tel-uri

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

PresenceRulesException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

removeWatchers

void removeWatchers(List<java.lang.String> watchers)
                    throws java.lang.IllegalArgumentException,
                           DocumentConflictException,
                           XDMException,
                           PresenceRulesException,
                           BuddyListException

Remove the watchers from the presence rules document. Any watchers that did not exist on the presence rules document will silently be ignored. If the user did not even have a presence rules document on the remote server, this method will silently return.

Parameters:

watchers - the watchers to remove

Throws:

java.lang.IllegalArgumentException - in case any of the watchers are not a sip or a tel-uri

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler fails for any reason

PresenceRulesException - if any type of parse error occurs when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

updateBuddies

void updateBuddies(List<Buddy> buddies)
                   throws DocumentConflictException,
                          XDMException,
                          ResourceListException,
                          BuddyListException

Updates all the buddies in the passed in list of buddies in the default list. If any of the buddies does not exist in the default list then it will be created. If any of the buddies yield an exception when inserting it into the document, the whole process will be aborted, hence, none of the buddies will go into the buddy list.

If the user did not have a buddy list on the remote server, a new buddy list will be created with these buddies.

Parameters:

buddies - the buddies to update

Throws:

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

ResourceListException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

updateBuddies

void updateBuddies(List<Buddy> buddies,
                   java.lang.String listName)
                   throws DocumentConflictException,
                          XDMException,
                          ResourceListException,
                          BuddyListException

Updates all the buddies in the passed in list of buddies into the named list - NOT IMPLEMENTED. If any of the buddies does not exist in the buddy list then it will be created. If any of the buddies yield an exception when inserting it into the document, the whole process will be aborted, hence, none of the buddies will go into the buddy list. The named list must exist before this method is called ( maybe we should not have this requirement, because of the possibility of modifying the list from multiple clients )

Parameters:

buddies - the buddies to update

listName - the list on which to operate, in path-separated format (eg "friends/close" )

Throws:

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

ResourceListException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation. Currently, this will always be thrown.

updateBuddy

void updateBuddy(Buddy buddy)
                 throws DocumentConflictException,
                        XDMException,
                        ResourceListException,
                        BuddyListException

Updates or adds a new buddy on the default buddy list. Hence, if the buddy does not exist, it will be created. Also, if the user did not even have a buddy list on the remote server, then a new buddy list will be created and this buddy added to it.

Parameters:

buddy -

Throws:

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler failes for any reason

ResourceListException - if any type of parse error occured when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation

updateBuddy

void updateBuddy(Buddy buddy,
                 java.lang.String listName)
                 throws DocumentConflictException,
                        XDMException,
                        ResourceListException,
                        BuddyListException

Updates or adds a new buddy on the named list - NOT IMPLEMENTED. Hence, if the buddy does not exist, it will be created. The named list must exist before this method is called. Lists can be added using the addList() method ( maybe we should not have this requirement, because of the possibility of modifying the list from multiple clients )

Parameters:

buddy -

listName - the list on which to operate, in path-separated format (eg "friends/close" )

Throws:

DocumentConflictException - in case a mid-air collision is detected that cannot be resolved.

XDMException - if the connection with the XDM Enabler fails for any reason

ResourceListException - if any type of parse error occurs when manipulating the underlying XML document

BuddyListException - if any other unexpected events took place while performing this operation. Currently, this will always be thrown.