andreacavalli/netty5
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Added JavaDoc for handler.codec.frame package.

Browse Source
This commit is contained in:
Trustin Lee 2008-09-04 03:00:48 +00:00
parent a79f3ff159
commit 26a1d6e429
5 changed files with 104 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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) {

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

@ -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' }),

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

@ -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(

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

@ -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.
* <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
* one or more meaningful <strong>frames</strong> 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 <strong>frames</strong> 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:
* <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 {

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

@ -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);
}