1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-11-14 16:22:07 +01:00

More javadoc

This commit is contained in:
vanitasvitae 2017-08-25 19:42:19 +02:00
parent 5f1d2a7f20
commit d088233153
Signed by: vanitasvitae
GPG key ID: 62BEE9264BF17311
14 changed files with 267 additions and 10 deletions

View file

@ -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();
}

View file

@ -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);
}

View file

@ -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()));
}

View file

@ -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.

View file

@ -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.
* ...

View file

@ -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/>

View file

@ -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 {

View file

@ -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/>

View file

@ -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/>

View file

@ -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;

View file

@ -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;
}

View file

@ -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;
}

View file

@ -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;
}

View file

@ -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 {