LengthFieldBasedFrameDecoder (Netty API Reference (4.1.22.Final))

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

All Implemented Interfaces:: ChannelHandler ， ChannelInboundHandler

已知直接子类：: MarshallingDecoder ， ObjectDecoder

public class LengthFieldBasedFrameDecoder
extends ByteToMessageDecoder

一个解码器，通过消息中的长度字段的值动态分割接收到的ByteBuf 。当解码具有表示消息正文或整个消息长度的整数标题字段的二进制消息时，它特别有用。

LengthFieldBasedFrameDecoder有许多配置参数，因此它可以解码长度字段的任何消息，这在专有的客户端 - 服务器协议中经常见到。这里有一些例子会给你关于哪个选项做什么的基本想法。

在偏移量为0的2字节长度字段中，不要剥离标题

本例中长度字段的值为12 (0x0C) ，表示“HELLO，WORLD”的长度。默认情况下，解码器假定长度字段表示长度字段后面的字节数。因此，它可以用简单的参数组合来解码。

  lengthFieldOffset   = 0
 lengthFieldLength   = 2
 lengthAdjustment    = 0
 initialBytesToStrip = 0 (= do not strip header)

 BEFORE DECODE (14 bytes)         AFTER DECODE (14 bytes)
 +--------+----------------+      +--------+----------------+
 | Length | Actual Content |----->| Length | Actual Content |
 | 0x000C | "HELLO, WORLD" |      | 0x000C | "HELLO, WORLD" |
 +--------+----------------+      +--------+----------------+

带偏移量0的2字节长度字段，带头

因为我们可以通过调用ByteBuf.readableBytes()来获取内容的长度，所以您可能希望通过指定initialBytesToStrip来剥离长度字段。在这个例子中，我们指定了2 ，这与长度字段的长度相同，以去掉前两个字节。

  lengthFieldOffset   = 0
 lengthFieldLength   = 2
 lengthAdjustment    = 0
 initialBytesToStrip = 2 (= the length of the Length field)

 BEFORE DECODE (14 bytes)         AFTER DECODE (12 bytes)
 +--------+----------------+      +----------------+
 | Length | Actual Content |----->| Actual Content |
 | 0x000C | "HELLO, WORLD" |      | "HELLO, WORLD" |
 +--------+----------------+      +----------------+

在偏移量为0的2字节长度字段中，不剥离标题，长度字段表示整个消息的长度

在大多数情况下，长度字段仅表示消息主体的长度，如前面的示例所示。但是，在某些协议中，长度字段表示整个消息的长度，包括消息头。在这种情况下，我们指定一个非零lengthAdjustment 。由于此示例消息中的长度值始终大于2的正文长度， 因此我们将-2指定为lengthAdjustment进行补偿。

  lengthFieldOffset   =  0
 lengthFieldLength   =  2
 lengthAdjustment    = -2 (= the length of the Length field)
 initialBytesToStrip =  0

 BEFORE DECODE (14 bytes)         AFTER DECODE (14 bytes)
 +--------+----------------+      +--------+----------------+
 | Length | Actual Content |----->| Length | Actual Content |
 | 0x000E | "HELLO, WORLD" |      | 0x000E | "HELLO, WORLD" |
 +--------+----------------+      +--------+----------------+

3个字节的长度字段在5个字节的标题末尾，不要去掉标题

以下消息是第一个示例的简单变体。消息前面加了一个额外的头部值。 lengthAdjustment再次为零，因为在帧长度计算期间解码器始终考虑前置数据的长度。

  lengthFieldOffset   = 2 (= the length of Header 1)
 lengthFieldLength   = 3
 lengthAdjustment    = 0
 initialBytesToStrip = 0

 BEFORE DECODE (17 bytes)                      AFTER DECODE (17 bytes)
 +----------+----------+----------------+      +----------+----------+----------------+
 | Header 1 |  Length  | Actual Content |----->| Header 1 |  Length  | Actual Content |
 |  0xCAFE  | 0x00000C | "HELLO, WORLD" |      |  0xCAFE  | 0x00000C | "HELLO, WORLD" |
 +----------+----------+----------------+      +----------+----------+----------------+

