Interface ChannelPipeline
- All Superinterfaces:
ChannelInboundInvoker
,ChannelOutboundInvoker
,Iterable<Map.Entry<String,
ChannelHandler>>
- All Known Implementing Classes:
DefaultChannelPipeline
,EmbeddedChannel.EmbeddedChannelPipeline
ChannelHandler
s which handles or intercepts inbound events and outbound operations 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 a pipeline
interact with each other.
Creation of a pipeline
Each channel has its own pipeline and it is created automatically when a new channel is created.How an event flows in a pipeline
The following diagram describes how I/O events are processed byChannelHandler
s in a ChannelPipeline
typically. An I/O event is handled by either a ChannelInboundHandler
or a ChannelOutboundHandler
and be forwarded to its closest handler by calling the event propagation methods defined in
ChannelHandlerContext
, such as ChannelHandlerContext.fireChannelRead(Object)
and
ChannelOutboundInvoker.write(Object)
.
I/O Request viaAn inbound event is handled by the inbound handlers in the bottom-up direction as shown on the left side of the diagram. An inbound 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 | | | \|/ | | +---------------------+ +-----------+----------+ | | | Inbound Handler N | | Outbound Handler 1 | | | +----------+----------+ +-----------+----------+ | | /|\ | | | | \|/ | | +----------+----------+ +-----------+----------+ | | | Inbound Handler N-1 | | Outbound Handler 2 | | | +----------+----------+ +-----------+----------+ | | /|\ . | | . . | | ChannelHandlerContext.fireIN_EVT() ChannelHandlerContext.OUT_EVT()| | [ method call] [method call] | | . . | | . \|/ | | +----------+----------+ +-----------+----------+ | | | Inbound Handler 2 | | Outbound Handler M-1 | | | +----------+----------+ +-----------+----------+ | | /|\ | | | | \|/ | | +----------+----------+ +-----------+----------+ | | | Inbound Handler 1 | | Outbound Handler M | | | +----------+----------+ +-----------+----------+ | | /|\ | | +---------------+-----------------------------------+---------------+ | \|/ +---------------+-----------------------------------+---------------+ | | | | | [ Socket.read() ] [ Socket.write() ] | | | | Netty Internal I/O Threads (Transport Implementation) | +-------------------------------------------------------------------+
SocketChannel.read(ByteBuffer)
. If an inbound event goes beyond the top inbound handler, it is discarded
silently, or logged if it needs your attention.
An outbound event is handled by the outbound handler in the top-down direction as shown on the right side of the
diagram. An outbound handler usually generates or transforms the outbound traffic such as write requests.
If an outbound event goes beyond the bottom outbound 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
SocketChannel.write(ByteBuffer)
.
For example, let us assume that we created the following pipeline:
ChannelPipeline
p = ...;
p.addLast("1", new InboundHandlerA());
p.addLast("2", new InboundHandlerB());
p.addLast("3", new OutboundHandlerA());
p.addLast("4", new OutboundHandlerB());
p.addLast("5", new InboundOutboundHandlerX());
In the example above, the class whose name starts with Inbound
means it is an inbound handler.
The class whose name starts with Outbound
means it is a outbound handler.
In the given example configuration, the handler evaluation order is 1, 2, 3, 4, 5 when an event goes inbound.
When an event goes outbound, 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:
- 3 and 4 don't implement
ChannelInboundHandler
, and therefore the actual evaluation order of an inbound event will be: 1, 2, and 5. - 1 and 2 don't implement
ChannelOutboundHandler
, and therefore the actual evaluation order of a outbound event will be: 5, 4, and 3. - If 5 implements both
ChannelInboundHandler
andChannelOutboundHandler
, the evaluation order of an inbound and a outbound event could be 125 and 543 respectively.
Forwarding an event to the next handler
As you might noticed in the diagram shows, a handler has to invoke the event propagation methods inChannelHandlerContext
to forward an event to its next handler. Those methods include:
- Inbound event propagation methods:
ChannelHandlerContext.fireChannelRegistered()
ChannelHandlerContext.fireChannelActive()
ChannelHandlerContext.fireChannelRead(Object)
ChannelHandlerContext.fireChannelReadComplete()
ChannelHandlerContext.fireExceptionCaught(Throwable)
ChannelHandlerContext.fireUserEventTriggered(Object)
ChannelHandlerContext.fireChannelWritabilityChanged()
ChannelHandlerContext.fireChannelInactive()
ChannelHandlerContext.fireChannelUnregistered()
- Outbound event propagation methods:
ChannelOutboundInvoker.bind(SocketAddress, ChannelPromise)
ChannelOutboundInvoker.connect(SocketAddress, SocketAddress, ChannelPromise)
ChannelOutboundInvoker.write(Object, ChannelPromise)
ChannelHandlerContext.flush()
ChannelHandlerContext.read()
ChannelOutboundInvoker.disconnect(ChannelPromise)
ChannelOutboundInvoker.close(ChannelPromise)
ChannelOutboundInvoker.deregister(ChannelPromise)
public class MyInboundHandler extendsChannelInboundHandlerAdapter
{@Override
public void channelActive(ChannelHandlerContext
ctx) { System.out.println("Connected!"); ctx.fireChannelActive(); } } public class MyOutboundHandler extendsChannelOutboundHandlerAdapter
{@Override
public void close(ChannelHandlerContext
ctx,ChannelPromise
promise) { System.out.println("Closing .."); ctx.close(promise); } }
Building a pipeline
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:
- Protocol Decoder - translates binary data (e.g.
ByteBuf
) into a Java object. - Protocol Encoder - translates a Java object into binary data.
- Business Logic Handler - performs the actual business logic (e.g. database access).
static finalBe aware that while usingEventExecutorGroup
group = newDefaultEventExecutorGroup
(16); ...ChannelPipeline
pipeline = ch.pipeline(); pipeline.addLast("decoder", new MyProtocolDecoder()); pipeline.addLast("encoder", new MyProtocolEncoder()); // Tell the pipeline to run MyBusinessLogicHandler's event handler methods // in a different thread than an I/O thread so that the I/O thread is not blocked by // a time-consuming task. // If your business logic is fully asynchronous or finished very quickly, you don't // need to specify a group. pipeline.addLast(group, "handler", new MyBusinessLogicHandler());
DefaultEventLoopGroup
will offload the operation from the EventLoop
it will
still process tasks in a serial fashion per ChannelHandlerContext
and so guarantee ordering. Due the ordering
it may still become a bottle-neck. If ordering is not a requirement for your use-case you may want to consider using
UnorderedThreadPoolEventExecutor
to maximize the parallelism of the task execution.
Thread safety
A ChannelHandler
can be added or removed at any time because a ChannelPipeline
is thread safe.
For example, you can insert an encryption handler when sensitive information is about to be exchanged, and remove it
after the exchange.
-
Method Summary
Modifier and TypeMethodDescriptionaddAfter
(EventExecutorGroup group, String baseName, String name, ChannelHandler handler) Inserts aChannelHandler
after an existing handler of this pipeline.addAfter
(String baseName, String name, ChannelHandler handler) Inserts aChannelHandler
after an existing handler of this pipeline.addBefore
(EventExecutorGroup group, String baseName, String name, ChannelHandler handler) Inserts aChannelHandler
before an existing handler of this pipeline.addBefore
(String baseName, String name, ChannelHandler handler) Inserts aChannelHandler
before an existing handler of this pipeline.addFirst
(ChannelHandler... handlers) InsertsChannelHandler
s at the first position of this pipeline.addFirst
(EventExecutorGroup group, ChannelHandler... handlers) InsertsChannelHandler
s at the first position of this pipeline.addFirst
(EventExecutorGroup group, String name, ChannelHandler handler) Inserts aChannelHandler
at the first position of this pipeline.addFirst
(String name, ChannelHandler handler) Inserts aChannelHandler
at the first position of this pipeline.addLast
(ChannelHandler... handlers) InsertsChannelHandler
s at the last position of this pipeline.addLast
(EventExecutorGroup group, ChannelHandler... handlers) InsertsChannelHandler
s at the last position of this pipeline.addLast
(EventExecutorGroup group, String name, ChannelHandler handler) Appends aChannelHandler
at the last position of this pipeline.addLast
(String name, ChannelHandler handler) Appends aChannelHandler
at the last position of this pipeline.channel()
Returns theChannel
that this pipeline is attached to.context
(ChannelHandler handler) Returns the context object of the specifiedChannelHandler
in this pipeline.context
(Class<? extends ChannelHandler> handlerType) Returns the context object of theChannelHandler
of the specified type in this pipeline.Returns the context object of theChannelHandler
with the specified name in this pipeline.AChannel
is active now, which means it is connected.AChannel
is inactive now, which means it is closed.fireChannelRead
(Object msg) AChannel
received a message.Triggers anChannelInboundHandler.channelReadComplete(ChannelHandlerContext)
event to the nextChannelInboundHandler
in theChannelPipeline
.Triggers anChannelInboundHandler.channelWritabilityChanged(ChannelHandlerContext)
event to the nextChannelInboundHandler
in theChannelPipeline
.fireExceptionCaught
(Throwable cause) fireUserEventTriggered
(Object event) AChannel
received an user defined event.first()
Returns the firstChannelHandler
in this pipeline.Returns the context of the firstChannelHandler
in this pipeline.flush()
Request to flush all pending messages via this ChannelOutboundInvoker.<T extends ChannelHandler>
TReturns theChannelHandler
of the specified type in this pipeline.Returns theChannelHandler
with the specified name in this pipeline.last()
Returns the lastChannelHandler
in this pipeline.Returns the context of the lastChannelHandler
in this pipeline.names()
Returns theList
of the handler names.remove
(ChannelHandler handler) Removes the specifiedChannelHandler
from this pipeline.<T extends ChannelHandler>
TRemoves theChannelHandler
of the specified type from this pipeline.Removes theChannelHandler
with the specified name from this pipeline.Removes the firstChannelHandler
in this pipeline.Removes the lastChannelHandler
in this pipeline.replace
(ChannelHandler oldHandler, String newName, ChannelHandler newHandler) Replaces the specifiedChannelHandler
with a new handler in this pipeline.<T extends ChannelHandler>
Treplace
(Class<T> oldHandlerType, String newName, ChannelHandler newHandler) Replaces theChannelHandler
of the specified type with a new handler in this pipeline.replace
(String oldName, String newName, ChannelHandler newHandler) Replaces theChannelHandler
of the specified name with a new handler in this pipeline.toMap()
Converts this pipeline into an orderedMap
whose keys are handler names and whose values are handlers.Methods inherited from interface io.netty.channel.ChannelOutboundInvoker
bind, bind, close, close, connect, connect, connect, connect, deregister, deregister, disconnect, disconnect, newFailedFuture, newProgressivePromise, newPromise, newSucceededFuture, read, voidPromise, write, write, writeAndFlush, writeAndFlush
Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator
-
Method Details
-
addFirst
Inserts aChannelHandler
at the first position of this pipeline.- Parameters:
name
- the name of the handler to insert firsthandler
- the handler to insert first- Throws:
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified handler isnull
-
addFirst
Inserts aChannelHandler
at the first position of this pipeline.- Parameters:
group
- theEventExecutorGroup
which will be used to execute theChannelHandler
methodsname
- the name of the handler to insert firsthandler
- the handler to insert first- Throws:
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified handler isnull
-
addLast
Appends aChannelHandler
at the last position of this pipeline.- Parameters:
name
- the name of the handler to appendhandler
- the handler to append- Throws:
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified handler isnull
-
addLast
Appends aChannelHandler
at the last position of this pipeline.- Parameters:
group
- theEventExecutorGroup
which will be used to execute theChannelHandler
methodsname
- the name of the handler to appendhandler
- the handler to append- Throws:
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified handler isnull
-
addBefore
Inserts aChannelHandler
before an existing handler of this pipeline.- Parameters:
baseName
- the name of the existing handlername
- the name of the handler to insert beforehandler
- the handler to insert before- Throws:
NoSuchElementException
- if there's no such entry with the specifiedbaseName
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified baseName or handler isnull
-
addBefore
ChannelPipeline addBefore(EventExecutorGroup group, String baseName, String name, ChannelHandler handler) Inserts aChannelHandler
before an existing handler of this pipeline.- Parameters:
group
- theEventExecutorGroup
which will be used to execute theChannelHandler
methodsbaseName
- the name of the existing handlername
- the name of the handler to insert beforehandler
- the handler to insert before- Throws:
NoSuchElementException
- if there's no such entry with the specifiedbaseName
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified baseName or handler isnull
-
addAfter
Inserts aChannelHandler
after an existing handler of this pipeline.- Parameters:
baseName
- the name of the existing handlername
- the name of the handler to insert afterhandler
- the handler to insert after- Throws:
NoSuchElementException
- if there's no such entry with the specifiedbaseName
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified baseName or handler isnull
-
addAfter
ChannelPipeline addAfter(EventExecutorGroup group, String baseName, String name, ChannelHandler handler) Inserts aChannelHandler
after an existing handler of this pipeline.- Parameters:
group
- theEventExecutorGroup
which will be used to execute theChannelHandler
methodsbaseName
- the name of the existing handlername
- the name of the handler to insert afterhandler
- the handler to insert after- Throws:
NoSuchElementException
- if there's no such entry with the specifiedbaseName
IllegalArgumentException
- if there's an entry with the same name already in the pipelineNullPointerException
- if the specified baseName or handler isnull
-
addFirst
InsertsChannelHandler
s at the first position of this pipeline.- Parameters:
handlers
- the handlers to insert first
-
addFirst
InsertsChannelHandler
s at the first position of this pipeline.- Parameters:
group
- theEventExecutorGroup
which will be used to execute theChannelHandler
s methods.handlers
- the handlers to insert first
-
addLast
InsertsChannelHandler
s at the last position of this pipeline.- Parameters:
handlers
- the handlers to insert last
-
addLast
InsertsChannelHandler
s at the last position of this pipeline.- Parameters:
group
- theEventExecutorGroup
which will be used to execute theChannelHandler
s methods.handlers
- the handlers to insert last
-
remove
Removes the specifiedChannelHandler
from this pipeline.- Parameters:
handler
- theChannelHandler
to remove- Throws:
NoSuchElementException
- if there's no such handler in this pipelineNullPointerException
- if the specified handler isnull
-
remove
Removes theChannelHandler
with the specified name from this pipeline.- Parameters:
name
- the name under which theChannelHandler
was stored.- Returns:
- the removed handler
- Throws:
NoSuchElementException
- if there's no such handler with the specified name in this pipelineNullPointerException
- if the specified name isnull
-
remove
Removes theChannelHandler
of the specified type from this pipeline.- Type Parameters:
T
- the type of the handler- Parameters:
handlerType
- the type of the handler- Returns:
- the removed handler
- Throws:
NoSuchElementException
- if there's no such handler of the specified type in this pipelineNullPointerException
- if the specified handler type isnull
-
removeFirst
ChannelHandler removeFirst()Removes the firstChannelHandler
in this pipeline.- Returns:
- the removed handler
- Throws:
NoSuchElementException
- if this pipeline is empty
-
removeLast
ChannelHandler removeLast()Removes the lastChannelHandler
in this pipeline.- Returns:
- the removed handler
- Throws:
NoSuchElementException
- if this pipeline is empty
-
replace
Replaces the specifiedChannelHandler
with a new handler in this pipeline.- Parameters:
oldHandler
- theChannelHandler
to be replacednewName
- the name under which the replacement should be addednewHandler
- theChannelHandler
which is used as replacement- Returns:
- itself
- Throws:
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 or new handler isnull
-
replace
Replaces theChannelHandler
of the specified name with a new handler in this pipeline.- Parameters:
oldName
- the name of theChannelHandler
to be replacednewName
- the name under which the replacement should be addednewHandler
- theChannelHandler
which is used as replacement- Returns:
- the removed handler
- Throws:
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 or new handler isnull
-
replace
<T extends ChannelHandler> T replace(Class<T> oldHandlerType, String newName, ChannelHandler newHandler) Replaces theChannelHandler
of the specified type with a new handler in this pipeline.- Parameters:
oldHandlerType
- the type of the handler to be removednewName
- the name under which the replacement should be addednewHandler
- theChannelHandler
which is used as replacement- Returns:
- the removed handler
- Throws:
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 or new handler isnull
-
first
ChannelHandler first()Returns the firstChannelHandler
in this pipeline.- Returns:
- the first handler.
null
if this pipeline is empty.
-
firstContext
ChannelHandlerContext firstContext()Returns the context of the firstChannelHandler
in this pipeline.- Returns:
- the context of the first handler.
null
if this pipeline is empty.
-
last
ChannelHandler last()Returns the lastChannelHandler
in this pipeline.- Returns:
- the last handler.
null
if this pipeline is empty.
-
lastContext
ChannelHandlerContext lastContext()Returns the context of the lastChannelHandler
in this pipeline.- Returns:
- the context of the last handler.
null
if this pipeline is empty.
-
get
Returns theChannelHandler
with the specified name in this pipeline.- Returns:
- the handler with the specified name.
null
if there's no such handler in this pipeline.
-
get
Returns theChannelHandler
of the specified type in this pipeline.- Returns:
- the handler of the specified handler type.
null
if there's no such handler in this pipeline.
-
context
Returns the context object of the specifiedChannelHandler
in this pipeline.- Returns:
- the context object of the specified handler.
null
if there's no such handler in this pipeline.
-
context
Returns the context object of theChannelHandler
with the specified name in this pipeline.- Returns:
- the context object of the handler with the specified name.
null
if there's no such handler in this pipeline.
-
context
Returns the context object of theChannelHandler
of the specified type in this pipeline.- Returns:
- the context object of the handler of the specified type.
null
if there's no such handler in this pipeline.
-
channel
Channel channel()Returns theChannel
that this pipeline is attached to.- Returns:
- the channel.
null
if this pipeline is not attached yet.
-
names
Returns theList
of the handler names. -
toMap
Map<String,ChannelHandler> toMap()Converts this pipeline into an orderedMap
whose keys are handler names and whose values are handlers. -
fireChannelRegistered
ChannelPipeline fireChannelRegistered()Description copied from interface:ChannelInboundInvoker
AChannel
was registered to itsEventLoop
. This will result in having theChannelInboundHandler.channelRegistered(ChannelHandlerContext)
method called of the nextChannelInboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
fireChannelRegistered
in interfaceChannelInboundInvoker
-
fireChannelUnregistered
ChannelPipeline fireChannelUnregistered()Description copied from interface:ChannelInboundInvoker
AChannel
was unregistered from itsEventLoop
. This will result in having theChannelInboundHandler.channelUnregistered(ChannelHandlerContext)
method called of the nextChannelInboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
fireChannelUnregistered
in interfaceChannelInboundInvoker
-
fireChannelActive
ChannelPipeline fireChannelActive()Description copied from interface:ChannelInboundInvoker
AChannel
is active now, which means it is connected. This will result in having theChannelInboundHandler.channelActive(ChannelHandlerContext)
method called of the nextChannelInboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
fireChannelActive
in interfaceChannelInboundInvoker
-
fireChannelInactive
ChannelPipeline fireChannelInactive()Description copied from interface:ChannelInboundInvoker
AChannel
is inactive now, which means it is closed. This will result in having theChannelInboundHandler.channelInactive(ChannelHandlerContext)
method called of the nextChannelInboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
fireChannelInactive
in interfaceChannelInboundInvoker
-
fireExceptionCaught
Description copied from interface:ChannelInboundInvoker
AChannel
received anThrowable
in one of its inbound operations. This will result in having theChannelInboundHandler.exceptionCaught(ChannelHandlerContext, Throwable)
method called of the nextChannelInboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
fireExceptionCaught
in interfaceChannelInboundInvoker
-
fireUserEventTriggered
Description copied from interface:ChannelInboundInvoker
AChannel
received an user defined event. This will result in having theChannelInboundHandler.userEventTriggered(ChannelHandlerContext, Object)
method called of the nextChannelInboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
fireUserEventTriggered
in interfaceChannelInboundInvoker
-
fireChannelRead
Description copied from interface:ChannelInboundInvoker
AChannel
received a message. This will result in having theChannelInboundHandler.channelRead(ChannelHandlerContext, Object)
method called of the nextChannelInboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
fireChannelRead
in interfaceChannelInboundInvoker
-
fireChannelReadComplete
ChannelPipeline fireChannelReadComplete()Description copied from interface:ChannelInboundInvoker
Triggers anChannelInboundHandler.channelReadComplete(ChannelHandlerContext)
event to the nextChannelInboundHandler
in theChannelPipeline
.- Specified by:
fireChannelReadComplete
in interfaceChannelInboundInvoker
-
fireChannelWritabilityChanged
ChannelPipeline fireChannelWritabilityChanged()Description copied from interface:ChannelInboundInvoker
Triggers anChannelInboundHandler.channelWritabilityChanged(ChannelHandlerContext)
event to the nextChannelInboundHandler
in theChannelPipeline
.- Specified by:
fireChannelWritabilityChanged
in interfaceChannelInboundInvoker
-
flush
ChannelPipeline flush()Description copied from interface:ChannelOutboundInvoker
Request to flush all pending messages via this ChannelOutboundInvoker.- Specified by:
flush
in interfaceChannelOutboundInvoker
-