Javadoc

src/main/java/org/jboss/netty/handler/codec/frame/LengthFieldPrepender.java

@@ -24,14 +24,42 @@ package org.jboss.netty.handler.codec.frame;
 
 import static org.jboss.netty.buffer.ChannelBuffers.*;
 
+import java.nio.ByteOrder;
+
 import org.jboss.netty.buffer.ChannelBuffer;
+import org.jboss.netty.buffer.ChannelBufferFactory;
 import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelHandlerContext;
 import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.handler.codec.oneone.OneToOneEncoder;
 
 /**
- * TODO Documentation
+ * An encoder that prepends the length of the message.  The length value is
+ * prepended as a binary form.  It is encoded in either big endian or little
+ * endian depending on the default {@link ByteOrder} of the current
+ * {@link ChannelBufferFactory}.
+ * <p>
+ * For example, <tt>{@link LengthFieldPrepender}(2)</tt> will encode the
+ * following 12-bytes string:
+ * <pre>
+ * +----------------+
+ * | "HELLO, WORLD" |
+ * +----------------+
+ * </pre>
+ * into the following:
+ * <pre>
+ * +--------+----------------+
+ * + 0x000C | "HELLO, WORLD" |
+ * +--------+----------------+
+ * </pre>
+ * If you turned on the {@code lengthIncludesLengthFieldLength} flag in the
+ * constructor, the encoded data would look like the following
+ * (12 (original data) + 2 (prepended data) = 14 (0xE)):
+ * <pre>
+ * +--------+----------------+
+ * + 0x000E | "HELLO, WORLD" |
+ * +--------+----------------+
+ * </pre>
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -43,10 +71,32 @@ public class LengthFieldPrepender extends OneToOneEncoder {
     private final int lengthFieldLength;
     private final boolean lengthIncludesLengthFieldLength;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param lengthFieldLength the length of the prepended length field.
+     *                          Only 1, 2, 3, 4, and 8 are allowed.
+     *
+     * @throws IllegalArgumentException
+     *         if {@code lengthFieldLength} is not 1, 2, 3, 4, or 8
+     */
     public LengthFieldPrepender(int lengthFieldLength) {
         this(lengthFieldLength, false);
     }
 
+    /**
+     * Creates a new instance.
+     *
+     * @param lengthFieldLength the length of the prepended length field.
+     *                          Only 1, 2, 3, 4, and 8 are allowed.
+     * @param lengthIncludesLengthFieldLength
+     *                          if {@code true}, the length of the prepended
+     *                          length field is added to the value of the
+     *                          prepended length field.
+     *
+     * @throws IllegalArgumentException
+     *         if {@code lengthFieldLength} is not 1, 2, 3, 4, or 8
+     */
     public LengthFieldPrepender(
             int lengthFieldLength, boolean lengthIncludesLengthFieldLength) {
         if (lengthFieldLength != 1 && lengthFieldLength != 2 &&