3个字节的长度字段在5个字节的头部开头，不要去掉头部

这是一个高级示例，它显示了长度字段和消息正文之间存在额外标题的情况。您必须指定正数lengthAdjustment，以便解码器将额外的报头计入帧长度计算中。

  lengthFieldOffset   = 0
 lengthFieldLength   = 3
 lengthAdjustment    = 2 (= the length of Header 1)
 initialBytesToStrip = 0

 BEFORE DECODE (17 bytes)                      AFTER DECODE (17 bytes)
 +----------+----------+----------------+      +----------+----------+----------------+
 |  Length  | Header 1 | Actual Content |----->|  Length  | Header 1 | Actual Content |
 | 0x00000C |  0xCAFE  | "HELLO, WORLD" |      | 0x00000C |  0xCAFE  | "HELLO, WORLD" |
 +----------+----------+----------------+      +----------+----------+----------------+

2字节长度字段在4字节标题中间偏移1处，剥离第一个标题字段和长度字段

这是上述所有示例的组合。在长度字段之前有前置标题，在长度字段之后有额外的标题。前置标题影响lengthFieldOffset ，额外标题影响lengthAdjustment 。我们还指定了一个非零initialBytesToStrip去除帧中的长度字段和前置头。如果您不想去除前置标题， 则可以为initialBytesToSkip指定0 。

  lengthFieldOffset   = 1 (= the length of HDR1)
 lengthFieldLength   = 2
 lengthAdjustment    = 1 (= the length of HDR2)
 initialBytesToStrip = 3 (= the length of HDR1 + LEN)

 BEFORE DECODE (16 bytes)                       AFTER DECODE (13 bytes)
 +------+--------+------+----------------+      +------+----------------+
 | HDR1 | Length | HDR2 | Actual Content |----->| HDR2 | Actual Content |
 | 0xCA | 0x000C | 0xFE | "HELLO, WORLD" |      | 0xFE | "HELLO, WORLD" |
 +------+--------+------+----------------+      +------+----------------+

2字节长度字段在偏移量为1的4字节头中间，剥离第一个头字段和长度字段，长度字段表示整个消息的长度

让我们再来看看前面的例子。与前面的示例唯一的区别是，长度字段代表整个消息的长度而不是消息正文，就像第三个示例一样。我们必须计算HDR1的长度和长度为lengthAdjustment 。请注意，我们不需要考虑HDR2的长度，因为长度字段已包含整个标题长度。

  lengthFieldOffset   =  1
 lengthFieldLength   =  2
 lengthAdjustment    = -3 (= the length of HDR1 + LEN, negative)
 initialBytesToStrip =  3

 BEFORE DECODE (16 bytes)                       AFTER DECODE (13 bytes)
 +------+--------+------+----------------+      +------+----------------+
 | HDR1 | Length | HDR2 | Actual Content |----->| HDR2 | Actual Content |
 | 0xCA | 0x0010 | 0xFE | "HELLO, WORLD" |      | 0xFE | "HELLO, WORLD" |
 +------+--------+------+----------------+      +------+----------------+

另请参见：: LengthFieldPrepender

Nested Class Summary
- Nested classes/interfaces inherited from class io.netty.handler.codec.ByteToMessageDecoder
  ByteToMessageDecoder.Cumulator
- Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler
  ChannelHandler.Sharable

Field Summary
- Fields inherited from class io.netty.handler.codec.ByteToMessageDecoder
  COMPOSITE_CUMULATOR, MERGE_CUMULATOR

构造方法摘要

构造方法
Constructor and Description
`LengthFieldBasedFrameDecoder(java.nio.ByteOrder byteOrder, int maxFrameLength, int lengthFieldOffset, int lengthFieldLength, int lengthAdjustment, int initialBytesToStrip, boolean failFast)` 创建一个新的实例。
`LengthFieldBasedFrameDecoder(int maxFrameLength, int lengthFieldOffset, int lengthFieldLength)` 创建一个新的实例。
`LengthFieldBasedFrameDecoder(int maxFrameLength, int lengthFieldOffset, int lengthFieldLength, int lengthAdjustment, int initialBytesToStrip)` 创建一个新的实例。
`LengthFieldBasedFrameDecoder(int maxFrameLength, int lengthFieldOffset, int lengthFieldLength, int lengthAdjustment, int initialBytesToStrip, boolean failFast)` 创建一个新的实例。

