Module io.netty5.codec

Package io.netty5.handler.codec

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.

Field Summary

Fields

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

Constructor Summary

Constructors

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

Method Summary

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