net.java.sip.communicator.impl.protocol.icq
Class OperationSetPersistentPresenceIcqImpl

java.lang.Object
  net.java.sip.communicator.service.protocol.AbstractOperationSetPersistentPresence<ProtocolProviderServiceIcqImpl>
      net.java.sip.communicator.impl.protocol.icq.OperationSetPersistentPresenceIcqImpl

All Implemented Interfaces:

OperationSet, OperationSetPersistentPresence, OperationSetPresence

public class OperationSetPersistentPresenceIcqImpl
extends AbstractOperationSetPersistentPresence<ProtocolProviderServiceIcqImpl>

The ICQ implementation of a Persistent Presence Operation set. This class manages our own presence status as well as subscriptions for the presence status of our buddies. It also offers methods for retrieving and modifying the buddy contact list and adding listeners for changes in its layout.

Author:

Emil Ivov

Field Summary

Fields inherited from class net.java.sip.communicator.service.protocol.AbstractOperationSetPersistentPresence

parentProvider

Constructor Summary

protected

OperationSetPersistentPresenceIcqImpl(ProtocolProviderServiceIcqImpl icqProvider, String uin) Creates a new Presence OperationSet over the specified icq provider.

Method Summary

void	addServerStoredGroupChangeListener(ServerStoredGroupListener listener) Registers a listener that would receive events upong 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) Creates and returns a unresolved contact from the specified address and persistentData.
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.
ContactIcqImpl	createVolatileContact(String uin) Creates a non persistent contact for the specified address.
Contact	findContactByID(String contactID) Returns a reference to the contact with the specified ID in case we have a subscription for it and null otherwise/
(package private) void	fireProviderPresenceStatusChangeEvent(long oldStatusL, long newStatusL) Notify all provider presence listeners of the corresponding event change
String	getCurrentStatusMessage() Returns the status message that was confirmed by the serfver
Contact	getLocalContact() Returns the protocol specific contact instance representing the local user.
PresenceStatus	getPresenceStatus() Returns a PresenceStatus instance representing the state this provider is currently in.
(package private) ServerStoredContactListIcqImpl	getServerStoredContactList() Returns a snapshot ieves a server stored list of subscriptions/contacts that have been made previously.
ContactGroup	getServerStoredContactListRoot() Returns the root group of the server stored contact list.
Iterator<PresenceStatus>	getSupportedStatusSet() Returns the set of PresenceStatus objects that a user of this service may request the provider to enter.
void	moveContactToGroup(Contact contactToMove, ContactGroup newParent) Removes the specified contact from its current parent and places it under newParent.
void	publishPresenceStatus(PresenceStatus status, String statusMessage) Requests the provider to enter into a status corresponding to the specified paramters.
PresenceStatus	queryContactStatus(String contactIdentifier) Get the PresenceStatus for a particular contact.
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	setAuthorizationHandler(AuthorizationHandler handler) Handler for incoming authorization requests.
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) Adds a subscription for the presence status of the contact corresponding to the specified contactIdentifier.
void	unsubscribe(Contact contact) Removes a subscription for the presence status of the specified contact.

Methods inherited from class net.java.sip.communicator.service.protocol.AbstractOperationSetPersistentPresence

addContactPresenceStatusListener, addProviderPresenceStatusListener, addSubscriptionListener, fireContactPresenceStatusChangeEvent, fireContactPresenceStatusChangeEvent, fireContactPropertyChangeEvent, fireProviderStatusChangeEvent, fireProviderStatusChangeEvent, fireProviderStatusMessageChangeEvent, fireServerStoredGroupEvent, fireSubscriptionEvent, fireSubscriptionEvent, fireSubscriptionMovedEvent, removeContactPresenceStatusListener, removeProviderPresenceStatusListener, removeSubscriptionListener, setDisplayName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OperationSetPersistentPresenceIcqImpl

protected OperationSetPersistentPresenceIcqImpl(ProtocolProviderServiceIcqImpl icqProvider,
                                                String uin)

Creates a new Presence OperationSet over the specified icq provider.

Parameters:

icqProvider - IcqProtocolProviderServiceImpl

uin - the UIN of our account.

Method Detail

queryContactStatus

public PresenceStatus queryContactStatus(String contactIdentifier)
                                  throws IllegalStateException,
                                         IllegalArgumentException

Get the PresenceStatus for a particular contact. This method is not meant to be used by the user interface (which would simply register as a presence listener and always follow contact status) but rather by other plugins that may for some reason need to know the status of a particular contact.

Parameters:

contactIdentifier - the dientifier of the contact whose status we're interested in.

Returns:

PresenceStatus the PresenceStatus of the specified contact

Throws:

IllegalStateException - if the provider is not signed on ICQ

IllegalArgumentException - if contact is not a valid IcqContact

subscribe

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

Adds a subscription for the presence status of the contact corresponding to the specified contactIdentifier. 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.

This subscription is not going to be persistent (as opposed to subscriptions added from the OperationSetPersistentPresence.subscribe() method)

Parameters:

contactIdentifier - the identifier of 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.

createVolatileContact

