Add Javadoc for CoreClient, EventLoop, JID

Test-information: Looks okay.
author: Mili Verma <mili.verma@isode.com> 2012-01-06 12:27:41 (GMT)
committer: Kevin Smith <git@kismith.co.uk> 2012-01-12 12:08:21 (GMT)
commit: d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3 (patch)
tree: af6afb653a21f3304dec0f72ee833259f9c1ff02 /src
parent: be94e872d9423501c688c84c6cb945a420a5cb18 (diff)
download: stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.zip
stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.tar.bz2
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_;
author	Mili Verma <mili.verma@isode.com>	2012-01-06 12:27:41 (GMT)
committer	Kevin Smith <git@kismith.co.uk>	2012-01-12 12:08:21 (GMT)
commit	d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3 (patch)
tree	af6afb653a21f3304dec0f72ee833259f9c1ff02 /src
parent	be94e872d9423501c688c84c6cb945a420a5cb18 (diff)
download	stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.zip stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.tar.bz2