ChannelHandler (Netty API Reference (5.0.0.Alpha4))

Interface ChannelHandler

All Known Subinterfaces:

WebSocketFrameDecoder , WebSocketFrameEncoder

All Known Implementing Classes:

AbstractRemoteAddressFilter , AbstractSniHandler , AbstractTrafficShapingHandler , ApplicationProtocolNegotiationHandler , Base64Decoder , Base64Encoder , ByteArrayDecoder , ByteArrayEncoder , ByteToMessageCodec , ByteToMessageDecoder , ChannelHandlerAdapter , ChannelInitializer , ChannelTrafficShapingHandler , ChunkedWriteHandler , CleartextHttp2ServerUpgradeHandler , CombinedChannelDuplexHandler , CompressionHandler , CorsHandler , DatagramDnsQueryDecoder , DatagramDnsQueryEncoder , DatagramDnsResponseDecoder , DatagramDnsResponseEncoder , DatagramPacketDecoder , DatagramPacketEncoder , DecompressionHandler , DelimiterBasedFrameDecoder , DynamicAddressConnectHandler , FixedLengthFrameDecoder , FlowControlHandler , FlushConsolidationHandler , GlobalChannelTrafficShapingHandler , GlobalTrafficShapingHandler , Http2ChannelDuplexHandler , Http2ConnectionHandler , Http2FrameCodec , Http2MultiplexHandler , Http2StreamFrameToHttpObjectCodec , HttpClientCodec , HttpClientUpgradeHandler , HttpContentCompressor , HttpContentDecoder , HttpContentDecompressor , HttpContentEncoder , HttpObjectAggregator , HttpObjectDecoder , HttpObjectEncoder , HttpRequestDecoder , HttpRequestEncoder , HttpResponseDecoder , HttpResponseEncoder , HttpServerCodec , HttpServerExpectContinueHandler , HttpServerKeepAliveHandler , HttpServerUpgradeHandler , HttpToHttp2ConnectionHandler , IdleStateHandler , InboundHttpToHttp2Adapter , IpSubnetFilter , LengthFieldBasedFrameDecoder , LengthFieldPrepender , LineBasedFrameDecoder , LineEncoder , LoggingHandler , MessageAggregator , MessageToByteEncoder , MessageToMessageCodec , MessageToMessageDecoder , MessageToMessageEncoder , OcspClientHandler , OptionalSslHandler , ReadTimeoutHandler , ResolveAddressHandler , RtspDecoder , RtspEncoder , RuleBasedIpFilter , SimpleChannelInboundHandler , SimpleUserEventChannelHandler , SniHandler , SslClientHelloHandler , SslHandler , SslMasterKeyHandler , StringDecoder , StringEncoder , TcpDnsQueryDecoder , TcpDnsQueryEncoder , TcpDnsResponseDecoder , TcpDnsResponseEncoder , UniqueIpFilter , Utf8FrameValidator , WebSocket13FrameDecoder , WebSocket13FrameEncoder , WebSocketClientCompressionHandler , WebSocketClientExtensionHandler , WebSocketClientProtocolHandler , WebSocketExtensionDecoder , WebSocketExtensionEncoder , WebSocketFrameAggregator , WebSocketServerCompressionHandler , WebSocketServerExtensionHandler , WebSocketServerProtocolHandler , WriteTimeoutHandler
```
public interface ChannelHandler
```
Handles an I/O event or intercepts an I/O operation, and forwards it to its next handler in its ChannelPipeline.
The context object

