ByteToMessageDecoder (Netty API Reference (4.0.56.Final))

JavaScript is disabled on your browser.

Skip navigation links

All Classes

Summary:
Nested |
Field |
Constr |
Method

Detail:
Field |
Constr |
Method

io.netty.handler.codec

Class ByteToMessageDecoder

java.lang.Object
- io.netty.channel.ChannelHandlerAdapter
- - io.netty.channel.ChannelInboundHandlerAdapter
  - - io.netty.handler.codec.ByteToMessageDecoder

All Implemented Interfaces:

ChannelHandler, ChannelInboundHandler

Direct Known Subclasses:

DelimiterBasedFrameDecoder, FixedLengthFrameDecoder, HAProxyMessageDecoder, HttpObjectDecoder, LengthFieldBasedFrameDecoder, LineBasedFrameDecoder, OptionalSslHandler, ProtobufVarint32FrameDecoder, ReplayingDecoder, SnappyFramedDecoder, SniHandler, SpdyFrameCodec, SpdyOrHttpChooser, SslHandler, ZlibDecoder
```
public abstract class ByteToMessageDecoder
extends ChannelInboundHandlerAdapter 
```
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 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

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

Field Summary

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

Constructor Summary

Constructors
Modifier Constructor and Description

protected ByteToMessageDecoder ()

Constructors
Modifier	Constructor and Description
`protected`	`ByteToMessageDecoder ()`

Method Summary

All 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, java.util.List<java.lang.Object> out)` Called once data should be decoded from the given `ByteBuf`.
`void`	`channelInactive (ChannelHandlerContext ctx)` Calls `ChannelHandlerContext.fireChannelInactive()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
`void`	`channelRead (ChannelHandlerContext ctx, java.lang.Object msg)` Calls `ChannelHandlerContext.fireChannelRead(Object)` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
`void`	`channelReadComplete (ChannelHandlerContext ctx)` Calls `ChannelHandlerContext.fireChannelReadComplete()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
`protected abstract void`	`decode (ChannelHandlerContext ctx, ByteBuf in, java.util.List<java.lang.Object> out)` Decode the from one `ByteBuf` to an other.
`protected void`	`decodeLast (ChannelHandlerContext ctx, ByteBuf in, java.util.List<java.lang.Object> out)` Is called one last time when the `ChannelHandlerContext` goes in-active.
`protected void`	`discardSomeReadBytes ()`
`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 `ByteBuf`s.
`void`	`setDiscardAfterReads (int discardAfterReads)` Set the number of reads after which `ByteBuf.discardSomeReadBytes()` are called and so free up memory.
`void`	`setSingleDecode (boolean singleDecode)` If set then only one message is decoded on each `channelRead(ChannelHandlerContext, Object)` call.
`void`	`userEventTriggered (ChannelHandlerContext ctx, java.lang.Object evt)` Calls `ChannelHandlerContext.fireUserEventTriggered(Object)` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.

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 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.
  - setDiscardAfterReads
```
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.
  - 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 java.lang.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:
    
    java.lang.Exception
  - handlerRemoved0
```
protected void handlerRemoved0(ChannelHandlerContext ctx)
 throws java.lang.Exception
```
    Gets called after the ByteToMessageDecoder was removed from the actual context and it doesn't handle events anymore.
    
    Throws:
    
    java.lang.Exception
  - channelRead
```
public void channelRead(ChannelHandlerContext ctx,
 java.lang.Object msg)
 throws java.lang.Exception
```
    Description copied from class: ChannelInboundHandlerAdapter
    
    Calls ChannelHandlerContext.fireChannelRead(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.
    
    Specified by:
    
    channelRead in interface ChannelInboundHandler
    
    Overrides:
    
    channelRead in class ChannelInboundHandlerAdapter
    
    Throws:
    
    java.lang.Exception
  - channelReadComplete
```
public void channelReadComplete(ChannelHandlerContext ctx)
 throws java.lang.Exception
```
    Description copied from class: ChannelInboundHandlerAdapter
    
    Calls ChannelHandlerContext.fireChannelReadComplete() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.
    
    Specified by:
    
    channelReadComplete in interface ChannelInboundHandler
    
    Overrides:
    
    channelReadComplete in class ChannelInboundHandlerAdapter
    
    Throws:
    
    java.lang.Exception
  - discardSomeReadBytes
```
protected final void discardSomeReadBytes()
```
  - channelInactive
```
public void channelInactive(ChannelHandlerContext ctx)
 throws java.lang.Exception
```
    Description copied from class: ChannelInboundHandlerAdapter
    
    Calls ChannelHandlerContext.fireChannelInactive() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.
    
    Specified by:
    
    channelInactive in interface ChannelInboundHandler
    
    Overrides:
    
    channelInactive in class ChannelInboundHandlerAdapter
    
    Throws:
    
    java.lang.Exception
  - userEventTriggered
```
public void userEventTriggered(ChannelHandlerContext ctx,
 java.lang.Object evt)
 throws java.lang.Exception
```
    Description copied from class: ChannelInboundHandlerAdapter
    
    Calls ChannelHandlerContext.fireUserEventTriggered(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.
    
    Specified by:
    
    userEventTriggered in interface ChannelInboundHandler
    
    Overrides:
    
    userEventTriggered in class ChannelInboundHandlerAdapter
    
    Throws:
    
    java.lang.Exception
  - callDecode
```
protected void callDecode(ChannelHandlerContext ctx,
 ByteBuf in,
 java.util.List<java.lang.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,
 java.util.List<java.lang.Object> out)
 throws java.lang.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:
    
    java.lang.Exception - is thrown if an error occurs
  - decodeLast
```
protected void decodeLast(ChannelHandlerContext ctx,
 ByteBuf in,
 java.util.List<java.lang.Object> out)
 throws java.lang.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:
    
    java.lang.Exception

Skip navigation links

All Classes

Summary:
Nested |
Field |
Constr |
Method

Detail:
Field |
Constr |
Method

Class ByteToMessageDecoder

Frame detection

Pitfalls

Nested Class Summary

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

Field Summary

Constructor Summary

Method Summary

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

Methods inherited from class java.lang.Object

Methods inherited from interface io.netty.channel.ChannelHandler

Field Detail

MERGE_CUMULATOR

COMPOSITE_CUMULATOR

Constructor Detail

ByteToMessageDecoder

Method Detail

setSingleDecode

isSingleDecode

setCumulator

setDiscardAfterReads

actualReadableBytes

internalBuffer

handlerRemoved

handlerRemoved0

channelRead

channelReadComplete

discardSomeReadBytes

channelInactive

userEventTriggered

callDecode

decode

decodeLast