com.echomine.jabber

Class JabberRosterService

java.lang.Object

com.echomine.jabber.JabberRosterService

public class JabberRosterService
extends java.lang.Object

Contains all the methods to work with rosters. Roster Management is really simple.

Few things to note about roster management. If you're adding a user to the roster, you will not be notified of the user's presence. You need to explicitly submit a presence subscription message after you add a user to the roster. However, if you're removing an user from the roster, the server will automatically unsubscribe you from that user's presence automatically. Be sure to pay attention to this distinction or you will have some bugs in your application.

The recommended way of subscribing to an user's presence is to follow the simple procedure: (1) add the user to the roster, including the groups the user will be in, (2) send a presence subscription message, and (3) wait for replies from the server and update your application accordingly. Do not update your application after you submit these messages. The server will send you roster/presence update information automatically, which you can then use to update your application.

Constructor Summary

Constructors

Constructor and Description
JabberRosterService(JabberSession session)

Method Summary

Methods

Modifier and Type	Method and Description
void	addToRoster(JID jid, java.lang.String name, java.lang.String group, boolean wait) this is a convenience method to add a JID to the roster.
void	addToRoster(RosterItem item, boolean wait) adds a roster item to the list stored on the server.
void	removeFromRoster(JID jid, boolean wait) a convenience method to remove a JID from the roster.
void	removeFromRoster(RosterItem item, boolean wait) removes a specific item from the roster
java.util.List	requestRosterList(boolean wait) requests the server to send a list of the roster, the reply will be sent to roster listeners, so be sure to listen for the events.

Methods inherited from class java.lang.Object

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

Constructor Detail

JabberRosterService

public JabberRosterService(JabberSession session)

Method Detail

requestRosterList

public java.util.List requestRosterList(boolean wait)
                                 throws SendMessageFailedException

requests the server to send a list of the roster, the reply will be sent to roster listeners, so be sure to listen for the events.

Parameters:

wait - true if the caller wants to wait until there is a reply to the message

Returns:

a list of RosterItem objects or null if wait is false.

Throws:

SendMessageFailedException

addToRoster

public void addToRoster(JID jid,
               java.lang.String name,
               java.lang.String group,
               boolean wait)
                 throws SendMessageFailedException

this is a convenience method to add a JID to the roster. It probably will satisfy 80% of the uses. If you need to set more features, then you should create your own message and use the other addToRoster() method (ie. multiple groups rather than just one).

Parameters:

wait - true if the caller wants to wait until there is a reply to the message

Throws:

SendMessageFailedException

addToRoster

public void addToRoster(RosterItem item,
               boolean wait)
                 throws SendMessageFailedException

adds a roster item to the list stored on the server.

Parameters:

wait - true if the caller wants to wait until there is a reply to the message

Throws:

SendMessageFailedException

removeFromRoster

public void removeFromRoster(JID jid,
                    boolean wait)
                      throws SendMessageFailedException

a convenience method to remove a JID from the roster.

Parameters:

wait - true if the caller wants to wait until there is a reply to the message

Throws:

SendMessageFailedException

removeFromRoster

public void removeFromRoster(RosterItem item,
                    boolean wait)
                      throws SendMessageFailedException

removes a specific item from the roster

Parameters:

wait - true if the caller wants to wait until there is a reply to the message

Throws:

SendMessageFailedException