public final class RosterManager extends Manager
This class manages the roster (aka contact or buddy list).
You can listen for roster updates (aka roster pushes) and for initial roster retrieval, by adding a Consumer
.
Modifier and Type | Method and Description |
---|---|
AsyncResult<java.lang.Void> |
addContact(Contact contact,
boolean requestSubscription,
java.lang.String status)
Adds a contact to the roster and optionally also sends a subscription request to it.
|
void |
addRosterListener(java.util.function.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.
|
java.util.Collection<ContactGroup> |
getContactGroups()
Gets the contact groups.
|
java.util.Collection<Contact> |
getContacts()
Gets the contacts.
|
java.lang.String |
getGroupDelimiter()
Gets the group delimiter.
|
java.util.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.
|
AsyncResult<java.lang.Void> |
removeContact(Jid jid)
Removes a contact from the roster.
|
AsyncResult<java.lang.Void> |
removeContactGroup(ContactGroup contactGroup)
Removes a contact group.
|
void |
removeRosterListener(java.util.function.Consumer<RosterEvent> rosterListener)
Removes a previously added roster listener.
|
AsyncResult<java.lang.Void> |
renameContactGroup(ContactGroup contactGroup,
java.lang.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(java.lang.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<java.lang.Void> |
storeGroupDelimiter(java.lang.String groupDelimiter)
Stores the roster group delimiter in the private storage and afterwards sets it.
|
AsyncResult<java.lang.Void> |
updateContact(Contact contact)
Updates a contact in the roster.
|
isEnabled, setEnabled
public final java.util.Collection<Contact> getContacts()
Gets the contacts.
public final Contact getContact(Jid jid)
Gets a contact by its JID.
jid
- The JID.public final java.util.Collection<ContactGroup> getContactGroups()
Gets the contact groups. The returned collection is sorted. It should not be shared.
public final java.util.Collection<Contact> getUnaffiliatedContacts()
Gets the contacts, which are not affiliated to any group.
public final void addRosterListener(java.util.function.Consumer<RosterEvent> rosterListener)
Adds a roster listener, which will get notified, whenever the roster changes.
rosterListener
- The roster listener.removeRosterListener(Consumer)
public final void removeRosterListener(java.util.function.Consumer<RosterEvent> rosterListener)
Removes a previously added roster listener.
rosterListener
- The roster listener.addRosterListener(Consumer)
public final boolean isRetrieveRosterOnLogin()
Controls, whether the roster is automatically retrieved as soon as the user has logged in.
setRetrieveRosterOnLogin(boolean)
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).
retrieveRosterOnLogin
- True, if the roster is automatically retrieved after login.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.
public final AsyncResult<java.lang.Void> addContact(Contact contact, boolean requestSubscription, java.lang.String status)
Adds a contact to the roster and optionally also sends a subscription request to it.
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.public final AsyncResult<java.lang.Void> updateContact(Contact contact)
Updates a contact in the roster.
contact
- The contact to update.public final AsyncResult<java.lang.Void> removeContact(Jid jid)
Removes a contact from the roster.
jid
- The contact’s JID.public final AsyncResult<java.lang.Void> renameContactGroup(ContactGroup contactGroup, java.lang.String name)
Renames a contact group.
contactGroup
- The contact group.name
- The new name.public final AsyncResult<java.lang.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.
contactGroup
- The contact group.public final java.lang.String getGroupDelimiter()
Gets the group delimiter.
setGroupDelimiter(String)
public final void setGroupDelimiter(java.lang.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.
groupDelimiter
- The group delimiter.storeGroupDelimiter(String)
,
XEP-0083: Nested Roster Groupspublic final AsyncResult<java.lang.Void> storeGroupDelimiter(java.lang.String groupDelimiter)
Stores the roster group delimiter in the private storage and afterwards sets it.
groupDelimiter
- The group delimiter.setGroupDelimiter(String)
,
XEP-0083: Nested Roster Groupspublic boolean isAskForGroupDelimiter()
Indicates whether the server is asked for the roster delimiter before requesting the roster.
public void setAskForGroupDelimiter(boolean askForGroupDelimiter)
Sets whether the server is asked for the roster delimiter before requesting the roster.
askForGroupDelimiter
- True, if the server is asked for the roster delimiter before requesting the roster.requestRoster()
public boolean isRosterVersioningSupported()
Indicates whether the server supports roster versioning.
Copyright © 2014–2019 XMPP.rocks. All rights reserved.