1
0
Fork 0
mirror of https://codeberg.org/Mercury-IM/Smack synced 2025-09-09 10:19:41 +02:00

Enable javadoc 'html' doclint

Also make all 'test' tasks depend on the 'javadoc' task.

Fixes SMACK-650.
This commit is contained in:
Florian Schmaus 2017-12-25 12:51:41 +01:00
parent 89c97bb46c
commit 34373e8710
71 changed files with 200 additions and 220 deletions

View file

@ -23,7 +23,7 @@ import org.jivesoftware.smackx.jingleold.packet.JingleError;
/**
* A Jingle exception.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public class JingleException extends XMPPException {
private static final long serialVersionUID = -1521230401958103382L;

View file

@ -56,34 +56,41 @@ import org.jxmpp.jid.Jid;
* Jingle is a session establishment protocol defined in (XEP-0166).
* It defines a framework for negotiating and managing out-of-band ( data that is send and receive through other connection than XMPP connection) data sessions over XMPP.
* With this protocol you can setup VOIP Calls, Video Streaming, File transfers and whatever out-of-band session based transmission.
* <p/>
* <p>
* To create a Jingle Session you need a Transport method and a Payload type.
* <p/>
* </p>
* <p>
* A transport method is how it will transmit and receive network packets. Transport MUST have one or more candidates.
* A transport candidate is an IP Address with a defined port, that other party must send data to.
* <p/>
* </p>
* <p>
* A supported payload type, is the data encoding format that the jmf will be transmitted.
* For instance an Audio Payload "GSM".
* <p/>
* </p>
* <p>
* A Jingle session negotiates a payload type and a pair of transport candidates.
* Which means that when a Jingle Session is established you will have two defined transport candidates with addresses
* and a defined Payload type.
* In other words, you will have two IP address with their respective ports, and a Codec type defined.
* <p/>
* </p>
* <p>
* The JingleManager is a facade built upon Jabber Jingle (XEP-166) to allow the
* use of Jingle. This implementation allows the user to simply
* use this class for setting the Jingle parameters, create and receive Jingle Sessions.
* <p/>
* </p>
* <p>
* In order to use the Jingle, the user must provide a
* TransportManager that will handle the resolution of potential IP addresses that can be used to transport the streaming (jmf).
* This TransportManager can be initialized with several default resolvers,
* including a fixed solver that can be used when the address and port are know
* in advance.
* This API have ready to use Transport Managers, for instance: BasicTransportManager, STUNTransportManager, BridgedTransportManager.
* <p/>
* </p>
* <p>
* You should also specify a JingleMediaManager if you want that JingleManager assume Media control
* Using a JingleMediaManager implementation is the easier way to implement a Jingle Application.
* <p/>
* </p>
* <p>
* Otherwise before creating an outgoing connection, the user must create jingle session
* listeners that will be called when different events happen. The most
* important event is <i>sessionEstablished()</i>, that will be called when all
@ -91,85 +98,60 @@ import org.jxmpp.jid.Jid;
* transmission as well as the remote and local addresses and ports for the
* communication. See JingleSessionListener for a complete list of events that can be
* observed.
* <p/>
* </p>
* This is an example of how to use the JingleManager:
* <i>This example implements a Jingle VOIP Call between two users.</i>
* <p/>
* <pre>
* <p/>
* To wait for an Incoming Jingle Session:
* <p/>
* try {
* <p/>
* // Connect to an XMPP Server
* XMPPConnection x1 = new XMPPTCPConnection("xmpp.com");
* x1.connect();
* x1.login("juliet", "juliet");
* <p/>
* // Create a JingleManager using a BasicResolver
* final JingleManager jm1 = new JingleManager(
* x1, new BasicTransportManager());
* <p/>
* // Create a JingleMediaManager. In this case using Jingle Audio Media API
* JingleMediaManager jingleMediaManager = new AudioMediaManager();
* <p/>
* // Set the JingleMediaManager
* jm1.setMediaManager(jingleMediaManager);
* <p/>
* // Listen for incoming calls
* jm1.addJingleSessionRequestListener(new JingleSessionRequestListener() {
* public void sessionRequested(JingleSessionRequest request) {
* <p/>
* try {
* // Accept the call
* IncomingJingleSession session = request.accept();
* <p/>
* <p/>
* // Start the call
* session.start();
* } catch (XMPPException e) {
* LOGGER.log(Level.WARNING, "exception", e);
* }
* <p/>
* }
* });
* <p/>
* Thread.sleep(15000);
* <p/>
* } catch (Exception e) {
* LOGGER.log(Level.WARNING, "exception", e);
* }
* <p/>
* To create an Outgoing Jingle Session:
* <p/>
* try {
* <p/>
* // Connect to an XMPP Server
* XMPPConnection x0 = new XMPPTCPConnection("xmpp.com");
* x0.connect();
* x0.login("romeo", "romeo");
* <p/>
* // Create a JingleManager using a BasicResolver
* final JingleManager jm0 = new JingleManager(
* x0, new BasicTransportManager());
* <p/>
* // Create a JingleMediaManager. In this case using Jingle Audio Media API
* JingleMediaManager jingleMediaManager = new AudioMediaManager(); // Using Jingle Media API
* <p/>
* // Set the JingleMediaManager
* jm0.setMediaManager(jingleMediaManager);
* <p/>
* // Create a new Jingle Call with a full JID
* OutgoingJingleSession js0 = jm0.createOutgoingJingleSession("juliet@xmpp.com/Smack");
* <p/>
* // Start the call
* js0.start();
* <p/>
* Thread.sleep(10000);
* js0.terminate();
* <p/>
* Thread.sleep(3000);
* <p/>
* } catch (Exception e) {
* LOGGER.log(Level.WARNING, "exception", e);
* }
@ -279,11 +261,11 @@ public class JingleManager implements JingleSessionListener {
/**
* Enables or disables the Jingle support on a given connection.
* <p/>
* <p/>
* <p>
* Before starting any Jingle jmf session, check that the user can handle
* it. Enable the Jingle support to indicate that this client handles Jingle
* messages.
* </p>
*
* @param connection the connection where the service will be enabled or
* disabled

View file

@ -29,13 +29,10 @@ import org.jivesoftware.smackx.jingleold.listeners.JingleListener;
/**
* Basic Jingle negotiator.
* <p/>
* </p>
* <p/>
* <p>
* JingleNegotiator implements some basic behavior for every Jingle negotiation.
* It implements a "state" pattern: each stage should process Jingle packets and
* act depending on the current state in the negotiation...
* <p/>
* </p>
*
* @author Alvaro Saurin
@ -215,18 +212,18 @@ public abstract class JingleNegotiator {
* Media Negotiator
* Transport Negotiator
*
* <jingle>
* <content>
* <description>
* <transport>
* <content>
* <description>
* <transport>
* &lt;jingle&gt;
* &lt;content&gt;
* &lt;description&gt;
* &lt;transport&gt;
* &lt;content&gt;
* &lt;description&gt;
* &lt;transport&gt;
*
* This way, each segment of a Jingle stanza(/packet) has a corresponding negotiator that know how to deal with that
* part of the Jingle packet. It also allows us to support Jingle packets of arbitraty complexity.
*
* Each parent calls dispatchIncomingPacket for each of its children. The children then pass back a List<> of
* Each parent calls dispatchIncomingPacket for each of its children. The children then pass back a List of
* results that will get sent when we reach the top level negotiator (JingleSession).
*
* @param iq the stanza(/packet) received

View file

@ -55,7 +55,7 @@ import org.jivesoftware.smackx.jingleold.packet.JingleError;
import org.jxmpp.jid.Jid;
/**
* An abstract Jingle session. <p/> This class contains some basic properties of
* An abstract Jingle session. This class contains some basic properties of
* every Jingle session. However, the concrete implementation can be found in
* subclasses.
*
@ -270,7 +270,7 @@ public class JingleSession extends JingleNegotiator implements MediaReceivedList
// ----------------------------------------------------------------------------------------------------------
/**
* Process and respond to an incoming packet. <p/> This method is called
* Process and respond to an incoming packet. This method is called
* from the stanza(/packet) listener dispatcher when a new stanza(/packet) has arrived. The
* method is responsible for recognizing the stanza(/packet) type and, depending on
* the current state, delivering it to the right event handler and wait for
@ -394,7 +394,7 @@ public class JingleSession extends JingleNegotiator implements MediaReceivedList
}
/**
* Add a new content negotiator on behalf of a <content> section received.
* Add a new content negotiator on behalf of a &lt;content/&gt; section received.
*/
public void addContentNegotiator(ContentNegotiator inContentNegotiator) {
contentNegotiators.add(inContentNegotiator);

View file

@ -28,7 +28,7 @@ import org.jxmpp.jid.Jid;
/**
* A Jingle session request.
* <p/>
*
* This class is a facade of a received Jingle request. The user can have direct
* access to the Jingle stanza(/packet) (<i>JingleSessionRequest.getJingle() </i>) of
* the request or can use the convenience methods provided by this class.
@ -107,7 +107,7 @@ public class JingleSessionRequest {
/**
* Accepts this request and creates the incoming Jingle session.
*
* @return Returns the <b><i>IncomingJingleSession</b></i> on which the
* @return Returns the IncomingJingleSession on which the
* negotiation can be carried out.
* @throws SmackException
* @throws InterruptedException

View file

@ -22,14 +22,14 @@ import java.util.Locale;
* Content info. Content info messages are complementary messages that can be
* transmitted for informing of events like "busy", "ringtone", etc.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public abstract class ContentInfo {
/**
* Audio content info messages.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public static class Audio extends ContentInfo {

View file

@ -25,10 +25,11 @@ import org.jivesoftware.smackx.jingleold.nat.TransportCandidate;
/**
* This class provides necessary Jingle Session jmf methods and behavior.
* <p/>
* <p>
* The goal of this class is to provide a flexible way to make JingleManager control jmf streaming APIs without implement them.
* For instance you can implement a file transfer using java sockets or a VOIP Media Manager using JMF.
* You can implement many JingleMediaManager according to you necessity.
* </p>
*
* @author Thiago Camargo
*/

View file

@ -24,11 +24,11 @@ import org.jivesoftware.smackx.jingleold.nat.TransportCandidate;
/**
* Public Abstract Class provides a clear interface between Media Session and Jingle API.
* <p/>
* <p>
* When a Jingle Session is fully stablished, we will have a Payload Type and two transport candidates defined for it.
* Smack Jingle API don't implement Media Transmit and Receive methods.
* But provides an interface to let the user implements it using another API. For instance: JMF.
* <p/>
* </p>
* <i>The Class that implements this one, must have the support to transmit and receive the jmf.</i>
* <i>This interface let the user choose his own jmf API.</i>
*

View file

@ -38,7 +38,7 @@ import org.jivesoftware.smackx.jingleold.packet.JingleDescription;
import org.jivesoftware.smackx.jingleold.packet.JingleError;
/**
* Manager for jmf descriptor negotiation. <p/> <p/> This class is responsible
* Manager for jmf descriptor negotiation. This class is responsible
* for managing the descriptor negotiation process, handling all the xmpp
* packets interchange and the stage control. handling all the xmpp packets
* interchange and the stage control.

View file

@ -54,15 +54,17 @@ import org.jivesoftware.smackx.jingleold.media.JingleMediaSession;
* It sends and receives jmf for and from desired IPs and ports.
* Also has a rport Symetric behavior for better NAT Traversal.
* It send data from a defined port and receive data in the same port, making NAT binds easier.
* <p/>
* <p>
* Send from portA to portB and receive from portB in portA.
* <p/>
* </p>
* <p>
* Sending
* portA ---> portB
* <p/>
* portA ---&gt; portB
* </p>
* <p>
* Receiving
* portB ---> portA
* <p/>
* portB ---&gt; portA
* </p>
* <i>Transmit and Receive are interdependence. To receive you MUST transmit. </i>
*
* @author Thiago Camargo

View file

@ -45,7 +45,7 @@ public class BasicResolver extends TransportResolver {
/**
* Resolve the IP address.
* <p/>
*
* The BasicResolver takes the IP addresses of the interfaces and uses the
* first non-loopback, non-linklocal and non-sitelocal address.
* @throws NotConnectedException

View file

@ -36,7 +36,7 @@ import org.jivesoftware.smackx.jingleold.JingleSession;
/**
* Bridged Resolver use a RTPBridge Service to add a relayed candidate.
* A very reliable solution for NAT Traversal.
* <p/>
*
* The resolver verify is the XMPP Server that the client is connected offer this service.
* If the server supports, a candidate is requested from the service.
* The resolver adds this candidate
@ -61,7 +61,7 @@ public class BridgedResolver extends TransportResolver {
/**1
* Resolve Bridged Candidate.
* <p/>
*
* The BridgedResolver takes the IP address and ports of a jmf proxy service.
* @throws NotConnectedException
* @throws InterruptedException

View file

@ -26,7 +26,7 @@ import org.jivesoftware.smackx.jingleold.JingleSession;
* the external address and port are previously known when the object is
* initialized.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public class FixedResolver extends TransportResolver {

View file

@ -24,7 +24,7 @@ import java.util.logging.Logger;
/**
* ICE Transport candidate.
* <p/>
*
* A candidate represents the possible transport for data interchange between
* the two endpoints.
*
@ -216,7 +216,7 @@ public class ICECandidate extends TransportCandidate implements Comparable<ICECa
* Check if a transport candidate is usable. The transport resolver should
* check if the transport candidate the other endpoint has provided is
* usable.
* <p/>
*
* ICE Candidate can check connectivity using UDP echo Test.
*/
@Override

View file

@ -45,9 +45,9 @@ import org.xmlpull.v1.XmlPullParserException;
* RTPBridge IQ Stanza(/Packet) used to request and retrieve a RTPBridge Candidates that can be used for a Jingle Media Transmission between two parties that are behind NAT.
* This Jingle Bridge has all the needed information to establish a full UDP Channel (Send and Receive) between two parties.
* <i>This transport method should be used only if other transport methods are not allowed. Or if you want a more reliable transport.</i>
* <p/>
*
* High Level Usage Example:
* <p/>
*
* RTPBridge rtpBridge = RTPBridge.getRTPBridge(connection, sessionID);
*
* @author Thiago Camargo

View file

@ -39,9 +39,9 @@ import org.xmlpull.v1.XmlPullParserException;
/**
* STUN IQ Stanza(/Packet) used to request and retrieve a STUN server and port to make p2p connections easier. STUN is usually used by Jingle Media Transmission between two parties that are behind NAT.
* <p/>
*
* High Level Usage Example:
* <p/>
*
* STUN stun = STUN.getSTUNServer(connection);
*
* @author Thiago Camargo

View file

@ -199,7 +199,7 @@ public class STUNResolver extends TransportResolver {
/**
* Load a list of services: STUN servers and ports. Some public STUN servers
* are:
* <p/>
*
* <pre>
* iphone-stun.freenet.de:3478
* larry.gloo.net:3478
@ -212,7 +212,7 @@ public class STUNResolver extends TransportResolver {
* stun.voxgratia.org (no DNS SRV record)
* stun.noc.ams-ix.net
* </pre>
* <p/>
*
* This list should be contained in a file in the "META-INF" directory
*
* @return a list of services
@ -494,7 +494,7 @@ public class STUNResolver extends TransportResolver {
/**
* Check a binding with the STUN currentServer.
* <p/>
*
* Note: this function blocks for some time, waiting for a response.
*
* @return true if the currentServer is usable.

View file

@ -37,7 +37,7 @@ import org.jxmpp.jid.Jid;
/**
* Transport candidate.
* <p/>
*
* A candidate represents the possible transport for data interchange between
* the two endpoints.
*
@ -346,7 +346,7 @@ public abstract class TransportCandidate {
* Check if a transport candidate is usable. The transport resolver should
* check if the transport candidate the other endpoint has provided is
* usable.
* <p/>
*
* Subclasses should provide better methods if they can...
*/
public void check(final List<TransportCandidate> localCandidates) {

View file

@ -45,12 +45,11 @@ import org.jivesoftware.smackx.jingleold.packet.JingleTransport.JingleTransportC
/**
* Transport negotiator.
* <p/>
* <p/>
*
* This class is responsible for managing the transport negotiation process,
* handling all the stanza(/packet) interchange and the stage control.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public abstract class TransportNegotiator extends JingleNegotiator {
@ -829,7 +828,7 @@ public abstract class TransportNegotiator extends JingleNegotiator {
/**
* Raw-UDP transport negotiator.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public static final class RawUdp extends TransportNegotiator {
@ -884,7 +883,7 @@ public abstract class TransportNegotiator extends JingleNegotiator {
/**
* Ice transport negotiator.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public static final class Ice extends TransportNegotiator {

View file

@ -37,7 +37,7 @@ import org.jivesoftware.smackx.jingleold.JingleSession;
* It is called candidate, because it can be elected or not.
*
* @author Thiago Camargo
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public abstract class TransportResolver {

View file

@ -30,11 +30,11 @@ import org.jxmpp.jid.Jid;
/**
* An Jingle sub-packet, which is used by XMPP clients to exchange info like
* descriptions and transports. <p/> The following link summarizes the
* descriptions and transports. The following link summarizes the
* requirements of Jingle IM: <a
* href="http://www.xmpp.org/extensions/jep-0166.html">Valid tags</a>.
* <p/>
* <p/> Warning: this is an non-standard protocol documented by <a
*
* Warning: this is an non-standard protocol documented by <a
* href="http://www.xmpp.org/extensions/jep-0166.html">XEP-166</a>. Because this is
* a non-standard protocol, it is subject to change.
*
@ -156,7 +156,7 @@ public class Jingle extends IQ {
* Set the session ID related to this session. The session ID is a unique
* identifier generated by the initiator. This should match the XML Nmtoken
* production so that XML character escaping is not needed for characters
* such as &.
* such as &amp;.
*
* @param sid the session ID
*/
@ -168,7 +168,7 @@ public class Jingle extends IQ {
* Returns the session ID related to the session. The session ID is a unique
* identifier generated by the initiator. This should match the XML Nmtoken
* production so that XML character escaping is not needed for characters
* such as &.
* such as &amp;.
*
* @return Returns the session ID related to the session.
* @see #setSid(String)

View file

@ -28,7 +28,7 @@ import org.jivesoftware.smackx.jingleold.media.PayloadType;
/**
* Jingle content description.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public abstract class JingleContentDescription implements ExtensionElement {

View file

@ -23,7 +23,7 @@ import org.jivesoftware.smackx.jingleold.media.ContentInfo;
/**
* Jingle content info.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public class JingleContentInfo implements ExtensionElement {

View file

@ -29,7 +29,7 @@ import org.jivesoftware.smackx.jingleold.media.PayloadType;
/**
* Jingle content description.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public abstract class JingleDescription implements ExtensionElement {

View file

@ -29,7 +29,7 @@ import org.jivesoftware.smackx.jingleold.nat.TransportCandidate;
/**
* A jingle transport extension.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public class JingleTransport implements ExtensionElement {

View file

@ -31,7 +31,7 @@ import org.xmlpull.v1.XmlPullParserException;
/**
* Parser for a Jingle description.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public abstract class JingleContentDescriptionProvider extends ExtensionElementProvider<JingleContentDescription> {

View file

@ -23,7 +23,7 @@ import org.jivesoftware.smackx.jingleold.packet.JingleContent;
import org.xmlpull.v1.XmlPullParser;
/**
* Jingle <content> provider.
* Jingle &lt;content&gt; provider.
*
* @author Jeff Williams
*/

View file

@ -30,7 +30,7 @@ import org.xmlpull.v1.XmlPullParserException;
/**
* Parser for a Jingle description.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public abstract class JingleDescriptionProvider extends ExtensionElementProvider<JingleDescription> {

View file

@ -32,7 +32,7 @@ import org.xmlpull.v1.XmlPullParserException;
/**
* Provider for a Jingle transport element.
*
* @author Alvaro Saurin <alvaro.saurin@gmail.com>
* @author Alvaro Saurin
*/
public abstract class JingleTransportProvider extends ExtensionElementProvider<JingleTransport> {