* 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()}. * + *
+ * 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): + * + *
+ * // 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(...));
+ * ...
+ * }
+ *
+ * + * You will also find various helper methods in {@link Channels} to be useful + * to generate and fire an artificial or manipulated event. + * *
* {@link #handleDownstream(ChannelHandlerContext, ChannelEvent) handleDownstream} diff --git a/src/main/java/org/jboss/netty/channel/ChannelHandler.java b/src/main/java/org/jboss/netty/channel/ChannelHandler.java index 83c6248807..8a5a88ef0b 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelHandler.java +++ b/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}. *
* This is a tag interface. There are two sub-interfaces which processes * a received event actually, one for upstream events and the other for diff --git a/src/main/java/org/jboss/netty/channel/ChannelPipeline.java b/src/main/java/org/jboss/netty/channel/ChannelPipeline.java index fff977babb..672439be30 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelPipeline.java +++ b/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). + * + *
+ * 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. + * + *
+ * The following diagram describes how events flows up and down in a + * {@link ChannelPipeline} typically: + * + *
+ * 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) | + * +----------------------------------------------------------+ + ** * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java index 481f26569b..329189a2a6 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java +++ b/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}. *
* 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. * + *
+ * 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): + * + *
+ * // 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(...));
+ * ...
+ * }
+ *
+ * + * You will also find various helper methods in {@link Channels} to be useful + * to generate and fire an artificial or manipulated event. + * * *