Overview | Package | Class | Tree | Deprecated | Index | Help
| Openfire 3.8.2 Javadoc
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.jivesoftware.openfire.roster
Class Roster

    java.lang.Object
      org.jivesoftware.openfire.roster.Roster

All Implemented Interfaces:
  Externalizable, Serializable, Cacheable

    public class Roster

extends Object
implements Cacheable, Externalizable

A roster is a list of users that the user wishes to know if they are online.

Rosters are similar to buddy groups in popular IM clients. The Roster class is a representation of the roster data.

Updates to this roster is effectively a change to the user's roster. To reflect this, the changes to this class will automatically update the persistently stored roster, as well as send out update announcements to all logged in user sessions.

Author:
  Gaston Dombiak
See Also:
  Serialized Form

Field Summary
`protected ConcurrentHashMap<String,Set<String>>` | `implicitFrom` Contacts with subscription FROM that only exist due to shared groups key: jabberid string; value: groups why the implicit roster item exists (aka invisibleSharedGroups).
`protected ConcurrentHashMap<String,RosterItem>` | `rosterItems` Roster item cache - table: key jabberid string; value roster item.

Constructor Summary
`Roster()` Constructor added for Externalizable.

Method Summary
`void` | `broadcast(RosterItem item, boolean optimize)` Broadcasts the RosterItem to all the connected resources of this user.
`void` | `broadcastPresence(org.xmpp.packet.Presence packet)` Broadcast the presence update to all subscribers of the roter.
`RosterItem` | `createRosterItem(org.xmpp.packet.JID user, boolean push, boolean persistent)` Create a new item to the roster.
`RosterItem` | `createRosterItem(org.xmpp.packet.JID user, String nickname, List<String> groups, boolean push, boolean persistent)` Create a new item to the roster.
`void` | `createRosterItem(org.xmpp.packet.Roster.Item item)` Create a new item to the roster based as a copy of the given item.
`RosterItem` | `deleteRosterItem(org.xmpp.packet.JID user, boolean doChecking)` Remove a user from the roster.
`int` | `getCachedSize()` Returns the approximate size of the Object in bytes.
`org.xmpp.packet.Roster` | `getReset()` Obtain a 'roster reset', a snapshot of the full cached roster as an Roster.
`RosterItem` | `getRosterItem(org.xmpp.packet.JID user)` Returns the roster item that is associated with the specified JID.
`Collection<RosterItem>` | `getRosterItems()` Returns a collection of users in this roster.
`String` | `getUsername()` Return the username of the user or chatbot that owns this roster.
`boolean` | `isRosterItem(org.xmpp.packet.JID user)` Returns true if the specified user is a member of the roster, false otherwise.
`protected RosterItem` | `provideRosterItem(org.xmpp.packet.JID user, String nickname, List<String> groups, boolean push, boolean persistent)` Generate a new RosterItem for use with createRosterItem.
`void` | `readExternal(ObjectInput in)`
`void` | `updateRosterItem(RosterItem item)` Update an item that is already in the roster.
`void` | `writeExternal(ObjectOutput out)`

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

Field Detail

### rosterItems

    protected ConcurrentHashMap<String,RosterItem> rosterItems

  Roster item cache - table: key jabberid string; value roster item.

### implicitFrom

    protected ConcurrentHashMap<String,Set<String>> implicitFrom

  Contacts with subscription FROM that only exist due to shared groups key: jabberid string; value: groups why the implicit roster item exists (aka invisibleSharedGroups).

Constructor Detail

### Roster

    public Roster()

  Constructor added for Externalizable. Do not use this constructor.

Method Detail

### isRosterItem

    public boolean isRosterItem(org.xmpp.packet.JID user)

  Returns true if the specified user is a member of the roster, false otherwise.

  Parameters:
    `user` - the user object to check.
  Returns:
    true if the specified user is a member of the roster, false otherwise.

### getRosterItems

    public Collection<RosterItem> getRosterItems()

  Returns a collection of users in this roster.

  Note: Roster items with subscription type FROM that exist only because of shared groups are not going to be returned.

  Returns:
    a collection of users in this roster.

### getRosterItem

    public RosterItem getRosterItem(org.xmpp.packet.JID user)
                             throws UserNotFoundException

  Returns the roster item that is associated with the specified JID. If no roster item was found then a UserNotFoundException will be thrown.

  Parameters:
    `user` - the XMPPAddress for the roster item to retrieve
  Returns:
    The roster item associated with the user XMPPAddress.
  Throws:
    `UserNotFoundException` - if no roster item was found for the specified JID.

