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

All Known Implementing Classes:

AbstractContactGroupIcqImpl, AbstractContactGroupJabberImpl, AbstractContactGroupMsnImpl, AbstractContactGroupYahooImpl, ContactGroupDictImpl, ContactGroupGibberishImpl, ContactGroupIcqImpl, ContactGroupJabberImpl, ContactGroupMsnImpl, ContactGroupRssImpl, ContactGroupSipImpl, ContactGroupSSHImpl, ContactGroupYahooImpl, ContactGroupZeroconfImpl, MockContactGroup, RootContactGroupIcqImpl, RootContactGroupJabberImpl, RootContactGroupMsnImpl, RootContactGroupYahooImpl, VolatileContactGroupJabberImpl, VolatileContactGroupYahooImpl

public interface ContactGroup

A ContactGroup is a collection of Contacts/Buddies/Subscriptions, stored by a communications service (e.g. AIM/ICQ or Skype)returned by persistent presence operation sets. A group may contain simple members or subgroups. Instances of ContactGroup cannot be directly modified by users of the protocol provider service. In order to add buddies or subgroups to a ContactGroup one needs to do so through the OperationSetPersistentPresence interface.

Author:

Emil Ivov

Method Summary

boolean	canContainSubgroups() Determines whether the group may contain subgroups or not.
Iterator<Contact>	contacts() Returns an Iterator over all contacts, member of this ContactGroup.
int	countContacts() Returns the number of Contact members of this ContactGroup
int	countSubgroups() Returns the number of subgroups contained by this ContactGroup.
Contact	getContact(String id) Returns the Contact with the specified address or identifier.
ContactGroup	getGroup(int index) Returns the subgroup with the specified index.
ContactGroup	getGroup(String groupName) Returns the subgroup with the specified name.
String	getGroupName() Returns the name of this group.
ContactGroup	getParentContactGroup() Returns the contact group that currently contains this group or null if this is the root contact group.
String	getPersistentData() Returns a String that can be used to create a unresolved instance of this group.
ProtocolProviderService	getProtocolProvider() Returns the protocol provider that this group belongs to.
String	getUID() Returns a String that uniquely represents the group inside the current protocol.
boolean	isPersistent() Determines whether or not this contact group is being stored by the server.
boolean	isResolved() Determines whether or not this group has been resolved against the server.
Iterator<ContactGroup>	subgroups() Returns an iterator over the sub groups that this ContactGroup contains.

Method Detail

subgroups

Iterator<ContactGroup> subgroups()

Returns an iterator over the sub groups that this ContactGroup contains.

Returns:

a java.util.Iterator over the ContactGroup children of this group (i.e. subgroups).

countSubgroups

int countSubgroups()

Returns the number of subgroups contained by this ContactGroup.

Returns:

an int indicating the number of subgroups that this ContactGroup contains.

getGroup

ContactGroup getGroup(int index)

Returns the subgroup with the specified index.

Parameters:

index - the index of the ContactGroup to retrieve.

Returns:

the ContactGroup with the specified index.

getGroup

ContactGroup getGroup(String groupName)

Returns the subgroup with the specified name.

Parameters:

groupName - the name of the ContactGroup to retrieve.

Returns:

the ContactGroup with the specified index.

contacts

Iterator<Contact> contacts()

Returns an Iterator over all contacts, member of this ContactGroup.

Returns:

a java.util.Iterator over all contacts inside this ContactGroup

countContacts

int countContacts()

Returns the number of Contact members of this ContactGroup

Returns:

an int indicating the number of Contacts, members of this ContactGroup.

getContact

Contact getContact(String id)

Returns the Contact with the specified address or identifier.

Parameters:

id - the addres or identifier of the Contact we are looking for.

Returns:

the Contact with the specified id or address.

canContainSubgroups

boolean canContainSubgroups()

Determines whether the group may contain subgroups or not.

Returns:

true if the groups may be a parent of other ContactGroups and false otherwise.

getGroupName

String getGroupName()

Returns the name of this group.

Returns:

a String containing the name of this group.

getProtocolProvider

ProtocolProviderService getProtocolProvider()

Returns the protocol provider that this group belongs to.

Returns:

a reference to the ProtocolProviderService instance that this ContactGroup belongs to.

getParentContactGroup

ContactGroup getParentContactGroup()

Returns the contact group that currently contains this group or null if this is the root contact group.

Returns:

the contact group that currently contains this group or null if this is the root contact group.

isPersistent

boolean isPersistent()

Determines whether or not this contact group is being stored by the server. Non persistent contact groups exist for the sole purpose of containing non persistent contacts.

Returns:

true if the contact group is persistent and false otherwise.

getUID

String getUID()

Returns a String that uniquely represents the group inside the current protocol. The string MUST be persistent (it must not change across connections or runs of the application). In many cases (Jabber, ICQ) the string may match the name of the group as these protocols only allow a single level of contact groups and there is no danger of having the same name twice in the same contact list. Other protocols (no examples come to mind but that doesn't bother me ;) ) may be supporting multiple levels of groups so it might be possible for group A and group B to both contain groups named C. In such cases the implementation must find a way to return a unique identifier in this method and this UID should never change for a given group.

Returns:

a String representing this group in a unique and persistent way.

isResolved

boolean isResolved()

Determines whether or not this group has been resolved against the server. Unresolved groups are used when initially loading a contact list that has been stored in a local file until the presence operation set has managed to retrieve all the contact list from the server and has properly mapped contact groups to their corresponding server stored groups.

Returns:

true if the group has been resolved (mapped against a server stored group) and false otherwise.

getPersistentData

String getPersistentData()

Returns a String that can be used to create a unresolved instance of this group. Unresolved contacts and groups are created through the createUnresolvedContactGroup() method in the persistent presence operation set. The method may also return null if no such data is required and the contact address is sufficient for restoring the contact group.

Returns:

A String that could be used to create a unresolved instance of this contact group during a next run of the application, before establishing network connectivity or null if no such data is required and a UID would be sufficient.