Improved Javadoc

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

@@ -16,25 +16,17 @@
 package org.jboss.netty.handler.codec.http;
 
 import org.jboss.netty.buffer.ChannelBuffer;
-import org.jboss.netty.channel.ChannelPipeline;
 import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.handler.codec.compression.ZlibEncoder;
 import org.jboss.netty.handler.codec.compression.ZlibWrapper;
 import org.jboss.netty.handler.codec.embedder.EncoderEmbedder;
 
 /**
- * Decompresses an {@link HttpMessage} and an {@link HttpChunk} compressed in
+ * Compresses an {@link HttpMessage} and an {@link HttpChunk} in {@code gzip} or
- * {@code gzip} or {@code deflate} encoding.  Insert this handler after
+ * {@code deflate} encoding while respecting the {@code "Accept-Encoding"} header.
- * {@link HttpMessageDecoder} in the {@link ChannelPipeline}:
+ * If there is no matching encoding, no compression is done.  For more
- * <pre>
+ * information on how this handler modifies the message, please refer to
- * ChannelPipeline p = ...;
+ * {@link HttpContentEncoder}.
- * ...
- * p.addLast("decoder", new HttpRequestDecoder());
- * p.addLast("inflater", <b>new HttpContentDecomperssor()</b>);
- * ...
- * p.addLast("encoder", new HttpResponseEncoder());
- * p.addLast("handler", new HttpRequestHandler());
- * </pre>
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (trustin@gmail.com)
@@ -45,10 +37,21 @@ public class HttpContentCompressor extends HttpContentEncoder {
 
     private final int compressionLevel;
 
+    /**
+     * Creates a new handler with the default compression level (<tt>6</tt>).
+     */
     public HttpContentCompressor() {
         this(6);
     }
 