A ChannelHandler is provided with a ChannelHandlerContext object. A ChannelHandler is supposed to interact with the ChannelPipeline it belongs to via a context object. Using the context object, the ChannelHandler can pass events upstream or downstream, modify the pipeline dynamically, or store the information (using AttributeKeys) which is specific to the handler.
State management
A ChannelHandler often needs to store some stateful information. The simplest and recommended approach is to use member variables:
```
 public interface Message {
 // your methods here
 }
 public class DataServerHandler extends SimpleChannelInboundHandler<Message> {
 private boolean loggedIn;
 @Override
 public void messageReceived(ChannelHandlerContext ctx, Message message) {
 if (message instanceof LoginMessage) {
 authenticate((LoginMessage) message);
 loggedIn = true;
 } else (message instanceof GetDataMessage) {
 if (loggedIn) {
 ctx.writeAndFlush(fetchSecret((GetDataMessage) message));
 } else {
 fail();
 }
 }
 }
 ...
 }
 
```
Because the handler instance has a state variable which is dedicated to one connection, you have to create a new handler instance for each new channel to avoid a race condition where a unauthenticated client can get the confidential information:
```
 // Create a new handler instance per channel.
 // See ChannelInitializer.initChannel(Channel).
 public class DataServerInitializer extends ChannelInitializer<Channel> {
 @Override
 public void initChannel(Channel channel) {
 channel.pipeline().addLast("handler", new DataServerHandler());
 }
 }
 
```
Using AttributeKeys
Although it's recommended to use member variables to store the state of a handler, for some reason you might not want to create many handler instances. In such a case, you can use AttributeKeys which is provided by ChannelHandlerContext:
```
 public interface Message {
 // your methods here
 }
 public class DataServerHandler extends SimpleChannelInboundHandler<Message> {
 private final AttributeKey<Boolean> auth =
 AttributeKey.valueOf("auth");
 @Override
 public boolean isSharable() {
 return true;
 }
 @Override
 public void channelRead(ChannelHandlerContext ctx, Message message) {
 Attribute<Boolean> attr = ctx.attr(auth);
 if (message instanceof LoginMessage) {
 authenticate((LoginMessage) o);
 attr.set(true);
 } else (message instanceof GetDataMessage) {
 if (Boolean.TRUE.equals(attr.get())) {
 ctx.writeAndFlush(fetchSecret((GetDataMessage) o));
 } else {
 fail();
 }
 }
 }
 ...
 }
 
```
Now that the state of the handler is attached to the ChannelHandlerContext, you can add the same handler instance to different pipelines:
```
 public class DataServerInitializer extends ChannelInitializer<Channel> {
 private static final DataServerHandler SHARED = new DataServerHandler();
 @Override
 public void initChannel(Channel channel) {
 channel.pipeline().addLast("handler", SHARED);
 }
 }
 
```
The isSharable() method

In the example above which used an AttributeKey, you might have noticed the isSharable() method is override to return true.
If the isSharable() is returningtrue, it means you can create an instance of the handler just once and add it to one or more ChannelPipelines multiple times without a race condition.
If this method is not implemented and return false, you have to create a new handler instance every time you add it to a pipeline because it has unshared state such as member variables.
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
Modifier and Type	Method	Description
`default Future<Void>`	`bind (ChannelHandlerContext ctx, SocketAddress localAddress)`	Called once a bind operation is made.
`default void`	`channelActive (ChannelHandlerContext ctx)`	The `Channel` of the `ChannelHandlerContext` is now active
`default void`	`channelExceptionCaught (ChannelHandlerContext ctx, Throwable cause)`	Gets called if a `Throwable` was thrown when handling inbound events.
`default void`	`channelInactive (ChannelHandlerContext ctx)`	The `Channel` of the `ChannelHandlerContext` was registered is now inactive and reached its end of lifetime.
`default void`	`channelInboundEvent (ChannelHandlerContext ctx, Object evt)`	Gets called if a custom inbound event happened.
`default void`	`channelRead (ChannelHandlerContext ctx, Object msg)`	Invoked when the current `Channel` has read a message from the peer.
`default void`	`channelReadComplete (ChannelHandlerContext ctx)`	Invoked when the last message read by the current read operation has been consumed by `channelRead(ChannelHandlerContext, Object)`.
`default void`	`channelRegistered (ChannelHandlerContext ctx)`	The `Channel` of the `ChannelHandlerContext` was registered with its `EventLoop`
`default void`	`channelShutdown (ChannelHandlerContext ctx, ChannelShutdownDirection direction)`	The `Channel` of the `ChannelHandlerContext` was shutdown in one direction.
`default void`	`channelUnregistered (ChannelHandlerContext ctx)`	The `Channel` of the `ChannelHandlerContext` was unregistered from its `EventLoop`
`default void`	`channelWritabilityChanged (ChannelHandlerContext ctx)`	Gets called once the writable state of a `Channel` changed.
`default Future<Void>`	`close (ChannelHandlerContext ctx)`	Called once a close operation is made.
`default Future<Void>`	`connect (ChannelHandlerContext ctx, SocketAddress remoteAddress, SocketAddress localAddress)`	Called once a connect operation is made.
`default Future<Void>`	`deregister (ChannelHandlerContext ctx)`	Called once a deregister operation is made from the current registered `EventLoop`.
`default Future<Void>`	`disconnect (ChannelHandlerContext ctx)`	Called once a disconnect operation is made.
`default void`	`flush (ChannelHandlerContext ctx)`	Called once a flush operation is made.
`default void`	`handlerAdded (ChannelHandlerContext ctx)`	Gets called after the `ChannelHandler` was added to the actual context and it's ready to handle events.
`default void`	`handlerRemoved (ChannelHandlerContext ctx)`	Gets called after the `ChannelHandler` was removed from the actual context and it doesn't handle events anymore.
`default boolean`	`isSharable ()`	Returns `true` if this handler is sharable and thus can be added to more than one `ChannelPipeline`.
`default long`	`pendingOutboundBytes (ChannelHandlerContext ctx)`	The number of the outbound bytes that are buffered / queued in this `ChannelHandler`.
`default void`	`read (ChannelHandlerContext ctx)`	Intercepts `ChannelHandlerContext.read()`.
`default Future<Void>`	`register (ChannelHandlerContext ctx)`	Called once a register operation is made to register for IO on the `EventLoop`.
`default Future<Void>`	`sendOutboundEvent (ChannelHandlerContext ctx, Object event)`	Called once a custom defined outbound event was sent.
`default Future<Void>`	`shutdown (ChannelHandlerContext ctx, ChannelShutdownDirection direction)`	Called once a shutdown operation was requested and should be executed.
`default Future<Void>`	`write (ChannelHandlerContext ctx, Object msg)`	Called once a write operation is made.

