Package org.jivesoftware.smack.roster

Class Roster

  • public final 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. Other 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)

    • Method Detail

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

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

      • 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

      • waitUntilLoaded

        protected boolean waitUntilLoaded()
                           throws java.lang.InterruptedException
        Throws:
        java.lang.InterruptedException

      • isLoaded

        public boolean isLoaded()
        Check if the roster is loaded.
        Returns:
        true if the roster is loaded.
        Since:
        4.1

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

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

      • createGroup

        public RosterGroup createGroup​(java.lang.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

      • 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

      • 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 java.util.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 java.util.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​(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 (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​(BareJid jid)
        Returns true if the specified XMPP address is an entry in the roster.
        Parameters:
        jid - the XMPP address of the user (eg "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​(java.lang.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 java.util.Collection<RosterGroup> getGroups()
        Returns an unmodifiable collections of all the roster groups.
        Returns:
        an iterator for all roster groups.

      • getPresence

        public Presence getPresence​(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 (eg "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 Presence getPresenceResource​(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 java.util.List<Presence> getAllPresences​(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 java.util.List<Presence> getAvailablePresences​(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 java.util.List<Presence> getPresences​(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​(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​(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(boolean)

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

      • 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