rocks.xmpp.core.roster

Class RosterManager

java.lang.Object

rocks.xmpp.core.roster.RosterManager

public final class RosterManager
extends Object

This class manages the roster (aka contact or buddy list).

Contacts are often organized in groups, which may contain nested groups by themselves. This manager takes care for sorting the the contacts in the right group and also creates the group hierarchy for nested groups.

Nested groups are determined by a delimiter, which must be set prior to requesting the roster.

By adding a RosterListener, you can listen for roster updates (aka roster pushes) in order to update the view.

Author:

Christian Schudt

Constructor Summary

Constructors

Constructor and Description
RosterManager(XmppSession xmppSession)

Method Summary

Modifier and Type	Method and Description
void	addContact(Contact contact, boolean requestSubscription, String status) Adds a contact to the roster and optionally also sends a subscription request to it.
void	addRosterListener(RosterListener rosterListener) Adds a roster listener, which will get notified, whenever the roster changes.
Contact	getContact(Jid jid) Gets a contact by its JID.
Collection<ContactGroup>	getContactGroups() Gets the contact groups.
Collection<Contact>	getContacts() Gets the contacts.
String	getGroupDelimiter() Gets the group delimiter.
Collection<Contact>	getUnaffiliatedContacts() Gets the contacts, which are not affiliated to any group.
boolean	isRetrieveRosterOnLogin() Controls, whether the roster is automatically retrieved as soon as the user has logged in.
void	removeContact(Jid jid) Removes a contact from the roster.
void	removeContactGroup(ContactGroup contactGroup) Removes a contact group.
void	removeRosterListener(RosterListener rosterListener) Removes a previously added roster listener.
void	renameContactGroup(ContactGroup contactGroup, String name) Renames a contact group.
void	requestRoster() Requests the roster from the server.
void	setGroupDelimiter(String groupDelimiter) Sets the group delimiter.
void	setRetrieveRosterOnLogin(boolean retrieveRosterOnLogin) Controls, whether the roster is automatically retrieved as soon as the user has logged in.
void	updateContact(Contact contact) Updates a contact in the roster.

Methods inherited from class java.lang.Object

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

Constructor Detail

RosterManager

public RosterManager(XmppSession xmppSession)

Method Detail

getContacts

public Collection<Contact> getContacts()

Gets the contacts.

Returns:

The contacts.

getContact

public Contact getContact(Jid jid)

Gets a contact by its JID.

Parameters:

jid - The JID.

Returns:

The contact or null, if it does not exist.

getContactGroups

public Collection<ContactGroup> getContactGroups()

Gets the contact groups.

Returns:

The contact groups.

getUnaffiliatedContacts

public Collection<Contact> getUnaffiliatedContacts()

Gets the contacts, which are not affiliated to any group.

Returns:

The contacts, which are not affiliated to any group.

addRosterListener

public void addRosterListener(RosterListener rosterListener)

Adds a roster listener, which will get notified, whenever the roster changes.

Parameters:

rosterListener - The roster listener.

See Also:

removeRosterListener(RosterListener)

removeRosterListener

public void removeRosterListener(RosterListener rosterListener)

Removes a previously added roster listener.

Parameters:

rosterListener - The roster listener.

See Also:

addRosterListener(RosterListener)

isRetrieveRosterOnLogin

public boolean isRetrieveRosterOnLogin()

Controls, whether the roster is automatically retrieved as soon as the user has logged in.

Returns:

True, if the roster is automatically retrieved after login.

See Also:

setRetrieveRosterOnLogin(boolean)

setRetrieveRosterOnLogin

public void setRetrieveRosterOnLogin(boolean retrieveRosterOnLogin)

Controls, whether the roster is automatically retrieved as soon as the user has logged in.

2.2. Retrieving the Roster on Login

Upon authenticating with a server and binding a resource (thus becoming a connected resource as defined in [XMPP-CORE]), a client SHOULD request the roster before sending initial presence (however, because receiving the roster is not necessarily desirable for all resources, e.g., a connection with limited bandwidth, the client's request for the roster is not mandatory).

Parameters:

retrieveRosterOnLogin - True, if the roster is automatically retrieved after login.

requestRoster

public void requestRoster()

Requests the roster from the server. When the server returns the result, the RosterListener are notified. That means, you should first register a RosterListener prior to calling this method.

addContact

public void addContact(Contact contact,
                       boolean requestSubscription,
                       String status)
                throws XmppException

Adds a contact to the roster and optionally also sends a subscription request to it.

Parameters:

contact - The contact.

requestSubscription - If true, the contact is also sent a subscription request.

status - The optional status text, which is sent together with a subscription request. May be null.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

updateContact

public void updateContact(Contact contact)
                   throws XmppException

Updates a contact in the roster.

Parameters:

contact - The contact to update.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

removeContact

public void removeContact(Jid jid)
                   throws XmppException

Removes a contact from the roster.

Parameters:

jid - The contact's JID.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

renameContactGroup

public void renameContactGroup(ContactGroup contactGroup,
                               String name)
                        throws XmppException

Renames a contact group.

Parameters:

contactGroup - The contact group.

name - The new name.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

removeContactGroup

public void removeContactGroup(ContactGroup contactGroup)
                        throws XmppException

Removes a contact group. If the group has sub groups, all sub groups are removed as well. All contacts in this group and all sub groups are moved to the parent group (if present) or to no group at all.

Parameters:

contactGroup - The contact group.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

getGroupDelimiter

public String getGroupDelimiter()

Gets the group delimiter.

Returns:

The group delimiter.

See Also:

setGroupDelimiter(String)

setGroupDelimiter

public void setGroupDelimiter(String groupDelimiter)

Sets the group delimiter.

If this is set to a non-null value, contact groups are split by the specified delimiter in order to build a nested hierarchy of groups.

Parameters:

groupDelimiter - The group delimiter.

See Also:

XEP-0083: Nested Roster Groups