net.java.sip.communicator.impl.contactlist
Class MetaContactImpl

java.lang.Object
  net.java.sip.communicator.impl.contactlist.MetaContactImpl

All Implemented Interfaces:

Comparable<MetaContact>, MetaContact

public class MetaContactImpl
extends Object
implements MetaContact

A default implementation of the MetaContact interface.

Author:

Emil Ivov, Lubomir Marinov

Constructor Summary

MetaContactImpl()
Creates new meta contact with a newly generated meta contact UID.

MetaContactImpl(String metaUID, Map<String,List<String>> details)
Creates a new meta contact with the specified UID.

Method Summary

void	addDetail(String name, String value) Adds a custom detail to this contact.
(package private) void	addProtoContact(Contact contact) Adds the specified protocol specific contact to the list of contacts merged in this meta contact.
void	cacheAvatar(Contact protoContact, byte[] avatarBytes) Stores avatar bytes in the given Contact.
void	changeDetail(String name, String oldValue, String newValue) Change the detail.
int	compareTo(MetaContact o) Compares this meta contact with the specified object for order.
boolean	containsContact(Contact protocolContact) Returns true if the given protocolContact is contained in this MetaContact, otherwise - returns false.
byte[]	getAvatar() Returns an avatar that can be used when presenting 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.
Contact	getContact(String contactAddress, String accountID) Returns a contact encapsulated by this meta contact, having the specified contactAddress and coming from a provider with a mathing accountID.
int	getContactCount() Returns the number of protocol specific Contacts that this MetaContact contains.
Iterator<Contact>	getContacts() Returns a java.util.Iterator over all protocol specific Contacts encapsulated by this MetaContact.
Iterator<Contact>	getContactsForContactGroup(ContactGroup parentProtoGroup) Returns contacts, encapsulated by this MetaContact and belonging to the specified protocol ContactGroup.
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 a Contact, encapsulated by this MetaContact and coming from the specified ProtocolProviderService.
Object	getData(Object key) Implements MetaContact.getData(Object).
Contact	getDefaultContact() Currently simply returns the most connected protocol contact.
Contact	getDefaultContact(Class<? extends OperationSet> operationSet) Returns a default contact for a specific operation (call, file transfer, IM ...)
List<String>	getDetails(String name) Gets all details with a 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
(package private) MetaContactGroupImpl	getParentGroup() Returns the group that is currently holding this meta contact.
MetaContactGroup	getParentMetaContactGroup() Returns the MetaContactGroup currently containing this meta contact
(package private) boolean	isDisplayNameUserDefined() Determines if display name was changed for this MetaContact in user interface.
(package private) int	reevalContact() Called by MetaContactListServiceImpl after a contact has changed its status, so that ordering in the parent group is updated.
(package private) boolean	removeContactsForGroup(ContactGroup protoGroup) Removes all proto contacts that belong to the specified protocol group.
(package private) boolean	removeContactsForProvider(ProtocolProviderService provider) Removes all proto contacts that belong to the specified provider.
void	removeDetail(String name, String value) Remove the given detail.
void	removeDetails(String name) Remove all details with given name.
(package private) void	removeProtoContact(Contact contact) Removes the specified protocol specific contact from the contacts encapsulated in this MetaContact.
void	setData(Object key, Object value) Implements MetaContact.setData(Object, Object).
(package private) void	setDisplayName(String displayName) Sets a name that can be used when displaying this contact in user interface components.
(package private) void	setDisplayNameUserDefined(boolean value) Changes that display name was changed for this MetaContact in user interface.
(package private) void	setParentGroup(MetaContactGroupImpl parentGroup) Sets parentGroup as a parent of this meta contact.
String	toString() Returns a string representation of this contact, containing most of its representative details.
(package private) void	unsetParentGroup(MetaContactGroupImpl parentGrp) If parentGroup was the parent of this meta contact then it sets it to null.
void	updateCapabilities(Contact contact, Map<String,? extends OperationSet> opSets) Updates the capabilities for the given contact.

Methods inherited from class java.lang.Object

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

Constructor Detail

MetaContactImpl

MetaContactImpl()

Creates new meta contact with a newly generated meta contact UID.

MetaContactImpl

MetaContactImpl(String metaUID,
                Map<String,List<String>> details)

Creates a new meta contact with the specified UID. This constructor MUST ONLY be used when restoring contacts stored in the contactlist.xml.

Parameters:

metaUID - the meta uid that this meta contact should have.

details - the already stored details for the contact.

Method Detail

getContactCount

public int getContactCount()

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

Specified by:

getContactCount in interface MetaContact

Returns:

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

