public interface ChannelPipeline
ChannelHandler
s which handles or intercepts
ChannelEvent
s of a Channel
. ChannelPipeline
implements an advanced form of the
Intercepting
Filter pattern to give a user full control over how an event is handled
and how the ChannelHandler
s in the pipeline interact with each other.
The recommended way to create a new pipeline is to use the helper methods in
Channels
rather than calling an individual implementation's
constructor:
import static org.jboss.netty.channel.Channels
.*;ChannelPipeline
pipeline = pipeline(); // same with Channels.pipeline()
ChannelEvent
s are processed by
ChannelHandler
s in a ChannelPipeline
typically.
A ChannelEvent
can be handled by either a ChannelUpstreamHandler
or a ChannelDownstreamHandler
and be forwarded to the closest
handler by calling ChannelHandlerContext.sendUpstream(ChannelEvent)
or ChannelHandlerContext.sendDownstream(ChannelEvent)
. The meaning
of the event is interpreted somewhat differently depending on whether it is
going upstream or going downstream. Please refer to ChannelEvent
for
more information.
I/O Request viaAn upstream event is handled by the upstream handlers in the bottom-up direction as shown on the left side of the diagram. An upstream handler usually handles the inbound data generated by the I/O thread on the bottom of the diagram. The inbound data is often read from a remote peer via the actual input operation such asChannel
orChannelHandlerContext
| +----------------------------------------+---------------+ | ChannelPipeline | | | \|/ | | +----------------------+ +-----------+------------+ | | | Upstream Handler N | | Downstream Handler 1 | | | +----------+-----------+ +-----------+------------+ | | /|\ | | | | \|/ | | +----------+-----------+ +-----------+------------+ | | | Upstream Handler N-1 | | Downstream Handler 2 | | | +----------+-----------+ +-----------+------------+ | | /|\ . | | . . | | [ sendUpstream() ] [ sendDownstream() ] | | [ + INBOUND data ] [ + OUTBOUND data ] | | . . | | . \|/ | | +----------+-----------+ +-----------+------------+ | | | Upstream Handler 2 | | Downstream Handler M-1 | | | +----------+-----------+ +-----------+------------+ | | /|\ | | | | \|/ | | +----------+-----------+ +-----------+------------+ | | | Upstream Handler 1 | | Downstream Handler M | | | +----------+-----------+ +-----------+------------+ | | /|\ | | +-------------+--------------------------+---------------+ | \|/ +-------------+--------------------------+---------------+ | | | | | [ Socket.read() ] [ Socket.write() ] | | | | Netty Internal I/O Threads (Transport Implementation) | +--------------------------------------------------------+
InputStream.read(byte[])
.
If an upstream event goes beyond the top upstream handler, it is discarded
silently.
A downstream event is handled by the downstream handler in the top-down
direction as shown on the right side of the diagram. A downstream handler
usually generates or transforms the outbound traffic such as write requests.
If a downstream event goes beyond the bottom downstream handler, it is
handled by an I/O thread associated with the Channel
. The I/O thread
often performs the actual output operation such as OutputStream.write(byte[])
.
For example, let us assume that we created the following pipeline:
In the example above, the class whose name starts withChannelPipeline
p =Channels
.pipeline(); p.addLast("1", new UpstreamHandlerA()); p.addLast("2", new UpstreamHandlerB()); p.addLast("3", new DownstreamHandlerA()); p.addLast("4", new DownstreamHandlerB()); p.addLast("5", new UpstreamHandlerX());
Upstream
means
it is an upstream handler. The class whose name starts with
Downstream
means it is a downstream handler.
In the given example configuration, the handler evaluation order is 1, 2, 3,
4, 5 when an event goes upstream. When an event goes downstream, the order
is 5, 4, 3, 2, 1. On top of this principle, ChannelPipeline
skips
the evaluation of certain handlers to shorten the stack depth:
ChannelUpstreamHandler
, and therefore the
actual evaluation order of an upstream event will be: 1, 2, and 5.ChannelDownstreamHandler
, and
therefore the actual evaluation order of a downstream event will be:
4 and 3.SimpleChannelHandler
which implements both
ChannelUpstreamHandler
and ChannelDownstreamHandler
, the
evaluation order of an upstream and a downstream event could be 125 and
543 respectively.
A user is supposed to have one or more ChannelHandler
s in a
pipeline to receive I/O events (e.g. read) and to request I/O operations
(e.g. write and close). For example, a typical server will have the following
handlers in each channel's pipeline, but your mileage may vary depending on
the complexity and characteristics of the protocol and business logic:
ChannelBuffer
)
into a Java object.ExecutionHandler
- applies a thread model.ChannelPipeline
pipeline =Channels.pipeline()
; pipeline.addLast("decoder", new MyProtocolDecoder()); pipeline.addLast("encoder", new MyProtocolEncoder()); pipeline.addLast("executor", newExecutionHandler
( newOrderedMemoryAwareThreadPoolExecutor
(16, 1048576, 1048576))); pipeline.addLast("handler", new MyBusinessLogicHandler());
A ChannelHandler
can be added or removed at any time because a
ChannelPipeline
is thread safe. For example, you can insert a
SslHandler
when sensitive information is about to be exchanged,
and remove it after the exchange.
Due to the internal implementation detail of the current default
ChannelPipeline
, the following code does not work as expected if
FirstHandler is the last handler in the pipeline:
public class FirstHandler extendsTo implement the expected behavior, you have to add SecondHandler before the removal or make sure there is at least one more handler between FirstHandler and SecondHandler.SimpleChannelUpstreamHandler
{@Override
public void messageReceived(ChannelHandlerContext
ctx,MessageEvent
e) { // Remove this handler from the pipeline, ctx.getPipeline().remove(this); // And let SecondHandler handle the current event. ctx.getPipeline().addLast("2nd", new SecondHandler()); ctx.sendUpstream(e); } }
Modifier and Type | Method and Description |
---|---|
void |
addAfter(String baseName,
String name,
ChannelHandler handler)
Inserts a
ChannelHandler after an existing handler of this
pipeline. |
void |
addBefore(String baseName,
String name,
ChannelHandler handler)
Inserts a
ChannelHandler before an existing handler of this
pipeline. |
void |
addFirst(String name,
ChannelHandler handler)
Inserts a
ChannelHandler at the first position of this pipeline. |
void |
addLast(String name,
ChannelHandler handler)
Appends a
ChannelHandler at the last position of this pipeline. |
void |
attach(Channel channel,
ChannelSink sink)
Attaches this pipeline to the specified
Channel and
ChannelSink . |
ChannelFuture |
execute(Runnable task)
Schedules the specified task to be executed in the I/O thread associated
with this pipeline's
Channel . |
<T extends ChannelHandler> |
get(Class<T> handlerType)
Returns the
ChannelHandler of the specified type in this
pipeline. |
ChannelHandler |
get(String name)
Returns the
ChannelHandler with the specified name in this
pipeline. |
Channel |
getChannel()
Returns the
Channel that this pipeline is attached to. |
ChannelHandlerContext |
getContext(ChannelHandler handler)
Returns the context object of the specified
ChannelHandler in
this pipeline. |
ChannelHandlerContext |
getContext(Class<? extends ChannelHandler> handlerType)
Returns the context object of the
ChannelHandler of the
specified type in this pipeline. |
ChannelHandlerContext |
getContext(String name)
Returns the context object of the
ChannelHandler with the
specified name in this pipeline. |
ChannelHandler |
getFirst()
Returns the first
ChannelHandler in this pipeline. |
ChannelHandler |
getLast()
Returns the last
ChannelHandler in this pipeline. |
List<String> |
getNames()
Returns the
List of the handler names. |
ChannelSink |
getSink()
Returns the
ChannelSink that this pipeline is attached to. |
boolean |
isAttached()
Returns
true if and only if this pipeline is attached to
a Channel . |
void |
remove(ChannelHandler handler)
Removes the specified
ChannelHandler from this pipeline. |
<T extends ChannelHandler> |
remove(Class<T> handlerType)
Removes the
ChannelHandler of the specified type from this
pipeline |
ChannelHandler |
remove(String name)
Removes the
ChannelHandler with the specified name from this
pipeline. |
ChannelHandler |
removeFirst()
Removes the first
ChannelHandler in this pipeline. |
ChannelHandler |
removeLast()
Removes the last
ChannelHandler in this pipeline. |
void |
replace(ChannelHandler oldHandler,
String newName,
ChannelHandler newHandler)
Replaces the specified
ChannelHandler with a new handler in
this pipeline. |
<T extends ChannelHandler> |
replace(Class<T> oldHandlerType,
String newName,
ChannelHandler newHandler)
Replaces the
ChannelHandler of the specified type with a new
handler in this pipeline. |
ChannelHandler |
replace(String oldName,
String newName,
ChannelHandler newHandler)
Replaces the
ChannelHandler of the specified name with a new
handler in this pipeline. |
void |
sendDownstream(ChannelEvent e)
Sends the specified
ChannelEvent to the last
ChannelDownstreamHandler in this pipeline. |
void |
sendUpstream(ChannelEvent e)
Sends the specified
ChannelEvent to the first
ChannelUpstreamHandler in this pipeline. |
Map<String,ChannelHandler> |
toMap()
Converts this pipeline into an ordered
Map whose keys are
handler names and whose values are handlers. |
void addFirst(String name, ChannelHandler handler)
ChannelHandler
at the first position of this pipeline.name
- the name of the handler to insert firsthandler
- the handler to insert firstIllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified name or handler is null
void addLast(String name, ChannelHandler handler)
ChannelHandler
at the last position of this pipeline.name
- the name of the handler to appendhandler
- the handler to appendIllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified name or handler is null
void addBefore(String baseName, String name, ChannelHandler handler)
ChannelHandler
before an existing handler of this
pipeline.baseName
- the name of the existing handlername
- the name of the handler to insert beforehandler
- the handler to insert beforeNoSuchElementException
- if there's no such entry with the specified baseName
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified baseName, name, or handler is null
void addAfter(String baseName, String name, ChannelHandler handler)
ChannelHandler
after an existing handler of this
pipeline.baseName
- the name of the existing handlername
- the name of the handler to insert afterhandler
- the handler to insert afterNoSuchElementException
- if there's no such entry with the specified baseName
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified baseName, name, or handler is null
void remove(ChannelHandler handler)
ChannelHandler
from this pipeline.NoSuchElementException
- if there's no such handler in this pipelineNullPointerException
- if the specified handler is null
ChannelHandler remove(String name)
ChannelHandler
with the specified name from this
pipeline.NoSuchElementException
- if there's no such handler with the specified name in this pipelineNullPointerException
- if the specified name is null
<T extends ChannelHandler> T remove(Class<T> handlerType)
ChannelHandler
of the specified type from this
pipelineT
- the type of the handlerhandlerType
- the type of the handlerNoSuchElementException
- if there's no such handler of the specified type in this pipelineNullPointerException
- if the specified handler type is null
ChannelHandler removeFirst()
ChannelHandler
in this pipeline.NoSuchElementException
- if this pipeline is emptyChannelHandler removeLast()
ChannelHandler
in this pipeline.NoSuchElementException
- if this pipeline is emptyvoid replace(ChannelHandler oldHandler, String newName, ChannelHandler newHandler)
ChannelHandler
with a new handler in
this pipeline.NoSuchElementException
- if the specified old handler does not exist in this pipelineIllegalArgumentException
- if a handler with the specified new name already exists in this
pipeline, except for the handler to be replacedNullPointerException
- if the specified old handler, new name, or new handler is
null
ChannelHandler replace(String oldName, String newName, ChannelHandler newHandler)
ChannelHandler
of the specified name with a new
handler in this pipeline.NoSuchElementException
- if the handler with the specified old name does not exist in this pipelineIllegalArgumentException
- if a handler with the specified new name already exists in this
pipeline, except for the handler to be replacedNullPointerException
- if the specified old handler, new name, or new handler is
null
<T extends ChannelHandler> T replace(Class<T> oldHandlerType, String newName, ChannelHandler newHandler)
ChannelHandler
of the specified type with a new
handler in this pipeline.NoSuchElementException
- if the handler of the specified old handler type does not exist
in this pipelineIllegalArgumentException
- if a handler with the specified new name already exists in this
pipeline, except for the handler to be replacedNullPointerException
- if the specified old handler, new name, or new handler is
null
ChannelHandler getFirst()
ChannelHandler
in this pipeline.null
if this pipeline is empty.ChannelHandler getLast()
ChannelHandler
in this pipeline.null
if this pipeline is empty.ChannelHandler get(String name)
ChannelHandler
with the specified name in this
pipeline.null
if there's no such handler in this pipeline.<T extends ChannelHandler> T get(Class<T> handlerType)
ChannelHandler
of the specified type in this
pipeline.null
if there's no such handler in this pipeline.ChannelHandlerContext getContext(ChannelHandler handler)
ChannelHandler
in
this pipeline.null
if there's no such handler in this pipeline.ChannelHandlerContext getContext(String name)
ChannelHandler
with the
specified name in this pipeline.null
if there's no such handler in this pipeline.ChannelHandlerContext getContext(Class<? extends ChannelHandler> handlerType)
ChannelHandler
of the
specified type in this pipeline.null
if there's no such handler in this pipeline.void sendUpstream(ChannelEvent e)
ChannelEvent
to the first
ChannelUpstreamHandler
in this pipeline.NullPointerException
- if the specified event is null
void sendDownstream(ChannelEvent e)
ChannelEvent
to the last
ChannelDownstreamHandler
in this pipeline.NullPointerException
- if the specified event is null
ChannelFuture execute(Runnable task)
Channel
.Channel getChannel()
Channel
that this pipeline is attached to.null
if this pipeline is not attached yet.ChannelSink getSink()
ChannelSink
that this pipeline is attached to.null
if this pipeline is not attached yet.void attach(Channel channel, ChannelSink sink)
Channel
and
ChannelSink
. Once a pipeline is attached, it can't be detached
nor attached again.IllegalStateException
- if this pipeline is attached alreadyboolean isAttached()
true
if and only if this pipeline is attached to
a Channel
.Map<String,ChannelHandler> toMap()
Map
whose keys are
handler names and whose values are handlers.Copyright © 2008-2014 The Netty Project. All Rights Reserved.