Swiftdiff options
| 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 | |
| parent | be94e872d9423501c688c84c6cb945a420a5cb18 (diff) | |
| download | stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.zip stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.tar.bz2 | |
Add Javadoc for CoreClient, EventLoop, JID
Test-information:
Looks okay.
| -rw-r--r-- | src/com/isode/stroke/client/CoreClient.java | 78 | ||||
| -rw-r--r-- | src/com/isode/stroke/eventloop/EventLoop.java | 47 | ||||
| -rw-r--r-- | src/com/isode/stroke/jid/JID.java | 9 |
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_; |