From f744de9d851d20e5b5334bae7cb1f0b86c287e5d Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Thu, 4 Sep 2008 05:48:41 +0000 Subject: [PATCH] * Added JavaDoc for the handler.codec.serialization package * Improved JavaDoc for handler.codec.string and handler.ssl --- .../CompatibleObjectDecoder.java | 31 ++++++++++-- .../CompatibleObjectEncoder.java | 33 +++++++++++-- .../codec/serialization/ObjectDecoder.java | 49 ++++++++++++++++--- .../ObjectDecoderInputStream.java | 49 ++++++++++++++++++- .../codec/serialization/ObjectEncoder.java | 28 ++++++++++- .../ObjectEncoderOutputStream.java | 30 ++++++++++++ .../handler/codec/string/package-info.java | 2 +- .../netty/handler/ssl/SslBufferPool.java | 8 +-- 8 files changed, 205 insertions(+), 25 deletions(-) diff --git a/src/main/java/org/jboss/netty/handler/codec/serialization/CompatibleObjectDecoder.java b/src/main/java/org/jboss/netty/handler/codec/serialization/CompatibleObjectDecoder.java index 2f06811161..e98ea8e02f 100644 --- a/src/main/java/org/jboss/netty/handler/codec/serialization/CompatibleObjectDecoder.java +++ b/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). + *

+ * This decoder is interoperable with the standard Java object + * streams such as {@link ObjectInputStream} and {@link ObjectOutputStream}. + *

+ * 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 DoS attack. + * 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 + * 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); - } } diff --git a/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectDecoder.java b/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectDecoder.java index f736e0afb6..441f1eebcb 100644 --- a/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectDecoder.java +++ b/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. + *

+ * 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. + *

+ * 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( - new ChannelBufferInputStream(buffer, dataLen), - classLoader).readObject(); + return new CompactObjectInputStream(new ChannelBufferInputStream( + buffer, dataLen), classLoader).readObject(); } } diff --git a/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectDecoderInputStream.java b/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectDecoderInputStream.java index d794511242..b40e621065 100644 --- a/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectDecoderInputStream.java +++ b/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"); diff --git a/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectEncoder.java b/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectEncoder.java index 616a6c49fe..786a443b6e 100644 --- a/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectEncoder.java +++ b/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}. + *

+ * 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. + *

+ * 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( diff --git a/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectEncoderOutputStream.java b/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectEncoderOutputStream.java index 30c29041f1..405efc225a 100644 --- a/src/main/java/org/jboss/netty/handler/codec/serialization/ObjectEncoderOutputStream.java +++ b/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"); diff --git a/src/main/java/org/jboss/netty/handler/codec/string/package-info.java b/src/main/java/org/jboss/netty/handler/codec/string/package-info.java index 966238f6c7..7e942554cf 100644 --- a/src/main/java/org/jboss/netty/handler/codec/string/package-info.java +++ b/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; \ No newline at end of file diff --git a/src/main/java/org/jboss/netty/handler/ssl/SslBufferPool.java b/src/main/java/org/jboss/netty/handler/ssl/SslBufferPool.java index 95a5891fe2..e06c9edfa0 100644 --- a/src/main/java/org/jboss/netty/handler/ssl/SslBufferPool.java +++ b/src/main/java/org/jboss/netty/handler/ssl/SslBufferPool.java @@ -35,10 +35,10 @@ import javax.net.ssl.SSLEngine; *

* 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 - * buffer is much smaller than that, and therefore allocating a 17KiB buffer - * for every 'wrap' and 'unwrap' operation wastes a lot of memory bandwidth, - * resulting in the application performance degradation. + * every 'wrap' and 'unwrap' operation. In most cases, the actual size of the + * required buffer is much smaller than that, and therefore allocating a 17KiB + * buffer for every 'wrap' and 'unwrap' operation wastes a lot of memory + * bandwidth, resulting in the application performance degradation. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com)