Improved ChannelPipeline documentation

This commit is contained in:
Trustin Lee 2008-09-03 01:48:08 +00:00
parent a73cdb1a4a
commit 78075ad7fc

View File

@ -33,57 +33,66 @@ import org.jboss.netty.handler.ssl.SslHandler;
/** /**
* A list of {@link ChannelHandler}s which handles or intercepts * A list of {@link ChannelHandler}s which handles or intercepts
* {@link ChannelEvent}s of a {@link Channel}. * {@link ChannelEvent}s of a {@link Channel}. {@link ChannelPipeline}
* <p> * implements an advanced form of the
* {@link ChannelPipeline} implements an advanced form of the
* <a href="http://java.sun.com/blueprints/corej2eepatterns/Patterns/InterceptingFilter.html">Intercepting * <a href="http://java.sun.com/blueprints/corej2eepatterns/Patterns/InterceptingFilter.html">Intercepting
* Filter</a> pattern to give a user full control over how an event is handled * Filter</a> pattern to give a user full control over how an event is handled
* and how the {@link ChannelHandler}s in the pipeline interact with each other. * and how the {@link ChannelHandler}s in the pipeline interact with each other.
* *
* <h3>Creation of a pipeline</h3>
* <p>
* It is recommended to create a new pipeline using the helper methods in
* {@link Channels} rather than calling an individual implementation's
* constructor.
*
* <h3>How an event flows in a pipeline</h3> * <h3>How an event flows in a pipeline</h3>
* <p> * <p>
* The following diagram describes how {@link ChannelEvent}s are processed by * The following diagram describes how {@link ChannelEvent}s are processed by
* {@link ChannelHandler}s in a {@link ChannelPipeline} typically. * {@link ChannelHandler}s in a {@link ChannelPipeline} typically.
* A {@link ChannelEvent} can be handled by either a {@link ChannelUpstreamHandler} * A {@link ChannelEvent} can be handled by either a {@link ChannelUpstreamHandler}
* or a {@link ChannelDownstreamHandler}. The meaning of the event is * or a {@link ChannelDownstreamHandler} and be forwarded to the next or
* interpreted somewhat differently depending on whether it's going upstream or * previous handler by calling {@link ChannelHandlerContext#sendUpstream(ChannelEvent)}
* going downstream. Please refer to the {@link ChannelEvent} documentation * or {@link ChannelHandlerContext#sendDownstream(ChannelEvent)}. The meaning
* for more explanation. * of the event is interpreted somewhat differently depending on whether it's
* going upstream or going downstream. Please refer to {@link ChannelEvent} for
* more explanation.
* *
* <pre> * <pre>
* I/O Request *
* via Channel * I/O Request
* | * via {@link Channel} or
* +-----------------------------------------+----------------+ * {@link ChannelHandlerContext}
* | ChannelPipeline | | * |
* | \|/ | * +-----------------------------------------+----------------+
* | +----------------------+ +-----------+------------+ | * | ChannelPipeline | |
* | | Upstream Handler N | | Downstream Handler 1 | | * | \|/ |
* | +----------+-----------+ +-----------+------------+ | * | +----------------------+ +-----------+------------+ |
* | /|\ | | * | | Upstream Handler N | | Downstream Handler 1 | |
* | | \|/ | * | +----------+-----------+ +-----------+------------+ |
* | +----------+-----------+ +-----------+------------+ | * | /|\ | |
* | | Upstream Handler N-1 | | Downstream Handler 2 | | * | | \|/ |
* | +----------+-----------+ +-----------+------------+ | * | +----------+-----------+ +-----------+------------+ |
* | /|\ . | * | | Upstream Handler N-1 | | Downstream Handler 2 | |
* | . . | * | +----------+-----------+ +-----------+------------+ |
* | [ Going Upstream ] [ Going Downstream ] | * | /|\ . |
* | . . | * | . . |
* | . \|/ | * | [ Going Upstream ] [ Going Downstream ] |
* | +----------+-----------+ +-----------+------------+ | * | . . |
* | | Upstream Handler 2 | | Downstream Handler M-1 | | * | . \|/ |
* | +----------+-----------+ +-----------+------------+ | * | +----------+-----------+ +-----------+------------+ |
* | /|\ | | * | | Upstream Handler 2 | | Downstream Handler M-1 | |
* | | \|/ | * | +----------+-----------+ +-----------+------------+ |
* | +----------+-----------+ +-----------+------------+ | * | /|\ | |
* | | Upstream Handler 1 | | Downstream Handler M | | * | | \|/ |
* | +----------+-----------+ +-----------+------------+ | * | +----------+-----------+ +-----------+------------+ |
* | /|\ | | * | | Upstream Handler 1 | | Downstream Handler M | |
* +--------------+--------------------------+----------------+ * | +----------+-----------+ +-----------+------------+ |
* | \|/ * | /|\ | |
* +--------------+--------------------------+----------------+ * +--------------+--------------------------+----------------+
* | I/O Threads (Transport Implementation) | * | \|/
* +----------------------------------------------------------+ * +--------------+--------------------------+----------------+
* | I/O Threads (Transport Implementation) |
* +----------------------------------------------------------+
* </pre> * </pre>
* *
* <h3>Building a pipeline</h3> * <h3>Building a pipeline</h3>