getContactsForProvider

public Iterator<Contact> getContactsForProvider(ProtocolProviderService provider)

Returns a Contact, encapsulated by this MetaContact and coming from the specified ProtocolProviderService.

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

Specified by:

getContactsForProvider in interface MetaContact

Parameters:

provider - a reference to the ProtocolProviderService that we'd like to get a Contact for.

Returns:

a Contact encapsulated in this MetaContact and originating from the specified provider.

getContactsForOperationSet

public 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 iterator is returned.

Specified by:

getContactsForOperationSet in interface MetaContact

Parameters:

opSetClass - the operation for which the default contact is needed

Returns:

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

getContactsForContactGroup

public Iterator<Contact> getContactsForContactGroup(ContactGroup parentProtoGroup)

Returns contacts, encapsulated by this MetaContact and belonging to the specified protocol ContactGroup.

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

Parameters:

parentProtoGroup - a reference to the ContactGroup whose children we'd like removed..

Returns:

an Iterator over all Contacts encapsulated in this MetaContact and belonging to the specified proto ContactGroup.

getContact

public Contact getContact(String contactAddress,
                          ProtocolProviderService ownerProvider)

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

Specified by:

getContact in interface MetaContact

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

getContact

public Contact getContact(String contactAddress,
                          String accountID)

Returns a contact encapsulated by this meta contact, having the specified contactAddress and coming from a provider with a mathing accountID. The method returns null if no such contact exists.

Parameters:

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

accountID - the identifier of the provider that the contact we're looking for must belong to.

Returns:

a reference to a Contact, encapsulated by this MetaContact, carrying the specified address and originating from the ownerProvider carryign accountID.

containsContact

public boolean containsContact(Contact protocolContact)

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

Specified by:

containsContact in interface MetaContact

Parameters:

protocolContact - the Contact we're looking for

Returns:

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

getContacts

public Iterator<Contact> getContacts()

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

In order to prevent problems with concurrency, the Iterator returned by this method is not over the actual list of contacts but over a copy of that list.

Specified by:

getContacts in interface MetaContact

Returns:

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

getDefaultContact

public Contact getDefaultContact()

Currently simply returns the most connected protocol contact. We should add the possibility to choose it also according to preconfigured preferences.

Specified by:

getDefaultContact in interface MetaContact

Returns:

the default Contact to use when communicating with this MetaContact

getDefaultContact

public Contact getDefaultContact(Class<? extends OperationSet> operationSet)

Returns a default contact for a specific operation (call, file transfer, IM ...)

Specified by:

getDefaultContact in interface MetaContact

Parameters:

operationSet - the operation for which the default contact is needed

Returns:

the default contact for the specified operation.

getMetaUID

public String getMetaUID()

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

Specified by:

getMetaUID in interface MetaContact

Returns:

a String uniquely identifying this meta contact.

compareTo

public int compareTo(MetaContact o)

Compares this meta contact with the specified object for order. Returns a negative integer, zero, or a positive integer as this meta contact is less than, equal to, or greater than the specified object.

The result of this method is calculated the following way:

(contactsOnline - o.contactsOnline) * 1 000 000
+ getDisplayName().compareTo(o.getDisplayName()) * 100 000 + getMetaUID().compareTo(o.getMetaUID())

Or in other words ordering of meta accounts would be first done by presence status, then display name, and finally (in order to avoid equalities) be the fairly random meta contact metaUID.

Specified by:

compareTo in interface Comparable<MetaContact>

Parameters:

o - the MetaContact to be compared.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

ClassCastException - if the specified object is not a MetaContactListImpl

toString

public String toString()

Returns a string representation of this contact, containing most of its representative details.

Specified by:

toString in interface MetaContact

Overrides:

toString in class Object

Returns:

a string representation of this contact.

getDisplayName

public String getDisplayName()

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

Specified by:

getDisplayName in interface MetaContact

Returns:

a human readable String that represents this meta contact.

isDisplayNameUserDefined

boolean isDisplayNameUserDefined()

Determines if display name was changed for this MetaContact in user interface.

Returns:

whether display name was changed by user.

setDisplayNameUserDefined

void setDisplayNameUserDefined(boolean value)

Changes that display name was changed for this MetaContact in user interface.

Parameters:

value - control whether display name is user defined

getAvatar

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

Specified by:

getAvatar in interface MetaContact

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.

getAvatar

public byte[] getAvatar()

Returns an avatar that can be used when presenting this MetaContact in user interface. The method would also make sure that we try the network for new versions of avatars.

Specified by:

getAvatar in interface MetaContact

Returns:

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

setDisplayName

