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

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

All Implemented Interfaces:

MetaContactGroup

public class MetaContactGroupImpl
extends Object
implements MetaContactGroup

A straightforward implementation of the meta contact group. The group implements a simple algorithm of sorting its children according to their status.

Author:

Emil Ivov, Lubomir Marinov

Constructor Summary

MetaContactGroupImpl(MetaContactListServiceImpl mclServiceImpl, String groupName)
Creates an instance of the root meta contact group.

MetaContactGroupImpl(MetaContactListServiceImpl mclServiceImpl, String groupName, String metaUID)
Creates an instance of the root meta contact group assigning it the specified meta contact uid.

Method Summary

(package private) void	addMetaContact(MetaContactImpl metaContact) Adds the specified metaContact to ths local list of child contacts.
(package private) void	addProtoGroup(ContactGroup protoGroup) Adds the specified group to the list of protocol specific groups that we're encapsulating in this meta contact group.
(package private) void	addSubgroup(MetaContactGroup subgroup) Adds the specified meta group to the subgroups of this one.
boolean	canContainSubgroups() Determines whether or not this group can contain subgroups.
boolean	contains(MetaContact contact) Returns true if and only if contact is a direct child of this group.
boolean	contains(MetaContactGroup group) Returns true if and only if group is a direct subgroup of this MetaContactGroup.
int	countChildContacts() Returns the number of MetaContacts that this group contains.
int	countContactGroups() Returns the number of ContactGroupss that this group encapsulates
int	countOnlineChildContacts() Returns the number of online MetaContacts that this group contains.
int	countSubgroups() Returns the number of subgroups that this MetaContactGroup contains.
MetaContact	findMetaContactByContact(Contact protoContact) Returns a meta contact, a child of this group or its subgroups, that has the specified protocol specific contact.
MetaContact	findMetaContactByContact(String contactAddress, String accountID) Returns a meta contact, a child of this group or its subgroups, with address equald to contactAddress and a source protocol provider with the matching accountID.
MetaContact	findMetaContactByMetaUID(String metaUID) Returns a meta contact, a child of this group or its subgroups, that has the specified metaUID.
MetaContactGroupImpl	findMetaContactGroupByContactGroup(ContactGroup protoContactGroup) Returns a meta contact group, encapsulated by this group or its subgroups, that has the specified protocol specific contact.
MetaContactGroup	findMetaContactGroupByMetaUID(String metaUID) Returns a meta contact group this group or some of its subgroups, that has the specified metaUID.
Iterator<MetaContact>	getChildContacts() Returns a java.util.Iterator over the MetaContacts contained in this MetaContactGroup.
ContactGroup	getContactGroup(String grpName, ProtocolProviderService ownerProvider) Returns a contact group encapsulated by this meta contact group, having the specified groupName and coming from the indicated ownerProvider.
Iterator<ContactGroup>	getContactGroups() Returns an iterator over all the protocol specific groups that this contact group represents.
Iterator<ContactGroup>	getContactGroupsForAccountID(String accountID) Returns all protocol specific ContactGroups, encapsulated by this MetaContactGroup and coming from the provider matching the accountID param.
Iterator<ContactGroup>	getContactGroupsForProvider(ProtocolProviderService provider) Returns all protocol specific ContactGroups, encapsulated by this MetaContactGroup and coming from the indicated ProtocolProviderService.
Object	getData(Object key) Implements MetaContactGroup.getData(Object).
String	getGroupName() Returns the name of this group.
(package private) MetaContactListServiceImpl	getMclServiceImpl() Returns the implementation of the MetaContactListService, to which this group belongs.
MetaContact	getMetaContact(int index) Returns the meta contact on the specified index.
MetaContact	getMetaContact(ProtocolProviderService provider, String contactID) Returns the meta contact encapsulating a contact belonging to the specified provider with the specified identifier.
MetaContact	getMetaContact(String metaContactID) Returns the contact with the specified identifier
MetaContactGroup	getMetaContactSubgroup(int index) Returns the MetaContactGroup with the specified index.
MetaContactGroup	getMetaContactSubgroup(String grpName) Returns the MetaContactGroup with the specified name.
MetaContactGroup	getMetaContactSubgroupByUID(String grpUID) Returns the MetaContactGroup with the specified groupUID.
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 group or null if this is the root group
Iterator<MetaContactGroup>	getSubgroups() Returns an java.util.Iterator over the sub groups that this MetaContactGroup contains.
int	indexOf(MetaContact metaContact) Returns the index of metaContact according to other contacts in this or -1 if metaContact does not belong to this group.
int	indexOf(MetaContactGroup metaContactGroup) Returns the index of metaContactGroup in relation to other subgroups in this group or -1 if metaContact does not belong to this group.
boolean	isPersistent() Determines whether or not this meta group contains only groups that are being stored by a server.
(package private) int	lightAddMetaContact(MetaContactImpl metaContact) Adds the metaContact to the local list of child contacts without setting its parrent contact and without any synchronization.
(package private) void	lightRemoveMetaContact(MetaContactImpl metaContact) Removes the metaContact from the local list of child contacts without unsetting its parrent contact and without any synchronization.
(package private) void	removeMetaContact(MetaContactImpl metaContact) Removes the specified metaContact from the local list of contacts.
(package private) void	removeProtoGroup(ContactGroup protoGroup) Removes the specified group from the list of protocol specific groups that we're encapsulating in this meta contact group.
(package private) MetaContactGroupImpl	removeSubgroup(int index) Removes the meta contact group with the specified index.
(package private) boolean	removeSubgroup(MetaContactGroup group) Removes the specified group from the list of groups in this list.
void	setData(Object key, Object value) Implements MetaContactGroup.setData(Object, Object).
(package private) void	setGroupName(String newGroupName) Sets the name of this group.
String	toString() Returns a String representation of this group and the contacts it contains (may turn out to be a relatively long string).

