Netty/Codec 4.1.107.Final · io.netty.handler.codec.ByteToMessageDecoder

ChannelInboundHandlerAdapter which decodes bytes in a stream-like fashion from one ByteBuf to an other Message type. For example here is an implementation which reads all readable bytes from the input ByteBuf and create a new ByteBuf.

    public class SquareDecoder extends ByteToMessageDecoder {
        @Override
        public void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out)
                throws Exception {
            out.add(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 ByteBuf#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 ByteBuf#getInt(int). One MUST use the reader index when using methods like ByteBuf#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 @Sharable.

Some methods such as ByteBuf#readBytes(int) will cause a memory leak if the returned buffer is not released or added to the out List. Use derived buffers like ByteBuf#readSlice(int) to avoid leaking memory.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	ByteToMessageDecoder.Cumulator Cumulate `ByteBuf`s.

Field Summary

Modifier and Type	Field and Description
public static final ByteToMessageDecoder.Cumulator	COMPOSITE_CUMULATOR Cumulate `ByteBuf`s by add them to a `CompositeByteBuf` and so do no memory copy whenever possible.
pack-priv ByteBuf	cumulation
private ByteToMessageDecoder.Cumulator	cumulator
private byte	decodeState A bitmask where the bits are defined as `STATE_INIT` `STATE_CALLING_CHILD_DECODE` `STATE_HANDLER_REMOVED_PENDING`
private int	discardAfterReads
private boolean	firedChannelRead This flag is used to determine if we need to call `ChannelHandlerContext#read()` to consume more data when `ChannelConfig#isAutoRead()` is `false`.
private boolean	first
public static final ByteToMessageDecoder.Cumulator	MERGE_CUMULATOR Cumulate `ByteBuf`s by merge them into one `ByteBuf`'s, using memory copies.
private int	numReads
private boolean	selfFiredChannelRead
private boolean	singleDecode
private static final byte	STATE_CALLING_CHILD_DECODE
private static final byte	STATE_HANDLER_REMOVED_PENDING
private static final byte	STATE_INIT

Constructor Summary

Access	Constructor and Description
protected	ByteToMessageDecoder()

Method Summary

Modifier and Type	Method and Description
protected int	actualReadableBytes() Returns the actual number of readable bytes in the internal cumulative buffer of this decoder.
protected void	callDecode(ChannelHandlerContext the `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to ctx, ByteBuf the `ByteBuf` from which to read data in, List<Object> the `List` to which decoded messages should be added out) Called once data should be decoded from the given `ByteBuf`.
public void	channelInactive(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelInactive. Implements io.netty.channel.ChannelInboundHandler.channelInactive. Calls `ChannelHandlerContext#fireChannelInactive()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
private void	channelInputClosed(ChannelHandlerContext ctx, boolean callChannelInactive)
pack-priv void	channelInputClosed(ChannelHandlerContext ctx, List<Object> out) Called when the input of the channel was closed which may be because it changed to inactive or because of `ChannelInputShutdownEvent`.
public void	channelRead(ChannelHandlerContext ctx, Object msg) Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRead. Implements io.netty.channel.ChannelInboundHandler.channelRead. Calls `ChannelHandlerContext#fireChannelRead(Object)` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
public void	channelReadComplete(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete. Implements io.netty.channel.ChannelInboundHandler.channelReadComplete. Calls `ChannelHandlerContext#fireChannelReadComplete()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
protected abstract void	decode(ChannelHandlerContext the `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to ctx, ByteBuf the `ByteBuf` from which to read data in, List<Object> the `List` to which decoded messages should be added out) Decode the from one `ByteBuf` to an other.
protected void	decodeLast(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) Is called one last time when the `ChannelHandlerContext` goes in-active.
pack-priv final void	decodeRemovalReentryProtection(ChannelHandlerContext the `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to ctx, ByteBuf the `ByteBuf` from which to read data in, List<Object> the `List` to which decoded messages should be added out) Decode the from one `ByteBuf` to an other.
protected final void	discardSomeReadBytes()
pack-priv static ByteBuf	expandCumulation(ByteBufAllocator alloc, ByteBuf oldCumulation, ByteBuf in)
pack-priv static void	fireChannelRead(ChannelHandlerContext ctx, List<Object> msgs, int numElements) Get `numElements` out of the `List` and forward these through the pipeline.
pack-priv static void	fireChannelRead(ChannelHandlerContext ctx, CodecOutputList msgs, int numElements) Get `numElements` out of the `CodecOutputList` and forward these through the pipeline.
public final void	handlerRemoved(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelHandlerAdapter.handlerRemoved. Implements io.netty.channel.ChannelHandler.handlerRemoved. 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 ByteBuf	internalBuffer() Returns the internal cumulative buffer of this decoder.
public boolean	isSingleDecode() If `true` then only one message is decoded on each `channelRead(ChannelHandlerContext, Object)` call.
public void	setCumulator(ByteToMessageDecoder.Cumulator cumulator) Set the `Cumulator` to use for cumulate the received `ByteBuf`s.
public void	setDiscardAfterReads(int discardAfterReads) Set the number of reads after which `ByteBuf#discardSomeReadBytes()` are called and so free up memory.
public void	setSingleDecode(boolean singleDecode) If set then only one message is decoded on each `channelRead(ChannelHandlerContext, Object)` call.
public void	userEventTriggered(ChannelHandlerContext ctx, Object evt) Overrides io.netty.channel.ChannelInboundHandlerAdapter.userEventTriggered. Implements io.netty.channel.ChannelInboundHandler.userEventTriggered. Calls `ChannelHandlerContext#fireUserEventTriggered(Object)` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.

Inherited from io.netty.channel.ChannelInboundHandlerAdapter:: channelActive channelRegistered channelUnregistered channelWritabilityChanged exceptionCaught

Field Detail

COMPOSITE_CUMULATOR	back to summary
public static final ByteToMessageDecoder.Cumulator COMPOSITE_CUMULATOR Cumulate `ByteBuf`s by add them to a `CompositeByteBuf` and so do no memory copy whenever possible. Be aware that `CompositeByteBuf` 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`.

cumulation	back to summary
pack-priv ByteBuf cumulation

cumulator	back to summary
private ByteToMessageDecoder.Cumulator cumulator

decodeState back to summary

decodeState	back to summary
private byte decodeState A bitmask where the bits are defined as `STATE_INIT` `STATE_CALLING_CHILD_DECODE` `STATE_HANDLER_REMOVED_PENDING`

private byte decodeState

A bitmask where the bits are defined as

discardAfterReads	back to summary
private int discardAfterReads

firedChannelRead	back to summary
private boolean firedChannelRead This flag is used to determine if we need to call `ChannelHandlerContext#read()` to consume more data when `ChannelConfig#isAutoRead()` is `false`.

first	back to summary
private boolean first

MERGE_CUMULATOR	back to summary
public static final ByteToMessageDecoder.Cumulator MERGE_CUMULATOR Cumulate `ByteBuf`s by merge them into one `ByteBuf`'s, using memory copies.

numReads	back to summary
private int numReads

selfFiredChannelRead	back to summary
private boolean selfFiredChannelRead

singleDecode	back to summary
private boolean singleDecode

STATE_CALLING_CHILD_DECODE	back to summary
private static final byte STATE_CALLING_CHILD_DECODE

STATE_HANDLER_REMOVED_PENDING	back to summary
private static final byte STATE_HANDLER_REMOVED_PENDING

STATE_INIT	back to summary
private static final byte STATE_INIT

Constructor Detail

ByteToMessageDecoder	back to summary
protected ByteToMessageDecoder()

Method Detail

actualReadableBytes	back to summary
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()`.

callDecode back to summary

callDecode	back to summary
protected void callDecode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) Called once data should be decoded from the given `ByteBuf`. This method will call `decode(ChannelHandlerContext, ByteBuf, List)` as long as decoding should take place. Parameters ctx:ChannelHandlerContext the `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to in:ByteBuf the `ByteBuf` from which to read data out:List<Object> the `List` to which decoded messages should be added

protected void callDecode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out)

Called once data should be decoded from the given ByteBuf. This method will call decode(ChannelHandlerContext, ByteBuf, List) as long as decoding should take place.

Parameters

ctx:ChannelHandlerContext: the ChannelHandlerContext which this ByteToMessageDecoder belongs to
in:ByteBuf: the ByteBuf from which to read data
out:List<Object>: the List to which decoded messages should be added

channelInactive back to summary

channelInactive	back to summary
public void channelInactive(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelInactive. Implements io.netty.channel.ChannelInboundHandler.channelInactive. Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelInactive. Calls `ChannelHandlerContext#fireChannelInactive()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override

public void channelInactive(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelInactive.

Implements io.netty.channel.ChannelInboundHandler.channelInactive.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelInactive.

Calls ChannelHandlerContext#fireChannelInactive() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Annotations

@Override

channelInputClosed	back to summary
private void channelInputClosed(ChannelHandlerContext ctx, boolean callChannelInactive)

channelInputClosed	back to summary
pack-priv void channelInputClosed(ChannelHandlerContext ctx, List<Object> out) throws Exception Called when the input of the channel was closed which may be because it changed to inactive or because of `ChannelInputShutdownEvent`.

channelRead back to summary

channelRead	back to summary
public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRead. Implements io.netty.channel.ChannelInboundHandler.channelRead. Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelRead. Calls `ChannelHandlerContext#fireChannelRead(Object)` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override

public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception

Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRead.

Implements io.netty.channel.ChannelInboundHandler.channelRead.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelRead.

Calls ChannelHandlerContext#fireChannelRead(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Annotations

@Override

channelReadComplete back to summary

channelReadComplete	back to summary
public void channelReadComplete(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete. Implements io.netty.channel.ChannelInboundHandler.channelReadComplete. Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete. Calls `ChannelHandlerContext#fireChannelReadComplete()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override

public void channelReadComplete(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete.

Implements io.netty.channel.ChannelInboundHandler.channelReadComplete.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete.

Calls ChannelHandlerContext#fireChannelReadComplete() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Annotations

@Override

decode back to summary

decode	back to summary
protected abstract void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws Exception Decode the from one `ByteBuf` to an other. This method will be called till either the input `ByteBuf` has nothing to read when return from this method or till nothing was read from the input `ByteBuf`. Parameters ctx:ChannelHandlerContext the `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to in:ByteBuf the `ByteBuf` from which to read data out:List<Object> the `List` to which decoded messages should be added Exceptions Exception: is thrown if an error occurs

protected abstract void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws Exception

Decode the from one ByteBuf to an other. This method will be called till either the input ByteBuf has nothing to read when return from this method or till nothing was read from the input ByteBuf.

Parameters

ctx:ChannelHandlerContext: the ChannelHandlerContext which this ByteToMessageDecoder belongs to
in:ByteBuf: the ByteBuf from which to read data
out:List<Object>: the List to which decoded messages should be added

Exceptions

Exception:: is thrown if an error occurs

decodeLast back to summary

decodeLast	back to summary
protected void decodeLast(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) 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, ByteBuf, List)` but sub-classes may override this for some special cleanup operation.

protected void decodeLast(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) 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, ByteBuf, List) but sub-classes may override this for some special cleanup operation.

decodeRemovalReentryProtection back to summary

decodeRemovalReentryProtection	back to summary
pack-priv final void decodeRemovalReentryProtection(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws Exception Decode the from one `ByteBuf` to an other. This method will be called till either the input `ByteBuf` has nothing to read when return from this method or till nothing was read from the input `ByteBuf`. Parameters ctx:ChannelHandlerContext the `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to in:ByteBuf the `ByteBuf` from which to read data out:List<Object> the `List` to which decoded messages should be added Exceptions Exception: is thrown if an error occurs

pack-priv final void decodeRemovalReentryProtection(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws Exception

Parameters

ctx:ChannelHandlerContext: the ChannelHandlerContext which this ByteToMessageDecoder belongs to
in:ByteBuf: the ByteBuf from which to read data
out:List<Object>: the List to which decoded messages should be added

Exceptions

Exception:: is thrown if an error occurs

discardSomeReadBytes	back to summary
protected final void discardSomeReadBytes()

expandCumulation	back to summary
pack-priv static ByteBuf expandCumulation(ByteBufAllocator alloc, ByteBuf oldCumulation, ByteBuf in)

fireChannelRead	back to summary
pack-priv static void fireChannelRead(ChannelHandlerContext ctx, List<Object> msgs, int numElements) Get `numElements` out of the `List` and forward these through the pipeline.

fireChannelRead	back to summary
pack-priv static void fireChannelRead(ChannelHandlerContext ctx, CodecOutputList msgs, int numElements) Get `numElements` out of the `CodecOutputList` and forward these through the pipeline.

handlerRemoved back to summary

handlerRemoved	back to summary
public final void handlerRemoved(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelHandlerAdapter.handlerRemoved. Implements io.netty.channel.ChannelHandler.handlerRemoved. Doc from io.netty.channel.ChannelHandler.handlerRemoved. Gets called after the `ChannelHandler` was removed from the actual context and it doesn't handle events anymore. Annotations @Override

public final void handlerRemoved(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelHandlerAdapter.handlerRemoved.

Implements io.netty.channel.ChannelHandler.handlerRemoved.

Doc from io.netty.channel.ChannelHandler.handlerRemoved.

Gets called after the ChannelHandler was removed from the actual context and it doesn't handle events anymore.

Annotations

@Override

handlerRemoved0	back to summary
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.

internalBuffer	back to summary
protected ByteBuf internalBuffer() Returns the internal cumulative buffer of this decoder. 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.

isSingleDecode	back to summary
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.

setCumulator	back to summary
public void setCumulator(ByteToMessageDecoder.Cumulator cumulator) Set the `Cumulator` to use for cumulate the received `ByteBuf`s.

setDiscardAfterReads	back to summary
public void setDiscardAfterReads(int discardAfterReads) Set the number of reads after which `ByteBuf#discardSomeReadBytes()` are called and so free up memory. The default is `16`.

setSingleDecode	back to summary
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.

userEventTriggered back to summary

userEventTriggered	back to summary
public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.userEventTriggered. Implements io.netty.channel.ChannelInboundHandler.userEventTriggered. Doc from io.netty.channel.ChannelInboundHandlerAdapter.userEventTriggered. Calls `ChannelHandlerContext#fireUserEventTriggered(Object)` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override