net.java.sip.communicator.impl.protocol.sip
Class ContactGroupSipImpl

java.lang.Object
  net.java.sip.communicator.impl.protocol.sip.ContactGroupSipImpl

All Implemented Interfaces:

ContactGroup

public class ContactGroupSipImpl
extends Object
implements ContactGroup

A simple, straightforward implementation of a SIP ContactGroup. Since the SIP protocol is not a real one, we simply store all group details in class fields. You should know that when implementing a real protocol, the contact group implementation would rather encapsulate group objects from the protocol stack and group property values should be returned by consulting the encapsulated object.

Author:

Emil Ivov, Grigorii Balutsel

Constructor Summary

ContactGroupSipImpl(String groupName, ProtocolProviderServiceSipImpl parentProvider)
Creates a ContactGroupSipImpl with the specified name.

Method Summary

void	addContact(ContactSipImpl contactToAdd) Adds the specified contact to this group.
void	addSubgroup(ContactGroupSipImpl subgroup) Adds the specified contact group to the contained by this group.
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.
(package private) static String	createNameFromUID(String uid) Ugly but tricky conversion method.
boolean	equals(Object obj) Indicates whether some other object is "equal to" this one which in terms of contact groups translates to having the equal names and matching subgroups and child contacts.
ContactSipImpl	findContactByID(String id) Returns the contact with the specified id or null if no such contact exists.
ContactGroupSipImpl	findContactParent(ContactSipImpl sipContact) Returns the group that is parent of the specified sipContact or null if no parent was found.
ContactGroupSipImpl	findGroupParent(ContactGroupSipImpl sipGroup) Returns the group that is parent of the specified sipGroup or null if no parent was found.
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.
(package private) ListType	getList() Gets the list.
ContactGroup	getParentContactGroup() Returns the contact group that currently contains this group or null if this is the root contact group.
String	getPersistentData() Returns null as no persistent data is required and the contact address is sufficient for restoring the contact.
ProtocolProviderService	getProtocolProvider() Returns the protocol provider that this group belongs to.
String	getUID() Returns a String that uniquely represnets 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 contact has been resolved against the server.
void	removeContact(ContactSipImpl contact) Removes the specified contact from this group.
void	removeSubGroup(ContactGroupSipImpl subgroup) Removes the specified contact group from the this group's subgroups.
(package private) void	setAny(List<Element> any) Sets the list custom elements.
(package private) void	setName(String newName) Sets the list name.
(package private) void	setOtherAttributes(Map<QName,String> otherAttributes) Sets the list custom attributes.
(package private) void	setParentGroup(ContactGroupSipImpl parent) Sets the group that is the new parent of this group
void	setPersistent(boolean isPersistent) Specifies whether or not this contact group is being stored by the server.
void	setResolved(boolean resolved) Makes the group resolved or unresolved.
Iterator<ContactGroup>	subgroups() Returns an iterator over the sub groups that this ContactGroup contains.
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, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ContactGroupSipImpl

public ContactGroupSipImpl(String groupName,
                           ProtocolProviderServiceSipImpl parentProvider)

Creates a ContactGroupSipImpl with the specified name.

Parameters:

groupName - the name of the group.

parentProvider - the protocol provider that created this group.

Method Detail

getList

ListType getList()

Gets the list.

Returns:

the list.

setOtherAttributes

void setOtherAttributes(Map<QName,String> otherAttributes)

Sets the list custom attributes.

Parameters:

otherAttributes - the custom attributes.

setAny

void setAny(List<Element> any)

Sets the list custom elements.

Parameters:

any - the custom elemets.

setName

void setName(String newName)

Sets the list name.

Parameters:

newName - the name.

canContainSubgroups

public boolean canContainSubgroups()

Determines whether the group may contain subgroups or not.

Specified by:

canContainSubgroups in interface ContactGroup

Returns:

always true in this implementation.

getProtocolProvider

public ProtocolProviderService getProtocolProvider()

Returns the protocol provider that this group belongs to.

Specified by:

getProtocolProvider in interface ContactGroup

Returns:

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

contacts

public Iterator<Contact> contacts()

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

Specified by:

contacts in interface ContactGroup

Returns:

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

addContact

public void addContact(ContactSipImpl contactToAdd)

Adds the specified contact to this group.

Parameters:

contactToAdd - the ContactSipImpl to add to this group.

countContacts

public int countContacts()

Returns the number of Contact members of this ContactGroup

Specified by:

countContacts in interface ContactGroup

Returns:

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

countSubgroups

public int countSubgroups()

Returns the number of subgroups contained by this ContactGroup.

Specified by:

countSubgroups in interface ContactGroup

Returns:

the number of subGroups currently added to this group.

setParentGroup

void setParentGroup(ContactGroupSipImpl parent)

Sets the group that is the new parent of this group