### createRosterItem

    public RosterItem createRosterItem(org.xmpp.packet.JID user,
                                       boolean push,
                                       boolean persistent)
                                throws UserAlreadyExistsException,
                                       SharedGroupException

  Create a new item to the roster. Roster items may not be created that contain the same user address as an existing item.

  Parameters:
    `user` - The item to add to the roster.
    `push` - True if the new item must be pushed to the user.
    `persistent` - True if the new roster item should be persisted to the DB.
  Throws:
    `UserAlreadyExistsException`
    `SharedGroupException`

### createRosterItem

    public RosterItem createRosterItem(org.xmpp.packet.JID user,
                                       String nickname,
                                       List<String> groups,
                                       boolean push,
                                       boolean persistent)
                                throws UserAlreadyExistsException,
                                       SharedGroupException

  Create a new item to the roster. Roster items may not be created that contain the same user address as an existing item.

  Parameters:
    `user` - The item to add to the roster.
    `nickname` - The nickname for the roster entry (can be null).
    `push` - True if the new item must be push to the user.
    `persistent` - True if the new roster item should be persisted to the DB.
    `groups` - The list of groups to assign this roster item to (can be null)
  Throws:
    `UserAlreadyExistsException`
    `SharedGroupException`

### createRosterItem

    public void createRosterItem(org.xmpp.packet.Roster.Item item)
                          throws UserAlreadyExistsException,
                                 SharedGroupException

  Create a new item to the roster based as a copy of the given item. Roster items may not be created that contain the same user address as an existing item in the roster.

  Parameters:
    `item` - the item to copy and add to the roster.
  Throws:
    `UserAlreadyExistsException`
    `SharedGroupException`

### provideRosterItem

    protected RosterItem provideRosterItem(org.xmpp.packet.JID user,
                                           String nickname,
                                           List<String> groups,
                                           boolean push,
                                           boolean persistent)
                                    throws UserAlreadyExistsException,
                                           SharedGroupException

  Generate a new RosterItem for use with createRosterItem.

  Parameters:
    `user` - The roster jid address to create the roster item for.
    `nickname` - The nickname to assign the item (or null for none).
    `groups` - The groups the item belongs to (or null for none).
    `push` - True if the new item must be push to the user.
    `persistent` - True if the new roster item should be persisted to the DB.
  Returns:
    The newly created roster items ready to be stored by the Roster item's hash table
  Throws:
    `UserAlreadyExistsException`
    `SharedGroupException`

### updateRosterItem

    public void updateRosterItem(RosterItem item)
                          throws UserNotFoundException

  Update an item that is already in the roster.

  Parameters:
    `item` - the item to update in the roster.
  Throws:
    `UserNotFoundException` - If the roster item for the given user doesn't already exist

### deleteRosterItem

    public RosterItem deleteRosterItem(org.xmpp.packet.JID user,
                                       boolean doChecking)
                                throws SharedGroupException

  Remove a user from the roster.

  Parameters:
    `user` - the user to remove from the roster.
    `doChecking` - flag that indicates if checkings should be done before deleting the user.
  Returns:
    The roster item being removed or null if none existed
  Throws:
    `SharedGroupException` - if the user to remove belongs to a shared group

### getUsername

    public String getUsername()

  Return the username of the user or chatbot that owns this roster.

  Returns:
    the username of the user or chatbot that owns this roster

### getReset

    public org.xmpp.packet.Roster getReset()

  Obtain a 'roster reset', a snapshot of the full cached roster as an Roster.

  Returns:
    The roster reset (snapshot) as an Roster

### broadcastPresence

    public void broadcastPresence(org.xmpp.packet.Presence packet)

  Broadcast the presence update to all subscribers of the roter.

  Any presence change typically results in a broadcast to the roster members.

  Parameters:
    `packet` - The presence packet to broadcast

### broadcast

    public void broadcast(RosterItem item,
                          boolean optimize)

  Broadcasts the RosterItem to all the connected resources of this user. Due to performance optimizations and due to some clients errors that are showing items with subscription status FROM we added a flag that indicates if a roster items that exists only because of a shared group with subscription status FROM will not be sent.

  Parameters:
    `item` - the item to broadcast.
    `optimize` - true indicates that items that exists only because of a shared group with subscription status FROM will not be sent

### 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`

### writeExternal

    public void writeExternal(ObjectOutput out)
                       throws IOException

  Specified by:
    `writeExternal` in interface `Externalizable`
  Throws:
    `IOException`

### readExternal

    public void readExternal(ObjectInput in)
                      throws IOException,
                             ClassNotFoundException

  Specified by:
    `readExternal` in interface `Externalizable`
  Throws:
    `IOException`
    `ClassNotFoundException`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Openfire 3.8.2 Javadoc
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003-2008 Jive Software.