net.java.sip.communicator.service.protocol
Interface OperationSetPersistentPresence

All Superinterfaces:

OperationSet, OperationSetPresence

All Known Implementing Classes:

AbstractOperationSetPersistentPresence, MockPersistentPresenceOperationSet, OperationSetPersistentPresenceDictImpl, OperationSetPersistentPresenceGibberishImpl, OperationSetPersistentPresenceIcqImpl, OperationSetPersistentPresenceJabberImpl, OperationSetPersistentPresenceMsnImpl, OperationSetPersistentPresenceRssImpl, OperationSetPersistentPresenceSSHImpl, OperationSetPersistentPresenceYahooImpl, OperationSetPersistentPresenceZeroconfImpl, OperationSetPresenceSipImpl

public interface OperationSetPersistentPresence
extends OperationSetPresence

This interface is an extension of the presence operation set, meant to be implemented by protocols that support server stored contact lists (like icq for example).

A server stored contact list is stored somewhere across the network and this interface allows GUI and other plugins to use it in a way similar to the way they'd use a javax.swing.tree.TreeModel, i.e. it would contain an initial number of members/children that is likely to change, dispatching a series of events delivered through the SubscriptionListener and ServerStoredGroupChangeListener interfaces.

The interfaces defines extended subscription methods that include an extra parentGroup parameter. Simple subscribe and usubscribe operations defined by the parent OperationSetPresence operation set, will still work, adding contacts to a default, root group. to be used by GUI and other plugins the same way that they would use a

Author:

Emil Ivov

Method Summary

void	addServerStoredGroupChangeListener(ServerStoredGroupListener listener) Registers a listener that would receive events upon changes in server stored groups.
void	createServerStoredContactGroup(ContactGroup parent, String groupName) Creates a group with the specified name and parent in the server stored contact list.
Contact	createUnresolvedContact(String address, String persistentData, ContactGroup parentGroup) Creates and returns a unresolved contact from the specified address and persistentData.
ContactGroup	createUnresolvedContactGroup(String groupUID, String persistentData, ContactGroup parentGroup) Creates and returns a unresolved contact group from the specified address and persistentData.
ContactGroup	getServerStoredContactListRoot() Returns the root group of the server stored contact list.
void	moveContactToGroup(Contact contactToMove, ContactGroup newParent) Removes the specified contact from its current parent and places it under newParent.
void	removeServerStoredContactGroup(ContactGroup group) Removes the specified group from the server stored contact list.
void	removeServerStoredGroupChangeListener(ServerStoredGroupListener listener) Removes the specified group change listener so that it won't receive any further events.
void	renameServerStoredContactGroup(ContactGroup group, String newName) Renames the specified group from the server stored contact list.
void	setDisplayName(Contact contact, String newName) Sets the display name for contact to be newName.
void	subscribe(ContactGroup parent, String contactIdentifier) Persistently adds a subscription for the presence status of the contact corresponding to the specified contactIdentifier and indicates that it should be added to the specified group of the server stored contact list.
void	subscribe(String contactIdentifier) Persistently adds a subscription for the presence status of the contact corresponding to the specified contactIdentifier to the top level group.
void	unsubscribe(Contact contact) Persistently removes a subscription for the presence status of the specified contact.

Methods inherited from interface net.java.sip.communicator.service.protocol.OperationSetPresence

addContactPresenceStatusListener, addProviderPresenceStatusListener, addSubscriptionListener, createUnresolvedContact, findContactByID, getCurrentStatusMessage, getPresenceStatus, getSupportedStatusSet, publishPresenceStatus, queryContactStatus, removeContactPresenceStatusListener, removeProviderPresenceStatusListener, removeSubscriptionListener, setAuthorizationHandler

Method Detail

subscribe

void subscribe(String contactIdentifier)
               throws IllegalArgumentException,
                      IllegalStateException,
                      OperationFailedException

Persistently adds a subscription for the presence status of the contact corresponding to the specified contactIdentifier to the top level group. Note that this method, unlike the subscribe method in OperationSetPresence, is going the subscribe the specified contact in a persistent manner or in other words, it will add it to a server stored contact list and thus making the subscription for its presence status last along multiple registrations/logins/signons.

Apart from an exception in the case of an immediate failure, the method won't return any indication of success or failure. That would happen later on through a SubscriptionEvent generated by one of the methods of the SubscriptionListener.

Specified by:

subscribe in interface OperationSetPresence

Parameters:

contactIdentifier - the contact whose status updates we are subscribing for.

Throws:

OperationFailedException - with code NETWORK_FAILURE if subscribing fails due to errors experienced during network communication

IllegalArgumentException - if contact is not a contact known to the underlying protocol provider

IllegalStateException - if the underlying protocol provider is not registered/signed on a public service.

subscribe

void subscribe(ContactGroup parent,
               String contactIdentifier)
               throws IllegalArgumentException,
                      IllegalStateException,
                      OperationFailedException

Persistently adds a subscription for the presence status of the contact corresponding to the specified contactIdentifier and indicates that it should be added to the specified group of the server stored contact list. Note that apart from an exception in the case of an immediate failure, the method won't return any indication of success or failure. That would happen later on through a SubscriptionEvent generated by one of the methods of the SubscriptionListener.

Parameters:

contactIdentifier - the contact whose status updates we are subscribing for.

parent - the parent group of the server stored contact list where the contact should be added.

Throws:

OperationFailedException - with code NETWORK_FAILURE if subscribing fails due to errors experienced during network communication

IllegalArgumentException - if contact or parent are not a contact known to the underlying protocol provider.

IllegalStateException - if the underlying protocol provider is not registered/signed on a public service.

unsubscribe

void unsubscribe(Contact contact)
                 throws IllegalArgumentException,
                        IllegalStateException,
                        OperationFailedException

Persistently removes a subscription for the presence status of the specified contact. This method has a persistent effect and the specified contact is completely removed from any server stored contact lists.

Specified by:

unsubscribe in interface OperationSetPresence

Parameters:

contact - the contact whose status updates we are unsubscribing from.

Throws:

OperationFailedException - with code NETWORK_FAILURE if unsubscribing fails due to errors experienced during network communication

IllegalArgumentException - if contact is not a contact known to the underlying protocol provider

IllegalStateException - if the underlying protocol provider is not registered/signed on a public service.

createServerStoredContactGroup

void createServerStoredContactGroup(ContactGroup parent,
                                    String groupName)
                                    throws OperationFailedException

Creates a group with the specified name and parent in the server stored contact list.

Parameters:

groupName - the name of the new group to create.

parent - the group where the new group should be created

Throws:

OperationFailedException - with code NETWORK_FAILURE if creating the group fails because of a network error.

IllegalArgumentException - if parent is not a contact known to the underlying protocol provider

IllegalStateException - if the underlying protocol provider is not registered/signed on a public service.

removeServerStoredContactGroup

void removeServerStoredContactGroup(ContactGroup group)

Removes the specified group from the server stored contact list.

Parameters:

group - the group to remove.

Throws:

OperationFailedException - with code NETWORK_FAILURE if deleting the group fails because of a network error.

IllegalArgumentException - if parent is not a contact known to the underlying protocol provider.

IllegalStateException - if the underlying protocol provider is not registered/signed on a public service.

renameServerStoredContactGroup

void renameServerStoredContactGroup(ContactGroup group,
                                    String newName)

Renames the specified group from the server stored contact list. This method would return before the group has actually been renamed. A ServerStoredGroupEvent would be dispatched once new name has been acknowledged by the server.

Parameters:

group - the group to rename.

newName - the new name of the group.

Throws:

OperationFailedException - with code NETWORK_FAILURE if deleting the group fails because of a network error.

IllegalArgumentException - if parent is not a contact known to the underlying protocol provider.

IllegalStateException - if the underlying protocol provider is not registered/signed on a public service.

moveContactToGroup

void moveContactToGroup(Contact contactToMove,
                        ContactGroup newParent)

Removes the specified contact from its current parent and places it under newParent.

Parameters:

contactToMove - the Contact to move

newParent - the ContactGroup where Contact would be placed.

getServerStoredContactListRoot

ContactGroup getServerStoredContactListRoot()

Returns the root group of the server stored contact list. Most often this would be a dummy group that user interface implementations may better not show.

Returns:

the root ContactGroup for the ContactList stored by this service.

addServerStoredGroupChangeListener

void addServerStoredGroupChangeListener(ServerStoredGroupListener listener)

Registers a listener that would receive events upon changes in server stored groups.

Parameters:

listener - a ServerStoredGroupChangeListener that would receive events upon group changes.

removeServerStoredGroupChangeListener

void removeServerStoredGroupChangeListener(ServerStoredGroupListener listener)

Removes the specified group change listener so that it won't receive any further events.

Parameters:

listener - the ServerStoredGroupChangeListener to remove

createUnresolvedContact

Contact createUnresolvedContact(String address,
                                String persistentData,
                                ContactGroup parentGroup)

Creates and returns a unresolved contact from the specified address and persistentData. The method will not try to establish a network connection and resolve the newly created Contact against the server. The protocol provider may will later try and resolve the contact. When this happens the corresponding event would notify interested subscription listeners.

Parameters:

address - an identifier of the contact that we'll be creating.

persistentData - a String returned Contact's getPersistentData() method during a previous run and that has been persistently stored locally.

parentGroup - the group where the unresolved contact is supposed to belong to.

Returns:

the unresolved Contact created from the specified address and persistentData

createUnresolvedContactGroup

ContactGroup createUnresolvedContactGroup(String groupUID,
                                          String persistentData,
                                          ContactGroup parentGroup)

Creates and returns a unresolved contact group from the specified address and persistentData. The method will not try to establish a network connection and resolve the newly created ContactGroup against the server or the contact itself. The protocol provider will later resolve the contact group. When this happens the corresponding event would notify interested subscription listeners.

Parameters:

groupUID - an identifier, returned by ContactGroup's getGroupUID, that the protocol provider may use in order to create the group.

persistentData - a String returned ContactGroups's getPersistentData() method during a previous run and that has been persistently stored locally.

parentGroup - the group under which the new group is to be created or null if this is group directly underneath the root.

Returns:

the unresolved ContactGroup created from the specified uid and persistentData

setDisplayName

void setDisplayName(Contact contact,
                    String newName)
                    throws IllegalArgumentException

Sets the display name for contact to be newName.

Parameters:

contact - the Contact that we are renaming

newName - a String containing the new display name for metaContact.

Throws:

IllegalArgumentException - if contact is not an instance that belongs to the underlying implementation.