-The roster lets you keep track of the availability (presence) of other users. Users -can be organized into groups such as "Friends" and "Co-workers", and then you -discover whether each user is online or offline.
+The roster lets you keep track of the availability ("presence") of other users. +A roster also allows you to organize users into groups such as "Friends" and +"Co-workers". Other IM systems refer to the roster as the buddy list, contact list, +etc.
A Roster instance is obtained using the XMPPConnection.getRoster() -method, but only after +method, but only after successfully logging into a server. + +
Roster Entries
+ ++Every user in a roster is represented by a RosterEntry, which consists of:
+Roster roster = con.getRoster();
+for (Iterator i=roster.getEntries(); i.hasNext(); ) {
+ System.out.println(i.next());
+}
+
+
+Methods also exist to get individual entries, the list of unfiled entries, or to get one or
+all roster groups.
+
+Presence
+ +
+
+Every entry in the roster has presence associated with it. The +Roster.getPresence(String user) method will return a Presence object with +the user's presence or null if the user is not online or you are not +subscribed to the user's presence. Note: typically, presence +subscription is always tied to the user being on the roster, but this is not +true in all cases.
+ +A user either has a presence of online or offline. When a user is online, their +presence may contain extended information such as what they are currently doing, whether +they wish to be disturbed, etc. See the Presence class for further details.
+ +Listening for Roster and Presence Changes
+ +The typical use of the roster class is to display a tree view of groups and entries +along with the current presence value of each entry. As an example, see the image showing +a Roster in the Exodus XMPP client to the right.
+ +The presence information will likely
+change often, and it's also possible for the roster entries to change or be deleted.
+To listen for changing roster and presence data, a RosterListener should be used.
+The following code snippet registers a RosterListener with the Roster that prints
+any presence changes in the roster to standard out. A normal client would use
+similar code to update the roster UI with the changing information.
+
+
+
+
+final Roster roster = con.getRoster();
+roster.addRosterListener(new RosterListener() {
+ public void rosterModified() {
+ // Ignore event for this example.
+ }
+
+ public void presenceChanged(String user) {
+ // If the presence is unavailable then "null" will be printed,
+ // which is fine for this example.
+ System.out.println("Presence changed: " + roster.getPresence(user));
+ }
+});
+
+
+Adding Entries to the Roster
+ +Rosters and presence use a permissions-based model where users must give permission before +they are added to someone else's roster. This protects a user's privacy by +making sure that only approved users are able to view their presence information. +Therefore, when you add a new roster entry it will be in a pending state until +the other user accepts your request.
+ +If another user requests a presence subscription so they can add you to their roster, +you must accept or reject that request. Smack handles presence subscription requests +in one of three ways: