ByteToMessageDecoder (Netty API Reference (5.0.0.Alpha4))

Class ByteToMessageDecoder

java.lang.Object
- io.netty5.channel.ChannelHandlerAdapter
- - io.netty5.handler.codec.ByteToMessageDecoder

All Implemented Interfaces:

ChannelHandler

Direct Known Subclasses:

CleartextHttp2ServerUpgradeHandler , DecompressionHandler , DelimiterBasedFrameDecoder , FixedLengthFrameDecoder , Http2ConnectionHandler , HttpObjectDecoder , LengthFieldBasedFrameDecoder , LineBasedFrameDecoder , OptionalSslHandler , SslClientHelloHandler , SslHandler , WebSocket13FrameDecoder
```
public abstract class ByteToMessageDecoder
extends ChannelHandlerAdapter 
```
ChannelHandler which decodes bytes in a stream-like fashion from one Buffer to an other Message type. For example here is an implementation which reads all readable bytes from the input Buffer, creates a new Buffer and forward it to the next ChannelHandler in the ChannelPipeline.
```
 public class SquareDecoder extends ByteToMessageDecoder {
 @Override
 public void decode(ChannelHandlerContext ctx, Buffer in)
 throws Exception {
 ctx.fireChannelRead(in.readBytes(in.readableBytes()));
 }
 }
 
```
Frame detection

Generally frame detection should be handled earlier in the pipeline by adding a DelimiterBasedFrameDecoder, FixedLengthFrameDecoder, LengthFieldBasedFrameDecoder, or LineBasedFrameDecoder.
If a custom frame decoder is required, then one needs to be careful when implementing one with ByteToMessageDecoder. Ensure there are enough bytes in the buffer for a complete frame by checking Buffer.readableBytes(). If there are not enough bytes for a complete frame, return without modifying the reader index to allow more bytes to arrive.
To check for complete frames without modifying the reader index, use methods like BufferAccessor.getInt(int). One MUST use the reader index when using methods like BufferAccessor.getInt(int). For example calling in.getInt(0) is assuming the frame starts at the beginning of the buffer, which is not always the case. Use in.getInt(in.readerIndex()) instead.
Pitfalls

Be aware that sub-classes of ByteToMessageDecoder MUST NOT annotated with {@link @Sharable}.

Nested Class Summary

Nested Classes
Modifier and Type Class Description

static interface ByteToMessageDecoder.Cumulator
Cumulate Buffers.

Nested Classes
Modifier and Type	Class	Description
`static interface`	`ByteToMessageDecoder.Cumulator`	Cumulate `Buffer`s.

Field Summary

Fields
Modifier and Type	Field	Description
`static ByteToMessageDecoder.Cumulator`	`COMPOSITE_CUMULATOR`	Cumulate `Buffer`s by add them to a `CompositeBuffer` and so do no memory copy whenever possible.
`static ByteToMessageDecoder.Cumulator`	`MERGE_CUMULATOR`	Cumulate `Buffer`s by merge them into one `Buffer`'s, using memory copies.

Constructor Summary

Constructors
Modifier Constructor Description

protected ByteToMessageDecoder ()

protected ByteToMessageDecoder (ByteToMessageDecoder.Cumulator cumulator)

Constructors
Modifier	Constructor	Description
`protected`	`ByteToMessageDecoder ()`
`protected`	`ByteToMessageDecoder (ByteToMessageDecoder.Cumulator cumulator)`

Method Summary

