org.jabber.jabberbeans
Class RosterBean

java.lang.Object
  |
  +--org.jabber.jabberbeans.RosterBean

public class RosterBean

extends java.lang.Object

implements java.io.Serializable

RosterBean is a bean to gain and utilize the roster information in jabber. A 'Roster' is a list of users, a type of subscription list or address book, if you will. By using a roster, you can get the status of other users (online/offline, etc), subscribe and unsubscribe users, as well as change your own status.

This bean hooks into an IQBean, it will not work until it is given a ConnectionBean to handle. RosterBean to ConnectionBean is a many to one relation - one ConnectionBean can have many RosterBeans, but if software wants to use more than a singular server connection, there is need for multiple RosterBeans, one per ConnectionBean.

Version:

$Revision: 1.1.1.1 $

Author:

David Waite <dwaite@jabber.com>, $Author: lucky $

See Also:

Serialized Form

Inner Class Summary

(package private) class

RosterBean.RosterPacketListener class RosterPacketListener filters out received packets and outputs only those which contain roster information, through the RosterListener vector.

Field Summary

private IQBean	connection parent connection class, an IQBean
private java.util.Hashtable	currentRoster we use the roster extension object to store our current roster.
private InfoQueryBuilder	IQBuilder an infoquery builder for sending roster change requests.
private RosterBean.RosterPacketListener	listener Internal object for processing the PacketListener events
private RosterBuilder	rosterBuilder a roster extension builder for sending roster change requests.
private RosterItemBuilder	rosterItemBuilder a roster item builder for sending custom roster changes.
private java.util.Vector	rosterListeners roster subscribed listener list

Constructor Summary

RosterBean()
Default do-nothing constructor.

Method Summary

void	addRosterItem(RosterItem ri) addRosterItem adds one precreated roster item to the roster, as stored on the server.
void	addRosterListener(RosterListener l) addRosterListener registers a class supporting RosterListener to receive events from this bean.
void	delRosterItem(RosterItem ri) delRosterItem deletes a roster item.
void	delRosterListener(RosterListener l) delRosterListener unregisters a RosterListener from receiving events from this bean.
java.util.Enumeration	entries() returns the entries int the maintained roster cache.
private void	fireUserRosterChanged(Roster r) fireUserRosterChanged is a helper method to notify all subscribed RosterListener objects that the roster has been altered.
private void	fireUserRosterReplaced(Roster r) fireUserRosterReplaced is a helper method to notify all subscribed RosterListener objects that the roster has been completely reloaded
IQBean	getIQBean() getIQBean returns the currently set parent bean, if any
void	refreshRoster() refreshRoster does a complete reload of the user roster.
void	setIQBean(IQBean connection) setIQBean sets the IQBean 'parent' for this class, which is used to send and receive events from the interface with the jabber server.

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

connection

private IQBean connection

parent connection class, an IQBean

rosterListeners

private java.util.Vector rosterListeners

roster subscribed listener list

currentRoster

private java.util.Hashtable currentRoster

we use the roster extension object to store our current roster.

IQBuilder

private InfoQueryBuilder IQBuilder

an infoquery builder for sending roster change requests. Not created until first use.

rosterBuilder

private RosterBuilder rosterBuilder

a roster extension builder for sending roster change requests. Not created until first use.

rosterItemBuilder

private RosterItemBuilder rosterItemBuilder

a roster item builder for sending custom roster changes. Not created until first use.

listener

private RosterBean.RosterPacketListener listener

Internal object for processing the PacketListener events

Constructor Detail

RosterBean

public RosterBean()

Default do-nothing constructor.

Method Detail

setIQBean

public void setIQBean(IQBean connection)

setIQBean sets the IQBean 'parent' for this class, which is used to send and receive events from the interface with the jabber server.

Parameters:

connection - an IQBean

getIQBean

public IQBean getIQBean()

getIQBean returns the currently set parent bean, if any

Returns:

an IQBean value, or null if none has been set.

refreshRoster

public void refreshRoster()
                   throws java.lang.InstantiationException

refreshRoster does a complete reload of the user roster.

Throws:

java.lang.InstantiationException - should never be thrown (may be removed after this is proven to be true)

addRosterItem

public void addRosterItem(RosterItem ri)
                   throws java.lang.InstantiationException

addRosterItem adds one precreated roster item to the roster, as stored on the server. A response will be sent by the server, which will trigger a changed event on any registered RosterListener interface.

Parameters:

ri - a RosterItem object to add

Throws:

java.lang.InstantiationException - if the build processes fail - this may be removed after debugging.

delRosterItem

public void delRosterItem(RosterItem ri)
                   throws java.lang.InstantiationException

delRosterItem deletes a roster item. The rosterItem can be taken directly from a valid Roster Extension object. The server will respond to this, at which time any registered RosterListener interfaces will be notified via a 'changed' type event.

Parameters:

ri - a RosterItem to delete

Throws:

java.lang.InstantiationException - if there is an error building objects, this may be removed later, after debugging.

addRosterListener

public void addRosterListener(RosterListener l)

addRosterListener registers a class supporting RosterListener to receive events from this bean.

Parameters:

l - a RosterListener to register

delRosterListener

public void delRosterListener(RosterListener l)

delRosterListener unregisters a RosterListener from receiving events from this bean.

Parameters:

l - a RosterListener to unregister

entries

public java.util.Enumeration entries()

returns the entries int the maintained roster cache.

Returns:

an Enumeration of RosterItems

fireUserRosterChanged

private void fireUserRosterChanged(Roster r)

fireUserRosterChanged is a helper method to notify all subscribed RosterListener objects that the roster has been altered.

Parameters:

r - an Roster Extension value holding a description of changes made.

fireUserRosterReplaced

private void fireUserRosterReplaced(Roster r)

fireUserRosterReplaced is a helper method to notify all subscribed RosterListener objects that the roster has been completely reloaded

Parameters:

r - an Roster Extension after reloading.