Roster (Smack 4.1.2 API)

java.lang.Object
- org.jivesoftware.smack.Manager
- - org.jivesoftware.smack.roster.Roster

```
public class Roster
extends Manager
```
Represents a user's roster, which is the collection of users a person receives presence updates for. Roster items are categorized into groups for easier management.

Others users may attempt to subscribe to this user using a subscription request. Three modes are supported for handling these requests:
- accept_all -- accept all subscription requests.
- reject_all -- reject all subscription requests.
- manual -- manually process all subscription requests.
See Also:

getInstanceFor(XMPPConnection)

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Roster.SubscriptionMode
An enumeration for the subscription mode options.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Roster.SubscriptionMode` An enumeration for the subscription mode options.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addRosterListener(RosterListener rosterListener)` Adds a listener to this roster.
`boolean`	`addRosterLoadedListener(RosterLoadedListener rosterLoadedListener)` Add a roster loaded listener.
`boolean`	`contains(String user)` Returns true if the specified XMPP address is an entry in the roster.
`void`	`createEntry(String user, String name, String[] groups)` Creates a new roster entry and presence subscription.
`RosterGroup`	`createGroup(String name)` Creates a new group.
`List<Presence>`	`getAllPresences(String bareJid)` Returns a List of Presence objects for all of a user's current presences if no presence information is available, such as when you are not subscribed to the user's presence updates.
`List<Presence>`	`getAvailablePresences(String bareJid)` Returns a List of all available Presence Objects for the given bare JID.
`static Roster.SubscriptionMode`	`getDefaultSubscriptionMode()` Returns the default subscription processing mode to use when a new Roster is created.
`Set<RosterEntry>`	`getEntries()` Returns a set of all entries in the roster, including entries that don't belong to any groups.
`void`	`getEntriesAndAddListener(RosterListener rosterListener, RosterEntries rosterEntries)` Add a roster listener and invoke the roster entries with all entries of the roster.
`RosterEntry`	`getEntry(String user)` Returns the roster entry associated with the given XMPP address or `null` if the user is not an entry in the roster.
`int`	`getEntryCount()` Returns a count of the entries in the roster.
`RosterGroup`	`getGroup(String name)` Returns the roster group with the specified name, or `null` if the group doesn't exist.
`int`	`getGroupCount()` Returns the number of the groups in the roster.
`Collection<RosterGroup>`	`getGroups()` Returns an unmodifiable collections of all the roster groups.
`static Roster`	`getInstanceFor(XMPPConnection connection)` Returns the roster for the user.
`Presence`	`getPresence(String user)` Returns the presence info for a particular user.
`Presence`	`getPresenceResource(String userWithResource)` Returns the presence info for a particular user's resource, or unavailable presence if the user is offline or if no presence information is available, such as when you are not subscribed to the user's presence updates.
`List<Presence>`	`getPresences(String user)` Returns a List of Presence objects for all of a user's current presences or an unavailable presence if the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.
`Roster.SubscriptionMode`	`getSubscriptionMode()` Returns the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made.
`Set<RosterEntry>`	`getUnfiledEntries()` Returns an unmodifiable set for the unfiled roster entries.
`int`	`getUnfiledEntryCount()` Returns a count of the unfiled entries in the roster.
`boolean`	`isLoaded()` Check if the roster is loaded.
`boolean`	`isRosterLoadedAtLogin()` Returns true if the roster will be loaded from the server when logging in.
`boolean`	`isRosterVersioningSupported()` Check if the server supports roster versioning.
`boolean`	`isSubscribedToMyPresence(String jid)` Check if the given JID is subscribed to the user's presence.
`void`	`reload()` Reloads the entire roster from the server.
`void`	`reloadAndWait()` Reload the roster and block until it is reloaded.
`void`	`removeEntry(RosterEntry entry)` Removes a roster entry from the roster.
`boolean`	`removeRosterListener(RosterListener rosterListener)` Removes a listener from this roster.
`boolean`	`removeRosterLoadedListener(RosterLoadedListener rosterLoadedListener)` Remove a roster loaded listener.
`static void`	`setDefaultSubscriptionMode(Roster.SubscriptionMode subscriptionMode)` Sets the default subscription processing mode to use when a new Roster is created.
`void`	`setRosterLoadedAtLogin(boolean rosterLoadedAtLogin)` Sets if the roster will be loaded from the server when logging in.
`boolean`	`setRosterStore(RosterStore rosterStore)` Set the roster store, may cause a roster reload
`void`	`setSubscriptionMode(Roster.SubscriptionMode subscriptionMode)` Sets the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made.
`protected boolean`	`waitUntilLoaded()`

Methods inherited from class org.jivesoftware.smack.Manager
connection

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getInstanceFor
```
public static Roster getInstanceFor(XMPPConnection connection)
```
    Returns the roster for the user.
    This method will never return null, instead if the user has not yet logged into the server or is logged in anonymously all modifying methods of the returned roster object like createEntry(String, String, String[]), removeEntry(RosterEntry) , etc. except adding or removing RosterListeners will throw an IllegalStateException.
    
    Returns:
    
    the user's roster.
    
    Throws:
    
    IllegalStateException - if the connection is anonymous
  - getDefaultSubscriptionMode
```
public static Roster.SubscriptionMode getDefaultSubscriptionMode()
```
    Returns the default subscription processing mode to use when a new Roster is created. The subscription processing mode dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is Roster.SubscriptionMode.accept_all.
    
    Returns:
    
    the default subscription mode to use for new Rosters
  - setDefaultSubscriptionMode
```
public static void setDefaultSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
```
    Sets the default subscription processing mode to use when a new Roster is created. The subscription processing mode dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is Roster.SubscriptionMode.accept_all.
    
    Parameters:
    
    subscriptionMode - the default subscription mode to use for new Rosters.
  - getSubscriptionMode
```
public Roster.SubscriptionMode getSubscriptionMode()
```
    Returns the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is Roster.SubscriptionMode.accept_all.
    
    If using the manual mode, a PacketListener should be registered that listens for Presence packets that have a type of Presence.Type.subscribe.
    
    Returns:
    
    the subscription mode.
  - setSubscriptionMode
```
public void setSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
```
    Sets the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is Roster.SubscriptionMode.accept_all.
    
    If using the manual mode, a PacketListener should be registered that listens for Presence packets that have a type of Presence.Type.subscribe.
    
    Parameters:
    
    subscriptionMode - the subscription mode.
  - reload
```
public void reload()
            throws SmackException.NotLoggedInException,
                   SmackException.NotConnectedException
```
    Reloads the entire roster from the server. This is an asynchronous operation, which means the method will return immediately, and the roster will be reloaded at a later point when the server responds to the reload request.
    
    Throws:
    
    SmackException.NotLoggedInException - If not logged in.
    
    SmackException.NotConnectedException
  - reloadAndWait
```
public void reloadAndWait()
                   throws SmackException.NotLoggedInException,
                          SmackException.NotConnectedException
```
    Reload the roster and block until it is reloaded.
    
    Throws:
    
    SmackException.NotLoggedInException
    
    SmackException.NotConnectedException
    
    Since:
    
    4.1
  - setRosterStore
```
public boolean setRosterStore(RosterStore rosterStore)
```
    Set the roster store, may cause a roster reload
    
    Parameters:
    
    rosterStore -
    
    Returns:
    
    true if the roster reload was initiated, false otherwise.
    
    Since:
    
    4.1
  - waitUntilLoaded
```
protected boolean waitUntilLoaded()
```
  - isLoaded
```
public boolean isLoaded()
```
    Check if the roster is loaded.
    
    Returns:
    
    true if the roster is loaded.
    
    Since:
    
    4.1
  - addRosterListener
```
public boolean addRosterListener(RosterListener rosterListener)
```
    Adds a listener to this roster. The listener will be fired anytime one or more changes to the roster are pushed from the server.
    
    Parameters:
    
    rosterListener - a roster listener.
    
    Returns:
    
    true if the listener was not already added.
    
    See Also:
    
    getEntriesAndAddListener(RosterListener, RosterEntries)
  - removeRosterListener
```
public boolean removeRosterListener(RosterListener rosterListener)
```
    Removes a listener from this roster. The listener will be fired anytime one or more changes to the roster are pushed from the server.
    
    Parameters:
    
    rosterListener - a roster listener.
    
    Returns:
    
    true if the listener was active and got removed.
  - addRosterLoadedListener
```
public boolean addRosterLoadedListener(RosterLoadedListener rosterLoadedListener)
```
    Add a roster loaded listener.
    
    Parameters:
    
    rosterLoadedListener - the listener to add.
    
    Returns:
    
    true if the listener was not already added.
    
    Since:
    
    4.1
    
    See Also:
    
    RosterLoadedListener
  - removeRosterLoadedListener
```
public boolean removeRosterLoadedListener(RosterLoadedListener rosterLoadedListener)
```
    Remove a roster loaded listener.
    
    Parameters:
    
    rosterLoadedListener - the listener to remove.
    
    Returns:
    
    true if the listener was active and got removed.
    
    Since:
    
    4.1
    
    See Also:
    
    RosterLoadedListener
  - createGroup
```
public RosterGroup createGroup(String name)
```
    Creates a new group.
    
    Note: you must add at least one entry to the group for the group to be kept after a logout/login. This is due to the way that XMPP stores group information.
    
    Parameters:
    
    name - the name of the group.
    
    Returns:
    
    a new group, or null if the group already exists
    
    Throws:
    
    IllegalStateException - if logged in anonymously
  - createEntry