Methods inherited from class java.lang.Object

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

Constructor Detail

MetaContactGroupImpl

MetaContactGroupImpl(MetaContactListServiceImpl mclServiceImpl,
                     String groupName)

Creates an instance of the root meta contact group.

Parameters:

mclServiceImpl - the MetaContactListService implementation which is to use the new MetaContactGroup instance as its root

groupName - the name of the group to create

MetaContactGroupImpl

MetaContactGroupImpl(MetaContactListServiceImpl mclServiceImpl,
                     String groupName,
                     String metaUID)

Creates an instance of the root meta contact group assigning it the specified meta contact uid. This constructor MUST NOT be used for nothing purposes else but restoring contacts extracted from the contactlist.xml

Parameters:

mclServiceImpl - the implementation of the MetaContactListService, to which this group belongs

groupName - the name of the group to create

metaUID - a UID that has been stored earlier or null when a new UID needs to be created.

Method Detail

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 MetaContactGroup

Returns:

a String uniquely identifying this meta contact.

getParentMetaContactGroup

public MetaContactGroup getParentMetaContactGroup()

Returns the MetaContactGroup currently containing this group or null if this is the root group

Specified by:

getParentMetaContactGroup in interface MetaContactGroup

Returns:

a reference to the MetaContactGroup currently containing this meta contact group or null if this is the root group.

canContainSubgroups

public boolean canContainSubgroups()

Determines whether or not this group can contain subgroups.

Specified by:

canContainSubgroups in interface MetaContactGroup

Returns:

always true since this is the root contact group and in our impl it can only contain groups.

countChildContacts

public int countChildContacts()

Returns the number of MetaContacts that this group contains.

Specified by:

countChildContacts in interface MetaContactGroup

Returns:

the number of MetaContacts that this group contains.

countOnlineChildContacts

public int countOnlineChildContacts()

Returns the number of online MetaContacts that this group contains.

Specified by:

countOnlineChildContacts in interface MetaContactGroup

Returns:

the number of online MetaContacts that this group contains.

countContactGroups

public int countContactGroups()

Returns the number of ContactGroupss that this group encapsulates