void setDisplayName(String displayName)

Sets a name that can be used when displaying this contact in user interface components.

Parameters:

displayName - a human readable String representing this MetaContact

addProtoContact

void addProtoContact(Contact contact)

Adds the specified protocol specific contact to the list of contacts merged in this meta contact. The method also keeps up to date the contactsOnline field which is used in the compareTo() method.

Parameters:

contact - the protocol specific Contact to add.

reevalContact

int reevalContact()

Called by MetaContactListServiceImpl after a contact has changed its status, so that ordering in the parent group is updated. The method also elects the most connected contact as default contact.

Returns:

the new index at which the contact was added.

removeProtoContact

void removeProtoContact(Contact contact)

Removes the specified protocol specific contact from the contacts encapsulated in this MetaContact. The method also updates the total status field accordingly. And updates its ordered position in its parent group. If the display name of this MetaContact was the one of the removed contact, we update it.

Parameters:

contact - the contact to remove

removeContactsForProvider

boolean removeContactsForProvider(ProtocolProviderService provider)

Removes all proto contacts that belong to the specified provider.

Parameters:

provider - the provider whose contacts we want removed.

Returns:

true if this MetaContact was modified and false otherwise.

removeContactsForGroup

boolean removeContactsForGroup(ContactGroup protoGroup)

Removes all proto contacts that belong to the specified protocol group.

Parameters:

protoGroup - the group whose children we want removed.

Returns:

true if this MetaContact was modified and false otherwise.

setParentGroup

void setParentGroup(MetaContactGroupImpl parentGroup)

Sets parentGroup as a parent of this meta contact. Do not call this method with a null argument even if a group is removing this contact from itself as this could lead to race conditions (imagine another group setting itself as the new parent and you removing it). Use unsetParentGroup instead.

Parameters:

parentGroup - the MetaContactGroupImpl that is currently a parent of this meta contact.

Throws:

NullPointerException - if parentGroup is null.

unsetParentGroup

void unsetParentGroup(MetaContactGroupImpl parentGrp)

If parentGroup was the parent of this meta contact then it sets it to null. Call this method when removing this contact from a meta contact group.

Parameters:

parentGrp - the MetaContactGroupImpl that we don't want considered as a parent of this contact any more.

getParentGroup

MetaContactGroupImpl getParentGroup()

Returns the group that is currently holding this meta contact.

Returns:

the group that is currently holding this meta contact.

getParentMetaContactGroup

public MetaContactGroup getParentMetaContactGroup()

Returns the MetaContactGroup currently containing this meta contact

Specified by:

getParentMetaContactGroup in interface MetaContact

Returns:

a reference to the MetaContactGroup currently containing this meta contact.

addDetail

public void addDetail(String name,
                      String value)

Adds a custom detail to this contact.

Specified by:

addDetail in interface MetaContact

Parameters:

name - name of the detail.

value - the value of the detail.

removeDetail

public void removeDetail(String name,
                         String value)

Remove the given detail.

Specified by:

removeDetail in interface MetaContact

Parameters:

name - of the detail to be removed.

value - value of the detail to be removed.

removeDetails

public void removeDetails(String name)

Remove all details with given name.

Specified by:

removeDetails in interface MetaContact

Parameters:

name - of the details to be removed.

changeDetail

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

Change the detail.

Specified by:

changeDetail in interface MetaContact

Parameters:

name - of the detail to be changed.

oldValue - the old value of the detail.

newValue - the new value of the detail.

getDetails

public List<String> getDetails(String name)

Gets all details with a given name.

Specified by:

getDetails in interface MetaContact

Parameters:

name - the name of the details we are searching for

Returns:

a List of Strings which represent the details with the specified name

cacheAvatar

public void cacheAvatar(Contact protoContact,
                        byte[] avatarBytes)

Stores avatar bytes in the given Contact.

Parameters:

protoContact - The contact in which we store the avatar.

avatarBytes - The avatar image bytes.

getData

public Object getData(Object key)

Implements MetaContact.getData(Object). Gets the user data associated with this instance and a specific key.

Specified by:

getData in interface MetaContact

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

See Also:

MetaContact.getData(Object)

setData

public void setData(Object key,
                    Object value)

Implements MetaContact.setData(Object, Object). 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.

Specified by:

setData in interface MetaContact

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

See Also:

MetaContact.setData(Object, Object)

updateCapabilities

public void updateCapabilities(Contact contact,
                               Map<String,? extends OperationSet> opSets)

Updates the capabilities for the given contact.

Parameters:

contact - the Contact, which capabilities have changed

opSets - the new updated set of operation sets