Javadoc

src/main/java/org/jboss/netty/channel/ChannelFuture.java

@@ -94,10 +94,10 @@ import org.jboss.netty.handler.execution.ExecutionHandler;
  * }
  * </pre>
  * <p>
- * In spite of the disadvantages mentioned above, there are certainly cases
+ * In spite of the disadvantages mentioned above, there are certainly the cases
  * where it is more convenient to call {@link #await()}. In such a case, please
  * make sure you do not call {@link #await()} in an I/O thread.  Otherwise,
- * {@link IllegalStateException} will be raised to avoid a dead lock.
+ * {@link IllegalStateException} will be raised to prevent a dead lock.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)

src/main/java/org/jboss/netty/channel/ChannelFutureListener.java

@@ -29,6 +29,12 @@ import java.util.EventListener;
  * asynchronous {@link Channel} I/O operation is notified once this listener
  * is added by calling {@link ChannelFuture#addListener(ChannelFutureListener)}.
  *
+ * <h3>Return the control to the caller quickly</h3>
+ *
+ * {@link #operationComplete(ChannelFuture)} is directly called by an I/O
+ * thread.  Therefore, performing a time consuming task or a blocking operation
+ * in the handler method can cause an unexpected pause during I/O.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *

src/main/java/org/jboss/netty/channel/ChannelHandler.java

@@ -29,15 +29,17 @@ package org.jboss.netty.channel;
  *
  * <h3>Sub-types</h3>
  * <p>
- * This is a tag interface.  There are two sub-interfaces which process a
- * received event, one for upstream events and the other for downstream events:
+ * {@link ChannelHandler} itself does not provide any method.  To handle a
+ * {@link ChannelEvent} you need to implement its sub-interfaces.  There are
+ * two sub-interfaces which handles a received event, one for upstream events
+ * and the other for downstream events:
  * <ul>
  * <li>{@link ChannelUpstreamHandler} handles and intercepts an upstream {@link ChannelEvent}.</li>
  * <li>{@link ChannelDownstreamHandler} handles and intercepts a downstream {@link ChannelEvent}.</li>
  * </ul>
  *
  * You will also find more detailed explanation from the documentation of
- * each sub-type on how an event is interpreted when it goes upstream and
+ * each sub-interface on how an event is interpreted when it goes upstream and
  * downstream respectively.
  *
  * <h3>The context object</h3>
@@ -46,14 +48,14 @@ package org.jboss.netty.channel;
  * object.  The {@link ChannelHandler} is supposed to interact with the
  * {@link ChannelPipeline} it belongs to via the context object.  Using the
  * context object, the {@link ChannelHandler} can pass events to the next
- * or previous handler or modify the behavior of the pipeline by adding or
+ * or the previous handler or modify the behavior of the pipeline by adding or
  * removing a handler for example.
  *
  * <h3>Additional resources worth reading</h3>
  * <p>
- * Please refer to the {@link ChannelEvent} documentation to find out what a
- * upstream event and a downstream event are and what fundamental differences
- * they have, if you didn't read yet.
+ * Please refer to the {@link ChannelEvent} and {@link ChannelPipeline}
+ * documentation to find out what a upstream event and a downstream event are,
+ * what fundamental differences they have, and how they flow in a pipeline.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -61,6 +63,7 @@ package org.jboss.netty.channel;
  * @version $Rev$, $Date$
  *
  * @apiviz.landmark
+ * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$
  */
 public interface ChannelHandler {
     // This is a tag interface.

src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java

@@ -27,12 +27,36 @@ package org.jboss.netty.channel;
  * {@link ChannelHandler} and the {@link ChannelPipeline} it belongs to.
  * Via a {@link ChannelHandlerContext}, a {@link ChannelHandler} can send
  * an upstream or downstream {@link ChannelEvent} to the next or previous
- * {@link ChannelHandler} in the {@link ChannelPipeline}.
+ * {@link ChannelHandler} in a {@link ChannelPipeline}.
  *
  * <pre>
- * +---------+ 1 .. 1 +----------------+ 1 .. n +----------+ 1 .. 1 +---------+
- * | Handler |------->| HandlerContext |------->| Pipeline |------->| Channel |
- * +---------+        +----------------+        +----------+        +---------+
+ * +---------+ 1 .. 1 +----------+ 1    n +---------+ n    m +---------+
+ * | Channel |--------| Pipeline |--------| Context |--------| Handler |
+ * +---------+        +----------+        +---------+        +---------+
+ *  n = the number of the handler entries in a pipeline
+ * </pre>
+ *
+ * Please note that a {@link ChannelHandler} instance can be added to more than
+ * one {@link ChannelPipeline}.  It means a single {@link ChannelHandler}
+ * instance can have more than one {@link ChannelHandlerContext} and therefore
+ * can be invoked with different {@link ChannelHandlerContext}s if it is added
+ * to one or more {@link ChannelPipeline}s more than once.  For example, the
+ * following handler will have as many independent attachments as how many
+ * times it is added to pipelines, regardless if it is added to the same
+ * pipeline multiple times or added to different pipelines multiple times:
+ * <pre>
+ * public class FibonacciHandler extends SimpleUpstreamChannelHandler {
+ *   public void messageReceived(ChannelHandlerContext ctx, MessageEvent evt) {
+ *     Integer a = (Integer) ctx.getAttachment();
+ *     Integer b = (Integer) evt.getMessage();
+ *
+ *     if (a == null) {
+ *       a = 0;
+ *     }
+ *
+ *     ctx.setAttachment(Integer.valueOf(a + b));
+ *   }
+ * }
  * </pre>
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)

src/main/java/org/jboss/netty/channel/group/ChannelGroupFuture.java

@@ -106,10 +106,10 @@ import org.jboss.netty.handler.execution.ExecutionHandler;
  * }
  * </pre>
  * <p>
- * In spite of the disadvantages mentioned above, there are certainly cases
+ * In spite of the disadvantages mentioned above, there are certainly the cases
  * where it is more convenient to call {@link #await()}. In such a case, please
  * make sure you do not call {@link #await()} in an I/O thread.  Otherwise,
- * {@link IllegalStateException} will be raised to avoid a dead lock.
+ * {@link IllegalStateException} will be raised to prevent a dead lock.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)