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:

• SUBSCRIPTION_ACCEPT_ALL -- accept all subscription requests.
• SUBSCRIPTION_REJECT_ALL -- reject all subscription requests.
• SUBSCRIPTION_MANUAL -- manually process all subscription 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	SUBSCRIPTION_ACCEPT_ALL Automatically accept 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.
static int	SUBSCRIPTION_REJECT_ALL Automatically reject all subscription requests.

Method Summary

void	addRosterListener(RosterListener rosterListener) Adds a listener to this roster.
boolean	contains(String user) Returns true if the specified XMPP address is an entry in the roster.
void	createEntry(String user, String name, String[] groups) Creates a new roster entry and presence subscription.
RosterGroup	createGroup(String name) Creates a new group.
static int	getDefaultSubscriptionMode() Returns the default subscription processing mode to use when a new Roster is created.
Iterator	getEntries() Returns all entries in the roster, including entries that don't belong to any groups.
RosterEntry	getEntry(String user) Returns the roster entry associated with the given XMPP address or null if the user is not an entry in the roster.
int	getEntryCount() Returns a count of the entries in the roster.
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 the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.
Presence	getPresenceResource(String userResource) Returns the presence info for a particular user's resource, or null if the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.
Iterator	getPresences(String user) Returns an iterator (of Presence objects) for all the user's current presences or null if the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.
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 unfiled roster entries.
int	getUnfiledEntryCount() Returns a count of the unfiled entries in the roster.
void	reload() Reloads the entire roster from the server.
void	removeEntry(RosterEntry entry) Removes a roster entry from the roster.
void	removeRosterListener(RosterListener rosterListener) Removes a listener from this roster.
static void	setDefaultSubscriptionMode(int subscriptionMode) Sets the default subscription processing mode to use when a new Roster is created.
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

SUBSCRIPTION_ACCEPT_ALL

public static final int SUBSCRIPTION_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

SUBSCRIPTION_REJECT_ALL

public static final int SUBSCRIPTION_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

getDefaultSubscriptionMode

public static int getDefaultSubscriptionMode()

Returns the default subscription processing mode to use when a new Roster is created. The subscription processing mode dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is SUBSCRIPTION_ACCEPT_ALL.

Returns:

the default subscription mode to use for new Rosters

setDefaultSubscriptionMode

public static void setDefaultSubscriptionMode(int subscriptionMode)

Sets the default subscription processing mode to use when a new Roster is created. The subscription processing mode dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is SUBSCRIPTION_ACCEPT_ALL.

Parameters:

subscriptionMode - the default subscription mode to use for new Rosters.

getSubscriptionMode

public int getSubscriptionMode()

Returns the subscription processing mode, which dictates what action Smack will take when subscription requests from other users are made. The default subscription mode is SUBSCRIPTION_ACCEPT_ALL.

If using the manual mode, a PacketListener should be registered that listens for Presence packets that have a type of Presence.Type.SUBSCRIBE.

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. The default subscription mode is SUBSCRIPTION_ACCEPT_ALL.

If using the manual mode, a PacketListener should be registered that listens for Presence packets that have a type of Presence.Type.SUBSCRIBE.

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.

Note: you must add at least one entry to the group for the group to be kept after a logout/login. This is due to the way that XMPP stores group information.

Parameters:

name - the name of the group.

Returns:

a new group.

createEntry

public void createEntry(String user,
                        String name,
                        String[] groups)
                 throws XMPPException

Creates a new roster entry and presence subscription. The server will asynchronously update the roster with the subscription status.

Parameters:

user - the user. (e.g. johndoe@jabber.org)

name - the nickname of the user.

groups - the list of group names the entry will belong to, or null if the the roster entry won't belong to a group.

Throws:

XMPPException

removeEntry

public void removeEntry(RosterEntry entry)

Removes a roster entry from the roster. The roster entry will also be removed from the unfiled entries or from any roster group where it could belong and will no longer be part of the roster.

Parameters:

entry - a roster entry.

getEntryCount

public int getEntryCount()

Returns a count of the entries in the roster.

Returns:

the number of entries in the roster.

getEntries

public Iterator getEntries()

Returns all entries in the roster, including entries that don't belong to any groups.

Returns:

all entries in the roster.

getUnfiledEntryCount

public int getUnfiledEntryCount()

Returns a count of the unfiled entries in the roster. An unfiled entry is an entry that doesn't belong to any groups.

Returns:

the number of unfiled entries in the roster.

getUnfiledEntries

public Iterator getUnfiledEntries()

Returns an Iterator for the unfiled roster entries. An unfiled entry is an entry that doesn't belong to any groups.

Returns:

an iterator the unfiled roster entries.

getEntry

public RosterEntry getEntry(String user)

Returns the roster entry associated with the given XMPP address or null if the user is not an entry in the roster.

Parameters:

user - the XMPP address of the user (eg "jsmith@example.com"). The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource").

Returns:

the roster entry or null if it does not exist.

contains

public boolean contains(String user)

Returns true if the specified XMPP address is an entry in the roster.

Parameters:

user - the XMPP address of the user (eg "jsmith@example.com"). The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource").

Returns:

true if the XMPP address is an entry in the roster.

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 the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.

If the user has several presences (one for each resource) then answer the presence with the highest priority.

Parameters:

user - a fully qualified xmpp ID. The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource").

Returns:

the user's current presence, or null if the user is unavailable or if no presence information is available..

getPresenceResource

public Presence getPresenceResource(String userResource)

Returns the presence info for a particular user's resource, or null if the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.

Parameters:

userResource - a fully qualified xmpp ID including a resource.

Returns:

the user's current presence, or null if the user is unavailable or if no presence information is available.

getPresences

public Iterator getPresences(String user)

Returns an iterator (of Presence objects) for all the user's current presences or null if the user is unavailable (offline) or if no presence information is available, such as when you are not subscribed to the user's presence updates.

Parameters:

user - a fully qualified xmpp ID, e.g. jdoe@example.com

Returns:

an iterator (of Presence objects) for all the user's current presences, or null if the user is unavailable or if no presence information is available.