ChannelHandlerContext (Netty API Reference (4.0.56.Final))

All Superinterfaces:

AttributeMap
```
public interface ChannelHandlerContext
extends AttributeMap
```
Enables a ChannelHandler to interact with its ChannelPipeline and other handlers. A handler can notify the next ChannelHandler in the ChannelPipeline, modify the ChannelPipeline it belongs to dynamically.
Notify
You can notify the closest handler in the same ChannelPipeline by calling one of the various methods provided here. Please refer to ChannelPipeline to understand how an event flows.
Modifying a pipeline
You can get the ChannelPipeline your handler belongs to by calling pipeline(). A non-trivial application could insert, remove, or replace handlers in the pipeline dynamically at 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 ChannelDuplexHandler {

     private ChannelHandlerContext ctx;

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

     public void login(String username, password) {
         ctx.write(new LoginMessage(username, password));
     }
     ...
 }
 
```
Storing stateful information
AttributeMap.attr(AttributeKey) 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 AttributeKeys 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<Integer> {

   private final AttributeKey<Integer> counter =
           new AttributeKey<Integer>("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));
   }
 }

 // 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 (using an AttributeKey), 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, and ChannelPipeline 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

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`ByteBufAllocator`	`alloc()` Return the assigned `ByteBufAllocator` which will be used to allocate `ByteBuf`s.
`ChannelFuture`	`bind(java.net.SocketAddress localAddress)` Request to bind to the given `SocketAddress` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`bind(java.net.SocketAddress localAddress, ChannelPromise promise)` Request to bind to the given `SocketAddress` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`Channel`	`channel()` Return the `Channel` which is bound to the `ChannelHandlerContext`.
`ChannelFuture`	`close()` Request to close the `Channel` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`close(ChannelPromise promise)` Request to close the `Channel` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`connect(java.net.SocketAddress remoteAddress)` Request to connect to the given `SocketAddress` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`connect(java.net.SocketAddress remoteAddress, ChannelPromise promise)` Request to connect to the given `SocketAddress` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress)` Request to connect to the given `SocketAddress` while bind to the localAddress and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress, ChannelPromise promise)` Request to connect to the given `SocketAddress` while bind to the localAddress and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`deregister()` Request to deregister from the previous assigned `EventExecutor` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`deregister(ChannelPromise promise)` Request to deregister from the previous assigned `EventExecutor` and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`disconnect()` Request to disconnect from the remote peer and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`ChannelFuture`	`disconnect(ChannelPromise promise)` Request to disconnect from the remote peer and notify the `ChannelFuture` once the operation completes, either because the operation was successful or because of an error.
`EventExecutor`	`executor()` The `EventExecutor` that is used to dispatch the events.
`ChannelHandlerContext`	`fireChannelActive()` A `Channel` is active now, which means it is connected.
`ChannelHandlerContext`	`fireChannelInactive()` A `Channel` is inactive now, which means it is closed.
`ChannelHandlerContext`	`fireChannelRead(java.lang.Object msg)` A `Channel` received a message.
`ChannelHandlerContext`	`fireChannelReadComplete()` Triggers an `ChannelInboundHandler.channelReadComplete(ChannelHandlerContext)` event to the next `ChannelInboundHandler` in the `ChannelPipeline`.
`ChannelHandlerContext`	`fireChannelRegistered()` A `Channel` was registered to its `EventLoop`.
`ChannelHandlerContext`	`fireChannelUnregistered()` A `Channel` was unregistered from its `EventLoop`.
`ChannelHandlerContext`	`fireChannelWritabilityChanged()` Triggers an `ChannelInboundHandler.channelWritabilityChanged(ChannelHandlerContext)` event to the next `ChannelInboundHandler` in the `ChannelPipeline`.
`ChannelHandlerContext`	`fireExceptionCaught(java.lang.Throwable cause)` A `Channel` received an `Throwable` in one of its inbound operations.
`ChannelHandlerContext`	`fireUserEventTriggered(java.lang.Object evt)` A `Channel` received an user defined event.
`ChannelHandlerContext`	`flush()` Request to flush all pending messages via this ChannelOutboundInvoker.
`ChannelHandler`	`handler()` The `ChannelHandler` that is bound this `ChannelHandlerContext`.
`boolean`	`isRemoved()` Return `true` if the `ChannelHandler` which belongs to this context was removed from the `ChannelPipeline`.
`java.lang.String`	`name()` The unique name of the `ChannelHandlerContext`.The name was used when then `ChannelHandler` was added to the `ChannelPipeline`.
`ChannelFuture`	`newFailedFuture(java.lang.Throwable cause)` Create a new `ChannelFuture` which is marked as failed already.
`ChannelProgressivePromise`	`newProgressivePromise()` Return an new `ChannelProgressivePromise`
`ChannelPromise`	`newPromise()` Return a new `ChannelPromise`.
`ChannelFuture`	`newSucceededFuture()` Create a new `ChannelFuture` which is marked as succeeded already.
`ChannelPipeline`	`pipeline()` Return the assigned `ChannelPipeline`
`ChannelHandlerContext`	`read()` Request to Read data from the `Channel` into the first inbound buffer, triggers an `ChannelInboundHandler.channelRead(ChannelHandlerContext, Object)` event if data was read, and triggers a `channelReadComplete` event so the handler can decide to continue reading.
`ChannelPromise`	`voidPromise()` Return a special ChannelPromise which can be reused for different operations.
`ChannelFuture`	`write(java.lang.Object msg)` Request to write a message via this `ChannelHandlerContext` through the `ChannelPipeline`.
`ChannelFuture`	`write(java.lang.Object msg, ChannelPromise promise)` Request to write a message via this `ChannelHandlerContext` through the `ChannelPipeline`.
`ChannelFuture`	`writeAndFlush(java.lang.Object msg)` Shortcut for call `write(Object)` and `flush()`.
`ChannelFuture`	`writeAndFlush(java.lang.Object msg, ChannelPromise promise)` Shortcut for call `write(Object, ChannelPromise)` and `flush()`.

Methods inherited from interface io.netty.util.AttributeMap
attr

- Method Detail
  - channel
```
Channel channel()
```
    Return the Channel which is bound to the 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 information please refer to the EventExecutor javadoc.
  - name
```
java.lang.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.
  - isRemoved
