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

All Superinterfaces:

OperationSet

All Known Subinterfaces:

OperationSetPersistentPresence

All Known Implementing Classes:

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

public interface OperationSetPresence
extends OperationSet

OperationSetPresence offers methods that allow managing the presence status of the provider, and subscribing to that of our buddies (i.e. adding contacts to our contact list).

This operation set is meant to be implemented by all protocols that support presence, regardless of whether or not they can store contacts somewhere on the network. Operations that allow managing server stored contact lists are part of OperationSetPersistentPresence.

Author:

Emil Ivov

Method Summary

void	addContactPresenceStatusListener(ContactPresenceStatusListener listener) Registers a listener that would receive a presence status change event every time a contact, whose status we're subscribed for, changes her status.
void	addProviderPresenceStatusListener(ProviderPresenceStatusListener listener) Adds a listener that would receive events upon changes of the provider presence status.
void	addSubscriptionListener(SubscriptionListener listener) Registers a listener that would get notifications any time a new subscription was successfully added, has failed or was removed.
Contact	createUnresolvedContact(String address, String persistentData) Creates and returns a unresolved contact from the specified address and persistentData.
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/
String	getCurrentStatusMessage() Returns the status message that was confirmed by the server
PresenceStatus	getPresenceStatus() Returns a PresenceStatus instance representing the state this provider is currently in.
Iterator<PresenceStatus>	getSupportedStatusSet() Returns the set of PresenceStatus objects that a user of this service may request the provider to enter.
void	publishPresenceStatus(PresenceStatus status, String statusMessage) Requests the provider to enter into a status corresponding to the specified parameters.
PresenceStatus	queryContactStatus(String contactIdentifier) Get the PresenceStatus for a particular contact.
void	removeContactPresenceStatusListener(ContactPresenceStatusListener listener) Removes the specified listener so that it won't receive any further updates on contact presence status changes
void	removeProviderPresenceStatusListener(ProviderPresenceStatusListener listener) Unregisters the specified listener so that it does not receive further events upon changes in local presence status.
void	removeSubscriptionListener(SubscriptionListener listener) Removes the specified subscription listener.
void	setAuthorizationHandler(AuthorizationHandler handler) Handler for incoming authorization requests.
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.

Method Detail

getPresenceStatus

PresenceStatus getPresenceStatus()

Returns a PresenceStatus instance representing the state this provider is currently in. Note that PresenceStatus instances returned by this method MUST adequately represent all possible states that a provider might enter during its lifecycle, including those that would not be visible to others (e.g. Initializing, Connecting, etc ..) and those that will be sent to contacts/buddies (On-Line, Eager to chat, etc.).

Returns:

the PresenceStatus last published by this provider.

publishPresenceStatus

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

Requests the provider to enter into a status corresponding to the specified parameters. 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.

getSupportedStatusSet

Iterator<PresenceStatus> getSupportedStatusSet()

Returns the set of PresenceStatus objects that a user of this service may request the provider to enter. Note that the provider would most probably enter more states than those returned by this method as they only depict instances that users may request to enter. (e.g. a user may not request a "Connecting..." state - it is a temporary state that the provider enters while trying to enter the "Connected" state).

Returns:

Iterator a PresenceStatus array containing "enterable" status instances.

queryContactStatus

PresenceStatus queryContactStatus(String contactIdentifier)
                                  throws IllegalArgumentException,
                                         IllegalStateException,
                                         OperationFailedException

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 identifier of the contact whose status we're interested in.

Returns:

PresenceStatus the PresenceStatus of the specified contact

Throws:

OperationFailedException - with code NETWORK_FAILURE if retrieving the status 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(String contactIdentifier)
               throws IllegalArgumentException,
                      IllegalStateException,
                      OperationFailedException

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

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.

unsubscribe

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 the underlying protocol provider

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

findContactByID

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.

setAuthorizationHandler

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.

addProviderPresenceStatusListener

void addProviderPresenceStatusListener(ProviderPresenceStatusListener listener)

Adds a listener that would receive events upon changes of the provider presence status.

Parameters:

listener - the listener to register for changes in our PresenceStatus.

removeProviderPresenceStatusListener

void removeProviderPresenceStatusListener(ProviderPresenceStatusListener listener)

Unregisters the specified listener so that it does not receive further events upon changes in local presence status.

Parameters:

listener - ProviderPresenceStatusListener

addContactPresenceStatusListener

void addContactPresenceStatusListener(ContactPresenceStatusListener listener)

Registers a listener that would receive a presence status change event every time a contact, whose status we're subscribed for, changes her status. Note that, for reasons of simplicity and ease of implementation, there is only a means of registering such "global" listeners that would receive updates for status changes for any contact and it is not currently possible to register such contacts for a single contact or a subset of contacts.

Parameters:

listener - the listener that would received presence status updates for contacts.

removeContactPresenceStatusListener

void removeContactPresenceStatusListener(ContactPresenceStatusListener listener)

Removes the specified listener so that it won't receive any further updates on contact presence status changes

Parameters:

listener - the listener to remove.

addSubscriptionListener

void addSubscriptionListener(SubscriptionListener listener)

Registers a listener that would get notifications any time a new subscription was successfully added, has failed or was removed.

Parameters:

listener - the SubscriptionListener to register

removeSubscriptionListener

void removeSubscriptionListener(SubscriptionListener listener)

Removes the specified subscription listener.

Parameters:

listener - the listener to remove.

getCurrentStatusMessage

String getCurrentStatusMessage()

Returns the status message that was confirmed by the server

Returns:

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

createUnresolvedContact

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