rocks.xmpp.im.roster

Class RosterManager

java.lang.Object

rocks.xmpp.core.session.Manager

rocks.xmpp.im.roster.RosterManager

public final class RosterManager
extends Manager

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

Roster Versioning

Because rosters can become quite large, but usually change infrequently, rosters can be cached on client side. Hence before requesting the roster, it is checked if there's a cached version of your roster in the cache directory. If so, the server is informed about your version and will not send the full roster, but only "diffs" to your version, thus being more efficient.

Retrieving the Roster on Login

As per RFC 6121 the roster should be retrieved on login. This behavior can also be changed.

Nested Roster Groups

XEP-0083: Nested Roster Groups are supported, but are disabled by default, which means the group delimiter is not retrieved before requesting the roster. You can change this behavior or set a group delimiter without retrieving it from the server in case you want to use a fix roster group delimiter.

You can listen for roster updates (aka roster pushes) and for initial roster retrieval, by adding a Consumer.

This class is unconditionally thread-safe.

See Also:

2.2. Retrieving the Roster on Login, 2.6. Roster Versioning, XEP-0083: Nested Roster Groups

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(Consumer<RosterEvent> rosterListener) Adds a roster listener, which will get notified, whenever the roster changes.
Contact	getContact(rocks.xmpp.addr.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	isAskForGroupDelimiter() Indicates whether the server is asked for the roster delimiter before requesting the roster.
boolean	isRetrieveRosterOnLogin() Controls, whether the roster is automatically retrieved as soon as the user has logged in.
boolean	isRosterVersioningSupported() Indicates whether the server supports roster versioning.
void	removeContact(rocks.xmpp.addr.Jid jid) Removes a contact from the roster.
void	removeContactGroup(ContactGroup contactGroup) Removes a contact group.
void	removeRosterListener(Consumer<RosterEvent> rosterListener) Removes a previously added roster listener.
void	renameContactGroup(ContactGroup contactGroup, String name) Renames a contact group.
Roster	requestRoster() Requests the roster from the server.
void	setAskForGroupDelimiter(boolean askForGroupDelimiter) Sets whether the server is asked for the roster delimiter before requesting the roster.
void	setGroupDelimiter(String groupDelimiter) Sets the group delimiter without storing it on the server.
void	setRetrieveRosterOnLogin(boolean retrieveRosterOnLogin) Controls, whether the roster is automatically retrieved as soon as the user has logged in.
void	storeGroupDelimiter(String groupDelimiter) Stores the roster group delimiter in the private storage and afterwards sets it.
void	updateContact(Contact contact) Updates a contact in the roster.

Methods inherited from class rocks.xmpp.core.session.Manager

isEnabled, setEnabled

Methods inherited from class java.lang.Object

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

Method Detail

getContacts

public final Collection<Contact> getContacts()

Gets the contacts.

Returns:

The contacts.

getContact

public final Contact getContact(rocks.xmpp.addr.Jid jid)

Gets a contact by its JID.

Parameters:

jid - The JID.

Returns:

The contact or null, if it does not exist.

getContactGroups

public final Collection<ContactGroup> getContactGroups()

Gets the contact groups. The returned collection is sorted. It should not be shared

Returns:

The contact groups.

getUnaffiliatedContacts

public final 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 final void addRosterListener(Consumer<RosterEvent> rosterListener)

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

Parameters:

rosterListener - The roster listener.

See Also:

removeRosterListener(Consumer)

removeRosterListener

public final void removeRosterListener(Consumer<RosterEvent> rosterListener)

Removes a previously added roster listener.

Parameters:

rosterListener - The roster listener.

See Also:

addRosterListener(Consumer)

isRetrieveRosterOnLogin

public final 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 final 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 final Roster requestRoster()
                           throws XmppException

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

Roster Versioning is supported, which means that this method checks if there's a cached version of your roster in the cache directory. If so and if Roster Versioning is supported by the server, the cached version is returned and any missing roster items are sent later by the server via roster pushes.

Returns:

The roster.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

addContact

public final 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 final 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 final void removeContact(rocks.xmpp.addr.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 final 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 final 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 final String getGroupDelimiter()

Gets the group delimiter.

Returns:

The group delimiter.

See Also:

setGroupDelimiter(String)

setGroupDelimiter

public final void setGroupDelimiter(String groupDelimiter)

Sets the group delimiter without storing it on the server.

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:

storeGroupDelimiter(String), XEP-0083: Nested Roster Groups

storeGroupDelimiter

public final void storeGroupDelimiter(String groupDelimiter)
                               throws XmppException

Stores the roster group delimiter in the private storage and afterwards sets it.

Parameters:

groupDelimiter - The group delimiter.

Throws:

StanzaException - If the entity returned a stanza error.

NoResponseException - If the entity did not respond.

XmppException

See Also:

setGroupDelimiter(String), XEP-0083: Nested Roster Groups

isAskForGroupDelimiter

public boolean isAskForGroupDelimiter()

Indicates whether the server is asked for the roster delimiter before requesting the roster.

Returns:

True, if the server is asked for the roster delimiter.

setAskForGroupDelimiter

public void setAskForGroupDelimiter(boolean askForGroupDelimiter)

Sets whether the server is asked for the roster delimiter before requesting the roster.

Parameters:

askForGroupDelimiter - True, if the server is asked for the roster delimiter before requesting the roster.

See Also:

requestRoster()

isRosterVersioningSupported

public boolean isRosterVersioningSupported()

Indicates whether the server supports roster versioning.

Returns:

True, if roster versioning is supported.

See Also:

2.6. Roster Versioning