```
boolean isRemoved()
```
    Return true if the ChannelHandler which belongs to this context was removed from the ChannelPipeline. Note that this method is only meant to be called from with in the EventLoop.
  - fireChannelRegistered
```
ChannelHandlerContext fireChannelRegistered()
```
    A Channel was registered to its EventLoop. This will result in having the ChannelInboundHandler.channelRegistered(ChannelHandlerContext) method called of the next ChannelInboundHandler contained in the ChannelPipeline of the Channel.
  - fireChannelUnregistered
```
ChannelHandlerContext fireChannelUnregistered()
```
    A Channel was unregistered from its EventLoop. This will result in having the ChannelInboundHandler.channelUnregistered(ChannelHandlerContext) method called of the next ChannelInboundHandler contained in the ChannelPipeline of the Channel.
  - fireChannelActive
```
ChannelHandlerContext fireChannelActive()
```
    A Channel is active now, which means it is connected. This will result in having the ChannelInboundHandler.channelActive(ChannelHandlerContext) method called of the next ChannelInboundHandler contained in the ChannelPipeline of the Channel.
  - fireChannelInactive
```
ChannelHandlerContext fireChannelInactive()
```
    A Channel is inactive now, which means it is closed. This will result in having the ChannelInboundHandler.channelInactive(ChannelHandlerContext) method called of the next ChannelInboundHandler contained in the ChannelPipeline of the Channel.
  - fireExceptionCaught
