|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface ChannelPipeline
A list of 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); } }
Method Summary | ||
---|---|---|
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 . |
|
|
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. |
|
|
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. |
|
|
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. |
Method Detail |
---|
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 first
IllegalArgumentException
- if there's an entry with the same name already in the pipeline
NullPointerException
- 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 append
IllegalArgumentException
- if there's an entry with the same name already in the pipeline
NullPointerException
- 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 before
NoSuchElementException
- if there's no such entry with the specified baseName
IllegalArgumentException
- if there's an entry with the same name already in the pipeline
NullPointerException
- 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 after
NoSuchElementException
- if there's no such entry with the specified baseName
IllegalArgumentException
- if there's an entry with the same name already in the pipeline
NullPointerException
- 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 pipeline
NullPointerException
- 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 pipeline
NullPointerException
- if the specified name is null
<T extends ChannelHandler> T remove(Class<T> handlerType)
ChannelHandler
of the specified type from this
pipeline
T
- the type of the handlerhandlerType
- the type of the handler
NoSuchElementException
- if there's no such handler of the specified type in this pipeline
NullPointerException
- 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 pipeline
IllegalArgumentException
- if a handler with the specified new name already exists in this
pipeline, except for the handler to be replaced
NullPointerException
- 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 pipeline
IllegalArgumentException
- if a handler with the specified new name already exists in this
pipeline, except for the handler to be replaced
NullPointerException
- 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 pipeline
IllegalArgumentException
- if a handler with the specified new name already exists in this
pipeline, except for the handler to be replaced
NullPointerException
- 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
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
.
List<String> getNames()
List
of the handler names.
Map<String,ChannelHandler> toMap()
Map
whose keys are
handler names and whose values are handlers.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |