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 +1 @@
|
|||
../../../../../../../smack-extensions/src/main/java/org/jivesoftware/smackx/package-info.java
|
||||
../../../../../../../smack-java8-full/src/main/java/org/jivesoftware/smackx/package-info.java
|
||||
|
|
@ -16,6 +16,183 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* TODO describe me.
|
||||
* This extension is used to send rosters, roster groups and roster entries from one XMPP Entity to another. It also
|
||||
* provides an easy way to hook up custom logic when entries are received from other XMPP clients.
|
||||
* <p>
|
||||
* Follow these links to learn how to send and receive roster items:
|
||||
* </p>
|
||||
* <ul>
|
||||
* <li>Send a complete roster</li>
|
||||
* <li>Send a roster’s group</li>
|
||||
* <li>Send a roster’s entry</li>
|
||||
* <li>Receive roster entries</li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* <strong>XEP related:</strong> <a href="http://www.xmpp.org/extensions/xep-0093.html">XEP-93</a>
|
||||
* </p>
|
||||
* <h2 id="send-a-entire-roster">Send a entire roster</h2>
|
||||
* <p>
|
||||
* <strong>Description</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* Sometimes it is useful to send a whole roster to another user. Smack provides a very easy way to send a complete
|
||||
* roster to another XMPP client.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Usage</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* Create an instance of <em><strong>RosterExchangeManager</strong></em> and use the <strong>#send(Roster,
|
||||
* String)</strong> message to send a roster to a given user. The first parameter is the roster to send and the second
|
||||
* parameter is the id of the user that will receive the roster entries.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Example</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* In this example we can see how user1 sends his roster to user2.
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>XMPPConnection conn1 = …
|
||||
|
||||
// Create a new roster exchange manager on conn1
|
||||
RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
|
||||
// Send user1's roster to user2
|
||||
rosterExchangeManager.send(Roster.getInstanceFor(conn1), user2);</code>
|
||||
* </pre>
|
||||
*
|
||||
* <h2 id="send-a-roster-group">Send a roster group</h2>
|
||||
* <p>
|
||||
* <strong>Description</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* It is also possible to send a roster group to another XMPP client. A roster group groups a set of roster entries
|
||||
* under a name.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Usage</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* Create an instance of <em><strong>RosterExchangeManager</strong></em> and use the <strong>#send(RosterGroup,
|
||||
* String)</strong> message to send a roster group to a given user. The first parameter is the roster group to send and
|
||||
* the second parameter is the id of the user that will receive the roster entries.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Example</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* In this example we can see how user1 sends his roster groups to user2.
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* XMPPConnection conn1 = …
|
||||
* // Create a new roster exchange manager on conn1
|
||||
* RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
|
||||
* // Send user1's RosterGroups to user2
|
||||
* for (Iterator it = Roster.getInstanceFor(conn1).getGroups(); it.hasNext(); )
|
||||
* rosterExchangeManager.send((RosterGroup)it.next(), user2);
|
||||
* </code>
|
||||
* </pre>
|
||||
*
|
||||
* <h2 id="send-a-roster-entry">Send a roster entry</h2>
|
||||
* <p>
|
||||
* <strong>Description</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* Sometimes you may need to send a single roster entry to another XMPP client. Smack also lets you send items at this
|
||||
* granularity level.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Usage</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* Create an instance of <em><strong>RosterExchangeManager</strong></em> and use the <strong>#send(RosterEntry,
|
||||
* String)</strong> message to send a roster entry to a given user. The first parameter is the roster entry to send and
|
||||
* the second parameter is the id of the user that will receive the roster entries.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Example</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* In this example we can see how user1 sends a roster entry to user2.
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* XMPPConnection conn1 = …
|
||||
* // Create a new roster exchange manager on conn1
|
||||
* RosterExchangeManager rosterExchangeManager = new RosterExchangeManager(conn1);
|
||||
* // Send a roster entry (any) to user2
|
||||
* rosterExchangeManager1.send((RosterEntry)Roster.getInstanceFor(conn1).getEntries().next(), user2);</code>
|
||||
* </pre>
|
||||
*
|
||||
* <h2 id="receive-roster-entries">Receive roster entries</h2>
|
||||
* <p>
|
||||
* <strong>Description</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* Since roster items are sent between XMPP clients, it is necessary to listen to possible roster entries receptions.
|
||||
* Smack provides a mechanism that you can use to execute custom logic when roster entries are received.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Usage</strong>
|
||||
* </p>
|
||||
* <ol type="1">
|
||||
* <li>Create a class that implements the <em><strong>RosterExchangeListener</strong></em> interface.</li>
|
||||
* <li>Implement the method <strong>entriesReceived(String, Iterator)</strong> that will be called when new entries are
|
||||
* received with custom logic.</li>
|
||||
* <li>Add the listener to the <em>RosterExchangeManager</em> that works on the desired <em>XMPPConnection</em>.</li>
|
||||
* </ol>
|
||||
* <p>
|
||||
* <strong>Example</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* In this example we can see how user1 sends a roster entry to user2 and user2 adds the received entries to his roster.
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* // Connect to the server and log in the users
|
||||
* XMPPConnection conn1 = …
|
||||
* XMPPConnection conn2 = …
|
||||
*
|
||||
* final Roster user2_roster = Roster.getInstanceFor(conn2);
|
||||
*
|
||||
* // Create a RosterExchangeManager that will help user2 to listen and accept
|
||||
* the entries received
|
||||
* RosterExchangeManager rosterExchangeManager2 = new RosterExchangeManager(conn2);
|
||||
* // Create a RosterExchangeListener that will iterate over the received roster entries
|
||||
* RosterExchangeListener rosterExchangeListener = new RosterExchangeListener() {
|
||||
* public void entriesReceived(String from, Iterator remoteRosterEntries) {
|
||||
* while (remoteRosterEntries.hasNext()) {
|
||||
* try {
|
||||
* // Get the received entry
|
||||
* RemoteRosterEntry remoteRosterEntry = (RemoteRosterEntry) remoteRosterEntries.next();
|
||||
* // Display the remote entry on the console
|
||||
* System.out.println(remoteRosterEntry);
|
||||
* // Add the entry to the user2's roster
|
||||
* user2_roster.createEntry(
|
||||
* remoteRosterEntry.getUser(),
|
||||
* remoteRosterEntry.getName(),
|
||||
* remoteRosterEntry.getGroupArrayNames());
|
||||
* }
|
||||
* catch (XMPPException e) {
|
||||
* e.printStackTrace();
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* };
|
||||
* // Add the RosterExchangeListener to the RosterExchangeManager that user2 is using
|
||||
* rosterExchangeManager2.addRosterListener(rosterExchangeListener);
|
||||
*
|
||||
* // Create a RosterExchangeManager that will help user1 to send his roster
|
||||
* RosterExchangeManager rosterExchangeManager1 = new RosterExchangeManager(conn1);
|
||||
* // Send user1's roster to user2
|
||||
* rosterExchangeManager1.send(Roster.getInstanceFor(conn1), user2);
|
||||
* </code>
|
||||
* </pre>
|
||||
* @see <a href="https://xmpp.org/extensions/xep-0093.html">XEP-0093: Roster Item Exchange</a>
|
||||
*/
|
||||
package org.jivesoftware.smackx.xroster;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue