Package org.jivesoftware.smack.roster

Class Roster

java.lang.Object
org.jivesoftware.smack.Manager
org.jivesoftware.smack.roster.Roster
public final class Roster extends org.jivesoftware.smack.Manager

The roster lets you keep track of the availability ("presence") of other users. A roster also allows you to organize users into groups such as "Friends" and "Co-workers". Other IM systems refer to the roster as the buddy list, contact list, etc.

You can obtain a Roster instance for your connection via getInstanceFor(XMPPConnection). A detailed description of the protocol behind the Roster and Presence semantics can be found in RFC 6120.

Roster Entries

Every user in a roster is represented by a RosterEntry, which consists of:
  • An XMPP address, aka. JID (e.g. jsmith@example.com).
  • A name you've assigned to the user (e.g. "Joe").
  • The list of groups in the roster that the entry belongs to. If the roster entry belongs to no groups, it's called an "unfiled entry".
The following code snippet prints all entries in the roster: 

 Roster roster = Roster.getInstanceFor(connection);
 Collection<RosterEntry> entries = roster.getEntries();
 for (RosterEntry entry : entries) {
     System.out.println(entry);
 }
Methods also exist to get individual entries, the list of unfiled entries, or to get one or all roster groups.

Presence

Every entry in the roster has presence associated with it. The getPresence(BareJid) method will return a Presence object with the user's presence or `null` if the user is not online or you are not subscribed to the user's presence. _Note:_ Presence subscription is not tied to the user being on the roster, and vice versa: You could be subscribed to a remote users presence without the user in your roster, and a remote user can be in your roster without any presence subscription relation.

A user either has a presence of online or offline. When a user is online, their presence may contain extended information such as what they are currently doing, whether they wish to be disturbed, etc. See the Presence class for further details.

Listening for Roster and Presence Changes

The typical use of the roster class is to display a tree view of groups and entries along with the current presence value of each entry. As an example, see the image showing a Roster in the Exodus XMPP client to the right.

The presence information will likely change often, and it's also possible for the roster entries to change or be deleted. To listen for changing roster and presence data, a RosterListener should be used. To be informed about all changes to the roster the RosterListener should be registered before logging into the XMPP server. The following code snippet registers a RosterListener with the Roster that prints any presence changes in the roster to standard out. A normal client would use similar code to update the roster UI with the changing information. 


 Roster roster = Roster.getInstanceFor(con);
 roster.addRosterListener(new RosterListener() {
     // Ignored events public void entriesAdded(Collection<String> addresses) {}
     public void entriesDeleted(Collection<String> addresses) {
     }

     public void entriesUpdated(Collection<String> addresses) {
     }

     public void presenceChanged(Presence presence) {
         System.out.println("Presence changed: " + presence.getFrom() + " " + presence);
      }
 });
Note that in order to receive presence changed events you need to be subscribed to the users presence. See the following section.

Adding Entries to the Roster

Rosters and presence use a permissions-based model where users must give permission before someone else can see their presence. This protects a user's privacy by making sure that only approved users are able to view their presence information. Therefore, when you add a new roster entry, you will not see the presence information until the other user accepts your request.

If another user requests a presence subscription, you must accept or reject that request. Smack handles presence subscription requests in one of three ways:

  • Automatically accept all presence subscription requests (accept_all)
  • Automatically reject all presence subscription requests (reject_all)
  • Process presence subscription requests manually. (manual)

The mode can be set using setSubscriptionMode(SubscriptionMode). Simple clients normally use one of the automated subscription modes, while full-featured clients should manually process subscription requests and let the end-user accept or reject each request.

