Jive Messenger 2.2.2 Javadoc

org.jivesoftware.messenger.roster
Class Roster

java.lang.Object
  extended by org.jivesoftware.messenger.roster.Roster
All Implemented Interfaces:
Serializable, Cacheable

public class Roster
extends Object
implements Cacheable

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,RosterItem> rosterItems
          Roster item cache - table: key jabberid string; value roster item.
 
Constructor Summary
Roster(String username)
          Create a roster for the given user, pulling the existing roster items out of the backend storage provider.
 
Method Summary
 void broadcastPresence(Presence packet)
          Broadcast the presence update to all subscribers of the roter.
 RosterItem createRosterItem(JID user)
          Create a new item to the roster.
 RosterItem createRosterItem(JID user, String nickname, List<String> groups)
          Create a new item to the roster.
 void createRosterItem(Roster.Item item)
          Create a new item to the roster based as a copy of the given item.
 RosterItem deleteRosterItem(JID user, boolean doChecking)
          Remove a user from the roster.
 int getCachedSize()
          Returns the approximate size of the Object in bytes.
 Roster getReset()
          Obtain a 'roster reset', a snapshot of the full cached roster as an Roster.
 RosterItem getRosterItem(JID user)
          Gets a user from the roster.
 Collection<RosterItem> getRosterItems()
          Returns a collection of users in this roster.
 int getTotalRosterItemCount()
          Returns the total number of users in the roster.
 String getUsername()
          Return the username of the user or chatbot that owns this roster.
 boolean isRosterItem(JID user)
          Returns true if the specified user is a member of the roster, false otherwise.
protected  RosterItem provideRosterItem(JID user, String nickname, List<String> groups)
          Generate a new RosterItem for use with createRosterItem.
protected  RosterItem provideRosterItem(Roster.Item item)
          Generate a new RosterItem for use with createRosterItem.
 void updateRosterItem(RosterItem item)
          Update an item that is already in the roster.
 
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.

Constructor Detail

Roster

public Roster(String username)

Create a roster for the given user, pulling the existing roster items out of the backend storage provider. The roster will also include items that belong to the user's shared groups.

RosterItems that ONLY belong to shared groups won't be persistent unless the user explicitly subscribes to the contact's presence, renames the contact in his roster or adds the item to a personal group.

Parameters:
username - The username of the user that owns this roster
Method Detail

isRosterItem

public boolean isRosterItem(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.

Returns:
a collection of users in this roster.

getTotalRosterItemCount

public int getTotalRosterItemCount()
Returns the total number of users in the roster.

Returns:
the number of online users in the roster.

getRosterItem

public RosterItem getRosterItem(JID user)
                         throws UserNotFoundException
Gets a user from the roster. If the roster item does not exist, an empty one is created. The new roster item is not stored in the roster until it is added using addRosterItem().

Parameters:
user - the XMPPAddress for the roster item to retrieve
Returns:
The roster item associated with the user XMPPAddress
Throws:
UserNotFoundException

createRosterItem

public RosterItem createRosterItem(JID user)
                            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.
Throws:
UserAlreadyExistsException
SharedGroupException

createRosterItem

public RosterItem createRosterItem(JID user,
                                   String nickname,
                                   List<String> groups)
                            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)
groups - The list of groups to assign this roster item to (can be null)
Throws:
UserAlreadyExistsException
SharedGroupException

createRosterItem

public void createRosterItem(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(Roster.Item item)
                                throws UserAlreadyExistsException,
                                       SharedGroupException

Generate a new RosterItem for use with createRosterItem.

Parameters:
item - The item to copy settings for the new item in this roster
Returns:
The newly created roster items ready to be stored by the Roster item's hash table
Throws:
UserAlreadyExistsException
SharedGroupException

provideRosterItem

protected RosterItem provideRosterItem(JID user,
                                       String nickname,
                                       List<String> groups)
                                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)
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(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 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(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

getCachedSize

public int getCachedSize()
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.

Jive Messenger 2.2.2 Javadoc

Copyright © 1999-2004 Jive Software.