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

All Superinterfaces:

OperationSet

All Known Implementing Classes:

AbstractOperationSetServerStoredAccountInfo, OperationSetServerStoredAccountInfoIcqImpl, OperationSetServerStoredAccountInfoJabberImpl, OperationSetServerStoredAccountInfoMsnImpl, OperationSetServerStoredAccountInfoSipImpl

public interface OperationSetServerStoredAccountInfo
extends OperationSet

The Account Info Operation set is a means of accessing and modifying detailed information on the user/account that is currently logged in through this provider. This operation set is more or less reciproce to OperationSetServerStoredContactInfo with the most essential difference being the fact that the account info operation set allows you to modify data in addition to reading it (quite natural given that it's your own info that you're dealing with).

Examples of account details are your picture, postal or e-mail addresses, work, hobbies, interests, and many many others.

Various types of details have been defined in the ServerStoredDetails class and can be used with the get methods of this interface. Implementors may also define their own details by extending or instantiating the ServerStoredDetails.GenericDetail class. Yet, they are encouraged to use existing detail types as fully as possible. Defining your own detail type may lead to limited visualization of its value.

As mentioned earlier the operation set supports adding, removing or replaing various details. The exact set of details that can be manipulated through this operation set depends on the implementation and can be retrieved through the getSupportedDetailTypes() method. The maximum number of detail instances supported for a given type of details can be retrieved through the getMaxDetailInstances() method.

The OperationSetServerStoredAccountInfo only concerns us (the user currently logged through this provider) and our own details. In order to query details concerning Contacts in our contact list we'd need to use the OperationSetServerStoredContactInfo

Author:

Emil Ivov

Method Summary

void	addDetail(ServerStoredDetails.GenericDetail detail) Adds the specified detail to the list of details registered on-line for this account.
void	addServerStoredDetailsChangeListener(ServerStoredDetailsChangeListener listener) Registers a ServerStoredDetailsChangeListener with this operation set so that it gets notifications of details change.
Iterator<ServerStoredDetails.GenericDetail>	getAllAvailableDetails() Returns all details currently available and set for our account.
Iterator<ServerStoredDetails.GenericDetail>	getDetails(Class<? extends ServerStoredDetails.GenericDetail> detailClass) Returns an iterator over all details that are instances of exactly the same class as the one specified.
Iterator<ServerStoredDetails.GenericDetail>	getDetailsAndDescendants(Class<? extends ServerStoredDetails.GenericDetail> detailClass) Returns an iterator over all details that are instances or descendants of the specified class.
int	getMaxDetailInstances(Class<? extends ServerStoredDetails.GenericDetail> detailClass) The method returns the number of instances supported for a particular detail type.
Iterator<Class<? extends ServerStoredDetails.GenericDetail>>	getSupportedDetailTypes() Returns all detail Class-es that the underlying implementation supports setting.
boolean	isDetailClassSupported(Class<? extends ServerStoredDetails.GenericDetail> detailClass) Determines whether a detail class represents a detail supported by the underlying implementation or not.
boolean	removeDetail(ServerStoredDetails.GenericDetail detail) Removes the specified detail from the list of details stored online for this account.
void	removeServerStoredDetailsChangeListener(ServerStoredDetailsChangeListener listener) Unregisters listener so that it won't receive any further notifications upon details change.
boolean	replaceDetail(ServerStoredDetails.GenericDetail currentDetailValue, ServerStoredDetails.GenericDetail newDetailValue) Replaces the currentDetailValue detail with newDetailValue and returns true if the operation was a success or false if currentDetailValue did not previously exist (in this case an additional call to addDetail is required).

Method Detail

getDetailsAndDescendants

Iterator<ServerStoredDetails.GenericDetail> getDetailsAndDescendants(Class<? extends ServerStoredDetails.GenericDetail> detailClass)

Returns an iterator over all details that are instances or descendants of the specified class. If for example an our account has a workaddress and an address detail, a call to this method with AddressDetail.class would return both of them.

Parameters:

detailClass - one of the detail classes defined in the ServerStoredDetails class, indicating the kind of details we're interested in.

Returns:

a java.util.Iterator over all details that are instances or descendants of the specified class.

getDetails

Iterator<ServerStoredDetails.GenericDetail> getDetails(Class<? extends ServerStoredDetails.GenericDetail> detailClass)

Returns an iterator over all details that are instances of exactly the same class as the one specified. Not that, contrary to the getDetailsAndDescendants() method this one would only return details that are instances of the specified class and not only its descendants. If for example our account has both a workaddress and an address detail, a call to this method with AddressDetail.class would return only the AddressDetail instance and not the WorkAddressDetail instance.

