io.netty.handler.codec

Class ByteToMessageDecoder

java.lang.Object

io.netty.channel.ChannelHandlerAdapter

io.netty.handler.codec.ByteToMessageDecoder

All Implemented Interfaces:

ChannelHandler

Direct Known Subclasses:

AbstractMemcacheObjectDecoder, Bzip2Decoder, DelimiterBasedFrameDecoder, FastLzFrameDecoder, FixedLengthFrameDecoder, HAProxyMessageDecoder, Http2ConnectionHandler, Http2OrHttpChooser, HttpObjectDecoder, JsonObjectDecoder, LengthFieldBasedFrameDecoder, LineBasedFrameDecoder, Lz4FrameDecoder, LzfDecoder, ProtobufVarint32FrameDecoder, ReplayingDecoder, SnappyFrameDecoder, SniHandler, SocksPortUnificationServerHandler, SpdyFrameCodec, SpdyOrHttpChooser, SslHandler, WebSocket08FrameDecoder, XmlFrameDecoder, ZlibDecoder

public abstract class ByteToMessageDecoder
extends ChannelHandlerAdapter

A ChannelHandler 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 Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ByteToMessageDecoder.Cumulator Cumulate ByteBufs.

Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

ChannelHandler.Sharable, ChannelHandler.Skip

Field Summary

Fields

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ByteToMessageDecoder()

Method Summary

Methods

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 ctx, ByteBuf in, List<Object> out) Called once data should be decoded from the given ByteBuf.
void	channelInactive(ChannelHandlerContext ctx) Calls ChannelHandlerContext.fireChannelInactive() to forward to the next ChannelHandler in the ChannelPipeline.
void	channelRead(ChannelHandlerContext ctx, Object msg) Calls ChannelHandlerContext.fireChannelRead(Object) to forward to the next ChannelHandler in the ChannelPipeline.
void	channelReadComplete(ChannelHandlerContext ctx) Calls ChannelHandlerContext.fireChannelReadComplete() to forward to the next ChannelHandler in the ChannelPipeline.
protected abstract void	decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> 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.
void	handlerRemoved(ChannelHandlerContext ctx) Do nothing by default, sub-classes may override this method.
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.
boolean	isSingleDecode() If true then only one message is decoded on each channelRead(ChannelHandlerContext, Object) call.
void	setCumulator(ByteToMessageDecoder.Cumulator cumulator) Set the ByteToMessageDecoder.Cumulator to use for cumulate the received ByteBufs.
void	setSingleDecode(boolean singleDecode) If set then only one message is decoded on each channelRead(ChannelHandlerContext, Object) call.

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

bind, channelActive, channelRegistered, channelUnregistered, channelWritabilityChanged, close, connect, deregister, disconnect, exceptionCaught, flush, handlerAdded, isSharable, read, userEventTriggered, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MERGE_CUMULATOR

public static final ByteToMessageDecoder.Cumulator MERGE_CUMULATOR

Cumulate ByteBufs by merge them into one ByteBuf's, using memory copies.

COMPOSITE_CUMULATOR

public static final ByteToMessageDecoder.Cumulator COMPOSITE_CUMULATOR

Cumulate ByteBufs 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 then just use the MERGE_CUMULATOR.

Constructor Detail

ByteToMessageDecoder

protected ByteToMessageDecoder()

Method Detail

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.

setCumulator

public void setCumulator(ByteToMessageDecoder.Cumulator cumulator)

Set the ByteToMessageDecoder.Cumulator to use for cumulate the received ByteBufs.

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 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.

handlerRemoved

public final void handlerRemoved(ChannelHandlerContext ctx)
                          throws Exception

Description copied from class: ChannelHandlerAdapter

Do nothing by default, sub-classes may override this method.

Specified by:

handlerRemoved in interface ChannelHandler

Overrides:

handlerRemoved in class ChannelHandlerAdapter

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 class: ChannelHandlerAdapter

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

Specified by:

channelRead in interface ChannelHandler

Overrides:

channelRead in class ChannelHandlerAdapter

Throws:

Exception

channelReadComplete

public void channelReadComplete(ChannelHandlerContext ctx)
                         throws Exception

Description copied from class: ChannelHandlerAdapter

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

Specified by:

channelReadComplete in interface ChannelHandler

Overrides:

channelReadComplete in class ChannelHandlerAdapter

Throws:

Exception

channelInactive

public void channelInactive(ChannelHandlerContext ctx)
                     throws Exception

Description copied from class: ChannelHandlerAdapter

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

Specified by:

channelInactive in interface ChannelHandler

Overrides:

channelInactive in class ChannelHandlerAdapter

Throws:

Exception

callDecode

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 - the ChannelHandlerContext which this ByteToMessageDecoder belongs to

in - the ByteBuf from which to read data

out - the List to which decoded messages should be added

decode

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 - the ChannelHandlerContext which this ByteToMessageDecoder belongs to

in - the ByteBuf from which to read data

out - the List to which decoded messages should be added

Throws:

Exception - is thrown if an error accour

decodeLast

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.

Throws:

Exception