This commit is contained in:
Trustin Lee 2008-09-01 15:19:34 +00:00
parent 47d141ed91
commit 4865bb7d45
4 changed files with 121 additions and 3 deletions

View File

@ -25,7 +25,8 @@ package org.jboss.netty.channel;
/** /**
* Handles or intercepts a downstream {@link ChannelEvent}, and fires a * 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> * <p>
* A downstream event is an event which is supposed to be processed from the * A downstream event is an event which is supposed to be processed from the
* last handler to the first handler in the {@link ChannelPipeline}. * 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 * 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()}. * 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> * <h3>Thread safety</h3>
* <p> * <p>
* {@link #handleDownstream(ChannelHandlerContext, ChannelEvent) handleDownstream} * {@link #handleDownstream(ChannelHandlerContext, ChannelEvent) handleDownstream}

View File

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

View File

@ -24,8 +24,71 @@ package org.jboss.netty.channel;
import java.util.Map; 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 The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com) * @author Trustin Lee (tlee@redhat.com)

View File

@ -30,7 +30,8 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
/** /**
* Handles or intercepts a upstream {@link ChannelEvent}, and fires a * 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> * <p>
* A upstream event is an event which is supposed to be processed from the * A upstream event is an event which is supposed to be processed from the
* first handler to the last handler in the {@link ChannelPipeline}. * 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 * directly though, when you want to handle various types of events in more
* generic way. * 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> * <a name="thread_safety"></a>
* <h3>Thread safety</h3> * <h3>Thread safety</h3>
* <p> * <p>