From 6058cf3981dc4cf8bfb4df9422a4624b6b23e8df Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Fri, 19 Jun 2009 15:35:19 +0000 Subject: [PATCH] Javadoc --- .../codec/http/HttpChunkAggregator.java | 14 +++++ .../codec/http/HttpMessageDecoder.java | 54 ++++++++++++++++++- .../codec/http/HttpMessageEncoder.java | 29 ++++++---- .../codec/http/HttpRequestDecoder.java | 43 ++++++++++++++- .../codec/http/HttpRequestEncoder.java | 10 +++- .../codec/http/HttpResponseDecoder.java | 44 ++++++++++++++- .../codec/http/HttpResponseEncoder.java | 11 +++- 7 files changed, 188 insertions(+), 17 deletions(-) diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpChunkAggregator.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpChunkAggregator.java index 2dd7e3c4b4..1bf9dae934 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpChunkAggregator.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpChunkAggregator.java @@ -26,6 +26,7 @@ import java.util.List; import org.jboss.netty.buffer.ChannelBuffer; import org.jboss.netty.buffer.ChannelBuffers; +import org.jboss.netty.channel.ChannelHandler; import org.jboss.netty.channel.ChannelHandlerContext; import org.jboss.netty.channel.ChannelPipelineCoverage; import org.jboss.netty.channel.Channels; @@ -34,6 +35,11 @@ import org.jboss.netty.channel.SimpleChannelUpstreamHandler; import org.jboss.netty.handler.codec.frame.TooLongFrameException; /** + * A {@link ChannelHandler} that aggregates an {@link HttpMessage} + * and its following {@link HttpChunk}s into an {@link HttpMessage} with no + * following {@link HttpChunk}s. It is useful when you don't want to take + * care of HTTP messages whose transfer encoding is 'chunked'. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ @@ -44,6 +50,14 @@ public class HttpChunkAggregator extends SimpleChannelUpstreamHandler { private final int maxContentLength; private volatile HttpMessage currentMessage; + /** + * Creates a new instance. + * + * @param maxContentLength + * the maximum length of the aggregated content. + * If the length of the aggregated content exceeds this value, + * a {@link TooLongFrameException} will be raised. + */ public HttpChunkAggregator(int maxContentLength) { if (maxContentLength <= 0) { throw new IllegalArgumentException( diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageDecoder.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageDecoder.java index 7adfbc897f..39a43321bd 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageDecoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpMessageDecoder.java @@ -27,11 +27,52 @@ import org.jboss.netty.buffer.ChannelBuffer; import org.jboss.netty.buffer.ChannelBuffers; import org.jboss.netty.channel.Channel; import org.jboss.netty.channel.ChannelHandlerContext; +import org.jboss.netty.channel.ChannelPipeline; import org.jboss.netty.handler.codec.frame.TooLongFrameException; import org.jboss.netty.handler.codec.replay.ReplayingDecoder; /** - * Decodes an Http type message. + * Decodes {@link ChannelBuffer}s into {@link HttpMessage}s and + * {@link HttpChunk}s. + * + *

Parameters that prevents excessive memory consumption

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NameMeaning
{@code maxInitialLineLength}The maximum length of the initial line + * (e.g. {@code "GET / HTTP/1.0"} or {@code "HTTP/1.0 200 OK"}) + * If the length of the initial line exceeds this value, a + * {@link TooLongFrameException} will be raised.
{@code maxHeaderSize}The maximum length of all headers. If the sum of the length of each + * header exceeds this value, a {@link TooLongFrameException} will be raised.
{@code maxChunkSize}The maximum length of the content or each chunk. If the content length + * exceeds this value, the transfer encoding of the decoded message will be + * converted to 'chunked' and the content will be split into multiple + * {@link HttpChunk}s. If the transfer encoding of the HTTP message is + * 'chunked' already, each chunk will be split into smaller chunks if the + * length of the chunk exceeds this value. If you prefer not to handle + * {@link HttpChunk}s in your handler, insert {@link HttpChunkAggregator} + * after this decoder in the {@link ChannelPipeline}.
+ * + *

Extensibility

+ * + * Please note that this decoder is designed to be extended to implement + * a protocol derived from HTTP, such as + * RTSP and + * ICAP. + * To implement the decoder of such a derived protocol, extend this class and + * implement all abstract methods properly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) @@ -49,6 +90,9 @@ public abstract class HttpMessageDecoder extends ReplayingDecoderInternal use only. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ @@ -70,10 +114,18 @@ public abstract class HttpMessageDecoder extends ReplayingDecoderExtensibility + * + * Please note that this encoder is designed to be extended to implement + * a protocol derived from HTTP, such as + * RTSP and + * ICAP. + * To implement the encoder of such a derived protocol, extend this class and + * implement all abstract methods properly. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) @@ -48,6 +58,13 @@ public abstract class HttpMessageEncoder extends OneToOneEncoder { private static final ChannelBuffer LAST_CHUNK = copiedBuffer("0\r\n\r\n", "ASCII"); + /** + * Creates a new instance. + */ + protected HttpMessageEncoder() { + super(); + } + @Override protected Object encode(ChannelHandlerContext ctx, Channel channel, Object msg) throws Exception { if (msg instanceof HttpMessage) { @@ -86,15 +103,7 @@ public abstract class HttpMessageEncoder extends OneToOneEncoder { return msg; } - /** - * writes the headers - * Header1: value1 - * Header2: value2 - * - * @param buf - * @param message - */ - public void encodeHeaders(ChannelBuffer buf, HttpMessage message) { + private void encodeHeaders(ChannelBuffer buf, HttpMessage message) { Set headers = message.getHeaderNames(); try { for (String header : headers) { diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpRequestDecoder.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpRequestDecoder.java index 6ca62d52d9..586a524ad5 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpRequestDecoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpRequestDecoder.java @@ -21,9 +21,42 @@ */ package org.jboss.netty.handler.codec.http; +import org.jboss.netty.buffer.ChannelBuffer; +import org.jboss.netty.channel.ChannelPipeline; +import org.jboss.netty.handler.codec.frame.TooLongFrameException; + /** - * decodes an http request. + * Decodes {@link ChannelBuffer}s into {@link HttpRequest}s and {@link HttpChunk}s. + * + *

Parameters that prevents excessive memory consumption

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NameMeaning
{@code maxInitialLineLength}The maximum length of the initial line (e.g. {@code "GET / HTTP/1.0"}) + * If the length of the initial line exceeds this value, a + * {@link TooLongFrameException} will be raised.
{@code maxHeaderSize}The maximum length of all headers. If the sum of the length of each + * header exceeds this value, a {@link TooLongFrameException} will be raised.
{@code maxChunkSize}The maximum length of the content or each chunk. If the content length + * exceeds this value, the transfer encoding of the decoded request will be + * converted to 'chunked' and the content will be split into multiple + * {@link HttpChunk}s. If the transfer encoding of the HTTP request is + * 'chunked' already, each chunk will be split into smaller chunks if the + * length of the chunk exceeds this value. If you prefer not to handle + * {@link HttpChunk}s in your handler, insert {@link HttpChunkAggregator} + * after this decoder in the {@link ChannelPipeline}.
* * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) @@ -32,10 +65,18 @@ package org.jboss.netty.handler.codec.http; */ public class HttpRequestDecoder extends HttpMessageDecoder { + /** + * Creates a new instance with the default + * {@code maxInitialLineLength (4096}}, {@code maxHeaderSize (4096)}, and + * {@code maxChunkSize (4096)}. + */ public HttpRequestDecoder() { super(); } + /** + * Creates a new instance with the specified parameters. + */ public HttpRequestDecoder( int maxInitialLineLength, int maxHeaderSize, int maxChunkSize) { super(maxInitialLineLength, maxHeaderSize, maxChunkSize); diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpRequestEncoder.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpRequestEncoder.java index 92b158a9ed..d0f453743e 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpRequestEncoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpRequestEncoder.java @@ -26,7 +26,8 @@ import static org.jboss.netty.handler.codec.http.HttpCodecUtil.*; import org.jboss.netty.buffer.ChannelBuffer; /** - * encodes an http request + * Encodes an {@link HttpRequest} or an {@link HttpChunk} into + * a {@link ChannelBuffer}. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) @@ -34,9 +35,14 @@ import org.jboss.netty.buffer.ChannelBuffer; * @version $Rev$, $Date$ */ public class HttpRequestEncoder extends HttpMessageEncoder { + /** - * writes the initial line i.e. 'GET /path/to/file/index.html HTTP/1.0' + * Creates a new instance. */ + public HttpRequestEncoder() { + super(); + } + @Override protected void encodeInitialLine(ChannelBuffer buf, HttpMessage message) throws Exception { HttpRequest request = (HttpRequest) message; diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpResponseDecoder.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpResponseDecoder.java index 740042e3f2..92003b6299 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpResponseDecoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpResponseDecoder.java @@ -21,9 +21,43 @@ */ package org.jboss.netty.handler.codec.http; +import org.jboss.netty.buffer.ChannelBuffer; +import org.jboss.netty.channel.ChannelPipeline; +import org.jboss.netty.handler.codec.frame.TooLongFrameException; + /** - * an http response decoder + * Decodes {@link ChannelBuffer}s into {@link HttpResponse}s and + * {@link HttpChunk}s. + * + *

Parameters that prevents excessive memory consumption

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
NameMeaning
{@code maxInitialLineLength}The maximum length of the initial line (e.g. {@code "HTTP/1.0 200 OK"}) + * If the length of the initial line exceeds this value, a + * {@link TooLongFrameException} will be raised.
{@code maxHeaderSize}The maximum length of all headers. If the sum of the length of each + * header exceeds this value, a {@link TooLongFrameException} will be raised.
{@code maxChunkSize}The maximum length of the content or each chunk. If the content length + * exceeds this value, the transfer encoding of the decoded response will be + * converted to 'chunked' and the content will be split into multiple + * {@link HttpChunk}s. If the transfer encoding of the HTTP response is + * 'chunked' already, each chunk will be split into smaller chunks if the + * length of the chunk exceeds this value. If you prefer not to handle + * {@link HttpChunk}s in your handler, insert {@link HttpChunkAggregator} + * after this decoder in the {@link ChannelPipeline}.
* * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) @@ -32,10 +66,18 @@ package org.jboss.netty.handler.codec.http; */ public class HttpResponseDecoder extends HttpMessageDecoder { + /** + * Creates a new instance with the default + * {@code maxInitialLineLength (4096}}, {@code maxHeaderSize (4096)}, and + * {@code maxChunkSize (4096)}. + */ public HttpResponseDecoder() { super(); } + /** + * Creates a new instance with the specified parameters. + */ public HttpResponseDecoder( int maxInitialLineLength, int maxHeaderSize, int maxChunkSize) { super(maxInitialLineLength, maxHeaderSize, maxChunkSize); diff --git a/src/main/java/org/jboss/netty/handler/codec/http/HttpResponseEncoder.java b/src/main/java/org/jboss/netty/handler/codec/http/HttpResponseEncoder.java index 6c61e91f23..156249de52 100644 --- a/src/main/java/org/jboss/netty/handler/codec/http/HttpResponseEncoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/http/HttpResponseEncoder.java @@ -28,7 +28,8 @@ import java.io.UnsupportedEncodingException; import org.jboss.netty.buffer.ChannelBuffer; /** - * encodes an http response + * Encodes an {@link HttpResponse} or an {@link HttpChunk} into + * a {@link ChannelBuffer}. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Andy Taylor (andy.taylor@jboss.org) @@ -37,6 +38,13 @@ import org.jboss.netty.buffer.ChannelBuffer; */ public class HttpResponseEncoder extends HttpMessageEncoder { + /** + * Creates a new instance. + */ + public HttpResponseEncoder() { + super(); + } + @Override protected void encodeInitialLine(ChannelBuffer buf, HttpMessage message) { HttpResponse response = (HttpResponse) message; @@ -51,5 +59,4 @@ public class HttpResponseEncoder extends HttpMessageEncoder { throw (Error) new Error().initCause(e); } } - }