public class Roster
extends java.lang.Object
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.XMPPConnection.getRoster()
Modifier and Type | Class and Description |
---|---|
static class |
Roster.SubscriptionMode
An enumeration for the subscription mode options.
|
Modifier and Type | Method and Description |
---|---|
void |
addRosterListener(RosterListener rosterListener)
Adds a listener to this roster.
|
boolean |
contains(java.lang.String user)
Returns true if the specified XMPP address is an entry in the roster.
|
void |
createEntry(java.lang.String user,
java.lang.String name,
java.lang.String[] groups)
Creates a new roster entry and presence subscription.
|
RosterGroup |
createGroup(java.lang.String name)
Creates a new group.
|
static Roster.SubscriptionMode |
getDefaultSubscriptionMode()
Returns the default subscription processing mode to use when a new Roster is created.
|
java.util.Collection<RosterEntry> |
getEntries()
Returns an unmodifiable collection of all entries in the roster, including entries
that don't belong to any groups.
|
RosterEntry |
getEntry(java.lang.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(java.lang.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.
|
java.util.Collection<RosterGroup> |
getGroups()
Returns an unmodifiable collections of all the roster groups.
|
Presence |
getPresence(java.lang.String user)
Returns the presence info for a particular user.
|
Presence |
getPresenceResource(java.lang.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.
|
java.util.List<Presence> |
getPresences(java.lang.String user)
Returns a List 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.
|
Roster.SubscriptionMode |
getSubscriptionMode()
Returns the subscription processing mode, which dictates what action
Smack will take when subscription requests from other users are made.
|
java.util.Collection<RosterEntry> |
getUnfiledEntries()
Returns an unmodifiable collection 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(Roster.SubscriptionMode subscriptionMode)
Sets the default subscription processing mode to use when a new Roster is created.
|
void |
setSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
Sets the subscription processing mode, which dictates what action
Smack will take when subscription requests from other users are made.
|
public static Roster.SubscriptionMode getDefaultSubscriptionMode()
Roster.SubscriptionMode.accept_all
.public static void setDefaultSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
Roster.SubscriptionMode.accept_all
.subscriptionMode
- the default subscription mode to use for new Rosters.public Roster.SubscriptionMode getSubscriptionMode()
Roster.SubscriptionMode.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
.public void setSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
Roster.SubscriptionMode.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
.subscriptionMode
- the subscription mode.public void reload() throws SmackException.NotLoggedInException, SmackException.NotConnectedException
SmackException.NotLoggedInException
- If not logged in.SmackException.NotConnectedException
public void addRosterListener(RosterListener rosterListener)
rosterListener
- a roster listener.public void removeRosterListener(RosterListener rosterListener)
rosterListener
- a roster listener.public RosterGroup createGroup(java.lang.String name)
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.
name
- the name of the group.java.lang.IllegalStateException
- if logged in anonymouslypublic void createEntry(java.lang.String user, java.lang.String name, java.lang.String[] groups) throws SmackException.NotLoggedInException, SmackException.NoResponseException, XMPPException.XMPPErrorException, SmackException.NotConnectedException
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.SmackException.NoResponseException
- if there was no response from the server.XMPPException.XMPPErrorException
- if an XMPP exception occurs.SmackException.NotLoggedInException
- If not logged in.SmackException.NotConnectedException
public void removeEntry(RosterEntry entry) throws SmackException.NotLoggedInException, SmackException.NoResponseException, XMPPException.XMPPErrorException, SmackException.NotConnectedException
entry
- a roster entry.XMPPException.XMPPErrorException
- if an XMPP error occurs.SmackException.NotLoggedInException
- if not logged in.SmackException.NoResponseException
- SmackException if there was no response from the server.SmackException.NotConnectedException
java.lang.IllegalStateException
- if connection is not logged in or logged in anonymouslypublic int getEntryCount()
public java.util.Collection<RosterEntry> getEntries()
public int getUnfiledEntryCount()
public java.util.Collection<RosterEntry> getUnfiledEntries()
public RosterEntry getEntry(java.lang.String user)
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").public boolean contains(java.lang.String user)
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").public RosterGroup getGroup(java.lang.String name)
name
- the name of the group.public int getGroupCount()
public java.util.Collection<RosterGroup> getGroups()
public Presence getPresence(java.lang.String user)
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
.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.public Presence getPresenceResource(java.lang.String userWithResource)
userWithResource
- a fully qualified XMPP ID including a resource (user@domain/resource).public java.util.List<Presence> getPresences(java.lang.String user)
user
- a XMPP ID, e.g. jdoe@example.com.