net.java.sip.communicator.service.contactlist
Interface MetaContact

All Superinterfaces:

Comparable<MetaContact>

All Known Implementing Classes:

MetaContactImpl

public interface MetaContact
extends Comparable<MetaContact>

A MetaContact is an abstraction used for merging multiple Contacts (most often) belonging to different ProtocolProviders.

Instances of a MetaContact are read-only objects that cannot be modified directly but only through the corresponding MetaContactListService.

Author:

Emil Ivov, Lubomir Marinov

Method Summary

void	addDetail(String name, String value) Adds a custom detail to this contact.
void	changeDetail(String name, String oldValue, String newValue) Change the detail.
boolean	containsContact(Contact protocolContact) Returns true if the given protocolContact is contained in this MetaContact, otherwise - returns false.
byte[]	getAvatar() Returns the avatar of this contact, that can be used when including this MetaContact in user interface.
byte[]	getAvatar(boolean isLazy) Returns the avatar of this contact, that can be used when including this MetaContact in user interface.
Contact	getContact(String contactAddress, ProtocolProviderService ownerProvider) Returns a contact encapsulated by this meta contact, having the specified contactAddress and coming from the indicated ownerProvider.
int	getContactCount() Returns the number of protocol speciic Contacts that this MetaContact contains.
Iterator<Contact>	getContacts() Returns a java.util.Iterator with all protocol specific Contacts encapsulated by this MetaContact.
List<Contact>	getContactsForOperationSet(Class<? extends OperationSet> opSetClass) Returns all protocol specific Contacts, encapsulated by this MetaContact and supporting the given opSetClass.
Iterator<Contact>	getContactsForProvider(ProtocolProviderService provider) Returns all protocol specific Contacts, encapsulated by this MetaContact and coming from the indicated ProtocolProviderService.
Object	getData(Object key) Gets the user data associated with this instance and a specific key.
Contact	getDefaultContact() Returns the default protocol specific Contact to use when communicating with this MetaContact.
Contact	getDefaultContact(Class<? extends OperationSet> operationSet) Returns the default protocol specific Contact to use with this MetaContact for a precise operation (IM, call, ...).
List<String>	getDetails(String name) Get all details with given name.
String	getDisplayName() Returns a characteristic display name that can be used when including this MetaContact in user interface.
String	getMetaUID() Returns a String identifier (the actual contents is left to implementations) that uniquely represents this MetaContact in the containing MetaContactList
MetaContactGroup	getParentMetaContactGroup() Returns the MetaContactGroup currently containing this meta contact
void	removeDetail(String name, String value) Remove the given detail.
void	removeDetails(String name) Remove all details with given name.
void	setData(Object key, Object value) Sets a user-specific association in this instance in the form of a key-value pair.
String	toString() Returns a String representation of this MetaContact.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getDefaultContact

Contact getDefaultContact()

Returns the default protocol specific Contact to use when communicating with this MetaContact.

Returns:

the default Contact to use when communicating with this MetaContact

getDefaultContact

Contact getDefaultContact(Class<? extends OperationSet> operationSet)

Returns the default protocol specific Contact to use with this MetaContact for a precise operation (IM, call, ...).

Parameters:

operationSet - the operation for which the default contact is needed

Returns:

the default contact for the specified operation.

getContacts

Iterator<Contact> getContacts()

Returns a java.util.Iterator with all protocol specific Contacts encapsulated by this MetaContact.

Note to implementors: In order to prevent problems with concurrency, the Iterator returned by this method should not be over the actual list of contacts but rather over a copy of that list.

Returns:

a java.util.Iterator containing all protocol specific Contacts that were registered as subcontacts for this MetaContact

getContact

Contact getContact(String contactAddress,
                   ProtocolProviderService ownerProvider)

Returns a contact encapsulated by this meta contact, having the specified contactAddress and coming from the indicated ownerProvider.

Parameters:

contactAddress - the address of the contact who we're looking for.

ownerProvider - a reference to the ProtocolProviderService that the contact we're looking for belongs to.

Returns:

a reference to a Contact, encapsulated by this MetaContact, carrying the specified address and originating from the specified ownerProvider or null if no such contact exists..

containsContact

boolean containsContact(Contact protocolContact)

Returns true if the given protocolContact is contained in this MetaContact, otherwise - returns false.

Parameters:

protocolContact - the Contact we're looking for

Returns:

true if the given protocolContact is contained in this MetaContact, otherwise - returns false

getContactCount

int getContactCount()

Returns the number of protocol speciic Contacts that this MetaContact contains.

Returns:

an int indicating the number of protocol specific contacts merged in this MetaContact

getContactsForProvider

Iterator<Contact> getContactsForProvider(ProtocolProviderService provider)

Returns all protocol specific Contacts, encapsulated by this MetaContact and coming from the indicated ProtocolProviderService. If none of the contacts encapsulated by this MetaContact is originating from the specified provider then an empty iterator is returned.

Note to implementors: In order to prevent problems with concurrency, the Iterator returned by this method should not be over the actual list of contacts but rather over a copy of that list.

Parameters:

provider - a reference to the ProtocolProviderService whose contacts we'd like to get.

Returns:

an Iterator over all contacts encapsulated in this MetaContact and originating from the specified provider.

getContactsForOperationSet

List<Contact> getContactsForOperationSet(Class<? extends OperationSet> opSetClass)

Returns all protocol specific Contacts, encapsulated by this MetaContact and supporting the given opSetClass. If none of the contacts encapsulated by this MetaContact is supporting the specified OperationSet class then an empty list is returned.

Note to implementors: In order to prevent problems with concurrency, the List returned by this method should not be the actual list of contacts but rather a copy of that list.

Parameters:

opSetClass - the operation for which the default contact is needed

Returns:

a List of all contacts encapsulated in this MetaContact and supporting the specified OperationSet

getParentMetaContactGroup

MetaContactGroup getParentMetaContactGroup()

Returns the MetaContactGroup currently containing this meta contact

Returns:

a reference to the MetaContactGroup currently containing this meta contact.

getMetaUID

String getMetaUID()

Returns a String identifier (the actual contents is left to implementations) that uniquely represents this MetaContact in the containing MetaContactList

Returns:

String

getDisplayName

String getDisplayName()

Returns a characteristic display name that can be used when including this MetaContact in user interface.

Returns:

a human readable String that represents this meta contact.

getAvatar

byte[] getAvatar()

Returns the avatar of this contact, that can be used when including this MetaContact in user interface.

Returns:

an avatar (e.g. user photo) of this contact.

getAvatar

byte[] getAvatar(boolean isLazy)

Returns the avatar of this contact, that can be used when including this MetaContact in user interface. The isLazy parameter would tell the implementation if it could return the locally stored avatar or it should obtain the avatar right from the server.

Parameters:

isLazy - Indicates if this method should return the locally stored avatar or it should obtain the avatar right from the server.

Returns:

an avatar (e.g. user photo) of this contact.

toString

String toString()

Returns a String representation of this MetaContact.

Overrides:

toString in class Object

Returns:

a String representation of this MetaContact.

addDetail

void addDetail(String name,
               String value)

Adds a custom detail to this contact.

Parameters:

name - name of the detail.

value - the value of the detail.

removeDetail

void removeDetail(String name,
                  String value)

Remove the given detail.

Parameters:

name - of the detail to be removed.

value - value of the detail to be removed.

removeDetails

void removeDetails(String name)

Remove all details with given name.

Parameters:

name - of the details to be removed.

changeDetail

void changeDetail(String name,
                  String oldValue,
                  String newValue)

Change the detail.

Parameters:

name - of the detail to be changed.

oldValue - the old value of the detail.

newValue - the new value of the detail.

getDetails

List<String> getDetails(String name)

Get all details with given name.

Parameters:

name - the name of the details we are searching.

Returns:

list of string values for the details with the given name.

getData

Object getData(Object key)

Gets the user data associated with this instance and a specific key.

Parameters:

key - the key of the user data associated with this instance to be retrieved

Returns:

an Object which represents the value associated with this instance and the specified key; null if no association with the specified key exists in this instance

setData

void setData(Object key,
             Object value)

Sets a user-specific association in this instance in the form of a key-value pair. If the specified key is already associated in this instance with a value, the existing value is overwritten with the specified value.

The user-defined association created by this method and stored in this instance is not serialized by this instance and is thus only meant for runtime use.

The storage of the user data is implementation-specific and is thus not guaranteed to be optimized for execution time and memory use.

Parameters:

key - the key to associate in this instance with the specified value

value - the value to be associated in this instance with the specified key