mirror of
https://github.com/vanitasvitae/Smack.git
synced 2025-09-09 00:59:39 +02:00
Migrate markdown documentation to javadoc
While markdown is easier to write, Smack's markdown documentation was never tightly coupled with the source. For example, the markdown documentation never provided links to the actual Java classes and methods. This poses the risk that the documentation and the code diverge over time. Furthermore, javadoc is constantly improving (for example @snippet annotations) and I expect that one will be able to write javadoc in markdown. Fixes SMACK-928.
This commit is contained in:
Florian Schmaus
parent
f65cf45b5c
commit
c9a9982cef
101 changed files with 4441 additions and 5754 deletions
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
*
|
||||
* Copyright 2003-2007 Jive Software, 2016-2021 Florian Schmaus.
|
||||
* Copyright 2003-2007 Jive Software, 2016-2022 Florian Schmaus.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
|
|
@ -78,15 +78,122 @@ import org.jxmpp.jid.parts.Resourcepart;
|
|||
import org.jxmpp.util.cache.LruCache;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* <p>
|
||||
* 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.
|
||||
* </p>
|
||||
* <p>
|
||||
* You can obtain a Roster instance for your connection via
|
||||
* {@link #getInstanceFor(XMPPConnection)}. A detailed description of the
|
||||
* protocol behind the Roster and Presence semantics can be found in
|
||||
* <a href="https://tools.ietf.org/html/rfc6121">RFC 6120</a>.
|
||||
* </p>
|
||||
*
|
||||
* Other users may attempt to subscribe to this user using a subscription request. Three
|
||||
* modes are supported for handling these requests: <ul>
|
||||
* <li>{@link SubscriptionMode#accept_all accept_all} -- accept all subscription requests.</li>
|
||||
* <li>{@link SubscriptionMode#reject_all reject_all} -- reject all subscription requests.</li>
|
||||
* <li>{@link SubscriptionMode#manual manual} -- manually process all subscription requests.</li>
|
||||
* <h2>Roster Entries</h2>
|
||||
* Every user in a roster is represented by a RosterEntry, which consists
|
||||
* of:
|
||||
* <ul>
|
||||
* <li>An XMPP address, aka. JID (e.g. jsmith@example.com).</li>
|
||||
* <li>A name you've assigned to the user (e.g. "Joe").</li>
|
||||
* <li>The list of groups in the roster that the entry belongs to. If the roster
|
||||
* entry belongs to no groups, it's called an "unfiled entry".</li>
|
||||
* </ul>
|
||||
* The following code snippet prints all entries in the roster:
|
||||
*
|
||||
* <pre>{@code
|
||||
* Roster roster = Roster.getInstanceFor(connection);
|
||||
* Collection<RosterEntry> entries = roster.getEntries();
|
||||
* for (RosterEntry entry : entries) {
|
||||
* System.out.println(entry);
|
||||
* }
|
||||
* }</pre>
|
||||
*
|
||||
* Methods also exist to get individual entries, the list of unfiled entries, or
|
||||
* to get one or all roster groups.
|
||||
*
|
||||
* <h2>Presence</h2>
|
||||
* <p>
|
||||
* Every entry in the roster has presence associated with it. The
|
||||
* {@link #getPresence(BareJid)} 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:_ Presence subscription is nnot tied to the
|
||||
* user being on the roster, and vice versa: You could be subscriped to a remote
|
||||
* users presence without the user in your roster, and a remote user can be in
|
||||
* your roster without any presence subscription relation.
|
||||
* </p>
|
||||
* <p>
|
||||
* 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.
|
||||
* </p>
|
||||
*
|
||||
* <h2>Listening for Roster and Presence Changes</h2>
|
||||
* <p>
|
||||
* 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.
|
||||
* </p>
|
||||
* <p>
|
||||
* 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. To be informed about all
|
||||
* changes to the roster the RosterListener should be registered before logging
|
||||
* into the XMPP server. 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.
|
||||
* </p>
|
||||
*
|
||||
* <pre>{@code
|
||||
* Roster roster = Roster.getInstanceFor(con);
|
||||
* roster.addRosterListener(new RosterListener() {
|
||||
* // Ignored events public void entriesAdded(Collection<String> addresses) {}
|
||||
* public void entriesDeleted(Collection<String> addresses) {
|
||||
* }
|
||||
*
|
||||
* public void entriesUpdated(Collection<String> addresses) {
|
||||
* }
|
||||
*
|
||||
* public void presenceChanged(Presence presence) {
|
||||
* System.out.println("Presence changed: " + presence.getFrom() + " " + presence);
|
||||
* }
|
||||
* });
|
||||
* }</pre>
|
||||
*
|
||||
* Note that in order to receive presence changed events you need to be
|
||||
* subscribed to the users presence. See the following section.
|
||||
*
|
||||
* <h2>Adding Entries to the Roster</h2>
|
||||
*
|
||||
* <p>
|
||||
* Rosters and presence use a permissions-based model where users must give
|
||||
* permission before someone else can see their presence. 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, you will
|
||||
* not see the presence information until the other user accepts your request.
|
||||
* </p>
|
||||
* <p>
|
||||
* If another user requests a presence subscription, you must accept or reject
|
||||
* that request. Smack handles presence subscription requests in one of three
|
||||
* ways:
|
||||
* </p>
|
||||
* <ul>
|
||||
* <li>Automatically accept all presence subscription requests
|
||||
* ({@link SubscriptionMode#accept_all accept_all})</li>
|
||||
* <li>Automatically reject all presence subscription requests
|
||||
* ({@link SubscriptionMode#reject_all reject_all})</li>
|
||||
* <li>Process presence subscription requests manually.
|
||||
* ({@link SubscriptionMode#manual manual})</li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* The mode can be set using {@link #setSubscriptionMode(SubscriptionMode)}.
|
||||
* Simple clients normally use one of the automated subscription modes, while
|
||||
* full-featured clients should manually process subscription requests and let
|
||||
* the end-user accept or reject each request.
|
||||
* </p>
|
||||
*
|
||||
* @author Matt Tucker
|
||||
* @see #getInstanceFor(XMPPConnection)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue