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