From 2a1be6a67f327e4aa8dc65e63b29b318efa39ad2 Mon Sep 17 00:00:00 2001 From: Naoyuki Kanezawa Date: Sun, 5 May 2013 02:30:28 +0900 Subject: [PATCH] add comments --- pom.xml | 9 -- .../com/github/nkzawa/emitter/Emitter.java | 56 ++++++++++++ .../github/nkzawa/engineio/client/Socket.java | 91 +++++++++++++++++-- 3 files changed, 140 insertions(+), 16 deletions(-) diff --git a/pom.xml b/pom.xml index 5ac5a15..93fe2db 100644 --- a/pom.xml +++ b/pom.xml @@ -41,15 +41,6 @@ 1.6 - - org.apache.maven.plugins - maven-javadoc-plugin - 2.9 - - protected - Engine.IO Client API - - org.apache.maven.plugins maven-surefire-plugin diff --git a/src/main/java/com/github/nkzawa/emitter/Emitter.java b/src/main/java/com/github/nkzawa/emitter/Emitter.java index 0aa2039..7a65617 100644 --- a/src/main/java/com/github/nkzawa/emitter/Emitter.java +++ b/src/main/java/com/github/nkzawa/emitter/Emitter.java @@ -7,6 +7,12 @@ import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentLinkedQueue; import java.util.concurrent.ConcurrentMap; + +/** + * The event emitter which is ported from the JavaScript module. + * + * @see https://github.com/component/emitter + */ public class Emitter { private ConcurrentMap> callbacks @@ -15,6 +21,12 @@ public class Emitter { private ConcurrentMap onceCallbacks = new ConcurrentHashMap(); + /** + * Listens on the event. + * @param event event name. + * @param fn + * @return a reference to to this object. + */ public Emitter on(String event, Listener fn) { ConcurrentLinkedQueue callbacks = this.callbacks.get(event); if (callbacks == null) { @@ -28,6 +40,13 @@ public class Emitter { return this; } + /** + * Adds a one time listener for the event. + * + * @param event + * @param fn + * @return a reference to to this object. + */ public Emitter once(final String event, final Listener fn) { Listener on = new Listener() { @Override @@ -42,12 +61,23 @@ public class Emitter { return this; } + /** + * Removes all registered listeners. + * + * @return a reference to to this object. + */ public Emitter off() { this.callbacks.clear(); this.onceCallbacks.clear(); return this; } + /** + * Removes all listeners of the specified event. + * + * @param event + * @return a reference to to this object. + */ public Emitter off(String event) { ConcurrentLinkedQueue callbacks = this.callbacks.remove(event); if (callbacks != null) { @@ -58,6 +88,13 @@ public class Emitter { return this; } + /** + * Removes the listener. + * + * @param event + * @param fn + * @return a reference to to this object. + */ public Emitter off(String event, Listener fn) { ConcurrentLinkedQueue callbacks = this.callbacks.get(event); if (callbacks != null) { @@ -67,6 +104,13 @@ public class Emitter { return this; } + /** + * Executes each of listeners with the given args. + * + * @param event + * @param args + * @return a reference to to this object. + */ public Emitter emit(String event, Object... args) { ConcurrentLinkedQueue callbacks = this.callbacks.get(event); if (callbacks != null) { @@ -78,12 +122,24 @@ public class Emitter { return this; } + /** + * Returns a list of listeners for the specified event. + * + * @param event + * @return a reference to to this object. + */ public List listeners(String event) { ConcurrentLinkedQueue callbacks = this.callbacks.get(event); return callbacks != null ? new ArrayList(callbacks) : new ArrayList(); } + /** + * Check if this emitter has listeners for the specified event. + * + * @param event + * @return a reference to to this object. + */ public boolean hasListeners(String event) { return !this.listeners(event).isEmpty(); } diff --git a/src/main/java/com/github/nkzawa/engineio/client/Socket.java b/src/main/java/com/github/nkzawa/engineio/client/Socket.java index 1971437..2e6ea65 100644 --- a/src/main/java/com/github/nkzawa/engineio/client/Socket.java +++ b/src/main/java/com/github/nkzawa/engineio/client/Socket.java @@ -15,6 +15,12 @@ import java.util.*; import java.util.concurrent.*; import java.util.logging.Logger; + +/** + * The socket class for Event.IO Client. + * + * @see https://github.com/LearnBoost/engine.io-client + */ public abstract class Socket extends Emitter { private static final Logger logger = Logger.getLogger(Socket.class.getName()); @@ -32,8 +38,36 @@ public abstract class Socket extends Emitter { put(CLOSED, "closed"); }}; + /** + * Called on successful connection. + */ public static final String EVENT_OPEN = "open"; + + /** + * Called on disconnection. + */ public static final String EVENT_CLOSE = "close"; + + /** + * Called when data is received from the server. + */ + public static final String EVENT_MESSAGE = "message"; + + /** + * Called when an error occurs. + */ + public static final String EVENT_ERROR = "error"; + + /** + * Called on completing a buffer flush. + */ + public static final String EVENT_FLUSH = "flush"; + + /** + * Called after `drain` event of transport if writeBuffer is empty. + */ + public static final String EVENT_DRAIN = "drain"; + public static final String EVENT_HANDSHAKE = "handshake"; public static final String EVENT_UPGRADING = "upgrading"; public static final String EVENT_UPGRADE = "upgrade"; @@ -41,17 +75,20 @@ public abstract class Socket extends Emitter { public static final String EVENT_PACKET_CREATE = "packetCreate"; public static final String EVENT_HEARTBEAT = "heartbeat"; public static final String EVENT_DATA = "data"; - public static final String EVENT_MESSAGE = "message"; - public static final String EVENT_ERROR = "error"; - public static final String EVENT_DRAIN = "drain"; - public static final String EVENT_FLUSH = "flush"; private static final Runnable noop = new Runnable() { @Override public void run() {} }; + /** + * List of Socket instances. + */ public static final Sockets sockets = new Sockets(); + + /** + * The protocol version. + */ public static final int protocol = Parser.protocol; private boolean secure; @@ -80,6 +117,12 @@ public abstract class Socket extends Emitter { private ScheduledExecutorService heartbeatScheduler = Executors.newSingleThreadScheduledExecutor(); + /** + * Creates a socket. + * + * @param uri URI to connect. + * @throws URISyntaxException + */ public Socket(String uri) throws URISyntaxException { this(uri, null); } @@ -88,6 +131,13 @@ public abstract class Socket extends Emitter { this(uri, null); } + /** + * Creates a socket with options. + * + * @param uri URI to connect. + * @param opts options for socket + * @throws URISyntaxException + */ public Socket(String uri, Options opts) throws URISyntaxException { this(new URI(uri), opts); } @@ -115,13 +165,16 @@ public abstract class Socket extends Emitter { this.timestampParam = opts.timestampParam != null ? opts.timestampParam : "t"; this.timestampRequests = opts.timestampRequests; this.transports = new ArrayList(Arrays.asList(opts.transports != null ? - opts.transports : new String[] {Polling.NAME, WebSocket.NAME})); + opts.transports : new String[]{Polling.NAME, WebSocket.NAME})); this.policyPort = opts.policyPort != 0 ? opts.policyPort : 843; Socket.sockets.add(this); Socket.sockets.evs.emit(Sockets.EVENT_ADD, this); } + /** + * Connects the client. + */ public void open() { this.readyState = OPENING; Transport transport = this.createTransport(this.transports.get(0)); @@ -434,10 +487,21 @@ public abstract class Socket extends Emitter { this.send(msg, fn); } + /** + * Sends a message. + * + * @param msg + */ public void send(String msg) { this.send(msg, null); } + /** + * Sends a message. + * + * @param msg + * @param fn callback to be called on drain + */ public void send(String msg, Runnable fn) { this.sendPacket(Packet.MESSAGE, msg, fn); } @@ -459,6 +523,11 @@ public abstract class Socket extends Emitter { this.flush(); } + /** + * Disconnects the client. + * + * @return a reference to to this object. + */ public Socket close() { if (this.readyState == OPENING || this.readyState == OPEN) { this.onClose("forced close"); @@ -524,10 +593,18 @@ public abstract class Socket extends Emitter { public static class Options extends Transport.Options { + /** + * List of transport names. + */ + public String[] transports; + + /** + * Whether to upgrade the transport. Defaults to `true`. + */ + public boolean upgrade = true; + public String host; public String query; - public String[] transports; - public boolean upgrade = true; private static Options fromURI(URI uri, Options opts) {