* Added JavaDoc for the handler.codec.serialization package

* Improved JavaDoc for handler.codec.string and handler.ssl

src/main/java/org/jboss/netty/handler/codec/serialization/CompatibleObjectDecoder.java

@@ -24,6 +24,7 @@ package org.jboss.netty.handler.codec.serialization;
 
 import java.io.InputStream;
 import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
 import java.io.ObjectStreamConstants;
 
 import org.jboss.netty.buffer.ChannelBuffer;
@@ -34,6 +35,20 @@ import org.jboss.netty.handler.codec.replay.ReplayingDecoder;
 import org.jboss.netty.util.SwitchableInputStream;
 
 /**
+ * A decoder which deserializes the received {@link ChannelBuffer}s into Java
+ * objects (interoperability version).
+ * <p>
+ * This decoder is interoperable with the standard Java object
+ * streams such as {@link ObjectInputStream} and {@link ObjectOutputStream}.
+ * <p>
+ * However, this decoder might perform worse than {@link ObjectDecoder} if
+ * the serialized object is big and complex.  Also, it doesn't limit the
+ * maximum size of the object, and consequently your application might face
+ * the risk of <a href="http://en.wikipedia.org/wiki/DoS">DoS attack</a>.
+ * Please use {@link ObjectEncoder} and {@link ObjectDecoder} if you are not
+ * required to keep the interoperability with the standard object streams.
+ *
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
@@ -45,10 +60,22 @@ public class CompatibleObjectDecoder extends ReplayingDecoder<CompatibleObjectDe
     private final SwitchableInputStream bin = new SwitchableInputStream();
     private volatile ObjectInputStream oin;
 
+    /**
+     * Creates a new decoder.
+     */
     public CompatibleObjectDecoder() {
         super(CompatibleObjectDecoderState.READ_HEADER);
     }
 
+    /**
+     * Creates a new {@link ObjectInputStream} which wraps the specified
+     * {@link InputStream}.  Override this method to use a subclass of the
+     * {@link ObjectInputStream}.
+     */
+    protected ObjectInputStream newObjectInputStream(InputStream in) throws Exception {
+        return new ObjectInputStream(in);
+    }
+
     @Override
     protected Object decode(
             ChannelHandlerContext ctx, Channel channel, ChannelBuffer buffer, CompatibleObjectDecoderState state) throws Exception {
@@ -65,10 +92,6 @@ public class CompatibleObjectDecoder extends ReplayingDecoder<CompatibleObjectDe
         }
     }
 
-    protected ObjectInputStream newObjectInputStream(InputStream in) throws Exception {
-        return new ObjectInputStream(in);
-    }
-
     @Override
     protected Object decodeLast(ChannelHandlerContext ctx, Channel channel,
             ChannelBuffer buffer, CompatibleObjectDecoderState state)

src/main/java/org/jboss/netty/handler/codec/serialization/CompatibleObjectEncoder.java

@@ -25,6 +25,7 @@ package org.jboss.netty.handler.codec.serialization;
 import static org.jboss.netty.buffer.ChannelBuffers.*;
 import static org.jboss.netty.channel.Channels.*;
 
+import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.OutputStream;
 
