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
|
|
@ -22,7 +22,19 @@ import org.jivesoftware.smack.util.SHA1;
|
|||
import org.hsluv.HUSLColorConverter;
|
||||
|
||||
/**
|
||||
* Implementation of XEP-0392: Consistent Color Generation version 0.6.0.
|
||||
* Smack API for Consistent Color Generation (XEP-0392).
|
||||
* <p>
|
||||
* Since XMPP can be used on multiple platforms at the same time, it might be a
|
||||
* good idea to render given Strings like nicknames in the same color on all
|
||||
* platforms to provide a consistent user experience.
|
||||
* </p>
|
||||
* <h2>Usage</h2>
|
||||
*
|
||||
* <h2>Color Deficiency Corrections</h2>
|
||||
* <p>
|
||||
* Some users might suffer from color vision deficiencies. To compensate those
|
||||
* deficiencies, the API allows for color correction.
|
||||
* </p>
|
||||
*
|
||||
* @author Paul Schaub
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -17,5 +17,122 @@
|
|||
|
||||
/**
|
||||
* Smack's API for XEP-0332: HTTP over XMPP transport.
|
||||
* <h2 id="discover-hoxt-support">Discover HOXT support</h2>
|
||||
* <p>
|
||||
* <strong>Description</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* Before using this extension you must ensure that your counterpart supports it also.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Usage</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* Once you have your <em><strong>ServiceDiscoveryManager</strong></em> you will be able to discover information
|
||||
* associated with an XMPP entity. To discover the information of a given XMPP entity send
|
||||
* <strong>discoverInfo(entityID)</strong> to your <em><strong>ServiceDiscoveryManager</strong></em> where entityID is
|
||||
* the ID of the entity. The message <strong>discoverInfo(entityID)</strong> will answer with an instance of
|
||||
* <em><strong>DiscoverInfo</strong></em> that contains the discovered information.
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Examples</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* In this example we can see how to check if the counterpart supports HOXT:
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>// Obtain the ServiceDiscoveryManager associated with my XMPPConnection
|
||||
* ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);
|
||||
* // Get the information of a given XMPP entity, where entityID is a Jid
|
||||
* DiscoverInfo discoInfo = discoManager.discoverInfo(entityID);
|
||||
* // Check if room is HOXT is supported
|
||||
* boolean isSupported = discoInfo.containsFeature("urn:xmpp:http");</code>
|
||||
* </pre>
|
||||
*
|
||||
* <h2 id="iq-exchange">IQ exchange</h2>
|
||||
* <p>
|
||||
* <strong>Description</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* You can use IQ’s to perform HTTP requests and responses. This is applicable to relatively short requests and
|
||||
* responses (due to the limitation of XMPP message size).
|
||||
* </p>
|
||||
* <p>
|
||||
* <strong>Usage</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* First you need to register a <em><strong>StanzaListener</strong></em> to be able to handle intended IQs.
|
||||
* </p>
|
||||
* <p>
|
||||
* For the HTTP client you:
|
||||
* </p>
|
||||
* <ul>
|
||||
* <li>You create and send <em><strong>HttpOverXmppReq</strong></em> request.</li>
|
||||
* <li>Then you handle the <em><strong>HttpOverXmppResp</strong></em> response in your
|
||||
* <em><strong>StanzaListener</strong></em>.</li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* For the HTTP server you:
|
||||
* </p>
|
||||
* <ul>
|
||||
* <li>You handle the <em><strong>HttpOverXmppReq</strong></em> requests in your
|
||||
* <em><strong>StanzaListener</strong></em>.</li>
|
||||
* <li>And create and send <em><strong>HttpOverXmppResp</strong></em> responses.</li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* <strong>Examples</strong>
|
||||
* </p>
|
||||
* <p>
|
||||
* In this example we are an HTTP client, so we send a request (POST) and handle the response:
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* // create a request body
|
||||
* String urlEncodedMessage = "I_love_you";
|
||||
*
|
||||
* // prepare headers
|
||||
* List<Header> headers = new ArrayList<>();
|
||||
* headers.add(new Header("Host", "juliet.capulet.com"));
|
||||
* headers.add(new Header("Content-Type", "application/x-www-form-urlencoded"));
|
||||
* headers.add(new Header("Content-Length", Integer.toString(urlEncodedMessage.length())));
|
||||
*
|
||||
* // provide body or request (not mandatory, - empty body is used for GET)
|
||||
* AbstractHttpOverXmpp.Text child = new AbstractHttpOverXmpp.Text(urlEncodedMessage);
|
||||
* AbstractHttpOverXmpp.Data data = new AbstractHttpOverXmpp.Data(child);
|
||||
*
|
||||
* // create request
|
||||
* HttpOverXmppReq req = HttpOverXmppReq.buider()
|
||||
* .setMethod(HttpMethod.POST)
|
||||
* .setResource("/mailbox")
|
||||
* .setHeaders(headers)
|
||||
* .setVersion("1.1")
|
||||
* .setData(data)
|
||||
* .build();
|
||||
*
|
||||
* // add to, where jid is the Jid of the individual the packet is sent to
|
||||
* req.setTo(jid);
|
||||
*
|
||||
* // send it
|
||||
* connection.sendIqWithResponseCallback(req, new StanzaListener() {
|
||||
* public void processStanza(Stanza iq) {
|
||||
* HttpOverXmppResp resp = (HttpOverXmppResp) iq;
|
||||
* // check HTTP response code
|
||||
* if (resp.getStatusCode() == 200) {
|
||||
* // get content of the response
|
||||
* NamedElement child = resp.getData().getChild();
|
||||
* // check which type of content of the response arrived
|
||||
* if (child instanceof AbstractHttpOverXmpp.Xml) {
|
||||
* // print the message and anxiously read if from the console ;)
|
||||
* System.out.println(((AbstractHttpOverXmpp.Xml) child).getText());
|
||||
* } else {
|
||||
* // process other AbstractHttpOverXmpp data child subtypes
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* });
|
||||
* </code>
|
||||
* </pre>
|
||||
*/
|
||||
package org.jivesoftware.smackx.hoxt;
|
||||
|
|
|
|||
|
|
@ -16,6 +16,167 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* Smack's API for XMPP IoT.
|
||||
* Smack's API for XMPP IoT (XEP-0323, -0324, -0325, -0347).
|
||||
* <p>
|
||||
* The Internet of Things (IoT) XEPs are an experimental open standard how XMPP
|
||||
* can be used for IoT. They currently consists of
|
||||
* </p>
|
||||
* <ul>
|
||||
* <li>XEP-0323 Sensor Data</li>
|
||||
* <li>XEP-0324 Provisioning</li>
|
||||
* <li>XEP-0325 Control</li>
|
||||
* <li>XEP-0326 Concentrators</li>
|
||||
* <li>XEP-0347 Discovery</li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* Smack only supports a subset of the functionality described by the XEPs!
|
||||
* </p>
|
||||
* <h2>Thing Builder</h2>
|
||||
* <p>
|
||||
* The {@link org.jivesoftware.smackx.iot.Thing} class acts as basic entity
|
||||
* representing a single "Thing" which can be used to retrieve data from or to
|
||||
* send control commands to. `Things` are constructed using a builder API.
|
||||
* </p>
|
||||
* <h2>Reading data from things</h2>
|
||||
* <p>
|
||||
* For example, we can build a Thing which provides the current temperature with
|
||||
* </p>
|
||||
*
|
||||
* <pre><code>
|
||||
* Thing dataThing = Thing.builder().setKey(key).setSerialNumber(sn).setMomentaryReadOutRequestHandler(new ThingMomentaryReadOutRequest() {
|
||||
* {@literal @}Override
|
||||
* public void momentaryReadOutRequest(ThingMomentaryReadOutResult callback) {
|
||||
* int temp = getCurrentTemperature();
|
||||
* IoTDataField.IntField field = new IntField("temperature", temp);
|
||||
* callback.momentaryReadOut(Collections.singletonList(field));
|
||||
* }
|
||||
* }).build();
|
||||
* </code></pre>
|
||||
* <p>
|
||||
* While not strictly required, most things are identified via a key and serial
|
||||
* number. We also build the thing with a "momentary read out request handler"
|
||||
* which when triggered, retrieves the current temperature and reports it back
|
||||
* to the requestor.
|
||||
* </p>
|
||||
* <p>
|
||||
* After the `Thing` is built, it needs to be made available so that other
|
||||
* entities within the federated XMPP network can use it. Right now we only
|
||||
* install the Thing in the `IoTDataManager`, which means the thing will act on
|
||||
* read out requests but not be managed by a provisioning server.
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* IoTDataManager iotDataManager = IoTDataManager.getInstanceFor(connection);
|
||||
* iotDataManager.installThing(thing);
|
||||
* </code>
|
||||
* </pre>
|
||||
* <p>
|
||||
* The data can be read out also by using the <code>IoTDataManager</code>:
|
||||
* </p>
|
||||
*
|
||||
* <pre>{@code
|
||||
* FullJid jid = …
|
||||
* List<IoTFieldsExtension> values = iotDataManager.requestMomentaryValuesReadOut(jid);
|
||||
* }</pre>
|
||||
* <p>
|
||||
* Now you have to unwrap the `IoTDataField` instances from the
|
||||
* `IoTFieldsExtension`. Note that Smack currently only supports a subset of the
|
||||
* specified data types.
|
||||
* </p>
|
||||
* <h2>Controlling a thing</h2>
|
||||
* <p>
|
||||
* Things can also be controlled, e.g. to turn on a light. Let's create a thing
|
||||
* which can be used to turn the light on and off.
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* Thing controlThing = Thing.builder().setKey(key).setSerialNumber(sn).setControlRequestHandler(new ThingControlRequest() {
|
||||
* {@literal @}Override
|
||||
* public void processRequest(Jid from, Collection<SetData>} setData) throws XMPPErrorException {
|
||||
* for (final SetData data : setData) {
|
||||
* if (!data.getName().equals("light")) continue;
|
||||
* if (!(data instanceof SetBoolData)) continue;
|
||||
* SetBoolData boolData = (SetBoolData) data;
|
||||
* setLight(boolData.getBooleanValue());
|
||||
* }
|
||||
* }
|
||||
* }).build();
|
||||
* </code>
|
||||
* </pre>
|
||||
* <p>
|
||||
* Now we have to install this thing into the `IoTControlManager`:
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* IoTControlManager iotControlManager = IoTControlManager.getInstanceFor(connection);
|
||||
* iotControlManager.installThing(thing);
|
||||
* </code>
|
||||
* </pre>
|
||||
* <p>
|
||||
* The `IoTControlManager` can also be used to control a thing:
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* FullJid jid = …
|
||||
* SetData setData = new SetBoolData("light", true);
|
||||
* iotControlManager.setUsingIq(jid, setData);
|
||||
* </code>
|
||||
* </pre>
|
||||
* <p>
|
||||
* Smack currently only supports a subset of the possible data types for set
|
||||
* data.
|
||||
* </p>
|
||||
* <h2>Discovery</h2>
|
||||
* <p>
|
||||
* You may have wondered how a full JIDs of things can be determined. One
|
||||
* approach is using the discovery mechanisms specified in XEP-0347. Smack
|
||||
* provides the `IoTDiscoveryManager` as an API for this.
|
||||
* </p>
|
||||
* <p>
|
||||
* For example, instead of just installing the previous things in the
|
||||
* `IoTDataManager` and/or `IoTControlManager`, we could also use the
|
||||
* `IoTDiscoveryManger` to register the thing with a registry. Doing this also
|
||||
* installs the thing in the `IoTDataManager` and the `IoTControlManager`.
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* IoTDiscoveryManager iotDiscoveryManager = IoTDiscoveryManager.getInstanceFor(connection);
|
||||
* iotDiscovyerManager.registerThing(thing);
|
||||
* </code>
|
||||
* </pre>
|
||||
* <p>
|
||||
* The registry will now make the thing known to a broader audience, and
|
||||
* available for a potential owner.
|
||||
* </p>
|
||||
* <p>
|
||||
* The `IoTDiscoveryManager` can also be used to claim, disown, remove and
|
||||
* unregister a thing.
|
||||
* </p>
|
||||
* <h2>Provisioning</h2>
|
||||
* <p>
|
||||
* Things can usually only be used by other things if they are friends. Since a
|
||||
* thing normally can't decide on its own if an incoming friendship request
|
||||
* should be granted or not, we can delegate this decision to a provisioning
|
||||
* service. Smack provides the `IoTProvisinoManager` to deal with friendship and
|
||||
* provisioning.
|
||||
* </p>
|
||||
* <p>
|
||||
* For example, if you want to befriend another thing:
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* BareJid jid = …
|
||||
* IoTProvisioningManager iotProvisioningManager = IoTProvisioningManager.getInstanceFor(connection);
|
||||
* iotProvisioningManager.sendFriendshipRequest(jid);
|
||||
* </code>
|
||||
* </pre>
|
||||
*
|
||||
*
|
||||
*/
|
||||
package org.jivesoftware.smackx.iot;
|
||||
|
|
|
|||
|
|
@ -16,10 +16,89 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* XEP-0394: Message Markup.
|
||||
* Smack's API for XEP-0394: Message Markup, which can be used to style message. Message Markup is an alternative to
|
||||
* XHTML-im to style message, which keeps the message body and the markup information strictly separated.
|
||||
* <h2>Usage</h2>
|
||||
* <p>
|
||||
* The most important class is the {@link org.jivesoftware.smackx.message_markup.element.MarkupElement} class, which
|
||||
* contains a Builder to construct message markup..
|
||||
* </p>
|
||||
* <p>
|
||||
* To start creating a Message Markup Extension, call
|
||||
* {@link org.jivesoftware.smackx.message_markup.element.MarkupElement#getBuilder}. (Almost) all method calls documented
|
||||
* below will be made on the builder.
|
||||
* </p>
|
||||
* <p>
|
||||
* Whenever a method call receives a `start` and `end` index, `start` represents the first character, which is affected
|
||||
* by the styling, while `end` is the character *after* the last affected character.
|
||||
* </p>
|
||||
* <h2>Inline styling</h2>
|
||||
* <p>
|
||||
* Currently there are 3 styles available:
|
||||
* <ul>
|
||||
* <li>*emphasis*, which should be rendered by a client as *italic*, or **bold**</li>
|
||||
* <li>*code*, which should be rendered in `monospace`</li>
|
||||
* <li>*deleted*, which should be rendered as ~~strikethrough~~.</li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* Those styles are available by calling `builder.setEmphasis(int start, int end)`, `builder.setDeleted(int start, int
|
||||
* end)` and `builder.setCode(int start, int end)`.
|
||||
* </p>
|
||||
* <p>
|
||||
* If you want to apply multiple inline styles to a section, you can do the following:
|
||||
* </p>
|
||||
*
|
||||
* @see <a href="http://xmpp.org/extensions/xep-0394.html">XEP-0394: Message
|
||||
* Markup</a>
|
||||
* <pre>
|
||||
* {@code
|
||||
* Set<SpanElement.SpanStyle> spanStyles = new HashSet<>();
|
||||
* styles.add(SpanElement.SpanStyle.emphasis);
|
||||
* styles.add(SpanElement.SpanStyle.deleted);
|
||||
* builder.addSpan(start, end, spanStyles);
|
||||
* }
|
||||
* </pre>
|
||||
* <p>
|
||||
* Note, that spans cannot overlap one another.
|
||||
* </p>
|
||||
* <h2 id="block-level-styling">Block Level Styling</h2>
|
||||
* <p>
|
||||
* Available block level styles are: * Code blocks, which should be rendered as
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>blocks
|
||||
* of
|
||||
* code</code>
|
||||
* </pre>
|
||||
* <ul>
|
||||
* <li>Itemized lists, which should render as
|
||||
* <ul>
|
||||
* <li>Lists</li>
|
||||
* <li>with possibly multiple</li>
|
||||
* <li>entries</li>
|
||||
* </ul>
|
||||
* </li>
|
||||
* <li>Block Quotes, which should be rendered by the client > as quotes, which >> also can be nested</li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* To mark a section as code block, call <code>builder.setCodeBlock(start, end)</code>.
|
||||
* </p>
|
||||
* <p>
|
||||
* To create a list, call <code>MarkupElement.Builder.ListBuilder lbuilder = builder.beginList()</code>, which will
|
||||
* return a list builder. On this you can call <code>lbuilder.addEntry(start, end)</code> to add an entry.
|
||||
* </p>
|
||||
* <p>
|
||||
* Note: If you add an entry, the start value MUST be equal to the end value of the previous added entry!
|
||||
* </p>
|
||||
* <p>
|
||||
* To end the list, call <code>lbuilder.endList()</code>, which will return the MessageElement builder.
|
||||
* </p>
|
||||
* <p>
|
||||
* To create a block quote, call <code>builder.setBlockQuote(start, end)</code>.
|
||||
* </p>
|
||||
* <p>
|
||||
* Note that block level elements MUST NOT overlap each other boundaries, but may be fully contained (nested) within
|
||||
* each other.
|
||||
* </p>
|
||||
* @see <a href="http://xmpp.org/extensions/xep-0394.html">XEP-0394: Message Markup</a>
|
||||
*/
|
||||
package org.jivesoftware.smackx.message_markup.element;
|
||||
|
|
|
|||
|
|
@ -1,25 +0,0 @@
|
|||
/**
|
||||
*
|
||||
* Copyright 2018 Paul Schaub
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
/**
|
||||
* XEP-0394: Message Markup.
|
||||
*
|
||||
* @see <a href="http://xmpp.org/extensions/xep-0394.html">XEP-0394: Message
|
||||
* Markup</a>
|
||||
*
|
||||
*/
|
||||
package org.jivesoftware.smackx.message_markup;
|
||||
|
|
@ -16,5 +16,23 @@
|
|||
*/
|
||||
/**
|
||||
* Smack's API for XEP-0372: References.
|
||||
*/
|
||||
* <p>
|
||||
* References are a way to refer to other entities like users, other messages or external data from within a message.
|
||||
* </p>
|
||||
* <p>
|
||||
* Typical use-cases are mentioning other users by name, but referencing to their BareJid, or linking to a sent file.
|
||||
* </p>
|
||||
* <h2 id="usage">Usage</h2>
|
||||
* <p>
|
||||
* Mention a user and link to their bare jid.
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* Message message = new Message("Alice is a realy nice person.");
|
||||
* BareJid alice = JidCreate.bareFrom("alice@capulet.lit");
|
||||
* ReferenceManager.addMention(message, 0, 5, alice);
|
||||
* </code>
|
||||
* </pre>
|
||||
*/
|
||||
package org.jivesoftware.smackx.reference;
|
||||
|
|
|
|||
|
|
@ -15,6 +15,24 @@
|
|||
* limitations under the License.
|
||||
*/
|
||||
/**
|
||||
* Smack's API for XEP-0382: Spoiler Messages.
|
||||
*/
|
||||
* Smack's API for XEP-0382: Spoiler Messages, that can be used to indicate that
|
||||
* the body of a message is a spoiler and should be displayed as such.
|
||||
* <h2>Usage</h2>
|
||||
* <p>
|
||||
* Invoke {@link SpoilerManager#startAnnounceSupport()} to announce support for
|
||||
* spoiler messages.
|
||||
* </p>
|
||||
* <p>
|
||||
* Add spoilers to messages via
|
||||
* {@link org.jivesoftware.smackx.spoiler.element.SpoilerElement#addSpoiler(Message)},
|
||||
* {@link org.jivesoftware.smackx.spoiler.element.SpoilerElement#addSpoiler(Message, String)},
|
||||
* or
|
||||
* {@link org.jivesoftware.smackx.spoiler.element.SpoilerElement#addSpoiler(Message, String, String)}.
|
||||
* To get spoilers use
|
||||
* {@link org.jivesoftware.smackx.spoiler.element.SpoilerElement#getSpoilers(Message)}.
|
||||
* </p>
|
||||
*
|
||||
* @see <a href="https://xmpp.org/extensions/xep-0382.html">XEP-0382: Spoiler
|
||||
* Messages</a>
|
||||
*/
|
||||
package org.jivesoftware.smackx.spoiler;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue