io.netty.channel

Interface ChannelHandlerContext

All Superinterfaces:

io.netty.util.AttributeMap, ChannelFutureFactory, ChannelInboundInvoker, ChannelOutboundInvoker

public interface ChannelHandlerContext
extends io.netty.util.AttributeMap, ChannelFutureFactory, ChannelInboundInvoker, ChannelOutboundInvoker

Enables a ChannelHandler to interact with its ChannelPipeline and other handlers. A handler can send a ChannelEvent upstream or downstream, modify the ChannelPipeline it belongs to dynamically.

Sending an event

You can send or forward a ChannelEvent to the closest handler in the same ChannelPipeline by calling #sendUpstream(ChannelEvent) or #sendDownstream(ChannelEvent). Please refer to ChannelPipeline to understand how an event flows.

Modifying a pipeline

You can get the ChannelPipeline your handler belongs to by calling #getPipeline(). A non-trivial application could insert, remove, or replace handlers in the pipeline dynamically in runtime.

Retrieving for later use

You can keep the ChannelHandlerContext for later use, such as triggering an event outside the handler methods, even from a different thread.

 public class MyHandler extends SimpleChannelHandler
                        implements LifeCycleAwareChannelHandler {

     private ChannelHandlerContext ctx;

     public void beforeAdd(ChannelHandlerContext ctx) {
         this.ctx = ctx;
     }

     public void login(String username, password) {
         Channels.write(
                 this.ctx,
                 Channels.succeededFuture(this.ctx.getChannel()),
                 new LoginMessage(username, password));
     }
     ...
 }
 

Storing stateful information

#setAttachment(Object) and #getAttachment() allow you to store and access stateful information that is related with a handler and its context. Please refer to ChannelHandler to learn various recommended ways to manage stateful information.

A handler can have more than one context

Please note that a ChannelHandler instance can be added to more than one ChannelPipeline. It means a single ChannelHandler instance can have more than one ChannelHandlerContext and therefore the single instance can be invoked with different ChannelHandlerContexts if it is added to one or more ChannelPipelines more than once.

For example, the following handler will have as many independent attachments 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 SimpleChannelHandler {

   // This handler will receive a sequence of increasing integers starting
   // from 1.
   @Override
   public void messageReceived(ChannelHandlerContext ctx, MessageEvent evt) {
     Integer a = (Integer) ctx.getAttachment();
     Integer b = (Integer) evt.getMessage();

     if (a == null) {
       a = 1;
     }

     ctx.setAttachment(Integer.valueOf(a * b));
   }
 }

 // 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 (as an attachment), 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, ChannelEvent, and ChannelPipeline to find out what a upstream event and a downstream event are, what fundamental differences they have, how they flow in a pipeline, and how to handle the event in your application.

Method Summary

Methods

Modifier and Type	Method and Description
Channel	channel() Return the Channel which is bound to the ChannelHandlerContext.
EventExecutor	executor() The EventExecutor that is used to dispatch the events.
ChannelHandler	handler() The ChannelHandler that is bound this ChannelHandlerContext.
boolean	hasInboundByteBuffer() Return true if the ChannelHandlerContext has an ByteBuf bound for inbound which can be used.
boolean	hasInboundMessageBuffer() Return true if the ChannelHandlerContext has a MessageBuf bound for inbound which can be used.
boolean	hasNextInboundByteBuffer() Return true if the next ChannelHandlerContext has a ByteBuf for handling inbound data.
boolean	hasNextInboundMessageBuffer() Return true if the next ChannelHandlerContext has a MessageBuf for handling inbound data.
boolean	hasNextOutboundByteBuffer() Return true if the next ChannelHandlerContext has a ByteBuf for handling outbound data.
boolean	hasNextOutboundMessageBuffer() Return true if the next ChannelHandlerContext has a MessageBuf for handling outbound data.
boolean	hasOutboundByteBuffer() Return true if the ChannelHandlerContext has an ByteBuf bound for outbound data which can be used.
boolean	hasOutboundMessageBuffer() Return true if the ChannelHandlerContext has a MessageBuf bound for outbound which can be used.
io.netty.buffer.ByteBuf	inboundByteBuffer() Return the bound ByteBuf for inbound data if hasInboundByteBuffer() returned true.
<T> io.netty.buffer.MessageBuf<T>	inboundMessageBuffer() Return the bound MessageBuf for inbound data if hasInboundMessageBuffer() returned true.
boolean	isReadable() Return true if the ChannelHandlerContext was marked as readable.
String	name() The unique name of the ChannelHandlerContext.The name was used when then ChannelHandler was added to the ChannelPipeline.
io.netty.buffer.ByteBuf	nextInboundByteBuffer() Return the ByteBuf of the next ChannelHandlerContext if hasNextInboundByteBuffer() returned true, otherwise a UnsupportedOperationException is thrown.
io.netty.buffer.MessageBuf<Object>	nextInboundMessageBuffer() Return the MessageBuf of the next ChannelHandlerContext if hasNextInboundMessageBuffer() returned true, otherwise a UnsupportedOperationException is thrown.
io.netty.buffer.ByteBuf	nextOutboundByteBuffer() Return the ByteBuf of the next ChannelHandlerContext if hasNextOutboundByteBuffer() returned true, otherwise a UnsupportedOperationException is thrown.
io.netty.buffer.MessageBuf<Object>	nextOutboundMessageBuffer() Return the MessageBuf of the next ChannelHandlerContext if hasNextOutboundMessageBuffer() returned true, otherwise a UnsupportedOperationException is thrown.
io.netty.buffer.ByteBuf	outboundByteBuffer() Return the bound ByteBuf for outbound data if hasOutboundByteBuffer() returned true.
<T> io.netty.buffer.MessageBuf<T>	outboundMessageBuffer() Return the bound MessageBuf for outbound data if hasOutboundMessageBuffer() returned true.
ChannelPipeline	pipeline() Return the ChannelPipeline which belongs this ChannelHandlerContext.
void	readable(boolean readable) Mark the ChannelHandlerContext as readable or suspend it.
Set<ChannelHandlerType>	types()