@@ -37,11 +38,16 @@ import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.channel.MessageEvent;
 
 /**
+ * An encoder which serializes a Java object into a {@link ChannelBuffer}
+ * (interoperability version).
+ * <p>
+ * This encoder is interoperable with the standard Java object streams such as
+ * {@link ObjectInputStream} and {@link ObjectOutputStream}.
+ *
  * @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) $
- *
  */
 @ChannelPipelineCoverage("all")
 public class CompatibleObjectEncoder implements ChannelDownstreamHandler {
@@ -51,10 +57,22 @@ public class CompatibleObjectEncoder implements ChannelDownstreamHandler {
     private volatile ObjectOutputStream oout;
     private int writtenObjects;
 
+    /**
+     * Creates a new instance with the reset interval of {@code 16}.
+     */
     public CompatibleObjectEncoder() {
         this(16); // Reset at every sixteen writes
     }
 
+    /**
+     * Creates a new instance.
+     *
+     * @param resetInterval
+     *        the number of objects between {@link ObjectOutputStream#reset()}.
+     *        {@code 0} will disable resetting the stream, but the remote
+     *        peer will be at the risk of getting {@link OutOfMemoryError} in
+     *        the long term.
+     */
     public CompatibleObjectEncoder(int resetInterval) {
         if (resetInterval < 0) {
             throw new IllegalArgumentException(
@@ -63,6 +81,15 @@ public class CompatibleObjectEncoder implements ChannelDownstreamHandler {
         this.resetInterval = resetInterval;
     }
 
+    /**
+     * Creates a new {@link ObjectOutputStream} which wraps the specified
+     * {@link OutputStream}.  Override this method to use a subclass of the
+     * {@link ObjectOutputStream}.
+     */
+    protected ObjectOutputStream newObjectOutputStream(OutputStream out) throws Exception {
+        return new ObjectOutputStream(out);
+    }
+
     public void handleDownstream(
             ChannelHandlerContext context, ChannelEvent evt) throws Exception {
         if (!(evt instanceof MessageEvent)) {
@@ -90,8 +117,4 @@ public class CompatibleObjectEncoder implements ChannelDownstreamHandler {
         ChannelBuffer encoded = buffer.readBytes(buffer.readableBytes());
         write(context, e.getChannel(), e.getFuture(), encoded, e.getRemoteAddress());
     }
-
-    protected ObjectOutputStream newObjectOutputStream(OutputStream out) throws Exception {
-        return new ObjectOutputStream(out);
-    }
 }

src/main/java/org/jboss/netty/handler/codec/serialization/ObjectDecoder.java

@@ -22,6 +22,7 @@
  */
 package org.jboss.netty.handler.codec.serialization;
 
+import java.io.ObjectOutputStream;
 import java.io.StreamCorruptedException;
 
 import org.jboss.netty.buffer.ChannelBuffer;
@@ -31,32 +32,65 @@ import org.jboss.netty.channel.ChannelHandlerContext;
 import org.jboss.netty.handler.codec.frame.FrameDecoder;
 
 /**
+ * A decoder which deserializes the received {@link ChannelBuffer}s into Java
+ * objects.
+ * <p>
+ * Please note that the serialized form this decoder expects is not
+ * compatible with the standard {@link ObjectOutputStream}.  Please use
+ * {@link ObjectEncoder} or {@link ObjectEncoderOutputStream} to ensure the
+ * interoperability with this decoder.
+ * <p>
+ * Unless there's a requirement for the interoperability with the standard
+ * object streams, it is recommended to use {@link ObjectEncoder} and
+ * {@link ObjectDecoder} rather than {@link CompatibleObjectEncoder} and
+ * {@link CompatibleObjectDecoder}.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
  * @version $Rev$, $Date$
- *
  */
 public class ObjectDecoder extends FrameDecoder {
 
     private final int maxObjectSize;
     private final ClassLoader classLoader;
 
+    /**
+     * Creates a new decoder whose maximum object size is {@code 1048576}
+     * bytes.  If the size of the received object is greater than
+     * {@code 1048576} bytes, a {@link StreamCorruptedException} will be
+     * raised.
+     */
     public ObjectDecoder() {
         this(1048576);
     }
 
+    /**
+     * Creates a new decoder with the specified maximum object size.
+     *
+     * @param maxObjectSize  the maximum byte length of the serialized object.
+     *                       if the length of the received object is greater
+     *                       than this value, {@link StreamCorruptedException}
+     *                       will be raised.
+     */
     public ObjectDecoder(int maxObjectSize) {
-        this(maxObjectSize, Thread.currentThread().getContextClassLoader());
+        this(maxObjectSize, null);
     }
 
+    /**
+     * Creates a new decoder with the specified maximum object size.
+     *
+     * @param maxObjectSize  the maximum byte length of the serialized object.
+     *                       if the length of the received object is greater
+     *                       than this value, {@link StreamCorruptedException}
+     *                       will be raised.
+     * @param classLoader    the {@link ClassLoader} which will load the class
+     *                       of the serialized object
+     */
     public ObjectDecoder(int maxObjectSize, ClassLoader classLoader) {
         if (maxObjectSize <= 0) {
             throw new IllegalArgumentException("maxObjectSize: " + maxObjectSize);
         }
-        if (classLoader == null) {
-            classLoader = Thread.currentThread().getContextClassLoader();
-        }
 
         this.maxObjectSize = maxObjectSize;
         this.classLoader = classLoader;
@@ -83,8 +117,7 @@ public class ObjectDecoder extends FrameDecoder {
         }
 
         buffer.skipBytes(4);
-        return new CompactObjectInputStream(
+        return new CompactObjectInputStream(new ChannelBufferInputStream(
-                new ChannelBufferInputStream(buffer, dataLen),
+                        buffer, dataLen), classLoader).readObject();
-                classLoader).readObject();
     }
 }

src/main/java/org/jboss/netty/handler/codec/serialization/ObjectDecoderInputStream.java

@@ -29,6 +29,9 @@ import java.io.ObjectInput;
 import java.io.StreamCorruptedException;
 
 /**
+ * An {@link ObjectInput} which is interoperable with {@link ObjectEncoder}
+ * and {@link ObjectEncoderOutputStream}.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
@@ -42,18 +45,60 @@ public class ObjectDecoderInputStream extends InputStream implements
     private final ClassLoader classLoader;
     private final int maxObjectSize;
 
+    /**
+     * Creates a new {@link ObjectInput}.
+     *
+     * @param in
+     *        the {@link InputStream} where the serialized form will be
+     *        read from
+     */
     public ObjectDecoderInputStream(InputStream in) {
-        this(in, Thread.currentThread().getContextClassLoader());
+        this(in, null);
     }
 
+    /**
+     * Creates a new {@link ObjectInput}.
+     *
+     * @param in
+     *        the {@link InputStream} where the serialized form will be
+     *        read from
+     * @param classLoader
+     *        the {@link ClassLoader} which will load the class of the
+     *        serialized object
+     */
     public ObjectDecoderInputStream(InputStream in, ClassLoader classLoader) {
         this(in, classLoader, 1048576);
     }
 
+    /**
+     * Creates a new {@link ObjectInput}.
+     *
+     * @param in
+     *        the {@link InputStream} where the serialized form will be
+     *        read from
+     * @param maxObjectSize
+     *        the maximum byte length of the serialized object.  if the length
+     *        of the received object is greater than this value,
+     *        a {@link StreamCorruptedException} will be raised.
+     */
     public ObjectDecoderInputStream(InputStream in, int maxObjectSize) {
-        this(in, Thread.currentThread().getContextClassLoader(), maxObjectSize);
+        this(in, null, maxObjectSize);
     }
 
+    /**
+     * Creates a new {@link ObjectInput}.
+     *
+     * @param in
+     *        the {@link InputStream} where the serialized form will be
+     *        read from
+     * @param classLoader
+     *        the {@link ClassLoader} which will load the class of the
+     *        serialized object
+     * @param maxObjectSize
+     *        the maximum byte length of the serialized object.  if the length
+     *        of the received object is greater than this value,
+     *        a {@link StreamCorruptedException} will be raised.
+     */
     public ObjectDecoderInputStream(InputStream in, ClassLoader classLoader, int maxObjectSize) {
         if (in == null) {
             throw new NullPointerException("in");

src/main/java/org/jboss/netty/handler/codec/serialization/ObjectEncoder.java

@@ -25,6 +25,7 @@ package org.jboss.netty.handler.codec.serialization;
 import static org.jboss.netty.buffer.ChannelBuffers.*;
 import static org.jboss.netty.channel.Channels.*;
 
+import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 
 import org.jboss.netty.buffer.ChannelBuffer;
@@ -36,11 +37,22 @@ import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.channel.MessageEvent;
 
 /**
+ * An encoder which serializes a Java object into a {@link ChannelBuffer}.
+ * <p>
+ * Please note that the serialized form this encoder produces is not
+ * compatible with the standard {@link ObjectInputStream}.  Please use
+ * {@link ObjectDecoder} or {@link ObjectDecoderInputStream} to ensure the
+ * interoperability with this encoder.
+ * <p>
+ * Unless there's a requirement for the interoperability with the standard
+ * object streams, it is recommended to use {@link ObjectEncoder} and
+ * {@link ObjectDecoder} rather than {@link CompatibleObjectEncoder} and
+ * {@link CompatibleObjectDecoder}.
+ *
  * @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) $
- *
  */
 @ChannelPipelineCoverage("all")
 public class ObjectEncoder implements ChannelDownstreamHandler {
@@ -48,10 +60,24 @@ public class ObjectEncoder implements ChannelDownstreamHandler {
 
     private final int estimatedLength;
 
+    /**
+     * Creates a new encoder with the estimated length of 512 bytes.
+     */
     public ObjectEncoder() {
         this(512);
     }
 
+    /**
+     * Creates a new encoder.
+     *
+     * @param estimatedLength
+     *        the estimated byte length of the serialized form of an object.
+     *        If the length of the serialized form exceeds this value, the
+     *        internal buffer will be expanded automatically at the cost of
+     *        memory bandwidth.  If this value is too big, it will also waste
+     *        memory bandwidth.  To avoid unnecessary memory copy or allocation
+     *        cost, please specify the properly estimated value.
+     */
     public ObjectEncoder(int estimatedLength) {
         if (estimatedLength < 0) {
             throw new IllegalArgumentException(

src/main/java/org/jboss/netty/handler/codec/serialization/ObjectEncoderOutputStream.java

@@ -33,6 +33,9 @@ import org.jboss.netty.buffer.ChannelBufferOutputStream;
 import org.jboss.netty.buffer.ChannelBuffers;
 
 /**
+ * An {@link ObjectOutput} which is interoperable with {@link ObjectDecoder}
+ * and {@link ObjectDecoderInputStream}.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
@@ -45,6 +48,33 @@ public class ObjectEncoderOutputStream extends OutputStream implements
     private final DataOutputStream out;
     private final int estimatedLength;
 
+    /**
+     * Creates a new {@link ObjectOutput} with the estimated length of 512
+     * bytes.
+     *
+     * @param out
+     *        the {@link OutputStream} where the serialized form will be
+     *        written out
+     */
+    public ObjectEncoderOutputStream(OutputStream out) {
+        this(out, 512);
+    }
+
+    /**
+     * Creates a new {@link ObjectOutput}.
+     *
+     * @param out
+     *        the {@link OutputStream} where the serialized form will be
+     *        written out
+     *
+     * @param estimatedLength
+     *        the estimated byte length of the serialized form of an object.
+     *        If the length of the serialized form exceeds this value, the
+     *        internal buffer will be expanded automatically at the cost of
+     *        memory bandwidth.  If this value is too big, it will also waste
+     *        memory bandwidth.  To avoid unnecessary memory copy or allocation
+     *        cost, please specify the properly estimated value.
+     */
     public ObjectEncoderOutputStream(OutputStream out, int estimatedLength) {
         if (out == null) {
             throw new NullPointerException("out");

src/main/java/org/jboss/netty/handler/codec/string/package-info.java

@@ -22,7 +22,7 @@
  */
 
 /**
- * Encoder and decoder which transform a {@link String} into a
+ * Encoder and decoder which transform a {@link java.lang.String} into a
  * {@link org.jboss.netty.buffer.ChannelBuffer} and vice versa.
  */
 package org.jboss.netty.handler.codec.string;

src/main/java/org/jboss/netty/handler/ssl/SslBufferPool.java

@@ -35,10 +35,10 @@ import javax.net.ssl.SSLEngine;
  * <p>
  * The reason why {@link SslHandler} requires a buffer pool is because the
  * current {@link SSLEngine} implementation always requires a 17KiB buffer for
- * the 'wrap' and 'unwrap' operation.  In most cases, the size of the required
+ * every 'wrap' and 'unwrap' operation.  In most cases, the actual size of the
- * buffer is much smaller than that, and therefore allocating a 17KiB buffer
+ * required buffer is much smaller than that, and therefore allocating a 17KiB
- * for every 'wrap' and 'unwrap' operation wastes a lot of memory bandwidth,
+ * buffer for every 'wrap' and 'unwrap' operation wastes a lot of memory
- * resulting in the application performance degradation.
+ * bandwidth, resulting in the application performance degradation.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)