All Methods
Modifier and Type	Method	Description
`protected int`	`actualReadableBytes ()`	Returns the actual number of readable bytes in the internal cumulative buffer of this decoder.
`void`	`channelInactive (ChannelHandlerContext ctx)`	The `Channel` of the `ChannelHandlerContext` was registered is now inactive and reached its end of lifetime.
`void`	`channelRead (ChannelHandlerContext ctx, Object msg)`	Invoked when the current `Channel` has read a message from the peer.
`void`	`channelReadComplete (ChannelHandlerContext ctx)`	Invoked when the last message read by the current read operation has been consumed by `ChannelHandler.channelRead(ChannelHandlerContext, Object)`.
`void`	`channelShutdown (ChannelHandlerContext ctx, ChannelShutdownDirection direction)`	The `Channel` of the `ChannelHandlerContext` was shutdown in one direction.
`protected abstract void`	`decode (ChannelHandlerContext ctx, Buffer in)`	Decode the from one `Buffer` to another.
`protected void`	`decodeLast (ChannelHandlerContext ctx, Buffer in)`	Is called one last time when the `ChannelHandlerContext` goes in-active.
`protected void`	`discardSomeReadBytes ()`
`void`	`handlerAdded (ChannelHandlerContext ctx)`	Gets called after the `ChannelHandler` was added to the actual context and it's ready to handle events.
`protected void`	`handlerAdded0 (ChannelHandlerContext ctx)`
`void`	`handlerRemoved (ChannelHandlerContext ctx)`	Gets called after the `ChannelHandler` was removed from the actual context and it doesn't handle events anymore.
`protected void`	`handlerRemoved0 (ChannelHandlerContext ctx)`	Gets called after the `ByteToMessageDecoder` was removed from the actual context and it doesn't handle events anymore.
`protected Buffer`	`internalBuffer ()`	Returns the internal cumulative buffer of this decoder, if exists, else `null`.
`boolean`	`isSharable ()`	Returns `true` if this handler is sharable and thus can be added to more than one `ChannelPipeline`.
`boolean`	`isSingleDecode ()`	If `true` then only one message is decoded on each `channelRead(ChannelHandlerContext, Object)` call.
`void`	`setSingleDecode (boolean singleDecode)`	If set then only one message is decoded on each `channelRead(ChannelHandlerContext, Object)` call.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.netty5.channel.ChannelHandler
bind, channelActive, channelExceptionCaught, channelInboundEvent, channelRegistered, channelUnregistered, channelWritabilityChanged, close, connect, deregister, disconnect, flush, pendingOutboundBytes, read, register, sendOutboundEvent, shutdown, write

- Field Detail
  - MERGE_CUMULATOR
```
public static final ByteToMessageDecoder.Cumulator MERGE_CUMULATOR
```
    Cumulate Buffers by merge them into one Buffer's, using memory copies.
  - COMPOSITE_CUMULATOR
```
public static final ByteToMessageDecoder.Cumulator COMPOSITE_CUMULATOR
```
    Cumulate Buffers by add them to a CompositeBuffer and so do no memory copy whenever possible. Be aware that CompositeBuffer use a more complex indexing implementation so depending on your use-case and the decoder implementation this may be slower than just use the MERGE_CUMULATOR.
- Constructor Detail
  - ByteToMessageDecoder
```
protected ByteToMessageDecoder()
```
  - ByteToMessageDecoder
```
protected ByteToMessageDecoder(ByteToMessageDecoder.Cumulator cumulator)
```
- Method Detail
  - isSharable
```
public final boolean isSharable()
```
    Description copied from interface: ChannelHandler
    
    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.
  - setSingleDecode
```
public void setSingleDecode(boolean singleDecode)
```
    If set then only one message is decoded on each channelRead(ChannelHandlerContext, Object) call. This may be useful if you need to do some protocol upgrade and want to make sure nothing is mixed up. Default is false as this has performance impacts.
  - isSingleDecode
```
public boolean isSingleDecode()
```
    If true then only one message is decoded on each channelRead(ChannelHandlerContext, Object) call. Default is false as this has performance impacts.
  - actualReadableBytes
```
protected int actualReadableBytes()
```
    Returns the actual number of readable bytes in the internal cumulative buffer of this decoder. You usually do not need to rely on this value to write a decoder. Use it only when you must use it at your own risk. This method is a shortcut to internalBuffer().readableBytes().
  - internalBuffer
