diff --git a/src/main/java/org/jboss/netty/handler/codec/frame/LengthFieldBasedFrameDecoder.java b/src/main/java/org/jboss/netty/handler/codec/frame/LengthFieldBasedFrameDecoder.java index 6c626d7f9b..5045852692 100644 --- a/src/main/java/org/jboss/netty/handler/codec/frame/LengthFieldBasedFrameDecoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/frame/LengthFieldBasedFrameDecoder.java @@ -27,7 +27,89 @@ import org.jboss.netty.channel.Channel; import org.jboss.netty.channel.ChannelHandlerContext; /** - * TODO Documentation + * A decoder that decodes the received {@link ChannelBuffer}s that contain + * a message length field into a meaningfully framed {@link ChannelBuffer}. + * It is particularly useful when you decode a binary message which has an + * integer header field that represents the length of the message body or the + * whole message. + *

+ * {@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 + * you the basic idea on which option does what. + * + *

4 bytes length field at offset 0, strip header

+ * 
+ * lengthFieldOffset   = 0
+ * lengthFieldLength   = 4
+ * lengthAdjustment    = 0
+ * initialBytesToStrip = 4
+ *
+ * BEFORE DECODE (16 bytes)               AFTER DECODE (12 bytes)
+ * +--------------+----------------+      +----------------+
+ * | Length Field | Actual Content |----->| Actual Content |
+ * |  0x0000000C  | "HELLO, WORLD" |      | "HELLO, WORLD" |
+ * +--------------+----------------+      +----------------+
+ *
+ * + *

2 bytes length Field at offset 0, do not strip header

+ * 
+ * lengthFieldOffset   = 0
+ * lengthFieldLength   = 2
+ * lengthAdjustment    = 0
+ * initialBytesToStrip = 0
+ *
+ * BEFORE DECODE (14 bytes)         AFTER DECODE (14 bytes)
+ * +--------+----------------+      +--------+----------------+
+ * | Length | Actual Content |----->| Length | Actual Content |
+ * | 0x000C | "HELLO, WORLD" |      | 0x000C | "HELLO, WORLD" |
+ * +--------+----------------+      +--------+----------------+
+ *
+ * + *

3 bytes length Field at the end of 5 bytes header, strip header

+ * 
+ * lengthFieldOffset   = 2 (= 5 - 3)
+ * lengthFieldLength   = 3
+ * lengthAdjustment    = 0
+ * initialBytesToStrip = 5
+ *
+ * BEFORE DECODE (17 bytes)                      AFTER DECODE (12 bytes)
+ * +----------+----------+----------------+      +----------------+
+ * | Header 1 |  Length  | Actual Content |----->| Actual Content |
+ * |  0xCAFE  | 0x00000C | "HELLO, WORLD" |      | "HELLO, WORLD" |
+ * +----------+----------+----------------+      +----------------+
+ *
+ * + *

2 bytes length Field at offset 1 in the middle of 4 bytes header, + * strip the first header field and the length field

+ * 
+ * lengthFieldOffset   = 1
+ * 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 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

+ * 
+ * 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" |
+ * +------+--------+------+----------------+      +------+----------------+
+ *
* * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -35,6 +117,7 @@ import org.jboss.netty.channel.ChannelHandlerContext; * @version $Rev:231 $, $Date:2008-06-12 16:44:50 +0900 (목, 12 6월 2008) $ * * @apiviz.landmark + * @see LengthFieldPrepender */ public class LengthFieldBasedFrameDecoder extends FrameDecoder { @@ -50,6 +133,16 @@ public class LengthFieldBasedFrameDecoder extends FrameDecoder { /** * Creates a new instance. + * + * @param maxFrameLength + * the maximum length of the frame. If the length of the frame is + * greater than this value, {@link TooLongFrameException} will be + * thrown. + * @param lengthFieldOffset + * the offset of the length field + * @param lengthFieldLength + * the length of the length field + * */ public LengthFieldBasedFrameDecoder( int maxFrameLength, @@ -59,6 +152,19 @@ public class LengthFieldBasedFrameDecoder extends FrameDecoder { /** * Creates a new instance. + * + * @param maxFrameLength + * the maximum length of the frame. If the length of the frame is + * greater than this value, {@link TooLongFrameException} will be + * thrown. + * @param lengthFieldOffset + * the offset of the length field + * @param lengthFieldLength + * the length of the length field + * @param lengthAdjustment + * the compensation value to add to the value of the length field + * @param initialBytesToStrip + * the number of first bytes to strip out from the decoded frame */ public LengthFieldBasedFrameDecoder( int maxFrameLength,