Added JavaDoc for handler.codec.frame package.

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

@@ -27,6 +27,41 @@ import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelHandlerContext;
 
 /**
+ * A {@link FrameDecoder} which decodes the received {@link ChannelBuffer}s
+ * into the {@link ChannelBuffer}s split by one or more delimiters.  It is
+ * particularly useful for decoding the frames which ends with a delimiter
+ * such as {@link Delimiters#nulDelimiter() NUL} or
+ *         {@linkplain Delimiters#lineDelimiter() newline characters}.
+ *
+ * <h3>Predefined delimiters</h3>
+ * <p>
+ * {@link Delimiters} defines frequently used delimiters for convenience' sake.
+ *
+ * <h3>Specifying more than one delimiter</h3>
+ * <p>
+ * {@link DelimiterBasedFrameDecoder} allows you to specify more than one
+ * delimiter.  If more than one delimiter is found in the buffer, it chooses
+ * the delimiter which produces the shortest frame.  For example, if you have
+ * the following data in the buffer:
+ * <pre>
+ * +--------------+
+ * | ABC\nDEF\r\n |
+ * +--------------+
+ * </pre>
+ * a {@link DelimiterBasedFrameDecoder}{@code (}{@link Delimiters#lineDelimiter() Delimiters.lineDelimiter()}{@code )}
+ * will choose {@code '\n'} as the first delimiter and produce two frames:
+ * <pre>
+ * +-----+-----+
+ * | ABC | DEF |
+ * +-----+-----+
+ * </pre>
+ * rather than incorrectly choosing {@code '\r\n'} as the first delimiter:
+ * <pre>
+ * +----------+
+ * | ABC\nDEF |
+ * +----------+
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
@@ -39,6 +74,14 @@ public class DelimiterBasedFrameDecoder extends FrameDecoder {
     private final ChannelBuffer[] delimiters;
     private final int maxFrameLength;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param maxFrameLength  the maximum length of the decoded frame.
+     *                        A {@link TooLongFrameException} is thrown if
+     *                        the length of the frame exceeds this value.
+     * @param delimiter  the delimiter
+     */
     public DelimiterBasedFrameDecoder(int maxFrameLength, ChannelBuffer delimiter) {
         validateMaxFrameLength(maxFrameLength);
         validateDelimiter(delimiter);
@@ -49,6 +92,14 @@ public class DelimiterBasedFrameDecoder extends FrameDecoder {
         this.maxFrameLength = maxFrameLength;
     }
 
+    /**
+     * Creates a new instance.
+     *
+     * @param maxFrameLength  the maximum length of the decoded frame.
+     *                        A {@link TooLongFrameException} is thrown if
+     *                        the length of the frame exceeds this value.
+     * @param delimiters  the delimiters
+     */
     public DelimiterBasedFrameDecoder(int maxFrameLength, ChannelBuffer... delimiters) {
         validateMaxFrameLength(maxFrameLength);
         if (delimiters == null) {

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

@@ -26,6 +26,8 @@ import org.jboss.netty.buffer.ChannelBuffer;
 import org.jboss.netty.buffer.ChannelBuffers;
 
 /**
+ * A set of delimiters for {@link DelimiterBasedFrameDecoder} for common use.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
@@ -34,11 +36,19 @@ import org.jboss.netty.buffer.ChannelBuffers;
  */
 public class Delimiters {
 
+    /**
+     * Returns a {@code NUL (0x00)} delimiter, which could be used for
+     * Flash XML socket or any similar protocols.
+     */
     public static ChannelBuffer[] nulDelimiter() {
         return new ChannelBuffer[] {
                 ChannelBuffers.wrappedBuffer(new byte[] { 0 }) };
     }
 
+    /**
+     * Returns {@code CR ('\r')} and {@code LF ('\n')} delimiters, which could
+     * be used for text-based line protocols.
+     */
     public static ChannelBuffer[] lineDelimiter() {
         return new ChannelBuffer[] {
                 ChannelBuffers.wrappedBuffer(new byte[] { '\r', '\n' }),

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

@@ -27,16 +27,36 @@ import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelHandlerContext;
 
 /**
+ * A {@link FrameDecoder} which decodes the received {@link ChannelBuffer}s
+ * into the {@link ChannelBuffer}s of the fixed length.  For example, if you
+ * received the following four fragmented packets:
+ * <pre>
+ * +---+----+------+----+
+ * | A | BC | DEFG | HI |
+ * +---+----+------+----+
+ * </pre>
+ * A {@link FixedLengthFrameDecoder}{@code (3)} will decode them into the
+ * following three packets with the fixed length:
+ * <pre>
+ * +-----+-----+-----+
+ * | ABC | DEF | GHI |
+ * +-----+-----+-----+
+ * </pre>
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
  * @version $Rev:231 $, $Date:2008-06-12 16:44:50 +0900 (목, 12 6월 2008) $
- *
  */
 public class FixedLengthFrameDecoder extends FrameDecoder {
 
     private final int frameLength;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param frameLength  the length of the frame
+     */
     public FixedLengthFrameDecoder(int frameLength) {
         if (frameLength <= 0) {
             throw new IllegalArgumentException(

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

@@ -38,8 +38,7 @@ import org.jboss.netty.channel.MessageEvent;
 import org.jboss.netty.channel.SimpleChannelHandler;
 
 /**
- * Assembles and splits incoming {@link ChannelBuffer}s into a meaningful
+ * Decodes the received {@link ChannelBuffer}s into a meaningful frame object.
- * frame object.
  * <p>
  * In a stream-based transport such as TCP/IP, packets can be fragmented and
  * reassembled during transmission even in a LAN environment.  For example,
@@ -57,18 +56,17 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  * +----+-------+---+---+
  * </pre>
  * <p>
- * {@link FrameDecoder} helps you defrag and split the received packets into
+ * {@link FrameDecoder} helps you defrag the received packets into one or more
- * one or more meaningful <strong>frames</strong> that could be easily
+ * meaningful <strong>frames</strong> that could be easily understood by the
- * understood by the application logic.  In case of the example above, your
+ * application logic.  In case of the example above, your {@link FrameDecoder}
- * {@link FrameDecoder} implementation could defrag the received packets like
+ * implementation could defrag the received packets like the following:
- * the following:
  * <pre>
  * +-----+-----+-----+
  * | ABC | DEF | GHI |
  * +-----+-----+-----+
  * </pre>
  * <p>
- * The following code shows an example decoder which decodes a frame whose
+ * The following code shows an example handler which decodes a frame whose
  * first 4 bytes header represents the length of the frame, excluding the
  * header.
  * <pre>
@@ -84,6 +82,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  * ======================
  *
  * public class IntegerHeaderFrameDecoder extends FrameDecoder {
+ *
  *   protected Object decode(ChannelHandlerContext ctx,
  *                           Channel channel,
  *                           ChannelBuffer buf) throws Exception {

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

@@ -23,6 +23,9 @@
 package org.jboss.netty.handler.codec.frame;
 
 /**
+ * An {@link Exception} which is thrown when the length of the frame
+ * decoded by {@link DelimiterBasedFrameDecoder} is greater than the maximum.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
@@ -34,18 +37,30 @@ public class TooLongFrameException extends Exception {
 
     private static final long serialVersionUID = -1995801950698951640L;
 
+    /**
+     * Creates a new instance.
+     */
     public TooLongFrameException() {
         super();
     }
 
+    /**
+     * Creates a new instance.
+     */
     public TooLongFrameException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Creates a new instance.
+     */
     public TooLongFrameException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a new instance.
+     */
     public TooLongFrameException(Throwable cause) {
         super(cause);
     }