Package org.jivesoftware.openfire.roster

Class RosterItem

  • All Implemented Interfaces:
    Externalizable, Serializable, Cacheable
    public class RosterItem
extends Object
implements Cacheable, Externalizable

    Represents a single roster item for a User's Roster.

    The server doesn't need to know anything about roster groups so they are not stored with easy retrieval or manipulation in mind. The important data elements of a roster item (beyond the jid adddress of the roster entry) includes:

    • nick - A nickname for the user when used in this roster
    • sub - A subscription type: to, from, none, both
    • ask - An optional subscription ask status: subscribe, unsubscribe
    • groups - A list of groups to organize roster entries under (e.g. friends, co-workers, etc)
    Author:
    Gaston Dombiak
    See Also:
    Serialized Form

    • Field Detail

      • SUB_REMOVE

        public static final RosterItem.SubType SUB_REMOVE

        Indicates the roster item should be removed.

      • SUB_NONE

        public static final RosterItem.SubType SUB_NONE

        No subscription is established.

      • SUB_TO

        public static final RosterItem.SubType SUB_TO

        The roster owner has a subscription to the roster item's presence.

      • SUB_FROM

        public static final RosterItem.SubType SUB_FROM

        The roster item has a subscription to the roster owner's presence.

      • SUB_BOTH

        public static final RosterItem.SubType SUB_BOTH

        The roster item and owner have a mutual subscription.

      • ASK_NONE

        public static final RosterItem.AskType ASK_NONE

        The roster item has no pending subscription requests.

      • ASK_SUBSCRIBE

        public static final RosterItem.AskType ASK_SUBSCRIBE

        The roster item has been asked for permission to subscribe to their presence but no response has been received.

      • ASK_UNSUBSCRIBE

        public static final RosterItem.AskType ASK_UNSUBSCRIBE

        The roster owner has asked to the roster item to unsubscribe from it's presence but has not received confirmation.

      • RECV_NONE

        public static final RosterItem.RecvType RECV_NONE

        There are no subscriptions that have been received but not presented to the user.

      • RECV_SUBSCRIBE

        public static final RosterItem.RecvType RECV_SUBSCRIBE

        The server has received a subscribe request, but has not forwarded it to the user.

      • RECV_UNSUBSCRIBE

        public static final RosterItem.RecvType RECV_UNSUBSCRIBE

        The server has received an unsubscribe request, but has not forwarded it to the user.

      • jid

        protected org.xmpp.packet.JID jid

      • nickname

        protected String nickname

      • sharedGroups

        protected Set<String> sharedGroups

      • invisibleSharedGroups

        protected Set<String> invisibleSharedGroups

    • Method Detail

      • getAskStatus

        public static RosterItem.AskType getAskStatus​(org.xmpp.packet.Roster.Item item)

      • getSubType

        public static RosterItem.SubType getSubType​(org.xmpp.packet.Roster.Item item)

      • getSubStatus

        public RosterItem.SubType getSubStatus()

        Obtain the current subscription status of the item.

        Returns:
        The subscription status of the item

      • setSubStatus

        public void setSubStatus​(RosterItem.SubType subStatus)

        Set the current subscription status of the item.

        Parameters:
        subStatus - The subscription status of the item

      • getAskStatus

        public RosterItem.AskType getAskStatus()

        Obtain the current ask status of the item.

        Returns:
        The ask status of the item

      • setAskStatus

        public void setAskStatus​(RosterItem.AskType askStatus)

        Set the current ask status of the item.

        Parameters:
        askStatus - The ask status of the item

      • getRecvStatus

        public RosterItem.RecvType getRecvStatus()

        Obtain the current recv status of the item.

        Returns:
        The recv status of the item

      • setRecvStatus

        public void setRecvStatus​(RosterItem.RecvType recvStatus)

        Set the current recv status of the item.

        Parameters:
        recvStatus - The recv status of the item

      • getJid

        public org.xmpp.packet.JID getJid()

        Obtain the address of the item.

        Returns:
        The address of the item

      • getNickname

        public String getNickname()

        Obtain the current nickname for the item.

        Returns:
        The subscription status of the item

      • setNickname

        public void setNickname​(String nickname)

        Set the current nickname for the item.

        Parameters:
        nickname - The subscription status of the item

      • getGroups

        public List<String> getGroups()
        Returns the groups for the item. Shared groups won't be included in the answer.
        Returns:
        The groups for the item.

      • setGroups

        public void setGroups​(List<String> groups)
               throws SharedGroupException
        Set the current groups for the item.
        Parameters:
        groups - The new lists of groups the item belongs to.
        Throws:
        SharedGroupException - if trying to remove shared group.

      • getSharedGroups

        public Collection<Group> getSharedGroups()
        Returns the shared groups for the item.
        Returns:
        The shared groups this item belongs to.

      • getInvisibleSharedGroups

        public Collection<Group> getInvisibleSharedGroups()
        Returns the invisible shared groups for the item. These groups are for internal use and help track the reason why a roster item has a presence subscription of type FROM when using shared groups.
        Returns:
        The shared groups this item belongs to.

      • addSharedGroup

        public void addSharedGroup​(Group sharedGroup)
        Adds a new group to the shared groups list.
        Parameters:
        sharedGroup - The shared group to add to the list of shared groups.

      • addInvisibleSharedGroup

        public void addInvisibleSharedGroup​(Group sharedGroup)
        Adds a new group to the list shared groups that won't be sent to the user. These groups are for internal use and help track the reason why a roster item has a presence subscription of type FROM when using shared groups.
        Parameters:
        sharedGroup - The shared group to add to the list of shared groups.

      • removeSharedGroup

        public void removeSharedGroup​(Group sharedGroup)
        Removes a group from the shared groups list.
        Parameters:
        sharedGroup - The shared group to remove from the list of shared groups.

      • isShared

        public boolean isShared()
        Returns true if this item belongs to a shared group. Return true even if the item belongs to a personal group and a shared group.
        Returns:
        true if this item belongs to a shared group.

      • isOnlyShared

        public boolean isOnlyShared()
        Returns true if this item belongs ONLY to shared groups. This means that the the item is considered to be "only shared" if it doesn't belong to a personal group but only to shared groups.
        Returns:
        true if this item belongs ONLY to shared groups.

      • getID

        public long getID()
        Returns the roster ID associated with this particular roster item. A value of zero means that the roster item is not being persisted in the backend store.

        Databases can use the roster ID as the key in locating roster items.

        Returns:
        The roster ID

      • setID

        public void setID​(long rosterID)
        Sets the roster ID associated with this particular roster item. A value of zero means that the roster item is not being persisted in the backend store.

        Databases can use the roster ID as the key in locating roster items.

        Parameters:
        rosterID - The roster ID.

      • setAsCopyOf

        public void setAsCopyOf​(org.xmpp.packet.Roster.Item item)
                 throws SharedGroupException

        Update the cached item as a copy of the given item.

        A convenience for getting the item and setting each attribute.

        Parameters:
        item - The item who's settings will be copied into the cached copy
        Throws:
        SharedGroupException - if trying to remove shared group.

      • getCachedSize

        public int getCachedSize()
                  throws CannotCalculateSizeException
        Description copied from interface: Cacheable
        Returns the approximate size of the Object in bytes. The size should be considered to be a best estimate of how much memory the Object occupies and may be based on empirical trials or dynamic calculations.

        Specified by:
        getCachedSize in interface Cacheable
        Returns:
        the size of the Object in bytes.
        Throws:
        CannotCalculateSizeException - if the size cannot be calculated