Smack

org.jivesoftware.smack
Class Roster

java.lang.Object
  |
  +--org.jivesoftware.smack.Roster

public class Roster
extends Object

Represents a user's roster, which is the collection of users a person receives presence updates for. Roster items are categorized into groups for easier management.

Others users may attempt to subscribe to this user using a subscription request. Three modes are supported for handling these requests:

All presence subscription requests are automatically approved to this client are automatically approved. This logic will be updated in the future to allow for pluggable behavior.

Author:
Matt Tucker
See Also:
XMPPConnection.getRoster()

Field Summary
static int SUBCRIPTION_ACCEPT_ALL
          Automatically accept all subscription requests.
static int SUBCRIPTION_REJECT_ALL
          Automatically reject all subscription requests.
static int SUBSCRIPTION_MANUAL
          Subscription requests are ignored, which means they must be manually processed by registering a listener for presence packets and then looking for any presence requests that have the type Presence.Type.SUBSCRIBE.
 
Method Summary
 void addRosterListener(RosterListener rosterListener)
          Adds a listener to this roster.
 void createEntry(String user, String name, String[] groups)
          Cretaes a new roster entry and prsence subscription.
 RosterGroup createGroup(String name)
          Creates a new group.
 RosterGroup getGroup(String name)
          Returns the roster group with the specified name, or null if the group doesn't exist.
 int getGroupCount()
          Returns the number of the groups in the roster.
 Iterator getGroups()
          Returns an iterator the for all the roster groups.
 Presence getPresence(String user)
          Returns the presence info for a particular user, or null if there is no presence information.
 int getSubscriptionMode()
          Returns the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made.
 Iterator getUnfiledEntries()
          Returns an Iterator for the roster entries that haven't been assigned to any groups.
 void reload()
          Reloads the entire roster from the server.
 void removeRosterListener(RosterListener rosterListener)
          Removes a listener from this roster.
 void setSubscriptionMode(int subscriptionMode)
          Sets the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SUBCRIPTION_ACCEPT_ALL

public static final int SUBCRIPTION_ACCEPT_ALL
Automatically accept all subscription requests. This is the default mode and is suitable for simple client. More complex client will likely wish to handle subscription requests manually.

See Also:
Constant Field Values

SUBCRIPTION_REJECT_ALL

public static final int SUBCRIPTION_REJECT_ALL
Automatically reject all subscription requests.

See Also:
Constant Field Values

SUBSCRIPTION_MANUAL

public static final int SUBSCRIPTION_MANUAL
Subscription requests are ignored, which means they must be manually processed by registering a listener for presence packets and then looking for any presence requests that have the type Presence.Type.SUBSCRIBE.

See Also:
Constant Field Values
Method Detail

getSubscriptionMode

public int getSubscriptionMode()
Returns the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made.

Returns:
the subscription mode.

setSubscriptionMode

public void setSubscriptionMode(int subscriptionMode)
Sets the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made.

Parameters:
subscriptionMode - the subscription mode.

reload

public void reload()
Reloads the entire roster from the server. This is an asynchronous operation, which means the method will return immediately, and the roster will be reloaded at a later point when the server responds to the reload request.


addRosterListener

public void addRosterListener(RosterListener rosterListener)
Adds a listener to this roster. The listener will be fired anytime one or more changes to the roster are pushed from the server.

Parameters:
rosterListener - a roster listener.

removeRosterListener

public void removeRosterListener(RosterListener rosterListener)
Removes a listener from this roster. The listener will be fired anytime one or more changes to the roster are pushed from the server.

Parameters:
rosterListener - a roster listener.

createGroup

public RosterGroup createGroup(String name)
Creates a new group.

Parameters:
name - the name of the group.
Returns:
a new group.

createEntry

public void createEntry(String user,
                        String name,
                        String[] groups)
                 throws XMPPException
Cretaes a new roster entry and prsence subscription. The server will asynchronously update the roster with the subscription status.

Parameters:
user - the user.
name - the nickname of the user.
groups - the list of groups entry will belong to, or null if the the roster entry won't belong to a group.
XMPPException

getUnfiledEntries

public Iterator getUnfiledEntries()
Returns an Iterator for the roster entries that haven't been assigned to any groups.

Returns:
an iterator the roster entries that haven't been filed into groups.

getGroup

public RosterGroup getGroup(String name)
Returns the roster group with the specified name, or null if the group doesn't exist.

Parameters:
name - the name of the group.
Returns:
the roster group with the specified name.

getGroupCount

public int getGroupCount()
Returns the number of the groups in the roster.

Returns:
the number of groups in the roster.

getGroups

public Iterator getGroups()
Returns an iterator the for all the roster groups.

Returns:
an iterator for all roster groups.

getPresence

public Presence getPresence(String user)
Returns the presence info for a particular user, or null if there is no presence information.

Parameters:
user - a fully qualified xmpp ID, e.g. jdoe@example.com
Returns:
the user's presence.

Smack

Copyright © 2003 Jive Software.