Improved Javadoc of LengthFieldBasedFrameDecoder
This commit is contained in:
Trustin Lee
parent
c729e34603
commit
50012fd8e6
@ -27,15 +27,21 @@ import org.jboss.netty.channel.ChannelHandlerContext;
|
||||
* <p>
|
||||
* {@link LengthFieldBasedFrameDecoder} has many configuration parameters so
|
||||
* that it can decode any message with a length field, which is often seen in
|
||||
* proprietary client-server protocols. Here are some example that will give
|
||||
* proprietary client-server protocols. Here are some example that will give
|
||||
* you the basic idea on which option does what.
|
||||
*
|
||||
* <h3>2 bytes length field at offset 0, do not strip header</h3>
|
||||
*
|
||||
* The value of the length field in this example is <tt>10 (0x0C)</tt> which
|
||||
* represents the length of "HELLO, WORLD". By default, the decoder assumes
|
||||
* that the length field represents the number of the bytes that follows the
|
||||
* length field. Therefore, it can be decoded with the simplistic parameter
|
||||
* combination.
|
||||
* <pre>
|
||||
* <b>lengthFieldOffset</b> = <b>0</b>
|
||||
* <b>lengthFieldLength</b> = <b>2</b>
|
||||
* <b>lengthAdjustment</b> = <b>0</b> (default)
|
||||
* <b>initialBytesToStrip</b> = <b>0</b> (default)
|
||||
* lengthAdjustment = 0
|
||||
* initialBytesToStrip = 0 (= do not strip header)
|
||||
*
|
||||
* BEFORE DECODE (14 bytes) AFTER DECODE (14 bytes)
|
||||
* +--------+----------------+ +--------+----------------+
|
||||
@ -45,11 +51,16 @@ import org.jboss.netty.channel.ChannelHandlerContext;
|
||||
* </pre>
|
||||
*
|
||||
* <h3>2 bytes length field at offset 0, strip header</h3>
|
||||
*
|
||||
* Because we can get the length of the content by calling
|
||||
* {@link ChannelBuffer#readableBytes()}, you might want to strip the length
|
||||
* field by specifying <tt>initialBytesToStrip</tt>. In this example, we
|
||||
* specified <tt>2</tt>, that is same with the length of the length field.
|
||||
* <pre>
|
||||
* <b>lengthFieldOffset</b> = <b>0</b>
|
||||
* <b>lengthFieldLength</b> = <b>2</b>
|
||||
* <b>lengthAdjustment</b> = <b>0</b>
|
||||
* <b>initialBytesToStrip</b> = <b>2</b>
|
||||
* lengthFieldOffset = 0
|
||||
* lengthFieldLength = 2
|
||||
* lengthAdjustment = 0
|
||||
* <b>initialBytesToStrip</b> = <b>2</b> (= the length of the Length field)
|
||||
*
|
||||
* BEFORE DECODE (14 bytes) AFTER DECODE (12 bytes)
|
||||
* +--------+----------------+ +----------------+
|
||||
@ -58,25 +69,80 @@ import org.jboss.netty.channel.ChannelHandlerContext;
|
||||
* +--------+----------------+ +----------------+
|
||||
* </pre>
|
||||
*
|
||||
* <h3>3 bytes length field at the end of 5 bytes header, strip header</h3>
|
||||
* <pre>
|
||||
* <b>lengthFieldOffset</b> = <b>2</b> (= 5 - 3)
|
||||
* <b>lengthFieldLength</b> = <b>3</b>
|
||||
* <b>lengthAdjustment</b> = <b>0</b>
|
||||
* <b>initialBytesToStrip</b> = <b>5</b>
|
||||
* <h3>2 bytes length field at offset 0, do not strip header, the length field
|
||||
* represents the length of the whole message</h3>
|
||||
*
|
||||
* BEFORE DECODE (17 bytes) AFTER DECODE (12 bytes)
|
||||
* +----------+----------+----------------+ +----------------+
|
||||
* | Header 1 | Length | Actual Content |----->| Actual Content |
|
||||
* | 0xCAFE | 0x00000C | "HELLO, WORLD" | | "HELLO, WORLD" |
|
||||
* +----------+----------+----------------+ +----------------+
|
||||
* In most cases, the length field represents the length of the message body
|
||||
* only, as shown in the previous examples. However, in some protocols, the
|
||||
* length field represents the length of the whole message, including the
|
||||
* message header. In such a case, we specify a non-zero
|
||||
* <tt>lengthAdjustment</tt>. Because the length value in this example message
|
||||
* is always greater than the body length by <tt>2</tt>, we specify <tt>-2</tt>
|
||||
* as <tt>lengthAdjustment</tt> for compensation.
|
||||
* <pre>
|
||||
* lengthFieldOffset = 0
|
||||
* lengthFieldLength = 2
|
||||
* <b>lengthAdjustment</b> = <b>-2</b> (= 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" |
|
||||
* +--------+----------------+ +--------+----------------+
|
||||
* </pre>
|
||||
*
|
||||
* <h3>3 bytes length field at the end of 5 bytes header, do not strip header</h3>
|
||||
*
|
||||
* The following message is a simple variation of the first example. An extra
|
||||
* header value is prepended to the message. <tt>lengthAdjustment</tt> is zero
|
||||
* again because the decoder always counts the length of the prepended data into
|
||||
* frame length calculation.
|
||||
* <pre>
|
||||
* <b>lengthFieldOffset</b> = <b>2</b> (= the length of Header 1)
|
||||
* <b>lengthFieldLength</b> = <b>3</b>
|
||||
* 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" |
|
||||
* +----------+----------+----------------+ +----------+----------+----------------+
|
||||
* </pre>
|
||||
*
|
||||
* <h3>3 bytes length field at the beginning of 5 bytes header, do not strip header</h3>
|
||||
*
|
||||
* This is an advanced example that shows a case where there is an extra header
|
||||
* between the length field and the message body. You have to specify a
|
||||
* positive <tt>lengthAdjustment</tt> so that the decoder counts the extra
|
||||
* header into the frame length calculation.
|
||||
* <pre>
|
||||
* lengthFieldOffset = 0
|
||||
* lengthFieldLength = 3
|
||||
* <b>lengthAdjustment</b> = <b>2</b> (= 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" |
|
||||
* +----------+----------+----------------+ +----------+----------+----------------+
|
||||
* </pre>
|
||||
*
|
||||
* <h3>2 bytes length field at offset 1 in the middle of 4 bytes header,
|
||||
* strip the first header field and the length field</h3>
|
||||
*
|
||||
* This is a combination of all the examples above. There are the prepended
|
||||
* header before the length field and the extra header after the length field.
|
||||
* The prepended header affects the <tt>lengthFieldOffset</tt> and the extra
|
||||
* header affects the <tt>lengthAdjustment</tt>. We also specified a non-zero
|
||||
* <tt>initialBytesToStrip</tt> to strip the length field and the prepended
|
||||
* header from the frame. If you don't want to strip the prepended header, you
|
||||
* could specify <tt>0</tt> for <tt>initialBytesToSkip</tt>.
|
||||
* <pre>
|
||||
* <b>lengthFieldOffset</b> = <b>1</b>
|
||||
* <b>lengthFieldLength</b> = <b>2</b>
|
||||
* lengthFieldOffset</b> = 1 (= the length of HDR1)
|
||||
* lengthFieldLength</b> = 2
|
||||
* <b>lengthAdjustment</b> = <b>1</b> (= the length of HDR2)
|
||||
* <b>initialBytesToStrip</b> = <b>3</b> (= the length of HDR1 + LEN)
|
||||
*
|
||||
@ -89,10 +155,17 @@ import org.jboss.netty.channel.ChannelHandlerContext;
|
||||
*
|
||||
* <h3>2 bytes length field at offset 1 in the middle of 4 bytes header,
|
||||
* strip the first header field and the length field, the length field
|
||||
* includes the header length</h3>
|
||||
* represents the length of the whole message</h3>
|
||||
*
|
||||
* Let's give another twist to the previous example. The only difference from
|
||||
* the previous example is that the length field represents the length of the
|
||||
* whole message instead of the message body, just like the third example.
|
||||
* We have to count the length of HDR1 and Length into <tt>lengthAdjustment</tt>.
|
||||
* Please note that we don't need to take the length of HDR2 into account
|
||||
* because the length field already includes the whole header length.
|
||||
* <pre>
|
||||
* <b>lengthFieldOffset</b> = <b> 1</b>
|
||||
* <b>lengthFieldLength</b> = <b> 2</b>
|
||||
* lengthFieldOffset = 1
|
||||
* lengthFieldLength = 2
|
||||
* <b>lengthAdjustment</b> = <b>-3</b> (= the length of HDR1 + LEN, negative)
|
||||
* <b>initialBytesToStrip</b> = <b> 3</b>
|
||||
*
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user