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

All Superinterfaces:

Comparable<MetaContactGroup>

All Known Implementing Classes:

MetaContactGroupImpl

public interface MetaContactGroup
extends Comparable<MetaContactGroup>

MetaContactGroups are used to merge groups (often originating in different protocols).

A MetaContactGroup may contain contacts and some groups may also have sub-groups as children. To verify whether or not a particular group may contain subgroups, a developer has to call the canContainSubgroups() method

Author:

Emil Ivov

Method Summary

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.
Iterator<MetaContact>	getChildContacts() Returns a java.util.Iterator over the MetaContacts contained in this MetaContactGroup.
ContactGroup	getContactGroup(String groupName, 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) Gets the user data associated with this instance and a specific key.
String	getGroupName() Returns the name of this group.
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 metaUID) Returns the contact with the specified identifier
MetaContactGroup	getMetaContactSubgroup(int index) Returns the MetaContactGroup with the specified index.
MetaContactGroup	getMetaContactSubgroup(String groupName) Returns the MetaContactGroup with the specified name.
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 in relation 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.
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 group and the contacts it contains (may turn out to be a relatively long string).

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getContactGroups

Iterator<ContactGroup> getContactGroups()

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

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.

Returns:

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

getContactGroupsForProvider

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.

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.

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

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.

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.

contains

boolean contains(MetaContact contact)

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

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

boolean contains(MetaContactGroup group)

Returns true if and only if group is a direct subgroup of this 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.

getContactGroup

ContactGroup getContactGroup(String groupName,
                             ProtocolProviderService ownerProvider)

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

Parameters:

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

getChildContacts

Iterator<MetaContact> getChildContacts()

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

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 over the MetaContacts in this group.

countChildContacts

int countChildContacts()

Returns the number of MetaContacts that this group contains

Returns:

an int indicating the number of MetaContact-s that this group contains.

countOnlineChildContacts

int countOnlineChildContacts()

Returns the number of online MetaContacts that this group contains.

Returns:

the number of online MetaContacts that this group contains.

countContactGroups

int countContactGroups()

Returns the number of ContactGroupss that this group encapsulates

Returns:

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

getSubgroups

Iterator<MetaContactGroup> getSubgroups()

Returns an java.util.Iterator over the sub groups that this MetaContactGroup contains. Not all MetaContactGroups can have sub groups. In case there are no subgroups in this MetaContactGroup, the method would return an empty list. The canContainSubgroups() method allows us to verify whether this is the case with the group at hand.

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.

Returns:

a java.util.Iterator containing all subgroups.

countSubgroups

int countSubgroups()

Returns the number of subgroups that this MetaContactGroup contains.

Returns:

an int indicating the number of subgroups in this group.

canContainSubgroups

boolean canContainSubgroups()

Determines whether or not this group can contain subgroups. The method should be called befor creating subgroups in order to avoir invalid argument exceptions.

Returns:

true if this groups can contain subgroups and false otherwise.

getMetaContact

MetaContact getMetaContact(ProtocolProviderService provider,
                           String contactID)

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

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

getMetaContact

MetaContact getMetaContact(String metaUID)

Returns the contact with the specified identifier

Parameters:

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

Returns:

the MetaContact with the specified idnetifier.

indexOf

int indexOf(MetaContact metaContact)

Returns the index of metaContact in relation 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.

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

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.

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

MetaContact getMetaContact(int index)
                           throws IndexOutOfBoundsException

Returns the meta contact on the specified index.

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.

getGroupName

String getGroupName()

Returns the name of this group.

Returns:

a String containing the name of this group.

getMetaContactSubgroup

MetaContactGroup getMetaContactSubgroup(String groupName)

Returns the MetaContactGroup with the specified name.

Parameters:

groupName - the name of the group to return.

Returns:

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

getMetaContactSubgroup

MetaContactGroup getMetaContactSubgroup(int index)
                                        throws IndexOutOfBoundsException

Returns the MetaContactGroup with the specified index.

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.

getParentMetaContactGroup

MetaContactGroup getParentMetaContactGroup()

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

Returns:

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

toString

String toString()

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

Overrides:

toString in class Object

Returns:

a String representing this group and its child contacts.

getMetaUID

String getMetaUID()

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

Returns:

a String uniquely identifying this meta contact.

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

isPersistent

boolean isPersistent()

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

Returns:

true if the meta group is persistent and false otherwise.