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