Swift
summaryrefslogtreecommitdiffstats
path: root/src/com
diff options
context:
space:
mode:
authorMili Verma <mili.verma@isode.com>2012-01-06 12:27:41 (GMT)
committerKevin Smith <git@kismith.co.uk>2012-01-12 12:08:21 (GMT)
commitd78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3 (patch)
treeaf6afb653a21f3304dec0f72ee833259f9c1ff02 /src/com
parentbe94e872d9423501c688c84c6cb945a420a5cb18 (diff)
downloadstroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.zip
stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.tar.bz2
Add Javadoc for CoreClient, EventLoop, JID
Test-information: Looks okay.
Diffstat (limited to 'src/com')
-rw-r--r--src/com/isode/stroke/client/CoreClient.java78
-rw-r--r--src/com/isode/stroke/eventloop/EventLoop.java47
-rw-r--r--src/com/isode/stroke/jid/JID.java9
3 files changed, 121 insertions, 13 deletions
diff --git a/src/com/isode/stroke/client/CoreClient.java b/src/com/isode/stroke/client/CoreClient.java
index d4cd430..cc9fd61 100644
--- a/src/com/isode/stroke/client/CoreClient.java
+++ b/src/com/isode/stroke/client/CoreClient.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2010, Isode Limited, London, England.
+ * Copyright (c) 2010-2012, Isode Limited, London, England.
* All rights reserved.
*/
/*
@@ -19,7 +19,6 @@ import com.isode.stroke.network.ConnectionFactory;
import com.isode.stroke.network.Connector;
import com.isode.stroke.network.NetworkFactories;
import com.isode.stroke.network.PlatformDomainNameResolver;
-import com.isode.stroke.network.TimerFactory;
import com.isode.stroke.parser.payloadparsers.FullPayloadParserFactoryCollection;
import com.isode.stroke.queries.IQRouter;
import com.isode.stroke.serializer.payloadserializers.FullPayloadSerializerCollection;
@@ -34,7 +33,6 @@ import com.isode.stroke.tls.CertificateTrustChecker;
import com.isode.stroke.tls.CertificateVerificationError;
import com.isode.stroke.tls.PKCS12Certificate;
import com.isode.stroke.tls.PlatformTLSFactories;
-import com.isode.stroke.tls.TLSContextFactory;
/**
* The central class for communicating with an XMPP server.
@@ -53,6 +51,22 @@ public class CoreClient {
private SignalConnection connectorConnectFinishedConnection_;
private final EventLoop eventLoop_;
+ /**
+ * Constructor.
+ *
+ * @param eventLoop Event loop used by the class, must not be null. The
+ * CoreClient creates threads to do certain tasks. However, it
+ * posts events that it expects to be done in the application's
+ * main thread to this eventLoop. The application should
+ * use an appropriate EventLoop implementation for the application type. This
+ * EventLoop is just a way for the CoreClient to pass these
+ * events back to the main thread, and should not be used by the
+ * application for its own purposes.
+ * @param jid User JID used to connect to the server, must not be null
+ * @param password User password to use, must not be null
+ * @param networkFactories An implementation of network interaction, must
+ * not be null.
+ */
public CoreClient(EventLoop eventLoop, JID jid, String password, NetworkFactories networkFactories) {
jid_ = jid;
password_ = password;
@@ -106,12 +120,24 @@ public class CoreClient {
stanzaChannel_->onStanzaAcked.disconnect(boost::ref(onStanzaAcked));
delete stanzaChannel_;
}*/
+
+ /**
+ * Connect using the standard XMPP connection rules (i.e. SRV then A/AAAA).
+ *
+ * @param o Client options to use in the connection, must not be null
+ */
public void connect(ClientOptions o) {
options = o;
connect(jid_.getDomain());
}
+ /**
+ * Connect to the specified host, overriding the standard lookup rules.
+ *
+ * @param host Host to connect to, non-null.
+ */
public void connect(String host) {
+ options = new ClientOptions();
disconnectRequested_ = false;
assert (connector_ == null);
/* FIXME: Port Proxies */
@@ -185,6 +211,9 @@ public class CoreClient {
}
}
+ /**
+ * Close the stream and disconnect from the server.
+ */
public void disconnect() {
// FIXME: We should be able to do without this boolean. We just have to make sure we can tell the difference between
// connector finishing without a connection due to an error or because of a disconnect.
@@ -334,6 +363,10 @@ public class CoreClient {
stanzaChannel_.sendPresence(presence);
}
+ /**
+ * Get the IQRouter responsible for all IQs on this connection.
+ * Use this to send IQs.
+ */
public IQRouter getIQRouter() {
return iqRouter_;
}
@@ -342,13 +375,18 @@ public class CoreClient {
return stanzaChannel_;
}
+ /**
+ * @return session is available for sending/receiving stanzas.
+ */
public boolean isAvailable() {
return stanzaChannel_.isAvailable();
}
/**
- * Returns the JID of the client.
- * After the session was initialized, this returns the bound JID.
+ * @return JID of the client, will never be null. After the session was
+ * initialized, this returns the bound JID (the JID provided by
+ * the server during resource binding). Prior to this it returns
+ * the JID provided by the user.
*/
public JID getJID() {
if (session_ != null) {
@@ -357,12 +395,42 @@ public class CoreClient {
return jid_;
}
}
+
+ /**
+ * The user should add a listener to this signal, which will be called when
+ * a stream or connection error (not stanza error) occurs.
+ */
public final Signal1<ClientError> onError = new Signal1<ClientError>();
+
+ /**
+ * The user should add a listener to this signal, which will be called when
+ * the connection is established with the server.
+ */
public final Signal onConnected = new Signal();
+
+ /**
+ * The user may add a listener to this signal, which will be called when
+ * data are received from the server. Useful for observing protocol exchange.
+ */
public final Signal1<String> onDataRead = new Signal1<String>();
+
+ /**
+ * The user may add a listener to this signal, which will be called when
+ * data are sent to the server. Useful for observing protocol exchange.
+ */
public final Signal1<String> onDataWritten = new Signal1<String>();
+
+ /**
+ * Called when a message stanza is received.
+ */
public final Signal1<Message> onMessageReceived = new Signal1<Message>();
+ /**
+ * Called when a presence stanza is received.
+ */
public final Signal1<Presence> onPresenceReceived = new Signal1<Presence>();
+ /**
+ * Called when a stanza has been received and acked by a server supporting XEP-0198.
+ */
public final Signal1<Stanza> onStanzaAcked = new Signal1<Stanza>();
private PlatformDomainNameResolver resolver_;
private JID jid_;
diff --git a/src/com/isode/stroke/eventloop/EventLoop.java b/src/com/isode/stroke/eventloop/EventLoop.java
index 145015a..67217b4 100644
--- a/src/com/isode/stroke/eventloop/EventLoop.java
+++ b/src/com/isode/stroke/eventloop/EventLoop.java
@@ -1,26 +1,50 @@
/*
+ * Copyright (c) 2010-2012, Isode Limited, London, England.
+ * All rights reserved.
+ */
+/*
* Copyright (c) 2010 Remko Tronçon
* Licensed under the GNU General Public License v3.
* See Documentation/Licenses/GPLv3.txt for more information.
*/
-/*
- * Copyright (c) 2010, Isode Limited, London, England.
- * All rights reserved.
- */
package com.isode.stroke.eventloop;
import java.util.ArrayList;
import java.util.Vector;
+/**
+ * An event loop is a seemingly infinite loop (runs for the duration of the use
+ * of the library) that waits for external events
+ * (e.g. incoming network packets, timers being activated, input happening) to
+ * happen; when such an event comes in, it notifies interested parties of this
+ * event, and then continues listening for the next event.
+ */
public abstract class EventLoop {
+ /**
+ * Create an event loop
+ */
public EventLoop() {
}
+ /**
+ * Post an event to the loop.
+ *
+ * @param callback Callback handler for the event, must not be null. This
+ * will be called when the event is processed.
+ */
public void postEvent(Event.Callback callback) {
postEvent(callback, null);
}
+ /**
+ * Post an event to the loop.
+ *
+ * @param callback Callback handler for the event, must not be null. This
+ * will be called when the event is processed.
+ * @param owner Owner of the event, non-null. This can be used to
+ * {@link EventLoop#removeEventsFromOwner} later.
+ */
public void postEvent(Event.Callback callback, EventOwner owner) {
Event event;
synchronized (eventsMutex_) {
@@ -31,6 +55,13 @@ public abstract class EventLoop {
post(event);
}
+ /**
+ * Remove all events from the given owner.
+ * \p
+ * This does a reference check (==), not calling owner.equals().
+ *
+ * @param owner Owner of the event, must not be null
+ */
public void removeEventsFromOwner(EventOwner owner) {
synchronized (eventsMutex_) {
ArrayList<Event> matches = new ArrayList<Event>();
@@ -44,11 +75,15 @@ public abstract class EventLoop {
}
/**
- * Reimplement this to call handleEvent(event) from the thread in which
- * the event loop is residing.
+ * Reimplement this to call handleEvent(event) from the thread in which the
+ * event loop is residing.
*/
protected abstract void post(Event event);
+ /**
+ * When reimplementing, call this from within the {@link EventLoop#post}
+ * method in the application's event loop (main thread).
+ */
protected void handleEvent(Event event) {
if (handlingEvents_) {
// We're being called recursively. Push in the list of events to
diff --git a/src/com/isode/stroke/jid/JID.java b/src/com/isode/stroke/jid/JID.java
index 00e210b..a256944 100644
--- a/src/com/isode/stroke/jid/JID.java
+++ b/src/com/isode/stroke/jid/JID.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2010-2011, Isode Limited, London, England.
+ * Copyright (c) 2010-2012, Isode Limited, London, England.
* All rights reserved.
*/
/*
@@ -21,6 +21,11 @@ package com.isode.stroke.jid;
*
* Note that invalid JIDs shouldn't have any calls made to them beyond isValid().
*
+ * JIDs may be invalid if received over the wire, and should be checked with {@link JID#isValid}
+ * before they're used.
+ *
+ * <p>
+ * This is an immutable class.
*/
public class JID {
public enum CompareType {
@@ -129,7 +134,7 @@ public class JID {
/**
* e.g. JID("node@domain").getNode() == "node"
- * @return null for nodeless JIDs.
+ * @return Node, or null for nodeless JIDs.
*/
public String getNode() {
return node_;