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

Fields

Modifier and Type	Field and Description
protected ConcurrentMap<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 ConcurrentMap<String,RosterItem>	rosterItems Roster item cache - table: key jabberid string; value roster item.

Constructor Summary

Constructors

Constructor and Description
Roster() Constructor added for Externalizable.

Method Summary

Modifier and Type	Method and Description
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 roster.
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.
boolean	equals(Object o)
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.
int	hashCode()
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, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

rosterItems

protected ConcurrentMap<String,RosterItem> rosterItems

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

implicitFrom

protected ConcurrentMap<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.

Returns:

the roster item

Throws:

UserAlreadyExistsException - if the user is already in the roster

SharedGroupException - if the group is a shared group

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)

Returns:

the roster item

Throws:

UserAlreadyExistsException - if the user is already in the roster

SharedGroupException - if the group is a shared group

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 - if the user is already in the roster

SharedGroupException - if the group is a shared group

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 - if the user is already in the roster

SharedGroupException - if the group is a shared group

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

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 - if the size cannot be calculated

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

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