```
protected Buffer internalBuffer()
```
    Returns the internal cumulative buffer of this decoder, if exists, else null. You usually do not need to access the internal buffer directly to write a decoder. Use it only when you must use it at your own risk.
    
    Returns:
    
    Internal Buffer if exists, else null.
  - handlerAdded
```
public final void handlerAdded(ChannelHandlerContext ctx)
 throws Exception 
```
    Description copied from interface: ChannelHandler
    
    Gets called after the ChannelHandler was added to the actual context and it's ready to handle events.
    
    Throws:
    
    Exception
  - handlerAdded0
```
protected void handlerAdded0(ChannelHandlerContext ctx)
 throws Exception 
```
    Throws:
    
    Exception
  - handlerRemoved
```
public final void handlerRemoved(ChannelHandlerContext ctx)
 throws Exception 
```
    Description copied from interface: ChannelHandler
    
    Gets called after the ChannelHandler was removed from the actual context and it doesn't handle events anymore.
    
    Throws:
    
    Exception
  - handlerRemoved0
```
protected void handlerRemoved0(ChannelHandlerContext ctx)
 throws Exception 
```
    Gets called after the ByteToMessageDecoder was removed from the actual context and it doesn't handle events anymore.
    
    Throws:
    
    Exception
  - channelRead
```
public void channelRead(ChannelHandlerContext ctx,
 Object msg)
 throws Exception 
```
    Description copied from interface: ChannelHandler
    
    Invoked when the current Channel has read a message from the peer.
    
    Throws:
    
    Exception
  - channelReadComplete
```
public void channelReadComplete(ChannelHandlerContext ctx)
 throws Exception 
```
    Description copied from interface: ChannelHandler
    
    Invoked when the last message read by the current read operation has been consumed by ChannelHandler.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
  - discardSomeReadBytes
```
protected final void discardSomeReadBytes()
```
  - channelInactive
```
public void channelInactive(ChannelHandlerContext ctx)
 throws Exception 
```
    Description copied from interface: ChannelHandler
    
    The Channel of the ChannelHandlerContext was registered is now inactive and reached its end of lifetime.
    
    Throws:
    
    Exception
  - channelShutdown
```
public void channelShutdown(ChannelHandlerContext ctx,
 ChannelShutdownDirection direction)
 throws Exception 
```
    Description copied from interface: ChannelHandler
    
    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
  - decode
```
protected abstract void decode(ChannelHandlerContext ctx,
 Buffer in)
 throws Exception 
```
    Decode the from one Buffer to another. This method will be called till either the input Buffer has nothing to read when return from this method or till nothing was read from the input Buffer.
    
    Parameters:
    
    ctx - the ChannelHandlerContext which this ByteToMessageDecoder belongs to
    
    in - the Buffer from which to read data
    
    Throws:
    
    Exception - is thrown if an error occurs
  - decodeLast
```
protected void decodeLast(ChannelHandlerContext ctx,
 Buffer in)
 throws Exception 
```
    Is called one last time when the ChannelHandlerContext goes in-active. Which means the channelInactive(ChannelHandlerContext) was triggered. By default this will just call decode(ChannelHandlerContext, Buffer) but sub-classes may override this for some special cleanup operation.
    
    Throws:
    
    Exception

Class ByteToMessageDecoder

Frame detection

Pitfalls

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface io.netty5.channel.ChannelHandler

Field Detail

MERGE_CUMULATOR

COMPOSITE_CUMULATOR

Constructor Detail

ByteToMessageDecoder

ByteToMessageDecoder

Method Detail

isSharable

setSingleDecode

isSingleDecode

actualReadableBytes

internalBuffer

handlerAdded

handlerAdded0

handlerRemoved

handlerRemoved0

channelRead

channelReadComplete

discardSomeReadBytes

channelInactive

channelShutdown

decode

decodeLast