方法摘要

所有方法接口方法具体的方法
Modifier and Type	Method and Description
`protected java.lang.Object`	`decode(ChannelHandlerContext ctx, ByteBuf in)` 从`ByteBuf`中创建一个框架并将其返回。
`protected void`	`decode(ChannelHandlerContext ctx, ByteBuf in, java.util.List<java.lang.Object> out)` 解码从一个`ByteBuf`到另一个。
`protected ByteBuf`	`extractFrame(ChannelHandlerContext ctx, ByteBuf buffer, int index, int length)` 提取指定缓冲区的子区域。
`protected long`	`getUnadjustedFrameLength(ByteBuf buf, int offset, int length, java.nio.ByteOrder order)` 将缓冲区的指定区域解码为未调整的帧长度。

Methods inherited from class io.netty.handler.codec.ByteToMessageDecoder
actualReadableBytes, callDecode, channelInactive, channelRead, channelReadComplete, decodeLast, discardSomeReadBytes, handlerRemoved, handlerRemoved0, internalBuffer, isSingleDecode, setCumulator, setDiscardAfterReads, setSingleDecode, userEventTriggered

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

- 构造方法详细信息
  - LengthFieldBasedFrameDecoder
```
public LengthFieldBasedFrameDecoder(int maxFrameLength,
                                    int lengthFieldOffset,
                                    int lengthFieldLength)
```
    创建一个新的实例。
    
    参数
    
    maxFrameLength - 帧的最大长度。如果帧的长度大于此值，则会抛出TooLongFrameException 。
    
    lengthFieldOffset - 长度字段的偏移量
    
    lengthFieldLength - 长度字段的长度
  - LengthFieldBasedFrameDecoder
```
public LengthFieldBasedFrameDecoder(int maxFrameLength,
                                    int lengthFieldOffset,
                                    int lengthFieldLength,
                                    int lengthAdjustment,
                                    int initialBytesToStrip)
```
    创建一个新的实例。
    
    参数
    
    maxFrameLength - 帧的最大长度。如果帧的长度大于此值，则会抛出TooLongFrameException 。
    
    lengthFieldOffset - 长度字段的偏移量
    
    lengthFieldLength - 长度字段的长度
    
    lengthAdjustment - 要添加到长度字段值的补偿值
    
    initialBytesToStrip - 从解码帧中 initialBytesToStrip的第一个字节数
  - LengthFieldBasedFrameDecoder
```
public LengthFieldBasedFrameDecoder(int maxFrameLength,
                                    int lengthFieldOffset,
                                    int lengthFieldLength,
                                    int lengthAdjustment,
                                    int initialBytesToStrip,
                                    boolean failFast)
```
    创建一个新的实例。
    
    参数
    
    maxFrameLength - 帧的最大长度。如果帧的长度大于此值，则会抛出TooLongFrameException 。
    
    lengthFieldOffset - 长度字段的偏移量
    
    lengthFieldLength - 长度字段的长度
    
    lengthAdjustment - 要添加到长度字段值的补偿值
    
    initialBytesToStrip - 从解码帧中 initialBytesToStrip的第一个字节数
    
    failFast -如果true，一个TooLongFrameException被只要解码器注意到该帧的长度将超过maxFrameLength不管整个帧是否已被读出抛出。如果false，一个TooLongFrameException超过maxFrameLength整个框架已经被读取之后被抛出。
  - LengthFieldBasedFrameDecoder
```
public LengthFieldBasedFrameDecoder(java.nio.ByteOrder byteOrder,
                                    int maxFrameLength,
                                    int lengthFieldOffset,
                                    int lengthFieldLength,
                                    int lengthAdjustment,
                                    int initialBytesToStrip,
                                    boolean failFast)
```
    创建一个新的实例。
    
    参数
    
    byteOrder - 长度字段的 ByteOrder
    
    maxFrameLength - 帧的最大长度。如果帧的长度大于此值，则会抛出TooLongFrameException 。
    
    lengthFieldOffset - 长度字段的偏移量
    
    lengthFieldLength - 长度字段的长度
    
    lengthAdjustment - 要添加到长度字段值的补偿值
    
    initialBytesToStrip - 从解码帧中 initialBytesToStrip的第一个字节数
    
    failFast -如果true，一个TooLongFrameException被只要解码器注意到该帧的长度将超过maxFrameLength不管整个帧是否已被读出抛出。如果false，一个TooLongFrameException超过maxFrameLength整个框架已经被读取之后被抛出。