```
ChannelHandlerContext fireExceptionCaught(java.lang.Throwable cause)
```
    A Channel received an Throwable in one of its inbound operations. This will result in having the ChannelInboundHandler.exceptionCaught(ChannelHandlerContext, Throwable) method called of the next ChannelInboundHandler contained in the ChannelPipeline of the Channel.
  - fireUserEventTriggered
```
ChannelHandlerContext fireUserEventTriggered(java.lang.Object evt)
```
    A Channel received an user defined event. This will result in having the ChannelInboundHandler.userEventTriggered(ChannelHandlerContext, Object) method called of the next ChannelInboundHandler contained in the ChannelPipeline of the Channel.
  - fireChannelRead
```
ChannelHandlerContext fireChannelRead(java.lang.Object msg)
```
    A Channel received a message. This will result in having the ChannelInboundHandler.channelRead(ChannelHandlerContext, Object) method called of the next ChannelInboundHandler contained in the ChannelPipeline of the Channel.
  - fireChannelReadComplete
```
ChannelHandlerContext fireChannelReadComplete()
```
    Triggers an ChannelInboundHandler.channelReadComplete(ChannelHandlerContext) event to the next ChannelInboundHandler in the ChannelPipeline.
  - fireChannelWritabilityChanged
```
ChannelHandlerContext fireChannelWritabilityChanged()
```
    Triggers an ChannelInboundHandler.channelWritabilityChanged(ChannelHandlerContext) event to the next ChannelInboundHandler in the ChannelPipeline.
  - bind
