More javadoc

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/JingleDescriptionController.java

@@ -16,8 +16,10 @@
  */
 package org.jivesoftware.smackx.jingle;
 
+import org.jivesoftware.smackx.jingle.component.JingleDescription;
+
 /**
- * Created by vanitas on 27.07.17.
+ * User interface which provides methods for the client to use.
  */
 public interface JingleDescriptionController {
 
@@ -29,5 +31,9 @@ public interface JingleDescriptionController {
         ended               //Successfully ended
     }
 
+    /**
+     * Return the state of the {@link JingleDescription}.
+     * @return state.
+     */
     State getState();
 }

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/JingleDescriptionManager.java

@@ -17,16 +17,30 @@
 package org.jivesoftware.smackx.jingle;
 
 import org.jivesoftware.smackx.jingle.component.JingleContent;
+import org.jivesoftware.smackx.jingle.component.JingleDescription;
 import org.jivesoftware.smackx.jingle.component.JingleSession;
 
 /**
- * Manager for JingleDescription components.
+ * Manager for {@link JingleDescription} components.
  */
 public interface JingleDescriptionManager {
 
+    /**
+     * Return the namespace of the {@link JingleDescription}.
+     * @return namespace.
+     */
     String getNamespace();
 
+    /**
+     * Notify about an incoming session-initiate wich contains a suitable {@link JingleDescription}.
+     * @param session initiated jingleSession.
+     */
     void notifySessionInitiate(JingleSession session);
 
+    /**
+     * Notify about a content-add request which tries to add a suitable {@link JingleDescription}.
+     * @param session affected jingleSession.
+     * @param content content which will be added.
+     */
     void notifyContentAdd(JingleSession session, JingleContent content);
 }

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/JingleManager.java

@@ -59,21 +59,60 @@ import org.jxmpp.jid.Jid;
  * Manager for Jingle (XEP-0166).
  */
 public final class JingleManager extends Manager {
+
     private static final Logger LOGGER = Logger.getLogger(JingleManager.class.getName());
     private static final WeakHashMap<XMPPConnection, JingleManager> INSTANCES = new WeakHashMap<>();
 
+    /**
+     * Map of registered {@link JingleContentDescriptionProvider}s and their namespaces.
+     */
     private static final WeakHashMap<String, JingleContentDescriptionProvider<?>> descriptionProviders = new WeakHashMap<>();
+
+    /**
+     * Map of registered {@link JingleContentTransportProvider}s and their namespaces.
+     */
     private static final WeakHashMap<String, JingleContentTransportProvider<?>> transportProviders = new WeakHashMap<>();
+
+    /**
+     * Map of registered {@link JingleContentSecurityProvider}s and their namespaces.
+     */
     private static final WeakHashMap<String, JingleContentSecurityProvider<?>> securityProviders = new WeakHashMap<>();
 
+
+    /**
+     * Map of registered {@link JingleDescriptionAdapter}s and their namespaces.
+     */
     private static final WeakHashMap<String, JingleDescriptionAdapter<?>> descriptionAdapters = new WeakHashMap<>();
+
+    /**
+     * Map of registered {@link JingleTransportAdapter}s and their namespaces.
+     */
     private static final WeakHashMap<String, JingleTransportAdapter<?>> transportAdapters = new WeakHashMap<>();
+
+    /**
+     * Map of registered {@link JingleSecurityAdapter}s and their namespaces.
+     */
     private static final WeakHashMap<String, JingleSecurityAdapter<?>> securityAdapters = new WeakHashMap<>();
 
+
+    /**
+     * Map of registered {@link JingleDescriptionManager}s and their namespaces.
+     */
     private final WeakHashMap<String, JingleDescriptionManager> descriptionManagers = new WeakHashMap<>();
+
+    /**
+     * Map of registered {@link JingleTransportManager}s and their namespaces.
+     */
     private final WeakHashMap<String, JingleTransportManager> transportManagers = new WeakHashMap<>();
+
+    /**
+     * Map of registered {@link JingleSecurityManager}s and their namespaces.
+     */
     private final WeakHashMap<String, JingleSecurityManager> securityManagers = new WeakHashMap<>();
 
+    /**
+     * Map of active {@link JingleSession}s.
+     */
     private final ConcurrentHashMap<FullJidAndSessionId, JingleSession> jingleSessions = new ConcurrentHashMap<>();
 
     private JingleManager(final XMPPConnection connection) {
@@ -123,6 +162,11 @@ public final class JingleManager extends Manager {
                 });
     }
 
