documentation/roster.html

   1 <html>
   2 <head>
   3         <title>Smack: Roster and Presence - Jive Software</title>
   4         <link rel="stylesheet" type="text/css" href="style.css" />
   5 </head>
   6
   7 <body>
   8
   9 <div class="header">
  10 Roster and Presence
  11 </div>
  12
  13 <div class="nav">
  14 &laquo; <a href="index.html">Table of Contents</a>
  15 </div>
  16
  17 <p>
  18
  19 The roster lets you keep track of the availability ("presence") of other users.
  20 A roster also allows you to organize users into groups such as "Friends" and
  21 "Co-workers". Other IM systems refer to the roster as the buddy list, contact list,
  22 etc.<p>
  23
  24 A <tt>Roster</tt> instance is obtained using the <tt>XMPPConnection.getRoster()</tt>
  25 method, but only after successfully logging into a server.
  26
  27 <p class="subheader">Roster Entries</p>
  28
  29 <p>
  30 Every user in a roster is represented by a RosterEntry, which consists of:<ul>
  31     <li>An XMPP address (e.g. jsmith@example.com).
  32     <li>A name you've assigned to the user (e.g. "Joe").
  33     <li>The list of groups in the roster that the entry belongs to. If the roster
  34         entry belongs to no groups, it's called an "unfiled entry".
  35 </ul>
  36
  37 The following code snippet prints all entries in the roster:
  38
  39 <pre>
  40 Roster roster = con.getRoster();
  41 <b>for</b> (Iterator i=roster.getEntries(); i.hasNext(); ) {
  42     System.out.println(i.next());
  43 }
  44 </pre>
  45
  46 Methods also exist to get individual entries, the list of unfiled entries, or to get one or
  47 all roster groups.
  48
  49 <p class="subheader">Presence</p>
  50
  51 <img src="images/roster.png" width="166" height="322" vspace="5" hspace="5" alt="Roster" border="0" align="right">
  52
  53 <p>Every entry in the roster has presence associated with it. The
  54 <tt>Roster.getPresence(String user)</tt> method will return a Presence object with
  55 the user's presence or <tt>null</tt> if the user is not online or you are not
  56 subscribed to the user's presence. <i>Note:</i> typically, presence
  57 subscription is always tied to the user being on the roster, but this is not
  58 true in all cases.</p>
  59
  60 <p>A user either has a presence of online or offline. When a user is online, their
  61 presence may contain extended information such as what they are currently doing, whether
  62 they wish to be disturbed, etc. See the Presence class for further details.</p>
  63
  64 <p class="subheader">Listening for Roster and Presence Changes</p>
  65
  66 <p>The typical use of the roster class is to display a tree view of groups and entries
  67 along with the current presence value of each entry. As an example, see the image showing
  68 a Roster in the Exodus XMPP client to the right.</p>
  69
  70 <p>The presence information will likely
  71 change often, and it's also possible for the roster entries to change or be deleted.
  72 To listen for changing roster and presence data, a RosterListener should be used.
  73 The following code snippet registers a RosterListener with the Roster that prints
  74 any presence changes in the roster to standard out. A normal client would use
  75 similar code to update the roster UI with the changing information.
  76
  77 <br clear="all">
  78
  79 <pre>
  80 final Roster roster = con.getRoster();
  81 roster.addRosterListener(new RosterListener() {
  82     <b>public void</b> rosterModified() {
  83         <font color="gray"><i>// Ignore event for this example.</i></font>
  84     }
  85
  86     <b>public void</b> presenceChanged(String user) {
  87         <font color="gray"><i>// If the presence is unavailable then "null" will be printed,
  88         // which is fine for this example.</i></font>
  89         System.out.println(<font color="green">"Presence changed: "</font> + roster.getPresence(user));
  90     }
  91 });
  92 </pre>
  93
  94 <p class="subheader">Adding Entries to the Roster</p>
  95
  96 <p>Rosters and presence use a permissions-based model where users must give permission before
  97 they are added to someone else's roster. This protects a user's privacy by
  98 making sure that only approved users are able to view their presence information.
  99 Therefore, when you add a new roster entry it will be in a pending state until
 100 the other user accepts your request.</p>
 101
 102 If another user requests a presence subscription so they can add you to their roster,
 103 you must accept or reject that request. Smack handles presence subscription requests
 104 in one of three ways: <ul>
 105
 106     <li> Automatically accept all presence subscription requests.
 107     <li> Automatically reject all presence subscription requests.
 108     <li> Process presence subscription requests manually.
 109 </ul>
 110
 111 The mode can be set using the <tt>Roster.setSubscriptionMode(int subscriptionMode)</tt>
 112 method. Simple clients normally use one of the automated subscription modes, while
 113 full-featured clients should manually process subscription requests and let the
 114 end-user accept or reject each request. If using the manual mode, a PacketListener
 115 should be registered that listens for Presence packets that have a type of
 116 <tt>Presence.Type.SUBSCRIBE</tt>.
 117
 118 <br clear="all" /><br><br>
 119
 120 <div class="footer">
 121 Copyright &copy; Jive Software 2002-2004
 122 </div>
 123
 124 </body>
 125 </html>