Classes
class	PresencePacketListener
class	RosterPacketListener
Public Types
enum	SubscriptionMode { accept_all, reject_all, manual }
Public Member Functions
SubscriptionMode	getSubscriptionMode ()
void	setSubscriptionMode (SubscriptionMode subscriptionMode)
void	reload ()
void	addRosterListener (RosterListener rosterListener)
void	removeRosterListener (RosterListener rosterListener)
RosterGroup	createGroup (String name)
void	createEntry (String user, String name, String[] groups) throws XMPPException
void	removeEntry (RosterEntry entry) throws XMPPException
int	getEntryCount ()
Collection< RosterEntry >	getEntries ()
int	getUnfiledEntryCount ()
Collection< RosterEntry >	getUnfiledEntries ()
RosterEntry	getEntry (String user)
boolean	contains (String user)
RosterGroup	getGroup (String name)
int	getGroupCount ()
Collection< RosterGroup >	getGroups ()
Presence	getPresence (String user)
Presence	getPresenceResource (String userWithResource)
Iterator< Presence >	getPresences (String user)
Static Public Member Functions
static SubscriptionMode	getDefaultSubscriptionMode ()
static void	setDefaultSubscriptionMode (SubscriptionMode subscriptionMode)
Package Functions
	Roster (final Connection connection)
Package Attributes
boolean	rosterInitialized = false

Detailed Description

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:

accept_all -- accept all subscription requests.
reject_all -- reject all subscription requests.
manual -- manually process all subscription requests.

Author:: Matt Tucker

See also:: Connection.getRoster()

Member Enumeration Documentation

enum org::jivesoftware::smack::Roster::SubscriptionMode

An enumeration for the subscription mode options.

Enumerator:

accept_all	Automatically accept all subscription and unsubscription requests. This is the default mode and is suitable for simple client. More complex client will likely wish to handle subscription requests manually.
reject_all	Automatically reject all subscription requests.
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 or Presence.Type.UNSUBSCRIBE.

Constructor & Destructor Documentation

org.jivesoftware.smack.Roster.Roster ( final Connection connection ) [package]

Creates a new roster.

Parameters:

connection an XMPP connection.

Member Function Documentation

void org.jivesoftware.smack.Roster.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.

boolean org.jivesoftware.smack.Roster.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.

void org.jivesoftware.smack.Roster.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.

Exceptions:

XMPPException	if an XMPP exception occurs.
IllegalStateException	if connection is not logged in or logged in anonymously

RosterGroup org.jivesoftware.smack.Roster.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.

Exceptions:

IllegalStateException if connection is not logged in or logged in anonymously

static SubscriptionMode org.jivesoftware.smack.Roster.getDefaultSubscriptionMode ( ) [static]

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 SubscriptionMode#accept_all.

Returns:: the default subscription mode to use for new Rosters

Collection<RosterEntry> org.jivesoftware.smack.Roster.getEntries ( )

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

Returns:: all entries in the roster.

RosterEntry org.jivesoftware.smack.Roster.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.

int org.jivesoftware.smack.Roster.getEntryCount ( )

Returns a count of the entries in the roster.

Returns:: the number of entries in the roster.

RosterGroup org.jivesoftware.smack.Roster.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.

int org.jivesoftware.smack.Roster.getGroupCount ( )

Returns the number of the groups in the roster.

Returns:: the number of groups in the roster.

Collection<RosterGroup> org.jivesoftware.smack.Roster.getGroups ( )

Returns an unmodifiable collections of all the roster groups.

Returns:: an iterator for all roster groups.

Presence org.jivesoftware.smack.Roster.getPresence ( String user )

Returns the presence info for a particular user. If the user is offline, or if no presence data is available (such as when you are not subscribed to the user's presence updates), unavailable presence will be returned.

If the user has several presences (one for each resource), then the presence with highest priority will be returned. If multiple presences have the same priority, the one with the "most available" presence mode will be returned. In order, that's free to chat, available, away, extended away, and do not disturb.

Note that presence information is received asynchronously. So, just after logging in to the server, presence values for users in the roster may be unavailable even if they are actually online. In other words, the value returned by this method should only be treated as a snapshot in time, and may not accurately reflect other user's presence instant by instant. If you need to track presence over time, such as when showing a visual representation of the roster, consider using a RosterListener.

Parameters:

user	an XMPP ID. The address could be in any valid format (e.g. "domain/resource", "user@domain" or "user@domain/resource"). Any resource information that's part of the ID will be discarded.

Returns:: the user's current presence, or unavailable presence if the user is offline or if no presence information is available..

Presence org.jivesoftware.smack.Roster.getPresenceResource ( String userWithResource )

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

Parameters:

userWithResource a fully qualified XMPP ID including a resource (user/resource).

Returns:: the user's current presence, or unavailable presence if the user is offline or if no presence information is available.

Iterator<Presence> org.jivesoftware.smack.Roster.getPresences ( String user )

Returns an iterator (of Presence objects) for all of a user's current presences or an unavailable presence 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 XMPP ID, e.g. jdoe@example.com.

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

SubscriptionMode org.jivesoftware.smack.Roster.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 SubscriptionMode#accept_all.

If using the manual mode, a PacketListener should be registered that listens for Presence packets that have a type of org.jivesoftware.smack.packet.Presence.Type#subscribe.

Returns:: the subscription mode.

Collection<RosterEntry> org.jivesoftware.smack.Roster.getUnfiledEntries ( )

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

Returns:: the unfiled roster entries.

int org.jivesoftware.smack.Roster.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.

void org.jivesoftware.smack.Roster.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.

Exceptions:

IllegalStateException if connection is not logged in or logged in anonymously

void org.jivesoftware.smack.Roster.removeEntry ( RosterEntry entry ) throws XMPPException

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. Note that this is an asynchronous call -- Smack must wait for the server to send an updated subscription status.

Parameters:

entry a roster entry.

Exceptions:

XMPPException	if an XMPP error occurs.
IllegalStateException	if connection is not logged in or logged in anonymously

void org.jivesoftware.smack.Roster.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.

static void org.jivesoftware.smack.Roster.setDefaultSubscriptionMode ( SubscriptionMode subscriptionMode ) [static]

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 SubscriptionMode#accept_all.

Parameters:

subscriptionMode the default subscription mode to use for new Rosters.

void org.jivesoftware.smack.Roster.setSubscriptionMode ( SubscriptionMode 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 SubscriptionMode#accept_all.

If using the manual mode, a PacketListener should be registered that listens for Presence packets that have a type of org.jivesoftware.smack.packet.Presence.Type#subscribe.

Parameters:

subscriptionMode the subscription mode.

Member Data Documentation

boolean org.jivesoftware.smack.Roster.rosterInitialized = false [package]

Classes

Public Types

Public Member Functions

Static Public Member Functions

Package Functions

Package Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation