JavaDoc
This commit is contained in:
Trustin Lee
parent
47d141ed91
commit
4865bb7d45
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user