See Also:

  • Field Details

    • INITIAL_DEFAULT_NON_ROSTER_PRESENCE_MAP_SIZE

      public static final int INITIAL_DEFAULT_NON_ROSTER_PRESENCE_MAP_SIZE
      The initial maximum size of the map holding presence information of entities without a Roster entry. Currently 1024.
      See Also:

  • Method Details

    • getInstanceFor

      public static Roster getInstanceFor(org.jivesoftware.smack.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 all modifying methods of the returned roster object like createItemAndRequestSubscription(BareJid, String, String[]), removeEntry(RosterEntry) , etc. except adding or removing RosterListeners will throw an IllegalStateException.

      Parameters:
      connection - the connection the roster should be retrieved for.
      Returns:
      the user's roster.

    • 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.reject_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.reject_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.reject_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.reject_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 org.jivesoftware.smack.SmackException.NotLoggedInException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException
      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:
      org.jivesoftware.smack.SmackException.NotLoggedInException - If not logged in.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.

    • reloadAndWait

      public void reloadAndWait() throws org.jivesoftware.smack.SmackException.NotLoggedInException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException
      Reload the roster and block until it is reloaded.
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - if the XMPP connection is not authenticated.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.
      Since:
      4.1

    • setRosterStore

      public boolean setRosterStore(RosterStore rosterStore)
      Set the roster store, may cause a roster reload.
      Parameters:
      rosterStore - TODO javadoc me please
      Returns:
      true if the roster reload was initiated, false otherwise.
      Since:
      4.1

    • 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:

    • 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. Roster loaded listeners are invoked once the Roster was successfully loaded.
      Parameters:
      rosterLoadedListener - the listener to add.
      Returns:
      true if the listener was not already added.
      Since:
      4.1
      See Also:

    • 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:

    • addPresenceEventListener

      public boolean addPresenceEventListener(PresenceEventListener presenceEventListener)
      Add a PresenceEventListener. Such a listener will be fired whenever certain presence events happen.

      Among those events are:

      • 'available' presence received
      • 'unavailable' presence received
      • 'error' presence received
      • 'subscribed' presence received
      • 'unsubscribed' presence received
      Parameters:
      presenceEventListener - listener to add.
      Returns:
      true if the listener was not already added.

    • removePresenceEventListener

      public boolean removePresenceEventListener(PresenceEventListener presenceEventListener)

    • 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

    • createItem

      public void createItem(org.jxmpp.jid.BareJid jid, String name, String[] groups) throws org.jivesoftware.smack.SmackException.NotLoggedInException, org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException
      Creates a new roster item. The server will asynchronously update the roster with the subscription status.

      There will be no presence subscription request. Consider using createItemAndRequestSubscription(BareJid, String, String[]) if you also want to request a presence subscription from the contact.

      Parameters:
      jid - the XMPP address of the contact (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 roster entry won't belong to a group.
      Throws:
      org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the server.
      org.jivesoftware.smack.XMPPException.XMPPErrorException - if an XMPP exception occurs.
      org.jivesoftware.smack.SmackException.NotLoggedInException - If not logged in.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.
      Since:
      4.4.0

    • createItemAndRequestSubscription

      public void createItemAndRequestSubscription(org.jxmpp.jid.BareJid jid, String name, String[] groups) throws org.jivesoftware.smack.SmackException.NotLoggedInException, org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException
      Creates a new roster entry and presence subscription. The server will asynchronously update the roster with the subscription status.
      Parameters:
      jid - the XMPP address of the contact (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 roster entry won't belong to a group.
      Throws:
      org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the server.
      org.jivesoftware.smack.XMPPException.XMPPErrorException - if an XMPP exception occurs.
      org.jivesoftware.smack.SmackException.NotLoggedInException - If not logged in.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.
      Since:
      4.4.0

    • preApproveAndCreateEntry

      public void preApproveAndCreateEntry(org.jxmpp.jid.BareJid user, String name, String[] groups) throws org.jivesoftware.smack.SmackException.NotLoggedInException, org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException, org.jivesoftware.smack.SmackException.FeatureNotSupportedException
      Creates a new pre-approved 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 roster entry won't belong to a group.
      Throws:
      org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the server.
      org.jivesoftware.smack.XMPPException.XMPPErrorException - if an XMPP exception occurs.
      org.jivesoftware.smack.SmackException.NotLoggedInException - if not logged in.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.
      org.jivesoftware.smack.SmackException.FeatureNotSupportedException - if pre-approving is not supported.
      Since:
      4.2

    • preApprove

      public void preApprove(org.jxmpp.jid.BareJid user) throws org.jivesoftware.smack.SmackException.NotLoggedInException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException, org.jivesoftware.smack.SmackException.FeatureNotSupportedException
      Pre-approve user presence subscription.
      Parameters:
      user - the user. (e.g. johndoe@jabber.org)
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - if not logged in.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.
      org.jivesoftware.smack.SmackException.FeatureNotSupportedException - if pre-approving is not supported.
      Since:
      4.2

    • isSubscriptionPreApprovalSupported

      public boolean isSubscriptionPreApprovalSupported() throws org.jivesoftware.smack.SmackException.NotLoggedInException
      Check for subscription pre-approval support.
      Returns:
      true if subscription pre-approval is supported by the server.
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - if not logged in.
      Since:
      4.2

    • sendSubscriptionRequest

      public void sendSubscriptionRequest(org.jxmpp.jid.BareJid jid) throws org.jivesoftware.smack.SmackException.NotLoggedInException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException
      org.jivesoftware.smack.SmackException.NotConnectedException
      InterruptedException

    • addSubscribeListener

      public boolean addSubscribeListener(SubscribeListener subscribeListener)
      Add a subscribe listener, which is invoked on incoming subscription requests and if Roster.SubscriptionMode is set to Roster.SubscriptionMode.manual. This also sets subscription mode to Roster.SubscriptionMode.manual.
      Parameters:
      subscribeListener - the subscribe listener to add.
      Returns:
      true if the listener was not already added.
      Since:
      4.2

    • removeSubscribeListener

      public boolean removeSubscribeListener(SubscribeListener subscribeListener)
      Remove a subscribe listener. Also restores the previous subscription mode state, if the last listener got removed.
      Parameters:
      subscribeListener - TODO javadoc me please the subscribe listener to remove.
      Returns:
      true if the listener registered and got removed.
      Since:
      4.2

    • removeEntry

      public void removeEntry(RosterEntry entry) throws org.jivesoftware.smack.SmackException.NotLoggedInException, org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException
      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:
      org.jivesoftware.smack.XMPPException.XMPPErrorException - if an XMPP error occurs.
      org.jivesoftware.smack.SmackException.NotLoggedInException - if not logged in.
      org.jivesoftware.smack.SmackException.NoResponseException - SmackException if there was no response from the server.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.

    • 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.rosterEntries(Collection) has been invoked, and that all roster events that happen while rosterEntries(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(org.jxmpp.jid.BareJid jid)
      Returns the roster entry associated with the given XMPP address or null if the user is not an entry in the roster.
      Parameters:
      jid - the XMPP address of the user (e.g."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(org.jxmpp.jid.BareJid jid)
      Returns true if the specified XMPP address is an entry in the roster.
      Parameters:
      jid - the XMPP address of the user (e.g."jsmith@example.com"). The address must be a bare JID e.g. "domain/resource" or "user@domain".
      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 org.jivesoftware.smack.packet.Presence getPresence(org.jxmpp.jid.BareJid jid)
      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:
      jid - the XMPP address of the user (e.g."jsmith@example.com"). The address must be a bare JID e.g. "domain/resource" or "user@domain".
      Returns:
      the user's current presence, or unavailable presence if the user is offline or if no presence information is available.

    • getPresenceResource

      public org.jivesoftware.smack.packet.Presence getPresenceResource(org.jxmpp.jid.FullJid 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<org.jivesoftware.smack.packet.Presence> getAllPresences(org.jxmpp.jid.BareJid 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<org.jivesoftware.smack.packet.Presence> getAvailablePresences(org.jxmpp.jid.BareJid 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<org.jivesoftware.smack.packet.Presence> getPresences(org.jxmpp.jid.BareJid jid)
      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:
      jid - 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(org.jxmpp.jid.Jid 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 - TODO javadoc me please
      Returns:
      true if the given JID is allowed to see the users presence.
      Since:
      4.1

    • iAmSubscribedTo

      public boolean iAmSubscribedTo(org.jxmpp.jid.Jid jid)
      Check if the XMPP entity this roster belongs to is subscribed to the presence of the given JID.
      Parameters:
      jid - the jid to check.
      Returns:
      true if we are subscribed to the presence of the given jid.
      Since:
      4.2

    • setRosterLoadedAtLoginDefault

      public static void setRosterLoadedAtLoginDefault(boolean rosterLoadedAtLoginDefault)
      Sets if the roster will be loaded from the server when logging in for newly created instances of Roster.
      Parameters:
      rosterLoadedAtLoginDefault - if the roster will be loaded from the server when logging in.
      Since:
      4.1.7
      See Also:

    • 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:

    • isRosterVersioningSupported

      public boolean isRosterVersioningSupported()
      Check if the server supports roster versioning.
      Returns:
      true if the server supports roster versioning, false otherwise.

    • setDefaultNonRosterPresenceMapMaxSize

      public static void setDefaultNonRosterPresenceMapMaxSize(int maximumSize)
      Set the default maximum size of the non-Roster presence map.

      The roster will only store this many presence entries for entities non in the Roster. The default is 1024.

      Parameters:
      maximumSize - the maximum size
      Since:
      4.2

    • setNonRosterPresenceMapMaxSize

      public void setNonRosterPresenceMapMaxSize(int maximumSize)
      Set the maximum size of the non-Roster presence map.
      Parameters:
      maximumSize - TODO javadoc me please
      Since:
      4.2
      See Also: