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}. + * + *
+ * {@link Delimiters} defines frequently used delimiters for convenience' sake. + * + *
+ * {@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); }