- Method Detail
  - handlerAdded
```
default void handlerAdded(ChannelHandlerContext ctx)
 throws Exception 
```
    Gets called after the ChannelHandler was added to the actual context and it's ready to handle events.
    
    Throws:
    
    Exception
  - handlerRemoved
```
default void handlerRemoved(ChannelHandlerContext ctx)
 throws Exception 
```
    Gets called after the ChannelHandler was removed from the actual context and it doesn't handle events anymore.
    
    Throws:
    
    Exception
  - isSharable
```
default boolean isSharable()
```
    Returns true if this handler is sharable and thus can be added to more than one ChannelPipeline. By default, this method returns false. If this method returns false, you have to create a new handler instance every time you add it to a pipeline because it has unshared state such as member variables.
  - channelRegistered
```
default void channelRegistered(ChannelHandlerContext ctx)
 throws Exception 
```
    The Channel of the ChannelHandlerContext was registered with its EventLoop
    
    Throws:
    
    Exception
  - channelUnregistered
```
default void channelUnregistered(ChannelHandlerContext ctx)
 throws Exception 
```
    The Channel of the ChannelHandlerContext was unregistered from its EventLoop
    
    Throws:
    
    Exception
  - channelActive
```
default void channelActive(ChannelHandlerContext ctx)
 throws Exception 
```
    The Channel of the ChannelHandlerContext is now active
    
    Throws:
    
    Exception
  - channelInactive
```
default void channelInactive(ChannelHandlerContext ctx)
 throws Exception 
```
    The Channel of the ChannelHandlerContext was registered is now inactive and reached its end of lifetime.
    
    Throws:
    
    Exception
  - channelShutdown
```
default void channelShutdown(ChannelHandlerContext ctx,
 ChannelShutdownDirection direction)
 throws Exception 
```
    The Channel of the ChannelHandlerContext was shutdown in one direction. This might either be because the remote peer did cause a shutdown of one direction or the shutdown was requested explicit by us and was executed.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which we notify about the completed shutdown.
    
    direction - the ChannelShutdownDirection of the completed shutdown.
    
    Throws:
    
    Exception
  - channelRead
```
default void channelRead(ChannelHandlerContext ctx,
 Object msg)
 throws Exception 
```
    Invoked when the current Channel has read a message from the peer.
    
    Throws:
    
    Exception
  - channelReadComplete
```
default void channelReadComplete(ChannelHandlerContext ctx)
 throws Exception 
```
    Invoked when the last message read by the current read operation has been consumed by channelRead(ChannelHandlerContext, Object). If ChannelOption.AUTO_READ is off, no further attempt to read an inbound data from the current Channel will be made until ChannelHandlerContext.read() is called.
    
    Throws:
    
    Exception
  - channelInboundEvent
```
default void channelInboundEvent(ChannelHandlerContext ctx,
 Object evt)
 throws Exception 
```
    Gets called if a custom inbound event happened.
    
    Throws:
    
    Exception
  - channelWritabilityChanged
