Package io.netty.channel
Interface ChannelHandlerContext
-
- All Superinterfaces:
AttributeMap
,ChannelInboundInvoker
,ChannelOutboundInvoker
- All Known Implementing Classes:
AbstractChannelHandlerContext
,CombinedChannelDuplexHandler.DelegatingChannelHandlerContext
,DefaultChannelHandlerContext
,DefaultChannelPipeline.HeadContext
,DefaultChannelPipeline.TailContext
public interface ChannelHandlerContext extends AttributeMap, ChannelInboundInvoker, ChannelOutboundInvoker
Enables aChannelHandler
to interact with itsChannelPipeline
and other handlers. Among other things a handler can notify the nextChannelHandler
in theChannelPipeline
as well as modify theChannelPipeline
it belongs to dynamically.Notify
You can notify the closest handler in the sameChannelPipeline
by calling one of the various methods provided here. Please refer toChannelPipeline
to understand how an event flows.Modifying a pipeline
You can get theChannelPipeline
your handler belongs to by callingpipeline()
. A non-trivial application could insert, remove, or replace handlers in the pipeline dynamically at runtime.Retrieving for later use
You can keep theChannelHandlerContext
for later use, such as triggering an event outside the handler methods, even from a different thread.public class MyHandler extends
ChannelDuplexHandler
{ privateChannelHandlerContext
ctx; public void beforeAdd(ChannelHandlerContext
ctx) { this.ctx = ctx; } public void login(String username, password) { ctx.write(new LoginMessage(username, password)); } ... }Storing stateful information
attr(AttributeKey)
allow you to store and access stateful information that is related with a handler and its context. Please refer toChannelHandler
to learn various recommended ways to manage stateful information.A handler can have more than one context
Please note that aChannelHandler
instance can be added to more than oneChannelPipeline
. It means a singleChannelHandler
instance can have more than oneChannelHandlerContext
and therefore the single instance can be invoked with differentChannelHandlerContext
s if it is added to one or moreChannelPipeline
s more than once.For example, the following handler will have as many independent
AttributeKey
s as how many times it is added to pipelines, regardless if it is added to the same pipeline multiple times or added to different pipelines multiple times:public class FactorialHandler extends
ChannelInboundHandlerAdapter
{ private finalAttributeKey
<Integer
> counter =AttributeKey
.valueOf("counter"); // This handler will receive a sequence of increasing integers starting // from 1.@Override
public void channelRead(ChannelHandlerContext
ctx, Object msg) { Integer a = ctx.attr(counter).get(); if (a == null) { a = 1; } attr.set(a * (Integer) msg); } } // Different context objects are given to "f1", "f2", "f3", and "f4" even if // they refer to the same handler instance. Because the FactorialHandler // stores its state in a context object (using anAttributeKey
), the factorial is // calculated correctly 4 times once the two pipelines (p1 and p2) are active. FactorialHandler fh = new FactorialHandler();ChannelPipeline
p1 =Channels
.pipeline(); p1.addLast("f1", fh); p1.addLast("f2", fh);ChannelPipeline
p2 =Channels
.pipeline(); p2.addLast("f3", fh); p2.addLast("f4", fh);Additional resources worth reading
Please refer to the
ChannelHandler
, andChannelPipeline
to find out more about inbound and outbound operations, what fundamental differences they have, how they flow in a pipeline, and how to handle the operation in your application.
-
-
Method Summary
-
Methods inherited from interface io.netty.channel.ChannelOutboundInvoker
bind, bind, close, close, connect, connect, connect, connect, deregister, deregister, disconnect, disconnect, newFailedFuture, newProgressivePromise, newPromise, newSucceededFuture, voidPromise, write, write, writeAndFlush, writeAndFlush
-
-
-
-
Method Detail
-
channel
Channel channel()
Return theChannel
which is bound to theChannelHandlerContext
.
-
executor
EventExecutor executor()
Returns theEventExecutor
which is used to execute an arbitrary task.
-
name
java.lang.String name()
The unique name of theChannelHandlerContext
.The name was used when thenChannelHandler
was added to theChannelPipeline
. This name can also be used to access the registeredChannelHandler
from theChannelPipeline
.
-
handler
ChannelHandler handler()
TheChannelHandler
that is bound thisChannelHandlerContext
.
-
isRemoved
boolean isRemoved()
Returntrue
if theChannelHandler
which belongs to this context was removed from theChannelPipeline
. Note that this method is only meant to be called from with in theEventLoop
.
-
fireChannelRegistered
ChannelHandlerContext 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
ChannelHandlerContext 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
ChannelHandlerContext 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
ChannelHandlerContext 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
ChannelHandlerContext fireExceptionCaught(java.lang.Throwable cause)
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
ChannelHandlerContext fireUserEventTriggered(java.lang.Object evt)
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
ChannelHandlerContext fireChannelRead(java.lang.Object msg)
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
ChannelHandlerContext fireChannelReadComplete()
Description copied from interface:ChannelInboundInvoker
Triggers anChannelInboundHandler.channelReadComplete(ChannelHandlerContext)
event to the nextChannelInboundHandler
in theChannelPipeline
.- Specified by:
fireChannelReadComplete
in interfaceChannelInboundInvoker
-
fireChannelWritabilityChanged
ChannelHandlerContext fireChannelWritabilityChanged()
Description copied from interface:ChannelInboundInvoker
Triggers anChannelInboundHandler.channelWritabilityChanged(ChannelHandlerContext)
event to the nextChannelInboundHandler
in theChannelPipeline
.- Specified by:
fireChannelWritabilityChanged
in interfaceChannelInboundInvoker
-
read
ChannelHandlerContext read()
Description copied from interface:ChannelOutboundInvoker
Request to Read data from theChannel
into the first inbound buffer, triggers anChannelInboundHandler.channelRead(ChannelHandlerContext, Object)
event if data was read, and triggers achannelReadComplete
event so the handler can decide to continue reading. If there's a pending read operation already, this method does nothing.This will result in having the
ChannelOutboundHandler.read(ChannelHandlerContext)
method called of the nextChannelOutboundHandler
contained in theChannelPipeline
of theChannel
.- Specified by:
read
in interfaceChannelOutboundInvoker
-
flush
ChannelHandlerContext flush()
Description copied from interface:ChannelOutboundInvoker
Request to flush all pending messages via this ChannelOutboundInvoker.- Specified by:
flush
in interfaceChannelOutboundInvoker
-
pipeline
ChannelPipeline pipeline()
Return the assignedChannelPipeline
-
alloc
ByteBufAllocator alloc()
Return the assignedByteBufAllocator
which will be used to allocateByteBuf
s.
-
attr
@Deprecated <T> Attribute<T> attr(AttributeKey<T> key)
Deprecated.Description copied from interface:AttributeMap
Get theAttribute
for the givenAttributeKey
. This method will never return null, but may return anAttribute
which does not have a value set yet.- Specified by:
attr
in interfaceAttributeMap
-
hasAttr
@Deprecated <T> boolean hasAttr(AttributeKey<T> key)
Deprecated.Description copied from interface:AttributeMap
- Specified by:
hasAttr
in interfaceAttributeMap
-
-