java.lang.Object
- rocks.xmpp.core.stanza.AbstractIQHandler
- - rocks.xmpp.im.roster.RosterManager

All Implemented Interfaces:

ExtensionProtocol, IQHandler
```
public final class RosterManager
extends AbstractIQHandler
implements ExtensionProtocol
```
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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`AsyncResult<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(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.
`String`	`getNamespace()`	The protocol's main namespace.
`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`	`isEnabled()`	Indicates whether this protocol is enabled.
`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.
`AsyncResult<Void>`	`removeContact(Jid jid)`	Removes a contact from the roster.
`AsyncResult<Void>`	`removeContactGroup(ContactGroup contactGroup)`	Removes a contact group.
`void`	`removeRosterListener(Consumer<RosterEvent> rosterListener)`	Removes a previously added roster listener.
`AsyncResult<Void>`	`renameContactGroup(ContactGroup contactGroup, String name)`	Renames a contact group.
`AsyncResult<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.
`AsyncResult<Void>`	`storeGroupDelimiter(String groupDelimiter)`	Stores the roster group delimiter in the private storage and afterwards sets it.
`AsyncResult<Void>`	`updateContact(Contact contact)`	Updates a contact in the roster.

Methods inherited from class rocks.xmpp.core.stanza.AbstractIQHandler
getPayloadClass, handleRequest

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(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 AsyncResult<Roster> requestRoster()
```
    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 async roster result.
  - addContact
```
public final AsyncResult<Void> addContact(Contact contact,
                                          boolean requestSubscription,
                                          String status)
```
    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.
    
    Returns:
    
    The async result.
  - updateContact
```
public final AsyncResult<Void> updateContact(Contact contact)
```
    Updates a contact in the roster.
    
    Parameters:
    
    contact - The contact to update.
    
    Returns:
    
    The async result.
  - removeContact
```
public final AsyncResult<Void> removeContact(Jid jid)
```
    Removes a contact from the roster.
    
    Parameters:
    
    jid - The contact's JID.
    
    Returns:
    
    The async result.
  - renameContactGroup
```
public final AsyncResult<Void> renameContactGroup(ContactGroup contactGroup,
                                                  String name)
```
    Renames a contact group.
    
    Parameters:
    
    contactGroup - The contact group.
    
    name - The new name.
    
    Returns:
    
    The async result.
  - removeContactGroup
```
public final AsyncResult<Void> removeContactGroup(ContactGroup contactGroup)
```
    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.
    
    Returns:
    
    The async result.
  - 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 AsyncResult<Void> storeGroupDelimiter(String groupDelimiter)
```
    Stores the roster group delimiter in the private storage and afterwards sets it.
    
    Parameters:
    
    groupDelimiter - The group delimiter.
    
    Returns:
    
    The async result.
    
    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
  - getNamespace
```
public String getNamespace()
```
    Description copied from interface: ExtensionProtocol
    
    The protocol's main namespace. This is used to uniquely identify the extension protocol.
    
    Specified by:
    
    getNamespace in interface ExtensionProtocol
    
    Returns:
    
    The main namespace.
  - isEnabled
```
public boolean isEnabled()
```
    Description copied from interface: ExtensionProtocol
    
    Indicates whether this protocol is enabled.
    
    Specified by:
    
    isEnabled in interface ExtensionProtocol
    
    Returns:
    
    true, if enabled; false if disabled.

Class RosterManager

Roster Versioning

Retrieving the Roster on Login

Nested Roster Groups

Method Summary

Methods inherited from class rocks.xmpp.core.stanza.AbstractIQHandler

Methods inherited from class java.lang.Object

Method Detail

getContacts

getContact

getContactGroups

getUnaffiliatedContacts

addRosterListener

removeRosterListener

isRetrieveRosterOnLogin

setRetrieveRosterOnLogin

requestRoster

addContact

updateContact

removeContact

renameContactGroup

removeContactGroup

getGroupDelimiter

setGroupDelimiter

storeGroupDelimiter

isAskForGroupDelimiter

setAskForGroupDelimiter

isRosterVersioningSupported

getNamespace

isEnabled