```
default void channelWritabilityChanged(ChannelHandlerContext ctx)
 throws Exception 
```
    Gets called once the writable state of a Channel changed. You can check the state with Channel.writableBytes() or Channel.isWritable().
    
    Throws:
    
    Exception
  - channelExceptionCaught
```
default void channelExceptionCaught(ChannelHandlerContext ctx,
 Throwable cause)
 throws Exception 
```
    Gets called if a Throwable was thrown when handling inbound events.
    
    Throws:
    
    Exception
  - bind
```
default Future<Void> bind(ChannelHandlerContext ctx,
 SocketAddress localAddress)
```
    Called once a bind operation is made.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the bind operation is made
    
    localAddress - the SocketAddress to which it should bound
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - connect
```
default Future<Void> connect(ChannelHandlerContext ctx,
 SocketAddress remoteAddress,
 SocketAddress localAddress)
```
    Called once a connect operation is made.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the connect operation is made
    
    remoteAddress - the SocketAddress to which it should connect
    
    localAddress - the SocketAddress which is used as source on connect
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - disconnect
```
default Future<Void> disconnect(ChannelHandlerContext ctx)
```
    Called once a disconnect operation is made.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the disconnect operation is made
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - close
```
default Future<Void> close(ChannelHandlerContext ctx)
```
    Called once a close operation is made.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the close operation is made
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - shutdown
```
default Future<Void> shutdown(ChannelHandlerContext ctx,
 ChannelShutdownDirection direction)
```
    Called once a shutdown operation was requested and should be executed.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the shutdown operation is made
    
    direction - the ChannelShutdownDirection that is used.
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - register
```
default Future<Void> register(ChannelHandlerContext ctx)
```
    Called once a register operation is made to register for IO on the EventLoop.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the register operation is made
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - deregister
```
default Future<Void> deregister(ChannelHandlerContext ctx)
```
    Called once a deregister operation is made from the current registered EventLoop.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the deregister operation is made
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - read
```
default void read(ChannelHandlerContext ctx)
```
    Intercepts ChannelHandlerContext.read().
  - write
```
default Future<Void> write(ChannelHandlerContext ctx,
 Object msg)
```
    Called once a write operation is made. The write operation will write the messages through the ChannelPipeline. Those are then ready to be flushed to the actual Channel once Channel.flush() is called.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the write operation is made
    
    msg - the message to write
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - flush
```
default void flush(ChannelHandlerContext ctx)
```
    Called once a flush operation is made. The flush operation will try to flush out all previous written messages that are pending.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the flush operation is made
  - sendOutboundEvent
```
default Future<Void> sendOutboundEvent(ChannelHandlerContext ctx,
 Object event)
```
    Called once a custom defined outbound event was sent. This operation will pass the event through the ChannelPipeline in the outbound direction.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the operation is made.
    
    event - the event.
    
    Returns:
    
    the Future which will be notified once the operation completes.
  - pendingOutboundBytes
```
default long pendingOutboundBytes(ChannelHandlerContext ctx)
```
    The number of the outbound bytes that are buffered / queued in this ChannelHandler. This number will affect the writability of the Channel together the buffered / queued bytes in the Channel itself. By default this methods returns 0. If the ChannelHandler implementation buffers / queues outbound data this methods should be implemented to return the correct value.
    
    Parameters:
    
    ctx - the ChannelHandlerContext for which the operation is made.
    
    Returns:
    
    the number of buffered / queued bytes.

Interface ChannelHandler

The context object

State management

Using `AttributeKey`s

The `isSharable()` method

Additional resources worth reading

Method Summary

Method Detail

handlerAdded

handlerRemoved

isSharable

channelRegistered

channelUnregistered

channelActive

channelInactive

channelShutdown

channelRead

channelReadComplete

channelInboundEvent

channelWritabilityChanged

channelExceptionCaught

bind

connect

disconnect

close

shutdown

register

deregister

read

write

flush

sendOutboundEvent

pendingOutboundBytes

Interface ChannelHandler

The context object

State management

Using AttributeKeys

The isSharable() method

Additional resources worth reading

Method Summary

Method Detail

handlerAdded

handlerRemoved

isSharable

channelRegistered

channelUnregistered

channelActive

channelInactive

channelShutdown

channelRead

channelReadComplete

channelInboundEvent

channelWritabilityChanged

channelExceptionCaught

bind

connect

disconnect

close

shutdown

register

deregister

read

write

flush

sendOutboundEvent

pendingOutboundBytes

Using `AttributeKey`s

The `isSharable()` method