- 方法详细信息
  - decode
```
protected final void decode(ChannelHandlerContext ctx,
                            ByteBuf in,
                            java.util.List<java.lang.Object> out)
                     throws java.lang.Exception
```
    从类复制的描述： ByteToMessageDecoder
    
    解码从一个ByteBuf到另一个。该方法将被调用，直到输入ByteBuf在从此方法返回时没有任何可读的内容或直到从输入ByteBuf中没有读取任何内容。
    
    Specified by:
    
    decode在课程 ByteToMessageDecoder
    
    参数
    
    ctx - 这是ByteToMessageDecoder所属的ChannelHandlerContext
    
    in - 从中读取数据的ByteBuf
    
    out - 应该添加解码消息的 List
    
    异常
    
    java.lang.Exception - 发生错误时抛出
  - decode
```
protected java.lang.Object decode(ChannelHandlerContext ctx,
                                  ByteBuf in)
                           throws java.lang.Exception
```
    从ByteBuf中创建一个框架并将其返回。
    
    参数
    
    ctx - ByteToMessageDecoder属于的ChannelHandlerContext
    
    in - 从中读取数据的ByteBuf
    
    结果
    
    如果没有帧可以被创建，则帧ByteBuf代表帧或null 。
    
    异常
    
    java.lang.Exception
  - getUnadjustedFrameLength
```
protected long getUnadjustedFrameLength(ByteBuf buf,
                                        int offset,
                                        int length,
                                        java.nio.ByteOrder order)
```
    将缓冲区的指定区域解码为未调整的帧长度。默认实现能够将指定区域解码为无符号8/16/24/32/64位整数。重写此方法来解码编码不同的长度字段。注意，此方法不能修改指定缓冲器的状态（例如readerIndex ， writerIndex和缓冲器的内容。）
    
    异常
    
    DecoderException - 如果未能解码指定区域
  - extractFrame
```
protected ByteBuf extractFrame(ChannelHandlerContext ctx,
                               ByteBuf buffer,
                               int index,
                               int length)
```
    提取指定缓冲区的子区域。
    如果您确定在当前的decode(ChannelHandlerContext, ByteBuf)调用返回后没有访问帧及其内容，则甚至可以通过返回切片的子区域（即return buffer.slice(index, length) ）来避免内存复制。将提取的帧转换为对象时通常很有用。请参阅源代码ObjectDecoder以了解如何覆盖此方法以避免内存复制。

Class LengthFieldBasedFrameDecoder

在偏移量为0的2字节长度字段中，不要剥离标题

带偏移量0的2字节长度字段，带头

在偏移量为0的2字节长度字段中，不剥离标题，长度字段表示整个消息的长度

3个字节的长度字段在5个字节的标题末尾，不要去掉标题

3个字节的长度字段在5个字节的头部开头，不要去掉头部

2字节长度字段在4字节标题中间偏移1处，剥离第一个标题字段和长度字段

2字节长度字段在偏移量为1的4字节头中间，剥离第一个头字段和长度字段，长度字段表示整个消息的长度

Nested Class Summary

Nested classes/interfaces inherited from class io.netty.handler.codec.ByteToMessageDecoder

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

Field Summary

Fields inherited from class io.netty.handler.codec.ByteToMessageDecoder

构造方法摘要

方法摘要

Methods inherited from class io.netty.handler.codec.ByteToMessageDecoder

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

构造方法详细信息

LengthFieldBasedFrameDecoder

LengthFieldBasedFrameDecoder

LengthFieldBasedFrameDecoder

LengthFieldBasedFrameDecoder

方法详细信息

decode

decode

getUnadjustedFrameLength

extractFrame