public ContactIcqImpl createVolatileContact(String uin)

Creates a non persistent contact for the specified address. This would also create (if necessary) a group for volatile contacts that would not be added to the server stored contact list. The volatile contact would remain in the list until it is really added to the contact list or until the application is terminated.

Parameters:

uin - the UIN/Screenname of the contact to create.

Returns:

the newly created volatile ContactIcqImpl

createUnresolvedContact

public Contact createUnresolvedContact(String address,
                                       String persistentData,
                                       ContactGroup parentGroup)
                                throws IllegalArgumentException

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 that the unresolved contact should belong to.

Returns:

the unresolved Contact created from the specified address and persistentData

Throws:

IllegalArgumentException - if parentGroup is not an instance of ContactGroupIcqImpl

createUnresolvedContact

public Contact createUnresolvedContact(String address,
                                       String persistentData)

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.

Returns:

the unresolved Contact created from the specified address and persistentData

createUnresolvedContactGroup

public 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

subscribe

public 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

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

Removes a subscription for the presence status of the specified contact.

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 this protocol provider or is not an ICQ contact

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

findContactByID

public Contact findContactByID(String contactID)

Returns a reference to the contact with the specified ID in case we have a subscription for it and null otherwise/

Parameters:

contactID - a String identifier of the contact which we're seeking a reference of.

Returns:

a reference to the Contact with the specified contactID or null if we don't have a subscription for the that identifier.

publishPresenceStatus

public void publishPresenceStatus(PresenceStatus status,
                                  String statusMessage)
                           throws IllegalArgumentException,
                                  IllegalStateException,
                                  OperationFailedException

Requests the provider to enter into a status corresponding to the specified paramters. Note that calling this method does not necessarily imply that the requested status would be entered. This method would return right after being called and the caller should add itself as a listener to this class in order to get notified when the state has actually changed.

Parameters:

status - the PresenceStatus as returned by getRequestableStatusSet

statusMessage - the message that should be set as the reason to enter that status

Throws:

IllegalArgumentException - if the status requested is not a valid PresenceStatus supported by this provider.

IllegalStateException - if the provider is not currently registered.

OperationFailedException - with code NETWORK_FAILURE if publishing the status fails due to a network error.

getCurrentStatusMessage

public String getCurrentStatusMessage()

Returns the status message that was confirmed by the serfver

Returns:

the last status message that we have requested and the aim server has confirmed.

getLocalContact

public Contact getLocalContact()

Returns the protocol specific contact instance representing the local user.

Returns:

the Contact (address, phone number, or uin) that the Provider implementation is communicating on behalf of.

createServerStoredContactGroup

public void createServerStoredContactGroup(ContactGroup parent,
                                           String groupName)

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 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.

removeServerStoredContactGroup

public 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

public 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

public 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.

getServerStoredContactList

ServerStoredContactListIcqImpl getServerStoredContactList()

Returns a snapshot ieves a server stored list of subscriptions/contacts that have been made previously. Note that the contact list returned by this method may be incomplete as it is only a snapshot of what has been retrieved through the network up to the moment when the method is called.

Returns:

a ConactGroup containing all previously made subscriptions stored on the server.

getPresenceStatus

public PresenceStatus getPresenceStatus()

Returns a PresenceStatus instance representing the state this provider is currently in.

Returns:

PresenceStatus

getSupportedStatusSet

public Iterator<PresenceStatus> getSupportedStatusSet()

Returns the set of PresenceStatus objects that a user of this service may request the provider to enter.

Returns:

Iterator a PresenceStatus array containing "enterable" status instances.

setAuthorizationHandler

public void setAuthorizationHandler(AuthorizationHandler handler)

Handler for incoming authorization requests. An authorization request notifies the user that someone is trying to add her to their contact list and requires her to approve or reject authorization for that action.

Parameters:

handler - an instance of an AuthorizationHandler for authorization requests coming from other users requesting permission add us to their contact list.

getServerStoredContactListRoot

public 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

public void addServerStoredGroupChangeListener(ServerStoredGroupListener listener)

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

Specified by:

addServerStoredGroupChangeListener in interface OperationSetPersistentPresence

Overrides:

addServerStoredGroupChangeListener in class AbstractOperationSetPersistentPresence<ProtocolProviderServiceIcqImpl>

Parameters:

listener - a ServerStoredGroupChangeListener impl that would receive events upong group changes.

removeServerStoredGroupChangeListener

public void removeServerStoredGroupChangeListener(ServerStoredGroupListener listener)

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

Specified by:

removeServerStoredGroupChangeListener in interface OperationSetPersistentPresence

Overrides:

removeServerStoredGroupChangeListener in class AbstractOperationSetPersistentPresence<ProtocolProviderServiceIcqImpl>

Parameters:

listener - the ServerStoredGroupChangeListener to remove

fireProviderPresenceStatusChangeEvent

void fireProviderPresenceStatusChangeEvent(long oldStatusL,
                                           long newStatusL)

Notify all provider presence listeners of the corresponding event change

Parameters:

oldStatusL - the status our icq stack had so far

newStatusL - the status we have from now on