Class ByteToMessageDecoder
- All Implemented Interfaces:
ChannelHandler
,ChannelInboundHandler
- Direct Known Subclasses:
AbstractMemcacheObjectDecoder
,Bzip2Decoder
,CleartextHttp2ServerUpgradeHandler
,DelimiterBasedFrameDecoder
,FastLzFrameDecoder
,FixedLengthFrameDecoder
,HAProxyMessageDecoder
,Http2ConnectionHandler
,HttpObjectDecoder
,JsonObjectDecoder
,LengthFieldBasedFrameDecoder
,LineBasedFrameDecoder
,OptionalSslHandler
,RedisDecoder
,ReplayingDecoder
,SnappyFrameDecoder
,SocksPortUnificationServerHandler
,SpdyFrameCodec
,SslClientHelloHandler
,SslHandler
,WebSocket08FrameDecoder
,XmlFrameDecoder
,ZlibDecoder
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 extendsByteToMessageDecoder
{@Override
public void decode(ChannelHandlerContext
ctx,ByteBuf
in, List<Object> out) throwsException
{ 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
invalid @link
{@link @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 ClassesNested classes/interfaces inherited from interface io.netty.channel.ChannelHandler
ChannelHandler.Sharable
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final ByteToMessageDecoder.Cumulator
CumulateByteBuf
s by add them to aCompositeByteBuf
and so do no memory copy whenever possible.(package private) ByteBuf
private ByteToMessageDecoder.Cumulator
private byte
A bitmask where the bits are defined asSTATE_INIT
STATE_CALLING_CHILD_DECODE
STATE_HANDLER_REMOVED_PENDING
private int
private boolean
This flag is used to determine if we need to callChannelHandlerContext.read()
to consume more data whenChannelConfig.isAutoRead()
isfalse
.private boolean
static final ByteToMessageDecoder.Cumulator
private int
private boolean
private boolean
private static final byte
private static final byte
private static final byte
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected int
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 givenByteBuf
.void
CallsChannelHandlerContext.fireChannelInactive()
to forward to the nextChannelInboundHandler
in theChannelPipeline
.private void
channelInputClosed
(ChannelHandlerContext ctx, boolean callChannelInactive) (package private) 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 ofChannelInputShutdownEvent
.void
channelRead
(ChannelHandlerContext ctx, Object msg) CallsChannelHandlerContext.fireChannelRead(Object)
to forward to the nextChannelInboundHandler
in theChannelPipeline
.void
CallsChannelHandlerContext.fireChannelReadComplete()
to forward to the nextChannelInboundHandler
in theChannelPipeline
.protected abstract void
decode
(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) Decode the from oneByteBuf
to an other.protected void
decodeLast
(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) Is called one last time when theChannelHandlerContext
goes in-active.(package private) final void
decodeRemovalReentryProtection
(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) Decode the from oneByteBuf
to an other.protected final void
(package private) static ByteBuf
expandCumulation
(ByteBufAllocator alloc, ByteBuf oldCumulation, ByteBuf in) (package private) static void
fireChannelRead
(ChannelHandlerContext ctx, CodecOutputList msgs, int numElements) GetnumElements
out of theCodecOutputList
and forward these through the pipeline.(package private) static void
fireChannelRead
(ChannelHandlerContext ctx, List<Object> msgs, int numElements) GetnumElements
out of theList
and forward these through the pipeline.final void
Do nothing by default, sub-classes may override this method.protected void
Gets called after theByteToMessageDecoder
was removed from the actual context and it doesn't handle events anymore.protected ByteBuf
Returns the internal cumulative buffer of this decoder.boolean
Iftrue
then only one message is decoded on eachchannelRead(ChannelHandlerContext, Object)
call.void
setCumulator
(ByteToMessageDecoder.Cumulator cumulator) Set theByteToMessageDecoder.Cumulator
to use for cumulate the receivedByteBuf
s.void
setDiscardAfterReads
(int discardAfterReads) Set the number of reads after whichByteBuf.discardSomeReadBytes()
are called and so free up memory.void
setSingleDecode
(boolean singleDecode) If set then only one message is decoded on eachchannelRead(ChannelHandlerContext, Object)
call.void
userEventTriggered
(ChannelHandlerContext ctx, Object evt) CallsChannelHandlerContext.fireUserEventTriggered(Object)
to forward to the nextChannelInboundHandler
in theChannelPipeline
.Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter
channelActive, channelRegistered, channelUnregistered, channelWritabilityChanged, exceptionCaught
Methods inherited from class io.netty.channel.ChannelHandlerAdapter
ensureNotSharable, handlerAdded, isSharable
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface io.netty.channel.ChannelHandler
handlerAdded
-
Field Details
-
MERGE_CUMULATOR
-
COMPOSITE_CUMULATOR
CumulateByteBuf
s by add them to aCompositeByteBuf
and so do no memory copy whenever possible. Be aware thatCompositeByteBuf
use a more complex indexing implementation so depending on your use-case and the decoder implementation this may be slower than just use theMERGE_CUMULATOR
. -
STATE_INIT
private static final byte STATE_INIT- See Also:
-
STATE_CALLING_CHILD_DECODE
private static final byte STATE_CALLING_CHILD_DECODE- See Also:
-
STATE_HANDLER_REMOVED_PENDING
private static final byte STATE_HANDLER_REMOVED_PENDING- See Also:
-
cumulation
ByteBuf cumulation -
cumulator
-
singleDecode
private boolean singleDecode -
first
private boolean first -
firedChannelRead
private boolean firedChannelReadThis flag is used to determine if we need to callChannelHandlerContext.read()
to consume more data whenChannelConfig.isAutoRead()
isfalse
. -
selfFiredChannelRead
private boolean selfFiredChannelRead -
decodeState
private byte decodeStateA bitmask where the bits are defined as -
discardAfterReads
private int discardAfterReads -
numReads
private int numReads
-
-
Constructor Details
-
ByteToMessageDecoder
protected ByteToMessageDecoder()
-
-
Method Details
-
setSingleDecode
public void setSingleDecode(boolean singleDecode) If set then only one message is decoded on eachchannelRead(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 isfalse
as this has performance impacts. -
isSingleDecode
public boolean isSingleDecode()Iftrue
then only one message is decoded on eachchannelRead(ChannelHandlerContext, Object)
call. Default isfalse
as this has performance impacts. -
setCumulator
Set theByteToMessageDecoder.Cumulator
to use for cumulate the receivedByteBuf
s. -
setDiscardAfterReads
public void setDiscardAfterReads(int discardAfterReads) Set the number of reads after whichByteBuf.discardSomeReadBytes()
are called and so free up memory. The default is16
. -
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 tointernalBuffer().readableBytes()
. -
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
Description copied from class:ChannelHandlerAdapter
Do nothing by default, sub-classes may override this method.- Specified by:
handlerRemoved
in interfaceChannelHandler
- Overrides:
handlerRemoved
in classChannelHandlerAdapter
- Throws:
Exception
-
handlerRemoved0
Gets called after theByteToMessageDecoder
was removed from the actual context and it doesn't handle events anymore.- Throws:
Exception
-
channelRead
Description copied from class:ChannelInboundHandlerAdapter
CallsChannelHandlerContext.fireChannelRead(Object)
to forward to the nextChannelInboundHandler
in theChannelPipeline
. Sub-classes may override this method to change behavior.- Specified by:
channelRead
in interfaceChannelInboundHandler
- Overrides:
channelRead
in classChannelInboundHandlerAdapter
- Throws:
Exception
-
fireChannelRead
GetnumElements
out of theList
and forward these through the pipeline. -
fireChannelRead
GetnumElements
out of theCodecOutputList
and forward these through the pipeline. -
channelReadComplete
Description copied from class:ChannelInboundHandlerAdapter
CallsChannelHandlerContext.fireChannelReadComplete()
to forward to the nextChannelInboundHandler
in theChannelPipeline
. Sub-classes may override this method to change behavior.- Specified by:
channelReadComplete
in interfaceChannelInboundHandler
- Overrides:
channelReadComplete
in classChannelInboundHandlerAdapter
- Throws:
Exception
-
discardSomeReadBytes
protected final void discardSomeReadBytes() -
channelInactive
Description copied from class:ChannelInboundHandlerAdapter
CallsChannelHandlerContext.fireChannelInactive()
to forward to the nextChannelInboundHandler
in theChannelPipeline
. Sub-classes may override this method to change behavior.- Specified by:
channelInactive
in interfaceChannelInboundHandler
- Overrides:
channelInactive
in classChannelInboundHandlerAdapter
- Throws:
Exception
-
userEventTriggered
Description copied from class:ChannelInboundHandlerAdapter
CallsChannelHandlerContext.fireUserEventTriggered(Object)
to forward to the nextChannelInboundHandler
in theChannelPipeline
. Sub-classes may override this method to change behavior.- Specified by:
userEventTriggered
in interfaceChannelInboundHandler
- Overrides:
userEventTriggered
in classChannelInboundHandlerAdapter
- Throws:
Exception
-
channelInputClosed
-
channelInputClosed
Called when the input of the channel was closed which may be because it changed to inactive or because ofChannelInputShutdownEvent
.- Throws:
Exception
-
callDecode
Called once data should be decoded from the givenByteBuf
. This method will calldecode(ChannelHandlerContext, ByteBuf, List)
as long as decoding should take place.- Parameters:
ctx
- theChannelHandlerContext
which thisByteToMessageDecoder
belongs toin
- theByteBuf
from which to read dataout
- theList
to which decoded messages should be added
-
decode
protected abstract void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws Exception Decode the from oneByteBuf
to an other. This method will be called till either the inputByteBuf
has nothing to read when return from this method or till nothing was read from the inputByteBuf
.- Parameters:
ctx
- theChannelHandlerContext
which thisByteToMessageDecoder
belongs toin
- theByteBuf
from which to read dataout
- theList
to which decoded messages should be added- Throws:
Exception
- is thrown if an error occurs
-
decodeRemovalReentryProtection
final void decodeRemovalReentryProtection(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) throws Exception Decode the from oneByteBuf
to an other. This method will be called till either the inputByteBuf
has nothing to read when return from this method or till nothing was read from the inputByteBuf
.- Parameters:
ctx
- theChannelHandlerContext
which thisByteToMessageDecoder
belongs toin
- theByteBuf
from which to read dataout
- theList
to which decoded messages should be added- Throws:
Exception
- is thrown if an error occurs
-
decodeLast
Is called one last time when theChannelHandlerContext
goes in-active. Which means thechannelInactive(ChannelHandlerContext)
was triggered. By default, this will just calldecode(ChannelHandlerContext, ByteBuf, List)
but sub-classes may override this for some special cleanup operation.- Throws:
Exception
-
expandCumulation
-