Parameters:

detailClass - one of the detail classes defined in the ServerStoredDetails class, indicating the kind of details we're interested in.

Returns:

a java.util.Iterator over all details of specified class.

getAllAvailableDetails

Iterator<ServerStoredDetails.GenericDetail> getAllAvailableDetails()

Returns all details currently available and set for our account.

Returns:

a java.util.Iterator over all details currently set our account.

getSupportedDetailTypes

Iterator<Class<? extends ServerStoredDetails.GenericDetail>> getSupportedDetailTypes()

Returns all detail Class-es that the underlying implementation supports setting. Note that if you call one of the modification methods (add remove or replace) with a detail not contained by the iterator returned by this method, an IllegalArgumentException will be thrown.

Returns:

a java.util.Iterator over all detail classes supported by the implementation.

isDetailClassSupported

boolean isDetailClassSupported(Class<? extends ServerStoredDetails.GenericDetail> detailClass)

Determines whether a detail class represents a detail supported by the underlying implementation or not. Note that if you call one of the modification methods (add remove or replace) with a detail that this method has determined to be unsupported (returned false) this would lead to an IllegalArgumentException being thrown.

Parameters:

detailClass - the class the support for which we'd like to determine.

Returns:

true if the underlying implementation supports setting details of this type and false otherwise.

getMaxDetailInstances

int getMaxDetailInstances(Class<? extends ServerStoredDetails.GenericDetail> detailClass)

The method returns the number of instances supported for a particular detail type. Some protocols offer storing mutliple values for a particular detail type. Spoken languages are a good example.

Parameters:

detailClass - the class whose max instance number we'd like to find out.

Returns:

int the maximum number of detail instances.

addDetail

void addDetail(ServerStoredDetails.GenericDetail detail)
               throws IllegalArgumentException,
                      OperationFailedException,
                      ArrayIndexOutOfBoundsException

Adds the specified detail to the list of details registered on-line for this account. If such a detail already exists its max instance number is consulted and if it allows it - a second instance is added or otherwise and illegal argument exception is thrown. An IllegalArgumentException is also thrown in case the class of the specified detail is not supported by the underlying implementation, i.e. its class name was not returned by the getSupportedDetailTypes() method.

Parameters:

detail - the detail that we'd like registered on the server.

Throws:

IllegalArgumentException - if such a detail already exists and its max instances number has been atteined or if the underlying implementation does not support setting details of the corresponding class.

OperationFailedException - with code Network Failure if putting the new value online has failed

ArrayIndexOutOfBoundsException - if the number of instances currently registered by the application is already equal to the maximum number of supported instances (@see getMaxDetailInstances())

removeDetail

boolean removeDetail(ServerStoredDetails.GenericDetail detail)
                     throws OperationFailedException

Removes the specified detail from the list of details stored online for this account. The method returns a boolean indicating if such a detail was found (and removed) or not.

Parameters:

detail - the detail to remove

Returns:

true if the specified detail existed and was successfully removed and false otherwise.

Throws:

OperationFailedException - with code Network Failure if removing the detail from the server has failed

replaceDetail

boolean replaceDetail(ServerStoredDetails.GenericDetail currentDetailValue,
                      ServerStoredDetails.GenericDetail newDetailValue)
                      throws ClassCastException,
                             OperationFailedException

Replaces the currentDetailValue detail with newDetailValue and returns true if the operation was a success or false if currentDetailValue did not previously exist (in this case an additional call to addDetail is required).

Parameters:

currentDetailValue - the detail value we'd like to replace.

newDetailValue - the value of the detail that we'd like to replace currentDetailValue with.

Throws:

ClassCastException - if newDetailValue is not an instance of the same class as currentDetailValue.

OperationFailedException - with code Network Failure if putting the new value back online has failed

addServerStoredDetailsChangeListener

void addServerStoredDetailsChangeListener(ServerStoredDetailsChangeListener listener)

Registers a ServerStoredDetailsChangeListener with this operation set so that it gets notifications of details change.

Parameters:

listener - the ServerStoredDetailsChangeListener to register.

removeServerStoredDetailsChangeListener

void removeServerStoredDetailsChangeListener(ServerStoredDetailsChangeListener listener)

Unregisters listener so that it won't receive any further notifications upon details change.

Parameters:

listener - the ServerStoredDetailsChangeListener to unregister.