```
public void createEntry(String user,
                        String name,
                        String[] groups)
                 throws SmackException.NotLoggedInException,
                        SmackException.NoResponseException,
                        XMPPException.XMPPErrorException,
                        SmackException.NotConnectedException
```
    Creates a new roster entry and presence subscription. The server will asynchronously update the roster with the subscription status.
    
    Parameters:
    
    user - the user. (e.g. johndoe@jabber.org)
    
    name - the nickname of the user.
    
    groups - the list of group names the entry will belong to, or null if the the roster entry won't belong to a group.
    
    Throws:
    
    SmackException.NoResponseException - if there was no response from the server.
    
    XMPPException.XMPPErrorException - if an XMPP exception occurs.
    
    SmackException.NotLoggedInException - If not logged in.
    
    SmackException.NotConnectedException
  - removeEntry
```
public void removeEntry(RosterEntry entry)
                 throws SmackException.NotLoggedInException,
                        SmackException.NoResponseException,
                        XMPPException.XMPPErrorException,
                        SmackException.NotConnectedException
```
    Removes a roster entry from the roster. The roster entry will also be removed from the unfiled entries or from any roster group where it could belong and will no longer be part of the roster. Note that this is a synchronous call -- Smack must wait for the server to send an updated subscription status.
    
    Parameters:
    
    entry - a roster entry.
    
    Throws:
    
    XMPPException.XMPPErrorException - if an XMPP error occurs.
    
    SmackException.NotLoggedInException - if not logged in.
    
    SmackException.NoResponseException - SmackException if there was no response from the server.
    
    SmackException.NotConnectedException
    
    IllegalStateException - if connection is not logged in or logged in anonymously
  - getEntryCount
```
public int getEntryCount()
```
    Returns a count of the entries in the roster.
    
    Returns:
    
    the number of entries in the roster.
  - getEntriesAndAddListener
```
public void getEntriesAndAddListener(RosterListener rosterListener,
                                     RosterEntries rosterEntries)
```
    Add a roster listener and invoke the roster entries with all entries of the roster.
    The method guarantees that the listener is only invoked after RosterEntries.rosterEntires(Collection) has been invoked, and that all roster events that happen while rosterEntires(Collection) is called are queued until the method returns.
    
    This guarantee makes this the ideal method to e.g. populate a UI element with the roster while installing a RosterListener to listen for subsequent roster events.
    
    Parameters:
    
    rosterListener - the listener to install
    
    rosterEntries - the roster entries callback interface
    
    Since:
    
    4.1
  - getEntries
```
public Set<RosterEntry> getEntries()
```
    Returns a set of all entries in the roster, including entries that don't belong to any groups.
    
    Returns:
    
    all entries in the roster.
  - getUnfiledEntryCount
```
public int getUnfiledEntryCount()
```
    Returns a count of the unfiled entries in the roster. An unfiled entry is an entry that doesn't belong to any groups.
    
    Returns:
    
    the number of unfiled entries in the roster.
  - getUnfiledEntries
```
public Set<RosterEntry> getUnfiledEntries()
```
    Returns an unmodifiable set for the unfiled roster entries. An unfiled entry is an entry that doesn't belong to any groups.
    
    Returns:
    
    the unfiled roster entries.
  - getEntry
```
public RosterEntry getEntry(String user)
```
    Returns the roster entry associated with the given XMPP address or null if the user is not an entry in the roster.
    
    Parameters:
    
    user - the XMPP address of the user (eg "jsmith@example.com"). The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource").
    
    Returns:
    
    the roster entry or null if it does not exist.
  - contains
```
public boolean contains(String user)
```
    Returns true if the specified XMPP address is an entry in the roster.
    
    Parameters:
    
    user - the XMPP address of the user (eg "jsmith@example.com"). The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource").
    
    Returns:
    
    true if the XMPP address is an entry in the roster.
  - getGroup
```
public RosterGroup getGroup(String name)
```
    Returns the roster group with the specified name, or null if the group doesn't exist.
    
    Parameters:
    
    name - the name of the group.
    
    Returns:
    
    the roster group with the specified name.
  - getGroupCount
```
public int getGroupCount()
```
    Returns the number of the groups in the roster.
    
    Returns:
    
    the number of groups in the roster.
  - getGroups
```
public Collection<RosterGroup> getGroups()
```
    Returns an unmodifiable collections of all the roster groups.
    
    Returns:
    
    an iterator for all roster groups.
  - getPresence
