Javadoc

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(

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.
+ *
+ * <h3>Parameters that prevents excessive memory consumption</h3>
+ * <table>
+ * <tr>
+ * <th>Name</th><th>Meaning</th>
+ * </tr>
+ * <tr>
+ * <td>{@code maxInitialLineLength}</td>
+ * <td>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.</td>
+ * </tr>
+ * <tr>
+ * <td>{@code maxHeaderSize}</td>
+ * <td>The maximum length of all headers.  If the sum of the length of each
+ *     header exceeds this value, a {@link TooLongFrameException} will be raised.</td>
+ * </tr>
+ * <tr>
+ * <td>{@code maxChunkSize}</td>
+ * <td>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}.</td>
+ * </tr>
+ * </table>
+ *
+ * <h3>Extensibility</h3>
+ *
+ * Please note that this decoder is designed to be extended to implement
+ * a protocol derived from HTTP, such as
+ * <a href="http://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
+ * <a href="http://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>.
+ * 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 ReplayingDecoder<HttpMessageDec
     private int headerSize;
 
     /**
+     * The internal state of {@link HttpMessageDecoder}.
+     * <em>Internal use only</em>.
+     *
      * @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 ReplayingDecoder<HttpMessageDec
         READ_CHUNK_FOOTER;
     }
 
+    /**
+     * Creates a new instance with the default
+     * {@code maxInitialLineLength (4096}}, {@code maxHeaderSize (4096)}, and
+     * {@code maxChunkSize (4096)}.
+     */
     protected HttpMessageDecoder() {
         this(4096, 8192, 8192);
     }
 
+    /**
+     * Creates a new instance with the specified parameters.
+     */
     protected HttpMessageDecoder(
             int maxInitialLineLength, int maxHeaderSize, int maxChunkSize) {
 

src/main/java/org/jboss/netty/handler/codec/http/HttpMessageEncoder.java

@@ -36,7 +36,17 @@ import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.handler.codec.oneone.OneToOneEncoder;
 
 /**
- * encodes an http message
+ * Encodes an {@link HttpMessage} or an {@link HttpChunk} into
+ * a {@link ChannelBuffer}.
+ *
+ * <h3>Extensibility</h3>
+ *
+ * Please note that this encoder is designed to be extended to implement
+ * a protocol derived from HTTP, such as
+ * <a href="http://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
+ * <a href="http://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>.
+ * 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;
     }
 
-    /**
+    private void encodeHeaders(ChannelBuffer buf, HttpMessage message) {
-     * writes the headers
-     * Header1: value1
-     * Header2: value2
-     *
-     * @param buf
-     * @param message
-     */
-    public void encodeHeaders(ChannelBuffer buf, HttpMessage message) {
         Set<String> headers = message.getHeaderNames();
         try {
             for (String header : headers) {

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.
+ *
+ * <h3>Parameters that prevents excessive memory consumption</h3>
+ * <table>
+ * <tr>
+ * <th>Name</th><th>Meaning</th>
+ * </tr>
+ * <tr>
+ * <td>{@code maxInitialLineLength}</td>
+ * <td>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.</td>
+ * </tr>
+ * <tr>
+ * <td>{@code maxHeaderSize}</td>
+ * <td>The maximum length of all headers.  If the sum of the length of each
+ *     header exceeds this value, a {@link TooLongFrameException} will be raised.</td>
+ * </tr>
+ * <tr>
+ * <td>{@code maxChunkSize}</td>
+ * <td>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}.</td>
+ * </tr>
+ * </table>
  *
  * @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);

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;

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.
+ *
+ * <h3>Parameters that prevents excessive memory consumption</h3>
+ * <table>
+ * <tr>
+ * <th>Name</th><th>Meaning</th>
+ * </tr>
+ * <tr>
+ * <td>{@code maxInitialLineLength}</td>
+ * <td>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.</td>
+ * </tr>
+ * <tr>
+ * <td>{@code maxHeaderSize}</td>
+ * <td>The maximum length of all headers.  If the sum of the length of each
+ *     header exceeds this value, a {@link TooLongFrameException} will be raised.</td>
+ * </tr>
+ * <tr>
+ * <td>{@code maxChunkSize}</td>
+ * <td>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}.</td>
+ * </tr>
+ * </table>
  *
  * @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);

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