JavaDoc

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

@@ -25,7 +25,8 @@ package org.jboss.netty.channel;
 
 /**
  * Handles or intercepts a downstream {@link ChannelEvent}, and fires a
- * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
+ * {@link ChannelEvent} to the previous or next handler in a
+ * {@link ChannelPipeline}.
  * <p>
  * A downstream event is an event which is supposed to be processed from the
  * last handler to the first handler in the {@link ChannelPipeline}.
@@ -35,6 +36,32 @@ package org.jboss.netty.channel;
  * In most common use case of this interface is to intercept an I/O request
  * such as {@link Channel#write(Object)} and {@link Channel#close()}.
  *
+ * <h3>Firing an event to the previous or next handler</h3>
+ * <p>
+ * You can forward the received event downstream or upstream.  In most cases,
+ * {@link ChannelDownstreamHandler} will fire the event to the previous handler
+ * (downstream) although it is absolutely normal to fire the event to the next
+ * handler (upstream):
+ *
+ * <pre>
+ * // Sending the event forward (downstream)
+ * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ *     ...
+ *     ctx.sendDownstream(e);
+ *     ...
+ * }
+ *
+ * // Sending the event backward (upstream)
+ * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ *     ...
+ *     ctx.sendUpstream(new DefaultChannelStateEvent(...));
+ *     ...
+ * }
+ * </pre>
+ * <p>
+ * You will also find various helper methods in {@link Channels} to be useful
+ * to generate and fire an artificial or manipulated event.
+ *
  * <h3>Thread safety</h3>
  * <p>
  * {@link #handleDownstream(ChannelHandlerContext, ChannelEvent) handleDownstream}

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

@@ -24,7 +24,8 @@ package org.jboss.netty.channel;
 
 /**
  * Handles or intercepts a {@link ChannelEvent}, and fires a
- * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
+ * {@link ChannelEvent} to the next or previous handler in a
+ * {@link ChannelPipeline}.
  * <p>
  * This is a tag interface.  There are two sub-interfaces which processes
  * a received event actually, one for upstream events and the other for

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

@@ -24,8 +24,71 @@ package org.jboss.netty.channel;
 
 import java.util.Map;
 
+import org.jboss.netty.handler.ssl.SslHandler;
+
 
 /**
+ * A chain of {@link ChannelHandler}s which handles a {@link ChannelEvent}.
+ * Every {@link Channel} has its own pipeline instance.  You can add one or
+ * more {@link ChannelHandler}s to the pipeline to receive I/O events
+ * (e.g. read) and to request I/O operations (e.g. write and close).
+ *
+ * <h3>Thread safety</h3>
+ * <p>
+ * You can also add or remove a {@link ChannelHandler} at any time because a
+ * {@link ChannelPipeline} is thread safe.  For example, you can insert a
+ * {@link SslHandler} when a sensitive information is about to be exchanged,
+ * and remove it after the exchange.
+ *
+ * <h3>How an event flows in a pipeline</h3>
+ * <p>
+ * The following diagram describes how events flows up and down in a
+ * {@link ChannelPipeline} typically:
+ *
+ * <pre>
+ *                                      I/O Request
+ *                                      via Channel
+ *                                           |
+ * +-----------------------------------------+----------------+
+ * |                     ChannelPipeline     |                |
+ * |                                        \|/               |
+ * |   +----------------------+  +-----------+------------+   |
+ * |   | Upstream Handler  N  |  | Downstream Handler  1  |   |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |             /|\                         |                |
+ * |              |                         \|/               |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |   | Upstream Handler N-1 |  | Downstream Handler  2  |   |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |             /|\                         |                |
+ * |              |                         \|/               |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |   | Upstream Handler N-2 |  | Downstream Handler  3  |   |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |              .                          .                |
+ * |              .                          .                |
+ * |             /|\                         |                |
+ * |              |                         \|/               |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |   | Upstream Handler  3  |  | Downstream Handler M-2 |   |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |             /|\                         |                |
+ * |              |                         \|/               |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |   | Upstream Handler  2  |  | Downstream Handler M-1 |   |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |             /|\                         |                |
+ * |              |                         \|/               |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |   | Upstream Handler  1  |  | Downstream Handler  M  |   |
+ * |   +----------+-----------+  +-----------+------------+   |
+ * |             /|\                         |                |
+ * +--------------+--------------------------+----------------+
+ *                |                         \|/
+ * +--------------+--------------------------+----------------+
+ * |         I/O Threads (Transport Implementation)           |
+ * +----------------------------------------------------------+
+ * </pre>
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)

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

@@ -30,7 +30,8 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
 
 /**
  * Handles or intercepts a upstream {@link ChannelEvent}, and fires a
- * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
+ * {@link ChannelEvent} to the next or previous handler in a
+ * {@link ChannelPipeline}.
  * <p>
  * A upstream event is an event which is supposed to be processed from the
  * first handler to the last handler in the {@link ChannelPipeline}.
@@ -41,6 +42,32 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  * directly though, when you want to handle various types of events in more
  * generic way.
  *
+ * <h3>Firing an event to the next or previous handler</h3>
+ * <p>
+ * You can forward the received event upstream or downstream.  In most cases,
+ * {@link ChannelUpstreamHandler} will fire the event to the next handler
+ * (upstream) although it is absolutely normal to fire the event to the
+ * previous handler (downstream):
+ *
+ * <pre>
+ * // Sending the event forward (upstream)
+ * void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ *     ...
+ *     ctx.sendUpstream(e);
+ *     ...
+ * }
+ *
+ * // Sending the event backward (downstream)
+ * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ *     ...
+ *     ctx.sendDownstream(new MessageEvent(...));
+ *     ...
+ * }
+ * </pre>
+ * <p>
+ * You will also find various helper methods in {@link Channels} to be useful
+ * to generate and fire an artificial or manipulated event.
+ *
  * <a name="thread_safety"></a>
  * <h3>Thread safety</h3>
  * <p>