```
public Presence getPresence(String user)
```
    Returns the presence info for a particular user. If the user is offline, or if no presence data is available (such as when you are not subscribed to the user's presence updates), unavailable presence will be returned.
    If the user has several presences (one for each resource), then the presence with highest priority will be returned. If multiple presences have the same priority, the one with the "most available" presence mode will be returned. In order, that's free to chat, available, away, extended away, and do not disturb.
    
    Note that presence information is received asynchronously. So, just after logging in to the server, presence values for users in the roster may be unavailable even if they are actually online. In other words, the value returned by this method should only be treated as a snapshot in time, and may not accurately reflect other user's presence instant by instant. If you need to track presence over time, such as when showing a visual representation of the roster, consider using a RosterListener.
    
    Parameters:
    
    user - an XMPP ID. The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource"). Any resource information that's part of the ID will be discarded.
    
    Returns:
    
    the user's current presence, or unavailable presence if the user is offline or if no presence information is available..
  - getPresenceResource
```
public Presence getPresenceResource(String userWithResource)
```
    Returns the presence info for a particular user's resource, or unavailable presence if the user is offline or if no presence information is available, such as when you are not subscribed to the user's presence updates.
    
    Parameters:
    
    userWithResource - a fully qualified XMPP ID including a resource (user@domain/resource).
    
    Returns:
    
    the user's current presence, or unavailable presence if the user is offline or if no presence information is available.
  - getAllPresences
```
public List<Presence> getAllPresences(String bareJid)
```
    Returns a List of Presence objects for all of a user's current presences if no presence information is available, such as when you are not subscribed to the user's presence updates.
    
    Parameters:
    
    bareJid - an XMPP ID, e.g. jdoe@example.com.
    
    Returns:
    
    a List of Presence objects for all the user's current presences, or an unavailable presence if no presence information is available.
  - getAvailablePresences
```
public List<Presence> getAvailablePresences(String bareJid)
```
    Returns a List of all available Presence Objects for the given bare JID. If there are no available presences, then the empty list will be returned.
    
    Parameters:
    
    bareJid - the bare JID from which the presences should be retrieved.
    
    Returns:
    
    available presences for the bare JID.
  - getPresences
```
public List<Presence> getPresences(String user)
```
    Returns a List of Presence objects for all of a user's current presences or an unavailable presence if the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.
    
    Parameters:
    
    user - an XMPP ID, e.g. jdoe@example.com.
    
    Returns:
    
    a List of Presence objects for all the user's current presences, or an unavailable presence if the user is offline or if no presence information is available.
  - isSubscribedToMyPresence
```
public boolean isSubscribedToMyPresence(String jid)
```
    Check if the given JID is subscribed to the user's presence.
    If the JID is subscribed to the user's presence then it is allowed to see the presence and will get notified about presence changes. Also returns true, if the JID is the service name of the XMPP connection (the "XMPP domain"), i.e. the XMPP service is treated like having an implicit subscription to the users presence.
    Note that if the roster is not loaded, then this method will always return false.
    
    Parameters:
    
    jid -
    
    Returns:
    
    true if the given JID is allowed to see the users presence.
    
    Since:
    
    4.1
  - setRosterLoadedAtLogin
```
public void setRosterLoadedAtLogin(boolean rosterLoadedAtLogin)
```
    Sets if the roster will be loaded from the server when logging in. This is the common behaviour for clients but sometimes clients may want to differ this or just never do it if not interested in rosters.
    
    Parameters:
    
    rosterLoadedAtLogin - if the roster will be loaded from the server when logging in.
  - isRosterLoadedAtLogin
```
public boolean isRosterLoadedAtLogin()
```
    Returns true if the roster will be loaded from the server when logging in. This is the common behavior for clients but sometimes clients may want to differ this or just never do it if not interested in rosters.
    
    Returns:
    
    true if the roster will be loaded from the server when logging in.
    
    See Also:
    
    RFC 6121 2.2 - Retrieving the Roster on Login
  - isRosterVersioningSupported
```
public boolean isRosterVersioningSupported()
```
    Check if the server supports roster versioning.
    
    Returns:
    
    true if the server supports roster versioning, false otherwise.

Class Roster

Nested Class Summary

Method Summary

Methods inherited from class org.jivesoftware.smack.Manager

Methods inherited from class java.lang.Object

Method Detail

getInstanceFor

getDefaultSubscriptionMode

setDefaultSubscriptionMode

getSubscriptionMode

setSubscriptionMode

reload

reloadAndWait

setRosterStore

waitUntilLoaded

isLoaded

addRosterListener

removeRosterListener

addRosterLoadedListener

removeRosterLoadedListener

createGroup

createEntry

removeEntry

getEntryCount

getEntriesAndAddListener

getEntries

getUnfiledEntryCount

getUnfiledEntries

getEntry

contains

getGroup

getGroupCount

getGroups

getPresence

getPresenceResource

getAllPresences

getAvailablePresences

getPresences

isSubscribedToMyPresence

setRosterLoadedAtLogin

isRosterLoadedAtLogin

isRosterVersioningSupported