```
ChannelFuture bind(java.net.SocketAddress localAddress)
```
    Request to bind to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
    This will result in having the ChannelOutboundHandler.bind(ChannelHandlerContext, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - connect
```
ChannelFuture connect(java.net.SocketAddress remoteAddress)
```
    Request to connect to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
    If the connection fails because of a connection timeout, the ChannelFuture will get failed with a ConnectTimeoutException. If it fails because of connection refused a ConnectException will be used.
    This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - connect
```
ChannelFuture connect(java.net.SocketAddress remoteAddress,
                      java.net.SocketAddress localAddress)
```
    Request to connect to the given SocketAddress while bind to the localAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
    This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - disconnect
```
ChannelFuture disconnect()
```
    Request to disconnect from the remote peer and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
    This will result in having the ChannelOutboundHandler.disconnect(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - close
```
ChannelFuture close()
```
    Request to close the Channel and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. After it is closed it is not possible to reuse it again.
    This will result in having the ChannelOutboundHandler.close(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - deregister
```
ChannelFuture deregister()
```
    Request to deregister from the previous assigned EventExecutor and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
    This will result in having the ChannelOutboundHandler.deregister(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - bind
```
ChannelFuture bind(java.net.SocketAddress localAddress,
                   ChannelPromise promise)
```
    Request to bind to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise will be notified.
    This will result in having the ChannelOutboundHandler.bind(ChannelHandlerContext, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - connect
```
ChannelFuture connect(java.net.SocketAddress remoteAddress,
                      ChannelPromise promise)
```
    Request to connect to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelFuture will be notified.
    If the connection fails because of a connection timeout, the ChannelFuture will get failed with a ConnectTimeoutException. If it fails because of connection refused a ConnectException will be used.
    This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - connect
```
ChannelFuture connect(java.net.SocketAddress remoteAddress,
                      java.net.SocketAddress localAddress,
                      ChannelPromise promise)
```
    Request to connect to the given SocketAddress while bind to the localAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise will be notified and also returned.
    This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - disconnect
```
ChannelFuture disconnect(ChannelPromise promise)
```
    Request to disconnect from the remote peer and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise will be notified.
    This will result in having the ChannelOutboundHandler.disconnect(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - close
```
ChannelFuture close(ChannelPromise promise)
```
    Request to close the Channel and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. After it is closed it is not possible to reuse it again. The given ChannelPromise will be notified.
    This will result in having the ChannelOutboundHandler.close(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - deregister
```
ChannelFuture deregister(ChannelPromise promise)
```
    Request to deregister from the previous assigned EventExecutor and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise will be notified.
    This will result in having the ChannelOutboundHandler.deregister(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - read
```
ChannelHandlerContext read()
```
    Request to Read data from the Channel into the first inbound buffer, triggers an ChannelInboundHandler.channelRead(ChannelHandlerContext, Object) event if data was read, and triggers a channelReadComplete 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 next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.
  - write
```
ChannelFuture write(java.lang.Object msg)
```
    Request to write a message via this ChannelHandlerContext through the ChannelPipeline. This method will not request to actual flush, so be sure to call flush() once you want to request to flush all pending data to the actual transport.
  - write
```
ChannelFuture write(java.lang.Object msg,
                    ChannelPromise promise)
```
    Request to write a message via this ChannelHandlerContext through the ChannelPipeline. This method will not request to actual flush, so be sure to call flush() once you want to request to flush all pending data to the actual transport.
  - flush
```
ChannelHandlerContext flush()
```
    Request to flush all pending messages via this ChannelOutboundInvoker.
  - writeAndFlush
```
ChannelFuture writeAndFlush(java.lang.Object msg,
                            ChannelPromise promise)
```
    Shortcut for call write(Object, ChannelPromise) and flush().
  - writeAndFlush
```
ChannelFuture writeAndFlush(java.lang.Object msg)
```
    Shortcut for call write(Object) and flush().
  - pipeline
```
ChannelPipeline pipeline()
```
    Return the assigned ChannelPipeline
  - alloc
```
ByteBufAllocator alloc()
```
    Return the assigned ByteBufAllocator which will be used to allocate ByteBufs.
  - newPromise
```
ChannelPromise newPromise()
```
    Return a new ChannelPromise.
  - newProgressivePromise
```
ChannelProgressivePromise newProgressivePromise()
```
    Return an new ChannelProgressivePromise
  - newSucceededFuture
```
ChannelFuture newSucceededFuture()
```
    Create a new ChannelFuture which is marked as succeeded already. So Future.isSuccess() will return true. All FutureListener added to it will be notified directly. Also every call of blocking methods will just return without blocking.
  - newFailedFuture
```
ChannelFuture newFailedFuture(java.lang.Throwable cause)
```
    Create a new ChannelFuture which is marked as failed already. So Future.isSuccess() will return false. All FutureListener added to it will be notified directly. Also every call of blocking methods will just return without blocking.
  - voidPromise
```
ChannelPromise voidPromise()
```
    Return a special ChannelPromise which can be reused for different operations.
    It's only supported to use it for write(Object, ChannelPromise).
    
    Be aware that the returned ChannelPromise will not support most operations and should only be used if you want to save an object allocation for every write operation. You will not be able to detect if the operation was complete, only if it failed as the implementation will call ChannelPipeline.fireExceptionCaught(Throwable) in this case.
    Be aware this is an expert feature and should be used with care!

Interface ChannelHandlerContext

Notify

Modifying a pipeline

Retrieving for later use

Storing stateful information

A handler can have more than one context

Additional resources worth reading

Method Summary

Methods inherited from interface io.netty.util.AttributeMap

Method Detail

channel

executor

name

handler

isRemoved

fireChannelRegistered

fireChannelUnregistered

fireChannelActive

fireChannelInactive

fireExceptionCaught

fireUserEventTriggered

fireChannelRead

fireChannelReadComplete

fireChannelWritabilityChanged

bind

connect

connect

disconnect

close

deregister

bind

connect

connect

disconnect

close

deregister

read

write

write

flush

writeAndFlush

writeAndFlush

pipeline

alloc

newPromise

newProgressivePromise

newSucceededFuture

newFailedFuture

voidPromise