Parameters:

parent - ContactGroupSipImpl

getParentContactGroup

public ContactGroup getParentContactGroup()

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

Specified by:

getParentContactGroup in interface ContactGroup

Returns:

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

addSubgroup

public void addSubgroup(ContactGroupSipImpl subgroup)

Adds the specified contact group to the contained by this group.

Parameters:

subgroup - the ContactGroupSipImpl to add as a subgroup to this group.

removeSubGroup

public void removeSubGroup(ContactGroupSipImpl subgroup)

Removes the specified contact group from the this group's subgroups.

Parameters:

subgroup - the ContactGroupSipImpl subgroup to remove.

findGroupParent

public ContactGroupSipImpl findGroupParent(ContactGroupSipImpl sipGroup)

Returns the group that is parent of the specified sipGroup or null if no parent was found.

Parameters:

sipGroup - the group whose parent we're looking for.

Returns:

the ContactGroupSipImpl instance that sipGroup belongs to or null if no parent was found.

findContactParent

public ContactGroupSipImpl findContactParent(ContactSipImpl sipContact)

Returns the group that is parent of the specified sipContact or null if no parent was found.

Parameters:

sipContact - the contact whose parent we're looking for.

Returns:

the ContactGroupSipImpl instance that sipContact belongs to or null if no parent was found.

getContact

public Contact getContact(String id)

Returns the Contact with the specified address or identifier.

Specified by:

getContact in interface ContactGroup

Parameters:

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

Returns:

the Contact with the specified id or address.

getGroup

public ContactGroup getGroup(int index)

Returns the subgroup with the specified index.

Specified by:

getGroup in interface ContactGroup

Parameters:

index - the index of the ContactGroup to retrieve.

Returns:

the ContactGroup with the specified index.

getGroup

public ContactGroup getGroup(String groupName)

Returns the subgroup with the specified name.

Specified by:

getGroup in interface ContactGroup

Parameters:

groupName - the name of the ContactGroup to retrieve.

Returns:

the ContactGroup with the specified index.

getGroupName

public String getGroupName()

Returns the name of this group.

Specified by:

getGroupName in interface ContactGroup

Returns:

a String containing the name of this group.

subgroups

public Iterator<ContactGroup> subgroups()

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

Specified by:

subgroups in interface ContactGroup

Returns:

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

removeContact

public void removeContact(ContactSipImpl contact)

Removes the specified contact from this group.

Parameters:

contact - the ContactSipImpl to remove from this group

findContactByID

public ContactSipImpl findContactByID(String id)

Returns the contact with the specified id or null if no such contact exists.

Parameters:

id - the id of the contact we're looking for.

Returns:

ContactSipImpl

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

Overrides:

toString in class Object

Returns:

a String representing this group and its child contacts.

setPersistent

public void setPersistent(boolean isPersistent)

Specifies whether or not this contact group is being stored by the server. Non persistent contact groups are common in the case of simple, non-persistent presence operation sets. They could however also be seen in persistent presence operation sets when for example we have received an event from someone not on our contact list and the contact that we associated with that user is placed in a non persistent group. Non persistent contact groups are volatile even when coming from a persistent presence op. set. They would only exist until the application is closed and will not be there next time it is loaded.

Parameters:

isPersistent - true if the contact group is to be persistent and false otherwise.

isPersistent

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

Specified by:

isPersistent in interface ContactGroup

Returns:

true if the contact group is persistent and false otherwise.

getPersistentData

public String getPersistentData()

Returns null as no persistent data is required and the contact address is sufficient for restoring the contact.

Specified by:

getPersistentData in interface ContactGroup

Returns:

null as no such data is needed.

isResolved

public boolean isResolved()

Determines whether or not this contact has been resolved against the server. Unresolved contacts 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 contacts to their on-line buddies.

Specified by:

isResolved in interface ContactGroup

Returns:

true if the contact has been resolved (mapped against a buddy) and false otherwise.

setResolved

public void setResolved(boolean resolved)

Makes the group resolved or unresolved.

Parameters:

resolved - true to make the group resolved; false to make it unresolved

getUID

public String getUID()

Returns a String that uniquely represnets 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 mutilple levels of grooups 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.

Specified by:

getUID in interface ContactGroup

Returns:

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

createNameFromUID

static String createNameFromUID(String uid)

Ugly but tricky conversion method.

Parameters:

uid - the uid we'd like to get a name from

Returns:

the name of the group with the specified uid.

equals

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this one which in terms of contact groups translates to having the equal names and matching subgroups and child contacts. The resolved status of contactgroups and contacts is deliberately ignored so that groups and/or contacts would be assumed equal even if it differs.

Overrides:

equals in class Object

Parameters:

obj - the reference object with which to compare.

Returns:

true if this contact group has the equal child contacts and subgroups to those of the obj argument.