public final class Roster extends Manager
accept_all
-- accept all subscription requests.reject_all
-- reject all subscription requests.manual
-- manually process all subscription requests.getInstanceFor(XMPPConnection)
Modifier and Type | Class and Description |
---|---|
static class |
Roster.SubscriptionMode
An enumeration for the subscription mode options.
|
Modifier and Type | Field and Description |
---|---|
static int |
INITIAL_DEFAULT_NON_ROSTER_PRESENCE_MAP_SIZE
The initial maximum size of the map holding presence information of entities without an Roster entry.
|
Modifier and Type | Method and Description |
---|---|
boolean |
addPresenceEventListener(PresenceEventListener presenceEventListener) |
boolean |
addRosterListener(RosterListener rosterListener)
Adds a listener to this roster.
|
boolean |
addRosterLoadedListener(RosterLoadedListener rosterLoadedListener)
Add a roster loaded listener.
|
boolean |
addSubscribeListener(SubscribeListener subscribeListener)
Add a subscribe listener, which is invoked on incoming subscription requests and if
Roster.SubscriptionMode is set to Roster.SubscriptionMode.manual . |
boolean |
contains(BareJid jid)
Returns true if the specified XMPP address is an entry in the roster.
|
void |
createEntry(BareJid 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.
|
java.util.List<Presence> |
getAllPresences(BareJid bareJid)
Returns a List of Presence objects for all of a user's current presences if no presence information is available,
such as when you are not subscribed to the user's presence updates.
|
java.util.List<Presence> |
getAvailablePresences(BareJid bareJid)
Returns a List of all available Presence Objects for the given bare JID.
|
static Roster.SubscriptionMode |
getDefaultSubscriptionMode()
Returns the default subscription processing mode to use when a new Roster is created.
|
java.util.Set<RosterEntry> |
getEntries()
Returns a set of all entries in the roster, including entries
that don't belong to any groups.
|
void |
getEntriesAndAddListener(RosterListener rosterListener,
RosterEntries rosterEntries)
Add a roster listener and invoke the roster entries with all entries of the roster.
|
RosterEntry |
getEntry(BareJid jid)
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.
|
static Roster |
getInstanceFor(XMPPConnection connection)
Returns the roster for the user.
|
Presence |
getPresence(BareJid jid)
Returns the presence info for a particular user.
|
Presence |
getPresenceResource(FullJid 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(BareJid jid)
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.Set<RosterEntry> |
getUnfiledEntries()
Returns an unmodifiable set for the unfiled roster entries.
|
int |
getUnfiledEntryCount()
Returns a count of the unfiled entries in the roster.
|
boolean |
iAmSubscribedTo(Jid jid)
Check if the XMPP entity this roster belongs to is subscribed to the presence of the given JID.
|
boolean |
isLoaded()
Check if the roster is loaded.
|
boolean |
isRosterLoadedAtLogin()
Returns true if the roster will be loaded from the server when logging in.
|
boolean |
isRosterVersioningSupported()
Check if the server supports roster versioning.
|
boolean |
isSubscribedToMyPresence(Jid jid)
Check if the given JID is subscribed to the user's presence.
|
boolean |
isSubscriptionPreApprovalSupported()
Check for subscription pre-approval support.
|
void |
preApprove(BareJid user)
Pre-approve user presence subscription.
|
void |
preApproveAndCreateEntry(BareJid user,
java.lang.String name,
java.lang.String[] groups)
Creates a new pre-approved roster entry and presence subscription.
|
void |
reload()
Reloads the entire roster from the server.
|
void |
reloadAndWait()
Reload the roster and block until it is reloaded.
|
void |
removeEntry(RosterEntry entry)
Removes a roster entry from the roster.
|
boolean |
removePresenceEventListener(PresenceEventListener presenceEventListener) |
boolean |
removeRosterListener(RosterListener rosterListener)
Removes a listener from this roster.
|
boolean |
removeRosterLoadedListener(RosterLoadedListener rosterLoadedListener)
Remove a roster loaded listener.
|
boolean |
removeSubscribeListener(SubscribeListener subscribeListener)
Remove a subscribe listener.
|
void |
sendSubscriptionRequest(BareJid jid) |
static void |
setDefaultNonRosterPresenceMapMaxSize(int maximumSize)
Set the default maximum size of the non-Roster presence map.
|
static void |
setDefaultSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
Sets the default subscription processing mode to use when a new Roster is created.
|
void |
setNonRosterPresenceMapMaxSize(int maximumSize)
Set the maximum size of the non-Roster presence map.
|
void |
setRosterLoadedAtLogin(boolean rosterLoadedAtLogin)
Sets if the roster will be loaded from the server when logging in.
|
static void |
setRosterLoadedAtLoginDefault(boolean rosterLoadedAtLoginDefault)
Sets if the roster will be loaded from the server when logging in for newly created instances
of
Roster . |
boolean |
setRosterStore(RosterStore rosterStore)
Set the roster store, may cause a roster reload.
|
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.
|
protected boolean |
waitUntilLoaded() |
connection, getAuthenticatedConnectionOrThrow
public static final int INITIAL_DEFAULT_NON_ROSTER_PRESENCE_MAP_SIZE
public static Roster getInstanceFor(XMPPConnection connection)
This method will never return null
, instead if the user has not yet logged into
the server all modifying methods of the returned roster object
like createEntry(BareJid, String, String[])
,
removeEntry(RosterEntry)
, etc. except adding or removing
RosterListener
s will throw an IllegalStateException.
connection
- the connection the roster should be retrieved for.public static Roster.SubscriptionMode getDefaultSubscriptionMode()
Roster.SubscriptionMode.reject_all
.public static void setDefaultSubscriptionMode(Roster.SubscriptionMode subscriptionMode)
Roster.SubscriptionMode.reject_all
.subscriptionMode
- the default subscription mode to use for new Rosters.public Roster.SubscriptionMode getSubscriptionMode()
Roster.SubscriptionMode.reject_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.reject_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, java.lang.InterruptedException
SmackException.NotLoggedInException
- If not logged in.SmackException.NotConnectedException
java.lang.InterruptedException
public void reloadAndWait() throws SmackException.NotLoggedInException, SmackException.NotConnectedException, java.lang.InterruptedException
SmackException.NotLoggedInException
SmackException.NotConnectedException
java.lang.InterruptedException
public boolean setRosterStore(RosterStore rosterStore)
rosterStore
- protected boolean waitUntilLoaded() throws java.lang.InterruptedException
java.lang.InterruptedException
public boolean isLoaded()
public boolean addRosterListener(RosterListener rosterListener)
rosterListener
- a roster listener.getEntriesAndAddListener(RosterListener, RosterEntries)
public boolean removeRosterListener(RosterListener rosterListener)
rosterListener
- a roster listener.public boolean addRosterLoadedListener(RosterLoadedListener rosterLoadedListener)
rosterLoadedListener
- the listener to add.RosterLoadedListener
public boolean removeRosterLoadedListener(RosterLoadedListener rosterLoadedListener)
rosterLoadedListener
- the listener to remove.RosterLoadedListener
public boolean addPresenceEventListener(PresenceEventListener presenceEventListener)
public boolean removePresenceEventListener(PresenceEventListener presenceEventListener)
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.public void createEntry(BareJid user, java.lang.String name, java.lang.String[] groups) throws SmackException.NotLoggedInException, SmackException.NoResponseException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, java.lang.InterruptedException
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
java.lang.InterruptedException
public void preApproveAndCreateEntry(BareJid user, java.lang.String name, java.lang.String[] groups) throws SmackException.NotLoggedInException, SmackException.NoResponseException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, java.lang.InterruptedException, SmackException.FeatureNotSupportedException
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
java.lang.InterruptedException
SmackException.FeatureNotSupportedException
- if pre-approving is not supported.public void preApprove(BareJid user) throws SmackException.NotLoggedInException, SmackException.NotConnectedException, java.lang.InterruptedException, SmackException.FeatureNotSupportedException
user
- the user. (e.g. johndoe@jabber.org)SmackException.NotLoggedInException
- if not logged in.SmackException.NotConnectedException
java.lang.InterruptedException
SmackException.FeatureNotSupportedException
- if pre-approving is not supported.public boolean isSubscriptionPreApprovalSupported() throws SmackException.NotLoggedInException
SmackException.NotLoggedInException
- if not logged in.public void sendSubscriptionRequest(BareJid jid) throws SmackException.NotLoggedInException, SmackException.NotConnectedException, java.lang.InterruptedException
SmackException.NotLoggedInException
SmackException.NotConnectedException
java.lang.InterruptedException
public boolean addSubscribeListener(SubscribeListener subscribeListener)
Roster.SubscriptionMode
is set to Roster.SubscriptionMode.manual
. This also sets subscription
mode to Roster.SubscriptionMode.manual
.subscribeListener
- the subscribe listener to add.true
if the listener was not already added.public boolean removeSubscribeListener(SubscribeListener subscribeListener)
subscribeListener
- the subscribe listener to remove.true
if the listener registered and got removed.public void removeEntry(RosterEntry entry) throws SmackException.NotLoggedInException, SmackException.NoResponseException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, java.lang.InterruptedException
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.InterruptedException
public int getEntryCount()
public void getEntriesAndAddListener(RosterListener rosterListener, RosterEntries rosterEntries)
The method guarantees that the listener is only invoked after
RosterEntries.rosterEntries(Collection)
has been invoked, and that all roster events
that happen while rosterEntries(Collection)
is called are queued until the
method returns.
This guarantee makes this the ideal method to e.g. populate a UI element with the roster while
installing a RosterListener
to listen for subsequent roster events.
rosterListener
- the listener to installrosterEntries
- the roster entries callback interfacepublic java.util.Set<RosterEntry> getEntries()
public int getUnfiledEntryCount()
public java.util.Set<RosterEntry> getUnfiledEntries()
public RosterEntry getEntry(BareJid jid)
jid
- 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(BareJid jid)
jid
- the XMPP address of the user (eg "jsmith@example.com"). The
address must be a bare JID e.g. "domain/resource" or
"user@domain".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(BareJid jid)
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
.
jid
- the XMPP address of the user (eg "jsmith@example.com"). The
address must be a bare JID e.g. "domain/resource" or
"user@domain".public Presence getPresenceResource(FullJid userWithResource)
userWithResource
- a fully qualified XMPP ID including a resource (user@domain/resource).public java.util.List<Presence> getAllPresences(BareJid bareJid)
bareJid
- an XMPP ID, e.g. jdoe@example.com.public java.util.List<Presence> getAvailablePresences(BareJid bareJid)
bareJid
- the bare JID from which the presences should be retrieved.public java.util.List<Presence> getPresences(BareJid jid)
jid
- an XMPP ID, e.g. jdoe@example.com.public boolean isSubscribedToMyPresence(Jid jid)
If the JID is subscribed to the user's presence then it is allowed to see the presence and will get notified about presence changes. Also returns true, if the JID is the service name of the XMPP connection (the "XMPP domain"), i.e. the XMPP service is treated like having an implicit subscription to the users presence.
Note that if the roster is not loaded, then this method will always return false.jid
- public boolean iAmSubscribedTo(Jid jid)
jid
- the jid to check.true
if we are subscribed to the presence of the given jid.public static void setRosterLoadedAtLoginDefault(boolean rosterLoadedAtLoginDefault)
Roster
.rosterLoadedAtLoginDefault
- if the roster will be loaded from the server when logging in.setRosterLoadedAtLogin(boolean)
public void setRosterLoadedAtLogin(boolean rosterLoadedAtLogin)
rosterLoadedAtLogin
- if the roster will be loaded from the server when logging in.public boolean isRosterLoadedAtLogin()
public boolean isRosterVersioningSupported()
public static void setDefaultNonRosterPresenceMapMaxSize(int maximumSize)
The roster will only store this many presence entries for entities non in the Roster. The default is 1024.
maximumSize
- the maximum sizepublic void setNonRosterPresenceMapMaxSize(int maximumSize)
maximumSize
- setDefaultNonRosterPresenceMapMaxSize(int)