+    /**
+     * Return connections Instance of the JingleManager.
+     * @param connection connection
+     * @return connections instance.
+     */
     public static JingleManager getInstanceFor(XMPPConnection connection) {
         JingleManager manager = INSTANCES.get(connection);
 
@@ -134,94 +178,207 @@ public final class JingleManager extends Manager {
         return manager;
     }
 
+    /**
+     * Register a {@link JingleDescriptionAdapter}.
+     * @param adapter adapter.
+     */
     public static void addJingleDescriptionAdapter(JingleDescriptionAdapter<?> adapter) {
         descriptionAdapters.put(adapter.getNamespace(), adapter);
     }
 
+    /**
+     * Register a {@link JingleTransportAdapter}.
+     * @param adapter adapter.
+     */
     public static void addJingleTransportAdapter(JingleTransportAdapter<?> adapter) {
         transportAdapters.put(adapter.getNamespace(), adapter);
     }
 
+    /**
+     * Register a {@link JingleSecurityAdapter}.
+     * @param adapter adapter.
+     */
     public static void addJingleSecurityAdapter(JingleSecurityAdapter<?> adapter) {
         securityAdapters.put(adapter.getNamespace(), adapter);
     }
 
+    /**
+     * Return the registered {@link JingleDescriptionAdapter} with namespace namespace or null.
+     * @param namespace namespace.
+     * @return adapter or null.
+     */
     public static JingleDescriptionAdapter<?> getJingleDescriptionAdapter(String namespace) {
         return descriptionAdapters.get(namespace);
     }
 
+    /**
+     * Return the registered {@link JingleTransportAdapter} with namespace namespace or null.
+     * @param namespace namespace.
+     * @return adapter or null.
+     */
     public static JingleTransportAdapter<?> getJingleTransportAdapter(String namespace) {
         return transportAdapters.get(namespace);
     }
 
+    /**
+     * Return the registered {@link JingleSecurityAdapter} with namespace namespace or null.
+     * @param namespace namespace.
+     * @return adapter or null.
+     */
     public static JingleSecurityAdapter<?> getJingleSecurityAdapter(String namespace) {
         return securityAdapters.get(namespace);
     }
 
+    /**
+     * Add a {@link JingleContentDescriptionProvider}.
+     * @param provider provider.
+     */
     public static void addJingleDescriptionProvider(JingleContentDescriptionProvider<?> provider) {
         descriptionProviders.put(provider.getNamespace(), provider);
     }
 
+    /**
+     * Remove the {@link JingleContentDescriptionProvider} with namespace namespace.
+     * @param namespace namespace.
+     */
     public static void removeJingleDescriptionProvider(String namespace) {
         descriptionProviders.remove(namespace);
     }
 
+    /**
+     * Return the {@link JingleContentDescriptionProvider} with namespace namespace or null.
+     * @param namespace namespace.
+     * @return provider or null.
+     */
     public static JingleContentDescriptionProvider<?> getJingleDescriptionProvider(String namespace) {
         return descriptionProviders.get(namespace);
     }
 
+    /**
+     * Add a {@link JingleContentTransportProvider}.
+     * @param provider provider.
+     */
     public static void addJingleTransportProvider(JingleContentTransportProvider<?> provider) {
         transportProviders.put(provider.getNamespace(), provider);
     }
 
+    /**
+     * Remove the {@link JingleContentTransportProvider} with namespace namespace.
+     * @param namespace namespace.
+     */
     public static void removeJingleTransportProvider(String namespace) {
         transportProviders.remove(namespace);
     }
 
+    /**
+     * Return the {@link JingleContentTransportProvider} with namespace namespace or null.
+     * @param namespace namespace.
+     * @return provider or null.
+     */
     public static JingleContentTransportProvider<?> getJingleTransportProvider(String namespace) {
         return transportProviders.get(namespace);
     }
 
+    /**
+     * Add a {@link JingleContentSecurityProvider}.
+     * @param provider provider.
+     */
     public static void addJingleSecurityProvider(JingleContentSecurityProvider<?> provider) {
         securityProviders.put(provider.getNamespace(), provider);
     }
 
+    /**
+     * Remove the {@link JingleContentSecurityProvider} with namespace namespace.
+     * @param namespace namespace.
+     */
     public static void removeJingleSecurityProvider(String namespace) {
         securityProviders.remove(namespace);
     }
 
+    /**
+     * Return the {@link JingleContentSecurityProvider} with namespace namespace or null.
+     * @param namespace namespace.
+     * @return provider or null.
+     */
     public static JingleContentSecurityProvider<?> getJingleSecurityProvider(String namespace) {
         return securityProviders.get(namespace);
     }
 
+    /**
+     * Add a {@link JingleDescriptionManager}.
+     * @param manager
+     */
     public void addJingleDescriptionManager(JingleDescriptionManager manager) {
         descriptionManagers.put(manager.getNamespace(), manager);
     }
 
+    /**
+     * Get the {@link JingleDescriptionManager} with namespace namespace.
+     * @param namespace namespace
+     * @return manager or null.
+     */
     public JingleDescriptionManager getDescriptionManager(String namespace) {
         return descriptionManagers.get(namespace);
     }
 
+    /**
+     * Add a {@link JingleTransportManager}.
+     * @param manager
+     */
     public void addJingleTransportManager(JingleTransportManager manager) {
         transportManagers.put(manager.getNamespace(), manager);
     }
 
+    /**
+     * Get the {@link JingleTransportManager} with namespace namespace.
+     * @param namespace namespace
+     * @return manager or null.
+     */
     public JingleTransportManager getTransportManager(String namespace) {
         return transportManagers.get(namespace);
     }
 
+    /**
+     * Add a {@link JingleSecurityManager}.
+     * @param manager
+     */
     public void addJingleSecurityManager(JingleSecurityManager manager) {
         securityManagers.put(manager.getNamespace(), manager);
     }
 
+    /**
+     * Get the {@link JingleSecurityManager} with namespace namespace.
+     * @param namespace namespace
+     * @return manager or null.
+     */
     public JingleSecurityManager getSecurityManager(String namespace) {
         return securityManagers.get(namespace);
     }
 
+    /**
+     * Return a list of all available {@link JingleTransportManager}s that the recipient and we support.
+     * @param to recipient
+     * @return list of {@link JingleTransportManager}s.
+     * @throws XMPPException.XMPPErrorException
+     * @throws SmackException.NotConnectedException
+     * @throws InterruptedException
+     * @throws SmackException.NoResponseException
+     */
     public List<JingleTransportManager> getAvailableTransportManagers(Jid to) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException {
         return getAvailableTransportManagers(to, Collections.<String>emptySet());
     }
 
+    /**
+     * Return a list of all available {@link JingleTransportManager}s that the recipient and we support,
+     * but exclude all managers whos namespaces are in the except set.
+     * @param to recipient
+     * @param except blacklist.
+     * @return list of {@link JingleTransportManager}s.
+     * @throws XMPPException.XMPPErrorException
+     * @throws SmackException.NotConnectedException
+     * @throws InterruptedException
+     * @throws SmackException.NoResponseException
+     */
     public List<JingleTransportManager> getAvailableTransportManagers(Jid to, Set<String> except) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException {
         Set<String> available = new HashSet<>(transportManagers.keySet());
         available.removeAll(except);
@@ -243,10 +400,30 @@ public final class JingleManager extends Manager {
         return remaining;
     }
 
+    /**
+     * Return the best available {@link JingleTransportManager}, which both we and the recipient support.
+     * @param to recipient.
+     * @return best available {@link JingleTransportManager}.
+     * @throws XMPPException.XMPPErrorException
+     * @throws SmackException.NotConnectedException
+     * @throws InterruptedException
+     * @throws SmackException.NoResponseException
+     */
     public JingleTransportManager getBestAvailableTransportManager(Jid to) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException {
         return getBestAvailableTransportManager(to, Collections.<String>emptySet());
     }
 
+    /**
+     * Return the best available {@link JingleTransportManager}, which both we and the recipient support,
+     * and whichs namespace is not on the blacklist.
+     * @param to recipient.
+     * @param except blacklist.
+     * @return best available {@link JingleTransportManager}.
+     * @throws XMPPException.XMPPErrorException
+     * @throws SmackException.NotConnectedException
+     * @throws InterruptedException
+     * @throws SmackException.NoResponseException
+     */
     public JingleTransportManager getBestAvailableTransportManager(Jid to, Set<String> except) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException {
         List<JingleTransportManager> managers = getAvailableTransportManagers(to, except);
 
@@ -257,10 +434,21 @@ public final class JingleManager extends Manager {
         return null;
     }
 
+    /**
+     * Return the connection.
+     * @return connection.
+     */
     public XMPPConnection getConnection() {
         return connection();
     }
 
+    /**
+     * Create a new {@link JingleSession} and add it to the list of sessions.
+     * Then return it.
+     * @param role our role.
+     * @param peer peer.
+     * @return session.
+     */
     public JingleSession createSession(Role role, FullJid peer) {
         JingleSession session;
 
@@ -276,12 +464,20 @@ public final class JingleManager extends Manager {
         return session;
     }
 
+    /**
+     * Add a {@link JingleSession} to the list of active sessions.
+     * @param session session.
+     */
     public void addSession(JingleSession session) {
         if (!jingleSessions.containsValue(session)) {
             jingleSessions.put(new FullJidAndSessionId(session.getPeer(), session.getSessionId()), session);
         }
     }
 
+    /**
+     * Remove a {@link JingleSession} from the list of active sessions.
+     * @param session session.
+     */
     public void removeSession(JingleSession session) {
         jingleSessions.remove(new FullJidAndSessionId(session.getPeer(), session.getSessionId()));
     }

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentDescriptionElement.java

@@ -22,9 +22,10 @@ import java.util.List;
 import org.jivesoftware.smack.packet.ExtensionElement;
 import org.jivesoftware.smack.packet.NamedElement;
 import org.jivesoftware.smack.util.XmlStringBuilder;
+import org.jivesoftware.smackx.jingle.component.JingleDescription;
 
 /**
- * Jingle content description.
+ * {@link ExtensionElement} representing a {@link JingleDescription}.
  * <jingle>
  *     <content>
  *         <description/> <- This element is us.

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentElement.java

@@ -20,9 +20,10 @@ import org.jivesoftware.smack.packet.NamedElement;
 import org.jivesoftware.smack.util.Objects;
 import org.jivesoftware.smack.util.StringUtils;
 import org.jivesoftware.smack.util.XmlStringBuilder;
+import org.jivesoftware.smackx.jingle.component.JingleContent;
 
 /**
- * Jingle content element.
+ * {@link NamedElement} representing a {@link JingleContent}.
  * <jingle>
  *     <content> <- Me.
  *         ...

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentSecurityElement.java

@@ -17,9 +17,10 @@
 package org.jivesoftware.smackx.jingle.element;
 
 import org.jivesoftware.smack.packet.ExtensionElement;
+import org.jivesoftware.smackx.jingle.component.JingleSecurity;
 
 /**
- * Jingle security element.
+ * {@link ExtensionElement} representing a {@link JingleSecurity}.
  * <jingle>
  *     <content>
  *         <description/>

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentSecurityInfoElement.java

@@ -19,7 +19,7 @@ package org.jivesoftware.smackx.jingle.element;
 import org.jivesoftware.smack.packet.NamedElement;
 
 /**
- * Created by vanitas on 19.07.17.
+ * JingleSecurity info element.
  */
 public abstract class JingleContentSecurityInfoElement implements NamedElement {
 

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentTransportCandidateElement.java

@@ -17,9 +17,10 @@
 package org.jivesoftware.smackx.jingle.element;
 
 import org.jivesoftware.smack.packet.NamedElement;
+import org.jivesoftware.smackx.jingle.component.JingleTransportCandidate;
 
 /**
- * An element found usually in Jingle 'transport' elements.
+ * {@link NamedElement} representing a {@link JingleTransportCandidate}
  * <jingle>
  *     <content>
  *         <description/>

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleContentTransportElement.java

@@ -21,9 +21,10 @@ import java.util.List;
 
 import org.jivesoftware.smack.packet.ExtensionElement;
 import org.jivesoftware.smack.util.XmlStringBuilder;
+import org.jivesoftware.smackx.jingle.component.JingleTransport;
 
 /**
- * A jingle transport extension.
+ * {@link ExtensionElement} representing a {@link JingleTransport}.
  * <jingle>
  *     <content>
  *         <description/>

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/JingleElement.java

@@ -25,11 +25,12 @@ import org.jivesoftware.smack.packet.IQ;
 import org.jivesoftware.smack.packet.XMPPError;
 import org.jivesoftware.smack.util.Objects;
 import org.jivesoftware.smack.util.StringUtils;
+import org.jivesoftware.smackx.jingle.component.JingleSession;
 
 import org.jxmpp.jid.FullJid;
 
 /**
- * The Jingle element.
+ * The Jingle element. This represents a {@link JingleSession}.
  * 
  * @author Florian Schmaus
  */
@@ -136,6 +137,12 @@ public final class JingleElement extends IQ {
         return contents;
     }
 
+    /**
+     * If there is only one {@link JingleContentElement}, return it.
+     * If there is none, return null.
+     * Otherwise throw a new {@link IllegalStateException}.
+     * @return jingleContentElement or null.
+     */
     public JingleContentElement getSoleContentOrThrow() {
         if (contents.isEmpty()) {
             return null;

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/UnknownJingleContentDescriptionElement.java

@@ -18,7 +18,12 @@ package org.jivesoftware.smackx.jingle.element;
 
 import org.jivesoftware.smack.packet.StandardExtensionElement;
 import org.jivesoftware.smack.util.XmlStringBuilder;
+import org.jivesoftware.smackx.jingle.provider.JingleContentDescriptionProvider;
 
+/**
+ * Default {@link JingleContentDescriptionElement}, which gets returned, if there is no suitable
+ * {@link JingleContentDescriptionProvider} registered.
+ */
 public final class UnknownJingleContentDescriptionElement extends JingleContentDescriptionElement {
 
     private final StandardExtensionElement standardExtensionElement;
@@ -43,6 +48,10 @@ public final class UnknownJingleContentDescriptionElement extends JingleContentD
         return standardExtensionElement.toXML();
     }
 
+    /**
+     * Return the {@link StandardExtensionElement} which represents this.
+     * @return element.
+     */
     public StandardExtensionElement getStandardExtensionElement() {
         return standardExtensionElement;
     }

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/UnknownJingleContentSecurityElement.java

@@ -18,7 +18,12 @@ package org.jivesoftware.smackx.jingle.element;
 
 import org.jivesoftware.smack.packet.StandardExtensionElement;
 import org.jivesoftware.smack.util.XmlStringBuilder;
+import org.jivesoftware.smackx.jingle.provider.JingleContentSecurityProvider;
 
+/**
+ * Default {@link JingleContentSecurityElement}, which gets returned, if there is no suitable
+ * {@link JingleContentSecurityProvider} registered.
+ */
 public final class UnknownJingleContentSecurityElement extends JingleContentSecurityElement {
 
     private final StandardExtensionElement standardExtensionElement;
@@ -48,6 +53,10 @@ public final class UnknownJingleContentSecurityElement extends JingleContentSecu
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * Return the {@link StandardExtensionElement} which represents this.
+     * @return element.
+     */
     public StandardExtensionElement getStandardExtensionElement() {
         return standardExtensionElement;
     }

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/element/UnknownJingleContentTransportElement.java

@@ -20,7 +20,12 @@ import java.util.List;
 
 import org.jivesoftware.smack.packet.StandardExtensionElement;
 import org.jivesoftware.smack.util.XmlStringBuilder;
+import org.jivesoftware.smackx.jingle.provider.JingleContentTransportProvider;
 
+/**
+ * Default {@link JingleContentTransportElement}, which gets returned, if there is no suitable
+ * {@link JingleContentTransportProvider} registered.
+ */
 public final class UnknownJingleContentTransportElement extends JingleContentTransportElement {
 
     private final StandardExtensionElement standardExtensionElement;
@@ -55,6 +60,10 @@ public final class UnknownJingleContentTransportElement extends JingleContentTra
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * Return the {@link StandardExtensionElement} which represents this.
+     * @return element.
+     */
     public StandardExtensionElement getStandardExtensionElement() {
         return standardExtensionElement;
     }

smack-extensions/src/main/java/org/jivesoftware/smackx/jingle/exception/FailedTransportException.java

@@ -16,8 +16,10 @@
  */
 package org.jivesoftware.smackx.jingle.exception;
 
+import org.jivesoftware.smackx.jingle.component.JingleTransport;
+
 /**
- * Created by vanitas on 25.07.17.
+ * Exception that gets thrown, if we failed to negotiate a {@link JingleTransport}.
  */
 public class FailedTransportException extends Exception {