Some comments added to AckCallback & AckRequest. Issue #30

src/main/java/com/corundumstudio/socketio/AckCallback.java

@@ -15,12 +15,20 @@
  */
 package com.corundumstudio.socketio;
 
+
 /**
  * Base ack callback class.
  *
  * Notifies about acknowledgement received from client
  * via {@link #onSuccess} callback method.
  *
+ * By default it may wait acknowledgement from client
+ * while {@link SocketIOClient} is alive. Timeout can be
+ * defined {@link #timeout} as constructor argument.
+ *
+ * This object is NOT actual anymore if {@link #onSuccess} or
+ * {@link #onTimeout} was executed.
+ *
  * @param <T> - any serializable type
  */
 public abstract class AckCallback<T> {
@@ -52,6 +60,11 @@ public abstract class AckCallback<T> {
         return timeout;
     }
 
+    /**
+     * Executes only once when acknowledgement received from client.
+     *
+     * @param result - object sended by client
+     */
     public abstract void onSuccess(T result);
 
     /**

src/main/java/com/corundumstudio/socketio/AckRequest.java

@@ -19,6 +19,7 @@ import java.util.Arrays;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicBoolean;
 
+import com.corundumstudio.socketio.listener.DataListener;
 import com.corundumstudio.socketio.parser.Packet;
 import com.corundumstudio.socketio.parser.PacketType;
 
@@ -27,6 +28,14 @@ import com.corundumstudio.socketio.parser.PacketType;
  * You can always check is it <code>true<code> through
  * {@link #isAckRequested()} method.
  *
+ * You can call {@link #sendAckData} methods only during
+ * {@link DataListener#onData} invocation. If {@link #sendAckData}
+ * not called it will be invoked with empty arguments right after
+ * {@link DataListener#onData} method execution by server.
+ *
+ * This object is NOT actual anymore if {@link #sendAckData} was
+ * executed or {@link DataListener#onData} invocation finished.
+ *
  */
 public class AckRequest {
 
@@ -50,7 +59,8 @@ public class AckRequest {
 
     /**
      * Send ack data to client.
-     * Can be invoked only once.
+     * Can be invoked only once during {@link DataListener#onData}
+     * method invocation.
      *
      * @param objs - ack data objects
      */
@@ -61,7 +71,8 @@ public class AckRequest {
 
     /**
      * Send ack data to client.
-     * Can be invoked only once.
+     * Can be invoked only once during {@link DataListener#onData}
+     * method invocation.
      *
      * @param objs - ack data object list
      */

src/main/java/com/corundumstudio/socketio/handler/PacketHandler.java

@@ -70,6 +70,9 @@ public class PacketHandler extends SimpleChannelUpstreamHandler {
                 SocketIOClient client = message.getClient().getChildClient(ns);
                 AckRequest ackSender = new AckRequest(packet, client);
                 packetListener.onPacket(packet, client, ackSender);
+
+                // send ack response if it not executed
+				// during {@link DataListener#onData} invocation
                 ackSender.sendAckData(Collections.emptyList());
             }
         } else {