Methods inherited from interface io.netty.util.AttributeMap

attr

Methods inherited from interface io.netty.channel.ChannelFutureFactory

newFailedFuture, newFuture, newSucceededFuture

Methods inherited from interface io.netty.channel.ChannelInboundInvoker

fireChannelActive, fireChannelInactive, fireChannelRegistered, fireChannelUnregistered, fireExceptionCaught, fireInboundBufferUpdated, fireUserEventTriggered

Methods inherited from interface io.netty.channel.ChannelOutboundInvoker

bind, bind, close, close, connect, connect, connect, connect, deregister, deregister, disconnect, disconnect, flush, flush, write, write

Method Detail

channel

Channel channel()

Return the Channel which is bound to the ChannelHandlerContext.

pipeline

ChannelPipeline pipeline()

Return the ChannelPipeline which belongs this ChannelHandlerContext.

executor

EventExecutor executor()

The EventExecutor that is used to dispatch the events. This can also be used to directly submit tasks that get executed in the event loop. For more informations please refer to the EventExecutor javadocs.

name

String name()

The unique name of the ChannelHandlerContext.The name was used when then ChannelHandler was added to the ChannelPipeline. This name can also be used to access the registered ChannelHandler from the ChannelPipeline.

handler

ChannelHandler handler()

The ChannelHandler that is bound this ChannelHandlerContext.

types

Set<ChannelHandlerType> types()

hasInboundByteBuffer

boolean hasInboundByteBuffer()

Return true if the ChannelHandlerContext has an ByteBuf bound for inbound which can be used.

hasInboundMessageBuffer

boolean hasInboundMessageBuffer()

Return true if the ChannelHandlerContext has a MessageBuf bound for inbound which can be used.

inboundByteBuffer

io.netty.buffer.ByteBuf inboundByteBuffer()

Return the bound ByteBuf for inbound data if hasInboundByteBuffer() returned true. If hasInboundByteBuffer() returned false it will throw a UnsupportedOperationException

inboundMessageBuffer

<T> io.netty.buffer.MessageBuf<T> inboundMessageBuffer()

Return the bound MessageBuf for inbound data if hasInboundMessageBuffer() returned true. If hasInboundMessageBuffer() returned false it will throw a UnsupportedOperationException.

hasOutboundByteBuffer

boolean hasOutboundByteBuffer()

Return true if the ChannelHandlerContext has an ByteBuf bound for outbound data which can be used.

hasOutboundMessageBuffer

boolean hasOutboundMessageBuffer()

Return true if the ChannelHandlerContext has a MessageBuf bound for outbound which can be used.

outboundByteBuffer

io.netty.buffer.ByteBuf outboundByteBuffer()

Return the bound ByteBuf for outbound data if hasOutboundByteBuffer() returned true. If hasOutboundByteBuffer() returned false it will throw a UnsupportedOperationException.

outboundMessageBuffer

<T> io.netty.buffer.MessageBuf<T> outboundMessageBuffer()

Return the bound MessageBuf for outbound data if hasOutboundMessageBuffer() returned true. If hasOutboundMessageBuffer() returned false it will throw a UnsupportedOperationException

hasNextInboundByteBuffer

boolean hasNextInboundByteBuffer()

Return true if the next ChannelHandlerContext has a ByteBuf for handling inbound data.

hasNextInboundMessageBuffer

boolean hasNextInboundMessageBuffer()

Return true if the next ChannelHandlerContext has a MessageBuf for handling inbound data.

nextInboundByteBuffer

io.netty.buffer.ByteBuf nextInboundByteBuffer()

Return the ByteBuf of the next ChannelHandlerContext if hasNextInboundByteBuffer() returned true, otherwise a UnsupportedOperationException is thrown.

nextInboundMessageBuffer

io.netty.buffer.MessageBuf<Object> nextInboundMessageBuffer()

Return the MessageBuf of the next ChannelHandlerContext if hasNextInboundMessageBuffer() returned true, otherwise a UnsupportedOperationException is thrown.

hasNextOutboundByteBuffer

boolean hasNextOutboundByteBuffer()

Return true if the next ChannelHandlerContext has a ByteBuf for handling outbound data.

hasNextOutboundMessageBuffer

boolean hasNextOutboundMessageBuffer()

Return true if the next ChannelHandlerContext has a MessageBuf for handling outbound data.

nextOutboundByteBuffer

io.netty.buffer.ByteBuf nextOutboundByteBuffer()

Return the ByteBuf of the next ChannelHandlerContext if hasNextOutboundByteBuffer() returned true, otherwise a UnsupportedOperationException is thrown.

nextOutboundMessageBuffer

io.netty.buffer.MessageBuf<Object> nextOutboundMessageBuffer()

Return the MessageBuf of the next ChannelHandlerContext if hasNextOutboundMessageBuffer() returned true, otherwise a UnsupportedOperationException is thrown.

isReadable

boolean isReadable()

Return true if the ChannelHandlerContext was marked as readable. This basically means that once its not readable anymore no new data will be read from the transport and passed down the ChannelPipeline. Only if all ChannelHandlerContext's isReadable() return true, the data is passed again down the ChannelPipeline.

readable

void readable(boolean readable)

Mark the ChannelHandlerContext as readable or suspend it. See isReadable()