From 26a1d6e429364575ff0f2c8bb989c8c4791b58b8 Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Thu, 4 Sep 2008 03:00:48 +0000 Subject: [PATCH] Added JavaDoc for handler.codec.frame package. --- .../frame/DelimiterBasedFrameDecoder.java | 51 +++++++++++++++++++ .../netty/handler/codec/frame/Delimiters.java | 10 ++++ .../codec/frame/FixedLengthFrameDecoder.java | 22 +++++++- .../handler/codec/frame/FrameDecoder.java | 15 +++--- .../codec/frame/TooLongFrameException.java | 15 ++++++ 5 files changed, 104 insertions(+), 9 deletions(-) diff --git a/src/main/java/org/jboss/netty/handler/codec/frame/DelimiterBasedFrameDecoder.java b/src/main/java/org/jboss/netty/handler/codec/frame/DelimiterBasedFrameDecoder.java index f978f279f6..b334a661de 100644 --- a/src/main/java/org/jboss/netty/handler/codec/frame/DelimiterBasedFrameDecoder.java +++ b/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}. + * + *

Predefined delimiters

+ *

+ * {@link Delimiters} defines frequently used delimiters for convenience' sake. + * + *

Specifying more than one delimiter

+ *

+ * {@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: + * 

+ * +--------------+
+ * | ABC\nDEF\r\n |
+ * +--------------+
+ *
+ * a {@link DelimiterBasedFrameDecoder}{@code (}{@link Delimiters#lineDelimiter() Delimiters.lineDelimiter()}{@code )} + * will choose {@code '\n'} as the first delimiter and produce two frames: + * 
+ * +-----+-----+
+ * | ABC | DEF |
+ * +-----+-----+
+ *
+ * rather than incorrectly choosing {@code '\r\n'} as the first delimiter: + * 
+ * +----------+
+ * | ABC\nDEF |
+ * +----------+
+ *
+ * * @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) { diff --git a/src/main/java/org/jboss/netty/handler/codec/frame/Delimiters.java b/src/main/java/org/jboss/netty/handler/codec/frame/Delimiters.java index 05024c90ec..ab4444c2e2 100644 --- a/src/main/java/org/jboss/netty/handler/codec/frame/Delimiters.java +++ b/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' }), diff --git a/src/main/java/org/jboss/netty/handler/codec/frame/FixedLengthFrameDecoder.java b/src/main/java/org/jboss/netty/handler/codec/frame/FixedLengthFrameDecoder.java index a92be0b889..a79aa1b01f 100644 --- a/src/main/java/org/jboss/netty/handler/codec/frame/FixedLengthFrameDecoder.java +++ b/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: + * 
+ * +---+----+------+----+
+ * | A | BC | DEFG | HI |
+ * +---+----+------+----+
+ *
+ * A {@link FixedLengthFrameDecoder}{@code (3)} will decode them into the + * following three packets with the fixed length: + * 
+ * +-----+-----+-----+
+ * | ABC | DEF | GHI |
+ * +-----+-----+-----+
+ *
+ * * @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( diff --git a/src/main/java/org/jboss/netty/handler/codec/frame/FrameDecoder.java b/src/main/java/org/jboss/netty/handler/codec/frame/FrameDecoder.java index 1516c151d6..1da74f6e03 100644 --- a/src/main/java/org/jboss/netty/handler/codec/frame/FrameDecoder.java +++ b/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 - * frame object. + * Decodes the received {@link ChannelBuffer}s into a meaningful frame object. *

* 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; * +----+-------+---+---+ * *

- * {@link FrameDecoder} helps you defrag and split the received packets into - * one or more meaningful frames that could be easily - * understood by the application logic. In case of the example above, your - * {@link FrameDecoder} implementation could defrag the received packets like - * the following: + * {@link FrameDecoder} helps you defrag the received packets into one or more + * meaningful frames that could be easily understood by the + * application logic. In case of the example above, your {@link FrameDecoder} + * implementation could defrag the received packets like the following: * 

  * +-----+-----+-----+
  * | ABC | DEF | GHI |
  * +-----+-----+-----+
  *
*

- * 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. * 

@@ -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 {
diff --git a/src/main/java/org/jboss/netty/handler/codec/frame/TooLongFrameException.java b/src/main/java/org/jboss/netty/handler/codec/frame/TooLongFrameException.java
index d8988a090e..53da68910e 100644
--- a/src/main/java/org/jboss/netty/handler/codec/frame/TooLongFrameException.java
+++ b/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);
     }