+    /**
+     * Creates a new handler with the specified compression level.
+     *
+     * @param compressionLevel
+     *        {@code 1} yields the fastest compression and {@code 9} yields the
+     *        best compression.  {@code 0} means no compression.  The default
+     *        compression level is {@code 6}.
+     */
     public HttpContentCompressor(int compressionLevel) {
         if (compressionLevel < 0 || compressionLevel > 9) {
             throw new IllegalArgumentException(

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

@@ -25,19 +25,23 @@ import org.jboss.netty.channel.SimpleChannelUpstreamHandler;
 import org.jboss.netty.handler.codec.embedder.DecoderEmbedder;
 
 /**
- * Decodes the content of the received {@link HttpMessage} and {@link HttpChunk}.
+ * Decodes the content of the received {@link HttpRequest} and {@link HttpChunk}.
- * The original content ({@link HttpMessage#getContent()} or {@link HttpChunk#getContent()})
+ * The original content is replaced with the new content decoded by the
- * is replaced with the new content decoded by the {@link DecoderEmbedder},
+ * {@link DecoderEmbedder}, which is created by {@link #newContentDecoder(String)}.
- * which is created by {@link #newContentDecoder(String)}.  Once decoding is finished,
+ * Once decoding is finished, the value of the <tt>'Content-Encoding'</tt>
- * the value of the <tt>'Content-Encoding'</tt> header is set to <tt>'identity'</tt>
+ * header is set to the target content encoding, as returned by {@link #getTargetContentEncoding(String)}.
- * and the <tt>'Content-Length'</tt> header is updated to the length of the
+ * Also, the <tt>'Content-Length'</tt> header is updated to the length of the
  * decoded content.  If the content encoding of the original is not supported
- * by the decoder, {@link #newContentDecoder(String)} returns {@code null} and no
+ * by the decoder, {@link #newContentDecoder(String)} should return {@code null}
- * decoding occurs (i.e. pass-through).
+ * so that no decoding occurs (i.e. pass-through).
  * <p>
  * Please note that this is an abstract class.  You have to extend this class
  * and implement {@link #newContentDecoder(String)} properly to make this class
  * functional.  For example, refer to the source code of {@link HttpContentDecompressor}.
+ * <p>
+ * This handler must be placed after {@link HttpMessageDecoder} in the pipeline
+ * so that this handler can intercept HTTP requests after {@link HttpMessageDecoder}
+ * converts {@link ChannelBuffer}s into HTTP requests.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (trustin@gmail.com)
@@ -147,7 +151,7 @@ public abstract class HttpContentDecoder extends SimpleChannelUpstreamHandler {
      * This method returns {@code "identity"} by default, which is the case for
      * most decoders.
      *
-     * @param contentEncoding the content encoding of the original content
+     * @param contentEncoding the value of the {@code "Content-Encoding"} header
      * @return the expected content encoding of the new content
      */
     protected String getTargetContentEncoding(String contentEncoding) throws Exception {

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

@@ -16,7 +16,6 @@
 package org.jboss.netty.handler.codec.http;
 
 import org.jboss.netty.buffer.ChannelBuffer;
-import org.jboss.netty.channel.ChannelPipeline;
 import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.handler.codec.compression.ZlibDecoder;
 import org.jboss.netty.handler.codec.compression.ZlibWrapper;
@@ -24,17 +23,8 @@ import org.jboss.netty.handler.codec.embedder.DecoderEmbedder;
 
 /**
  * Decompresses an {@link HttpMessage} and an {@link HttpChunk} compressed in
- * {@code gzip} or {@code deflate} encoding.  Insert this handler after
+ * {@code gzip} or {@code deflate} encoding.  For more information on how this
- * {@link HttpMessageDecoder} in the {@link ChannelPipeline}:
+ * handler modifies the message, please refer to {@link HttpContentDecoder}.
- * <pre>
- * ChannelPipeline p = ...;
- * ...
- * p.addLast("decoder", new HttpRequestDecoder());
- * p.addLast("inflater", <b>new HttpContentDecomperssor()</b>);
- * ...
- * p.addLast("encoder", new HttpResponseEncoder());
- * p.addLast("handler", new HttpRequestHandler());
- * </pre>
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (trustin@gmail.com)

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

@@ -23,11 +23,29 @@ import org.jboss.netty.channel.ChannelHandlerContext;
 import org.jboss.netty.channel.Channels;
 import org.jboss.netty.channel.MessageEvent;
 import org.jboss.netty.channel.SimpleChannelHandler;
-import org.jboss.netty.handler.codec.embedder.DecoderEmbedder;
 import org.jboss.netty.handler.codec.embedder.EncoderEmbedder;
 import org.jboss.netty.util.internal.LinkedTransferQueue;
 
 /**
+ * Encodes the content of the outbound {@link HttpResponse} and {@link HttpChunk}.
+ * The original content is replaced with the new content encoded by the
+ * {@link EncoderEmbedder}, which is created by {@link #newContentEncoder(String)}.
+ * Once encoding is finished, the value of the <tt>'Content-Encoding'</tt> header
+ * is set to the target content encoding, as returned by {@link #getTargetContentEncoding(String)}.
+ * Also, the <tt>'Content-Length'</tt> header is updated to the length of the
+ * encoded content.  If there is no supported encoding in the
+ * corresponding {@link HttpRequest}'s {@code "Accept-Encoding"} header,
+ * {@link #newContentEncoder(String)} should return {@code null} so that no
+ * encoding occurs (i.e. pass-through).
+ * <p>
+ * Please note that this is an abstract class.  You have to extend this class
+ * and implement {@link #newContentEncoder(String)} and {@link #getTargetContentEncoding(String)}
+ * properly to make this class functional.  For example, refer to the source
+ * code of {@link HttpContentCompressor}.
+ * <p>
+ * This handler must be placed after {@link HttpMessageEncoder} in the pipeline
+ * so that this handler can intercept HTTP responses before {@link HttpMessageEncoder}
+ * converts them into {@link ChannelBuffer}s.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (trustin@gmail.com)
@@ -145,18 +163,17 @@ public abstract class HttpContentEncoder extends SimpleChannelHandler {
      * content.
      *
      * @param acceptEncoding
-     *        the value of the {@code "Accept-Encoding"} header.
+     *        the value of the {@code "Accept-Encoding"} header
      *
-     * @return a new {@link DecoderEmbedder} if the specified encoding is supported.
+     * @return a new {@link EncoderEmbedder} if there is a supported encoding
-     *         {@code null} otherwise (alternatively, you can throw an exception
+     *         in {@code acceptEncoding}.  {@code null} otherwise.
-     *         to block unknown encoding).
      */
     protected abstract EncoderEmbedder<ChannelBuffer> newContentEncoder(String acceptEncoding) throws Exception;
 
     /**
      * Returns the expected content encoding of the encoded content.
      *
-     * @param contentEncoding the content encoding of the original content
+     * @param acceptEncoding the value of the {@code "Accept-Encoding"} header
      * @return the expected content encoding of the new content
      */
     protected abstract String getTargetContentEncoding(String acceptEncoding) throws Exception;