From 1743ae9c3505fa03360fc694575869135eca1b56 Mon Sep 17 00:00:00 2001 From: vanitasvitae Date: Fri, 25 Aug 2017 16:34:48 +0200 Subject: [PATCH] Comment JFT code --- .../JingleFileTransferManager.java | 13 +++++- .../adapter/JingleFileTransferAdapter.java | 3 +- .../component/AbstractJingleFileOffer.java | 2 +- .../component/AbstractJingleFileRequest.java | 3 +- .../component/JingleFile.java | 3 +- .../component/JingleFileTransfer.java | 23 ++++++++++- .../component/JingleIncomingFileOffer.java | 3 +- .../component/JingleIncomingFileRequest.java | 4 +- .../component/JingleOutgoingFileOffer.java | 2 +- .../component/JingleOutgoingFileRequest.java | 2 +- .../IncomingFileOfferController.java | 22 +++++++++- .../IncomingFileRequestController.java | 2 +- .../JingleFileTransferController.java | 20 +++++++++- .../OutgoingFileOfferController.java | 2 +- .../OutgoingFileRequestController.java | 2 +- .../element/ChecksumElement.java | 8 +++- .../JingleFileTransferChildElement.java | 40 ++++++++++++++++++- .../element/JingleFileTransferElement.java | 5 ++- .../listener/IncomingFileOfferListener.java | 6 ++- .../listener/IncomingFileRequestListener.java | 6 ++- .../listener/ProgressListener.java | 9 ++++- .../provider/ChecksumProvider.java | 4 +- .../JingleContentDescriptionInfoElement.java | 2 +- 23 files changed, 160 insertions(+), 26 deletions(-) diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/JingleFileTransferManager.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/JingleFileTransferManager.java index d689dbd0b..a0d845ffa 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/JingleFileTransferManager.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/JingleFileTransferManager.java @@ -59,22 +59,33 @@ import org.jivesoftware.smackx.jingle_filetransfer.provider.JingleFileTransferPr import org.jxmpp.jid.FullJid; /** - * Created by vanitas on 22.07.17. + * Manager for XEP-0234 - JingleFileTransfers. */ public final class JingleFileTransferManager extends Manager implements JingleDescriptionManager { private static final Logger LOGGER = Logger.getLogger(JingleFileTransferManager.class.getName()); private static final WeakHashMap INSTANCES = new WeakHashMap<>(); + + /** + * Reference to the JingleManager of the connection. + */ private final JingleManager jingleManager; + /** + * Listeners for incoming file offers. + */ private final List offerListeners = Collections.synchronizedList(new ArrayList()); + /** + * Listeners for incoming file requests. + */ private final List requestListeners = Collections.synchronizedList(new ArrayList()); static { + // Register adapters and providers. JingleManager.addJingleDescriptionAdapter(new JingleFileTransferAdapter()); JingleManager.addJingleDescriptionProvider(new JingleFileTransferProvider()); } diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/adapter/JingleFileTransferAdapter.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/adapter/JingleFileTransferAdapter.java index 76f016cb2..adc49716c 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/adapter/JingleFileTransferAdapter.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/adapter/JingleFileTransferAdapter.java @@ -31,9 +31,10 @@ import org.jivesoftware.smackx.jingle_filetransfer.element.JingleFileTransferChi import org.jivesoftware.smackx.jingle_filetransfer.element.JingleFileTransferElement; /** - * Created by vanitas on 28.07.17. + * Adapter to convert JingleFileTransferElements (element) to JingleFileTransfer objects (component). */ public class JingleFileTransferAdapter implements JingleDescriptionAdapter { + private static final Logger LOGGER = Logger.getLogger(JingleFileTransferAdapter.class.getName()); @Override diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/AbstractJingleFileOffer.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/AbstractJingleFileOffer.java index e53fd55d9..a29f31eb9 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/AbstractJingleFileOffer.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/AbstractJingleFileOffer.java @@ -17,7 +17,7 @@ package org.jivesoftware.smackx.jingle_filetransfer.component; /** - * Created by vanitas on 22.07.17. + * This class represents the base of a JingleFileOffer. */ public abstract class AbstractJingleFileOffer extends JingleFileTransfer { diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/AbstractJingleFileRequest.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/AbstractJingleFileRequest.java index 94f3b50c2..4cabd236b 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/AbstractJingleFileRequest.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/AbstractJingleFileRequest.java @@ -17,7 +17,8 @@ package org.jivesoftware.smackx.jingle_filetransfer.component; /** - * Created by vanitas on 22.07.17. + * Class representing the base of a JingleFileRequest. + * TODO: Implement. */ public abstract class AbstractJingleFileRequest extends JingleFileTransfer { diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/JingleFile.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/JingleFile.java index f809f848c..525cf6f66 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/JingleFile.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/JingleFile.java @@ -29,8 +29,7 @@ import org.jivesoftware.smackx.hashes.element.HashElement; import org.jivesoftware.smackx.jingle_filetransfer.element.JingleFileTransferChildElement; /** - * Represent a file sent in a file transfer. - * This can be both LocalFile (available to the client), or RemoteFile (file not yet available). + * Represent a file sent in a file transfer. This class contains metadata of the transferred file. */ public class JingleFile { diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/JingleFileTransfer.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/JingleFileTransfer.java index e84a756c3..0497ec084 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/JingleFileTransfer.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/component/JingleFileTransfer.java @@ -33,7 +33,7 @@ import org.jivesoftware.smackx.jingle_filetransfer.element.JingleFileTransferEle import org.jivesoftware.smackx.jingle_filetransfer.listener.ProgressListener; /** - * Created by vanitas on 22.07.17. + * Base class of a Jingle File Transfer. */ public abstract class JingleFileTransfer extends JingleDescription implements JingleFileTransferController { @@ -48,12 +48,24 @@ public abstract class JingleFileTransfer extends JingleDescription progressListeners = Collections.synchronizedList(new ArrayList()); + /** + * Create a new JingleFileTransfer. + * @param metadata metadata of the transferred file. + */ JingleFileTransfer(JingleFile metadata) { this.metadata = metadata; } + /** + * Is this a file offer? + * @return file offer? + */ public abstract boolean isOffer(); + /** + * Is this a file request? + * @return file request? + */ public abstract boolean isRequest(); @Override @@ -92,12 +104,21 @@ public abstract class JingleFileTransfer extends JingleDescriptionXEP-0234. */ public class ChecksumElement implements ExtensionElement { @@ -35,6 +35,12 @@ public class ChecksumElement implements ExtensionElement { private final String name; private final JingleFileTransferChildElement file; + /** + * Create a new ChecksumElement. + * @param creator creator of the content (party that added the file to the transmission). + * @param name name of the content. + * @param file metadata of the file. + */ public ChecksumElement(JingleContentElement.Creator creator, String name, JingleFileTransferChildElement file) { this.creator = creator; this.name = name; diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/element/JingleFileTransferChildElement.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/element/JingleFileTransferChildElement.java index 500f0ad50..dfbcd3bab 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/element/JingleFileTransferChildElement.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/element/JingleFileTransferChildElement.java @@ -24,7 +24,7 @@ import org.jivesoftware.smackx.hashes.element.HashElement; import org.jivesoftware.smackx.jingle.element.JingleContentDescriptionChildElement; /** - * Content of type File. + * Metadata about the transferred file. */ public class JingleFileTransferChildElement extends JingleContentDescriptionChildElement { @@ -43,6 +43,16 @@ public class JingleFileTransferChildElement extends JingleContentDescriptionChil private final long size; private final Range range; + /** + * Create a new JingleFileTransferChildElement. + * @param date last-modified date of the file. + * @param desc description of the file. + * @param hash hash value of the file (see XEP-0300). + * @param mediaType mediaType (https://www.iana.org/assignments/media-types/media-types.xhtml). + * @param name name of the file. + * @param size size of the file in bytes. + * @param range range of the transfer (see https://xmpp.org/extensions/xep-0234.html#range). + */ public JingleFileTransferChildElement(Date date, String desc, HashElement hash, String mediaType, String name, long size, Range range) { this.date = date; this.desc = desc; @@ -53,30 +63,58 @@ public class JingleFileTransferChildElement extends JingleContentDescriptionChil this.range = range; } + /** + * Return the last-modified date of the file. + * @return date. + */ public Date getDate() { return date; } + /** + * Return the description of the file. + * @return description. + */ public String getDescription() { return desc; } + /** + * Return the hash of the file. + * @return hash. + */ public HashElement getHash() { return hash; } + /** + * Return the mediaType of the file (https://www.iana.org/assignments/media-types/media-types.xhtml). + * @return media-type. + */ public String getMediaType() { return mediaType; } + /** + * Return the name of the file. + * @return filename. + */ public String getName() { return name; } + /** + * Return the size of the file in bytes. + * @return size. + */ public long getSize() { return size; } + /** + * In case of a ranged transfer: Return the range of the transmission. Otherwise return null. + * @return range of the transfer. + */ public Range getRange() { return range; } diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/element/JingleFileTransferElement.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/element/JingleFileTransferElement.java index b667b20ec..ef0fa55fe 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/element/JingleFileTransferElement.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/element/JingleFileTransferElement.java @@ -24,7 +24,7 @@ import org.jivesoftware.smackx.jingle.element.JingleContentDescriptionElement; import org.jivesoftware.smackx.jingle_filetransfer.component.JingleFileTransfer; /** - * File element. + * Jingle File Transfer Element. */ public class JingleFileTransferElement extends JingleContentDescriptionElement { @@ -34,6 +34,9 @@ public class JingleFileTransferElement extends JingleContentDescriptionElement { public JingleFileTransferElement(List payloads) { super(payloads); + if (payloads.size() != 1) { + throw new IllegalArgumentException("Jingle File Transfers only support one payload element."); + } } @Override diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/IncomingFileOfferListener.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/IncomingFileOfferListener.java index 450f753c8..3316e1e11 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/IncomingFileOfferListener.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/IncomingFileOfferListener.java @@ -19,9 +19,13 @@ package org.jivesoftware.smackx.jingle_filetransfer.listener; import org.jivesoftware.smackx.jingle_filetransfer.controller.IncomingFileOfferController; /** - * Created by vanitas on 26.07.17. + * Listener for incoming file offers. */ public interface IncomingFileOfferListener { + /** + * Notify client of an incoming file offer. + * @param offer offer. + */ void onIncomingFileOffer(IncomingFileOfferController offer); } diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/IncomingFileRequestListener.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/IncomingFileRequestListener.java index 19698089b..68dfac11c 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/IncomingFileRequestListener.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/IncomingFileRequestListener.java @@ -19,9 +19,13 @@ package org.jivesoftware.smackx.jingle_filetransfer.listener; import org.jivesoftware.smackx.jingle_filetransfer.controller.IncomingFileRequestController; /** - * Created by vanitas on 27.07.17. + * Listener for incoming file requests. */ public interface IncomingFileRequestListener { + /** + * Notify the client of an incoming file request. + * @param request request. + */ void onIncomingFileRequest(IncomingFileRequestController request); } diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/ProgressListener.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/ProgressListener.java index e3f3f613e..6ca2b2736 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/ProgressListener.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/listener/ProgressListener.java @@ -19,11 +19,18 @@ package org.jivesoftware.smackx.jingle_filetransfer.listener; import org.jivesoftware.smackx.jingle.element.JingleReasonElement; /** - * Created by vanitas on 27.07.17. + * ProgressListener that listens for progress changes of a file transfer. */ public interface ProgressListener { + /** + * Bytestream transmission has stared. This usually happens after the negotiation is finished. + */ void started(); + /** + * Transfer has been terminated. This might happen at all times. + * @param reason reason (eg. cancel). + */ void terminated(JingleReasonElement.Reason reason); } diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/provider/ChecksumProvider.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/provider/ChecksumProvider.java index ef9cba413..e0f19810e 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/provider/ChecksumProvider.java +++ b/smack-experimental/src/main/java/org/jivesoftware/smackx/jingle_filetransfer/provider/ChecksumProvider.java @@ -36,6 +36,8 @@ import org.xmlpull.v1.XmlPullParser; */ public class ChecksumProvider extends ExtensionElementProvider { + private static HashElementProvider hashProvider = new HashElementProvider(); + @Override public ChecksumElement parse(XmlPullParser parser, int initialDepth) throws Exception { JingleContentElement.Creator creator = null; @@ -58,7 +60,7 @@ public class ChecksumProvider extends ExtensionElementProvider if (tag == START_TAG) { switch (n) { case HashElement.ELEMENT: - hashElement = new HashElementProvider().parse(parser); + hashElement = hashProvider.parse(parser); break; case Range.ELEMENT: diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentDescriptionInfoElement.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentDescriptionInfoElement.java index 1287970fe..bec231ffd 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentDescriptionInfoElement.java +++ b/smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentDescriptionInfoElement.java @@ -19,7 +19,7 @@ package org.jivesoftware.smackx.jingle.element; import org.jivesoftware.smack.packet.NamedElement; /** - * Created by vanitas on 28.07.17. + * Info child element of a Jingle Content Description element. */ public abstract class JingleContentDescriptionInfoElement implements NamedElement {