Specified by:

countContactGroups in interface MetaContactGroup

Returns:

an int indicating the number of ContactGroups-s that this group encapsulates.

countSubgroups

public int countSubgroups()

Returns the number of subgroups that this MetaContactGroup contains.

Specified by:

countSubgroups in interface MetaContactGroup

Returns:

an int indicating the number of subgroups in this group.

getChildContacts

public Iterator<MetaContact> getChildContacts()

Returns a java.util.Iterator over the MetaContacts contained in this MetaContactGroup.

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

Specified by:

getChildContacts in interface MetaContactGroup

Returns:

a java.util.Iterator over an empty contacts list.

getMetaContact

public MetaContact getMetaContact(String metaContactID)

Returns the contact with the specified identifier

Specified by:

getMetaContact in interface MetaContactGroup

Parameters:

metaContactID - a String identifier obtained through the MetaContact.getMetaUID() method.

Returns:

the MetaContact with the specified idnetifier.

indexOf

public int indexOf(MetaContact metaContact)

Returns the index of metaContact according to other contacts in this or -1 if metaContact does not belong to this group. The returned index is only valid until another contact has been added / removed or a contact has changed its status and hence - position. In such a case a REORDERED event is fired.

Specified by:

indexOf in interface MetaContactGroup

Parameters:

metaContact - the MetaContact whose index we're looking for.

Returns:

the index of metaContact in the list of child contacts or -1 if metaContact.

indexOf

public int indexOf(MetaContactGroup metaContactGroup)

Returns the index of metaContactGroup in relation to other subgroups in this group or -1 if metaContact does not belong to this group. The returned index is only valid until another group has been added / removed or renamed In such a case a REORDERED event is fired.

Specified by:

indexOf in interface MetaContactGroup

Parameters:

metaContactGroup - the MetaContactGroup whose index we're looking for.

Returns:

the index of metaContactGroup in the list of child contacts or -1 if metaContact.

getMetaContact

public MetaContact getMetaContact(ProtocolProviderService provider,
                                  String contactID)

Returns the meta contact encapsulating a contact belonging to the specified provider with the specified identifier.

Specified by:

getMetaContact in interface MetaContactGroup

Parameters:

provider - the ProtocolProviderService that the specified contactID is pertaining to.

contactID - a String identifier of the protocol specific contact whose container meta contact we're looking for.

Returns:

the MetaContact with the specified identifier.

findMetaContactByMetaUID

public MetaContact findMetaContactByMetaUID(String metaUID)

Returns a meta contact, a child of this group or its subgroups, that has the specified metaUID. If no such meta contact exists, the method would return null.

Parameters:

metaUID - the Meta UID of the contact we're looking for.

Returns:

the MetaContact with the specified UID or null if no such contact exists.

findMetaContactGroupByMetaUID

public MetaContactGroup findMetaContactGroupByMetaUID(String metaUID)

Returns a meta contact group this group or some of its subgroups, that has the specified metaUID. If no such meta contact group exists, the method would return null.

Parameters:

metaUID - the Meta UID of the contact group we're looking for.

Returns:

the MetaContactGroup with the specified UID or null if no such contact exists.

getContactGroups

public Iterator<ContactGroup> getContactGroups()

Returns an iterator over all the protocol specific groups that this contact group represents.

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

Specified by:

getContactGroups in interface MetaContactGroup

Returns:

an Iterator over the protocol specific groups that this group represents.

getContactGroup

public ContactGroup getContactGroup(String grpName,
                                    ProtocolProviderService ownerProvider)

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

Specified by:

getContactGroup in interface MetaContactGroup

Parameters:

grpName - the name of the contact group 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 ContactGroup, encapsulated by this MetaContactGroup, carrying the specified name and originating from the specified ownerProvider or null if no such contact group was found.

getContactGroupsForProvider

public Iterator<ContactGroup> getContactGroupsForProvider(ProtocolProviderService provider)

Returns all protocol specific ContactGroups, encapsulated by this MetaContactGroup 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.

Specified by:

getContactGroupsForProvider in interface MetaContactGroup

Parameters:

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

Returns:

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

getContactGroupsForAccountID

public Iterator<ContactGroup> getContactGroupsForAccountID(String accountID)

Returns all protocol specific ContactGroups, encapsulated by this MetaContactGroup and coming from the provider matching the accountID param. If none of the contacts encapsulated by this MetaContact is originating from the specified account 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 groups but rather over a copy of that list.

Specified by:

getContactGroupsForAccountID in interface MetaContactGroup

Parameters:

accountID - the id of the account whose contact groups we'd like to retrieve.

Returns:

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

findMetaContactByContact

public MetaContact findMetaContactByContact(Contact protoContact)

Returns a meta contact, a child of this group or its subgroups, that has the specified protocol specific contact. If no such meta contact exists, the method would return null.

Parameters:

protoContact - the protocol specific contact whos meta contact we're looking for.

Returns:

the MetaContactImpl that contains the specified protocol specific contact.

findMetaContactByContact

public MetaContact findMetaContactByContact(String contactAddress,
                                            String accountID)

Returns a meta contact, a child of this group or its subgroups, with address equald to contactAddress and a source protocol provider with the matching accountID. If no such meta contact exists, the method would return null.

Parameters:

contactAddress - the address of the protocol specific contact whose meta contact we're looking for.

accountID - the ID of the account that the contact we are looking for must belong to.

Returns:

the MetaContactImpl that contains the specified protocol specific contact.

findMetaContactGroupByContactGroup

public MetaContactGroupImpl findMetaContactGroupByContactGroup(ContactGroup protoContactGroup)

Returns a meta contact group, encapsulated by this group or its subgroups, that has the specified protocol specific contact. If no such meta contact group exists, the method would return null.

Parameters:

protoContactGroup - the protocol specific contact group whose meta contact group we're looking for.

Returns:

the MetaContactImpl that contains the specified protocol specific contact.

getMetaContact

public MetaContact getMetaContact(int index)
                           throws IndexOutOfBoundsException

Returns the meta contact on the specified index.

Specified by:

getMetaContact in interface MetaContactGroup

Parameters:

index - the index of the meta contact to return.

Returns:

the MetaContact with the specified index,

Throws:

IndexOutOfBoundsException - in case index is not a valid index for this group.

addMetaContact

void addMetaContact(MetaContactImpl metaContact)

Adds the specified metaContact to ths local list of child contacts.

Parameters:

metaContact - the MetaContact to add in the local vector.

lightAddMetaContact

int lightAddMetaContact(MetaContactImpl metaContact)

Adds the metaContact to the local list of child contacts without setting its parrent contact and without any synchronization. This method is meant for use _PRIMARILY_ by the MetaContact itself upon chenge in its encapsulated protocol specific contacts.

Parameters:

metaContact - the MetaContact to add in the local vector.

Returns:

the index at which the contact was added.

lightRemoveMetaContact

void lightRemoveMetaContact(MetaContactImpl metaContact)

Removes the metaContact from the local list of child contacts without unsetting its parrent contact and without any synchronization. This method is meant for use _PRIMARILY_ by the MetaContact itself upon chenge in its encapsulated protocol specific contacts. The method would also regenerate the ordered copy used for generating iterators and performing search operations over the group.

Parameters:

metaContact - the MetaContact to remove from the local vector.

removeMetaContact

void removeMetaContact(MetaContactImpl metaContact)

Removes the specified metaContact from the local list of contacts.

Parameters:

metaContact - the MetaContact

getMetaContactSubgroup

public MetaContactGroup getMetaContactSubgroup(int index)
                                        throws IndexOutOfBoundsException

Returns the MetaContactGroup with the specified index.

Specified by:

getMetaContactSubgroup in interface MetaContactGroup

Parameters:

index - the index of the group to return.

Returns:

the MetaContactGroup with the specified index.

Throws:

IndexOutOfBoundsException - if index is not a valid index.

getMetaContactSubgroup

public MetaContactGroup getMetaContactSubgroup(String grpName)

Returns the MetaContactGroup with the specified name.

Specified by:

getMetaContactSubgroup in interface MetaContactGroup

Parameters:

grpName - the name of the group to return.

Returns:

the MetaContactGroup with the specified name or null if no such group exists.

getMetaContactSubgroupByUID

public MetaContactGroup getMetaContactSubgroupByUID(String grpUID)

Returns the MetaContactGroup with the specified groupUID.

Parameters:

grpUID - the uid of the group to return.

Returns:

the MetaContactGroup with the specified uid or null if no such group exists.

contains

public boolean contains(MetaContact contact)

Returns true if and only if contact is a direct child of this group.

Specified by:

contains in interface MetaContactGroup

Parameters:

contact - the MetaContact whose relation to this group we'd like to determine.

Returns:

true if contact is a direct child of this group and false otherwise.

contains

public boolean contains(MetaContactGroup group)

Returns true if and only if group is a direct subgroup of this MetaContactGroup.

Specified by:

contains in interface MetaContactGroup

Parameters:

group - the MetaContactGroup whose relation to this group we'd like to determine.

Returns:

true if group is a direct child of this MetaContactGroup and false otherwise.

getSubgroups

public Iterator<MetaContactGroup> getSubgroups()

Returns an java.util.Iterator over the sub groups that this MetaContactGroup contains.

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

Specified by:

getSubgroups in interface MetaContactGroup

Returns:

a java.util.Iterator containing all subgroups.

getGroupName

public String getGroupName()

Returns the name of this group.

Specified by:

getGroupName in interface MetaContactGroup

Returns:

a String containing the name of this group.

setGroupName

void setGroupName(String newGroupName)

Sets the name of this group.

Parameters:

newGroupName - a String containing the new name of this group.

toString

public String toString()

Returns a String representation of this group and the contacts it contains (may turn out to be a relatively long string).

Specified by:

toString in interface MetaContactGroup

Overrides:

toString in class Object

Returns:

a String representing this group and its child contacts.

addProtoGroup

void addProtoGroup(ContactGroup protoGroup)

Adds the specified group to the list of protocol specific groups that we're encapsulating in this meta contact group.

Parameters:

protoGroup - the root to add to the groups merged in this meta contact group.

removeProtoGroup

void removeProtoGroup(ContactGroup protoGroup)

Removes the specified group from the list of protocol specific groups that we're encapsulating in this meta contact group.

Parameters:

protoGroup - the group to remove from the groups merged in this meta contact group.

addSubgroup

void addSubgroup(MetaContactGroup subgroup)

Adds the specified meta group to the subgroups of this one.

Parameters:

subgroup - the MetaContactGroup to register as a subgroup to this root meta contact group.

removeSubgroup

MetaContactGroupImpl removeSubgroup(int index)

Removes the meta contact group with the specified index.

Parameters:

index - the index of the group to remove.

Returns:

the MetaContactGroup that has just been removed.

removeSubgroup

boolean removeSubgroup(MetaContactGroup group)

Removes the specified group from the list of groups in this list.

Parameters:

group - the MetaContactGroup to remove.

Returns:

true if the group has been successfully removed and false otherwise.

getMclServiceImpl

final MetaContactListServiceImpl getMclServiceImpl()

Returns the implementation of the MetaContactListService, to which this group belongs.

Returns:

the implementation of the MetaContactListService

getData

public Object getData(Object key)

Implements MetaContactGroup.getData(Object).

Specified by:

getData in interface MetaContactGroup

Parameters:

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

Returns:

the data value corresponding to the given key

setData

public void setData(Object key,
                    Object value)

Implements MetaContactGroup.setData(Object, Object).

Specified by:

setData in interface MetaContactGroup

Parameters:

key - the of the data

value - the value of the data

isPersistent

public boolean isPersistent()

Determines whether or not this meta group contains only groups that are being stored by a server.

Specified by:

isPersistent in interface MetaContactGroup

Returns:

true if the meta group is persistent and false otherwise.