From cb88eb0aefa94a8919b7cbef75d593ad5adef4a6 Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Sun, 10 Aug 2008 05:52:36 +0000 Subject: [PATCH] More JavaDoc --- .../netty/buffer/AbstractChannelBuffer.java | 1 + .../buffer/BigEndianHeapChannelBuffer.java | 1 + .../buffer/ByteBufferBackedChannelBuffer.java | 10 ++++++- .../org/jboss/netty/buffer/ChannelBuffer.java | 2 +- .../buffer/ChannelBufferInputStream.java | 26 +++++++++++++++++++ .../buffer/ChannelBufferOutputStream.java | 15 +++++++++++ .../jboss/netty/buffer/ChannelBuffers.java | 8 +++--- .../netty/buffer/CompositeChannelBuffer.java | 2 ++ .../netty/buffer/DuplicatedChannelBuffer.java | 3 +++ .../netty/buffer/DynamicChannelBuffer.java | 2 ++ .../jboss/netty/buffer/HeapChannelBuffer.java | 1 + .../buffer/LittleEndianHeapChannelBuffer.java | 1 + .../netty/buffer/ReadOnlyChannelBuffer.java | 9 +++++++ .../netty/buffer/SlicedChannelBuffer.java | 2 ++ .../netty/buffer/TruncatedChannelBuffer.java | 2 ++ .../netty/buffer/WrappedChannelBuffer.java | 5 ++++ 16 files changed, 84 insertions(+), 6 deletions(-) diff --git a/src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java index b377616512..e3b2a442cf 100644 --- a/src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java @@ -32,6 +32,7 @@ import java.util.NoSuchElementException; /** + * Skeletal implementation of a buffer. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java index 3cf9a75de3..867c8c49e7 100644 --- a/src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java @@ -26,6 +26,7 @@ import java.nio.ByteOrder; /** + * Big-endian Java heap buffer. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java index b2cfe8c949..22da1b5c41 100644 --- a/src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java @@ -33,7 +33,15 @@ import java.nio.channels.GatheringByteChannel; import java.nio.channels.ScatteringByteChannel; import java.nio.charset.UnsupportedCharsetException; - +/** + * NIO direct buffer based buffer. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + * + */ public class ByteBufferBackedChannelBuffer extends AbstractChannelBuffer { private final ByteBuffer buffer; diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java index 3453e56a84..e28da57e2f 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java @@ -31,7 +31,7 @@ import java.nio.channels.GatheringByteChannel; import java.nio.channels.ScatteringByteChannel; /** - * A random and sequential accessible sequence of zero or more bytes (octets). + * Random and sequential accessible sequence of zero or more bytes (octets). * This interface provides an abstract view for one or more primitive byte * arrays ({@code byte[]}) and {@linkplain ByteBuffer NIO buffers}. * diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java b/src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java index 4d585892bf..980a594d0f 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java @@ -29,6 +29,15 @@ import java.io.IOException; import java.io.InputStream; /** + * {@link InputStream} which reads data from a {@link ChannelBuffer}. + *

+ * A read operation against this stream will occur at the {@code readerIndex} + * of its underlying buffer and the {@code readerIndex} will increase during + * the read operation. + *

+ * This stream implements {@link DataInput} for your convenience. + * The endianness of the stream is not always big endian but depends on + * the endianness of the underlying buffer. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -44,10 +53,24 @@ public class ChannelBufferInputStream extends InputStream implements DataInput { private final int startIndex; private final int endIndex; + /** + * Creates a new stream which reads data from the specified {@code buffer} + * starting at the current {@code readerIndex} and ending at the current + * {@code writerIndex}. + */ public ChannelBufferInputStream(ChannelBuffer buffer) { this(buffer, buffer.readableBytes()); } + /** + * Creates a new stream which reads data from the specified {@code buffer} + * starting at the current {@code readerIndex} and ending at + * {@code readerIndex + length}. + * + * @throws IndexOutOfBoundsException + * if {@code readerIndex + length} is greater than + * {@code writerIndex} + */ public ChannelBufferInputStream(ChannelBuffer buffer, int length) { if (buffer == null) { throw new NullPointerException("buffer"); @@ -62,6 +85,9 @@ public class ChannelBufferInputStream extends InputStream implements DataInput { buffer.markReaderIndex(); } + /** + * Returns the number of read bytes by this stream so far. + */ public int readBytes() { return buffer.readerIndex() - startIndex; } diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java b/src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java index 9d471dd893..46a6cd72ec 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java @@ -28,6 +28,15 @@ import java.io.IOException; import java.io.OutputStream; /** + * {@link OutputStream} which writes data to a {@link ChannelBuffer}. + *

+ * A write operation against this stream will occur at the {@code writerIndex} + * of its underlying buffer and the {@code writerIndex} will increase during + * the write operation. + *

+ * This stream implements {@link DataOutput} for your convenience. + * The endianness of the stream is not always big endian but depends on + * the endianness of the underlying buffer. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -42,6 +51,9 @@ public class ChannelBufferOutputStream extends OutputStream implements DataOutpu private final ChannelBuffer buffer; private final DataOutputStream utf8out = new DataOutputStream(this); + /** + * Creates a new stream which writes data to the specified {@code buffer}. + */ public ChannelBufferOutputStream(ChannelBuffer buffer) { if (buffer == null) { throw new NullPointerException("buffer"); @@ -118,6 +130,9 @@ public class ChannelBufferOutputStream extends OutputStream implements DataOutpu utf8out.writeUTF(s); } + /** + * Returns the buffer where this stream is writing data. + */ public ChannelBuffer buffer() { return buffer; } diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java b/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java index ab524c2f1b..f2cab7b068 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java @@ -30,7 +30,7 @@ import java.nio.charset.UnsupportedCharsetException; /** * Creates a new {@link ChannelBuffer} by allocating new space or by wrapping - * or copying existing byte arrays. + * or copying existing byte arrays, byte buffer and string. * *

Use static import

* This classes is intended to be used with Java 5 static import statement: @@ -60,9 +60,9 @@ import java.nio.charset.UnsupportedCharsetException; *

Creating a wrapped buffer

* * Wrapped buffer is a buffer which is a view of one or more existing - * byte arrays or byte buffer. Any changes in the content of the original - * array or buffer will be reflected in the wrapped buffer. Various wrapper - * methods are provided and their name is all {@code wrappedBuffer()}. + * byte arrays, byte buffer and string. Any changes in the content of the + * original array or buffer will be reflected in the wrapped buffer. Various + * wrapper methods are provided and their name is all {@code wrappedBuffer()}. * You might want to take a look at this method closely if you want to create * a buffer which is composed of more than one array to reduce the number of * memory copy. diff --git a/src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java index 30dbfae669..a57b7e06aa 100644 --- a/src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java @@ -36,6 +36,8 @@ import java.util.List; /** + * Virtual buffer which shows multiple buffers as a single merged buffer. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * diff --git a/src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java index ffb31c98bd..0a7b9e8a2b 100644 --- a/src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java @@ -32,6 +32,9 @@ import java.nio.channels.ScatteringByteChannel; /** + * Derived buffer which simply forwards all data access requests to its + * parent. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * diff --git a/src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java index 29be9a0b45..943a3413c7 100644 --- a/src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java @@ -32,6 +32,8 @@ import java.nio.channels.ScatteringByteChannel; /** + * Dynamic capacity buffer which increases its capacity as needed. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * diff --git a/src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java index 84d652f0d6..8ca7e23a20 100644 --- a/src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java @@ -33,6 +33,7 @@ import java.nio.channels.ScatteringByteChannel; import java.nio.charset.UnsupportedCharsetException; /** + * Skeletal implementation for Java heap buffers. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java index 6de5831c9b..4f35c46954 100644 --- a/src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java @@ -26,6 +26,7 @@ import java.nio.ByteOrder; /** + * Little-endian Java heap buffer. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) diff --git a/src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java index 85d703967e..a61af8074c 100644 --- a/src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java @@ -30,6 +30,15 @@ import java.nio.ByteOrder; import java.nio.channels.GatheringByteChannel; import java.nio.channels.ScatteringByteChannel; +/** + * Derived buffer which forbids any write requests to its parent. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + * + */ public class ReadOnlyChannelBuffer extends AbstractChannelBuffer implements WrappedChannelBuffer { private final ChannelBuffer buffer; diff --git a/src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java index 194da48ece..b13740b3da 100644 --- a/src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java @@ -32,6 +32,8 @@ import java.nio.channels.ScatteringByteChannel; /** + * Derived buffer which exposes its parent's sub-region only. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * diff --git a/src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java index 6b38a92ec9..ce7779ae83 100644 --- a/src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java @@ -32,6 +32,8 @@ import java.nio.channels.ScatteringByteChannel; /** + * Derived buffer which hides its parent's tail data beyond a certain index. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * diff --git a/src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java index 48ada3e7fe..da139d08ea 100644 --- a/src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java @@ -23,6 +23,8 @@ package org.jboss.netty.buffer; /** + * Common interface for buffer wrappers and derived buffers. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @@ -30,5 +32,8 @@ package org.jboss.netty.buffer; * */ public interface WrappedChannelBuffer extends ChannelBuffer { + /** + * Returns this buffer's parent that this buffer is wrapping. + */ ChannelBuffer unwrap(); }