From ee62e8bbc0e1ccac8cd5befca27ec3ac59adc663 Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Sun, 10 Aug 2008 06:38:54 +0000 Subject: [PATCH] More JavaDoc --- .../jboss/netty/buffer/ChannelBuffers.java | 126 ++++++++++++++++-- 1 file changed, 115 insertions(+), 11 deletions(-) diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java b/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java index f2cab7b068..2b6a6a87a5 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java @@ -91,7 +91,14 @@ import java.nio.charset.UnsupportedCharsetException; */ public class ChannelBuffers { + /** + * Big endian byte order. + */ public static final ByteOrder BIG_ENDIAN = ByteOrder.BIG_ENDIAN; + + /** + * Little endian byte order. + */ public static final ByteOrder LITTLE_ENDIAN = ByteOrder.LITTLE_ENDIAN; private static final char[][] HEXDUMP_TABLE = new char[65536][]; @@ -102,53 +109,100 @@ public class ChannelBuffers { } } - public static ChannelBuffer buffer(int length) { - return buffer(BIG_ENDIAN, length); + /** + * Creates a new big-endian Java heap buffer with the specified + * {@code capacity}. The new buffer's {@code readerIndex} and + * {@code writerIndex} are {@code 0}. + */ + public static ChannelBuffer buffer(int capacity) { + return buffer(BIG_ENDIAN, capacity); } - public static ChannelBuffer buffer(ByteOrder endianness, int length) { - if (length == 0) { + /** + * Creates a new Java heap buffer with the specified {@code endianness} + * and {@code capacity}. The new buffer's {@code readerIndex} and + * {@code writerIndex} are {@code 0}. + */ + public static ChannelBuffer buffer(ByteOrder endianness, int capacity) { + if (capacity == 0) { return ChannelBuffer.EMPTY_BUFFER; } if (endianness == BIG_ENDIAN) { - return new BigEndianHeapChannelBuffer(length); + return new BigEndianHeapChannelBuffer(capacity); } else if (endianness == LITTLE_ENDIAN) { - return new LittleEndianHeapChannelBuffer(length); + return new LittleEndianHeapChannelBuffer(capacity); } else { throw new NullPointerException("endianness"); } } - public static ChannelBuffer directBuffer(int length) { - return directBuffer(BIG_ENDIAN, length); + /** + * Creates a new big-endian direct buffer with the specified + * {@code capacity}. The new buffer's {@code readerIndex} and + * {@code writerIndex} are {@code 0}. + */ + public static ChannelBuffer directBuffer(int capacity) { + return directBuffer(BIG_ENDIAN, capacity); } - public static ChannelBuffer directBuffer(ByteOrder endianness, int length) { - if (length == 0) { + /** + * Creates a new direct buffer with the specified {@code endianness} and + * {@code capacity}. The new buffer's {@code readerIndex} and + * {@code writerIndex} are {@code 0}. + */ + public static ChannelBuffer directBuffer(ByteOrder endianness, int capacity) { + if (capacity == 0) { return ChannelBuffer.EMPTY_BUFFER; } ChannelBuffer buffer = new ByteBufferBackedChannelBuffer( - ByteBuffer.allocateDirect(length).order(endianness)); + ByteBuffer.allocateDirect(capacity).order(endianness)); buffer.clear(); return buffer; } + /** + * Creates a new big-endian dynamic buffer whose estimated data length is + * {@code 256} bytes. The new buffer's {@code readerIndex} and + * {@code writerIndex} are {@code 0}. + */ public static ChannelBuffer dynamicBuffer() { return dynamicBuffer(BIG_ENDIAN, 256); } + /** + * Creates a new big-endian dynamic buffer with the specified estimated + * data length. More accurate estimation yields less unexpected + * reallocation overhead. The new buffer's {@code readerIndex} and + * {@code writerIndex} are {@code 0}. + */ public static ChannelBuffer dynamicBuffer(int estimatedLength) { return dynamicBuffer(BIG_ENDIAN, estimatedLength); } + /** + * Creates a new dynamic buffer with the specified endianness and + * the specified estimated data length. More accurate estimation yields + * less unexpected reallocation overhead. The new buffer's + * {@code readerIndex} and {@code writerIndex} are {@code 0}. + */ public static ChannelBuffer dynamicBuffer(ByteOrder endianness, int estimatedLength) { return new DynamicChannelBuffer(endianness, estimatedLength); } + /** + * Creates a new big-endian buffer which wraps the specified {@code array}. + * A modification on the specified array's content will be visible to the + * returned buffer. + */ public static ChannelBuffer wrappedBuffer(byte[] array) { return wrappedBuffer(BIG_ENDIAN, array); } + /** + * Creates a new buffer which wraps the specified {@code array} with the + * specified {@code endianness}. A modification on the specified array's + * content will be visible to the returned buffer. + */ public static ChannelBuffer wrappedBuffer(ByteOrder endianness, byte[] array) { if (array.length == 0) { return ChannelBuffer.EMPTY_BUFFER; @@ -162,10 +216,20 @@ public class ChannelBuffers { } } + /** + * Creates a new big-endian buffer which wraps the sub-region of the + * specified {@code array}. A modification on the specified array's + * content will be visible to the returned buffer. + */ public static ChannelBuffer wrappedBuffer(byte[] array, int offset, int length) { return wrappedBuffer(BIG_ENDIAN, array, offset, length); } + /** + * Creates a new buffer which wraps the sub-region of the specified + * {@code array} with the specified {@code endianness}. A modification on + * the specified array's content will be visible to the returned buffer. + */ public static ChannelBuffer wrappedBuffer(ByteOrder endianness, byte[] array, int offset, int length) { if (length == 0) { return ChannelBuffer.EMPTY_BUFFER; @@ -181,6 +245,11 @@ public class ChannelBuffers { } } + /** + * Creates a new buffer which wraps the specified NIO buffer's current + * slice. A modification on the specified buffer's content and endianness + * will be visible to the returned buffer. + */ public static ChannelBuffer wrappedBuffer(ByteBuffer buffer) { if (!buffer.hasRemaining()) { return ChannelBuffer.EMPTY_BUFFER; @@ -192,6 +261,11 @@ public class ChannelBuffers { } } + /** + * Creates a new buffer which wraps the specified buffer's readable bytes. + * A modification on the specified buffer's content will be visible to the + * returned buffer. + */ public static ChannelBuffer wrappedBuffer(ChannelBuffer buffer) { if (buffer.readable()) { return buffer.slice(); @@ -200,10 +274,22 @@ public class ChannelBuffers { } } + /** + * Creates a new big-endian composite buffer which wraps the specified + * arrays without copying them. A modification on the specified arrays' + * content will be visible to the returned buffer. + */ public static ChannelBuffer wrappedBuffer(byte[]... arrays) { return wrappedBuffer(BIG_ENDIAN, arrays); } + /** + * Creates a new composite buffer which wraps the specified arrays without + * copying them. A modification on the specified arrays' content will be + * visible to the returned buffer. + * + * @param endianness the endianness of the new buffer + */ public static ChannelBuffer wrappedBuffer(ByteOrder endianness, byte[]... arrays) { switch (arrays.length) { case 0: @@ -218,6 +304,15 @@ public class ChannelBuffers { return wrappedBuffer(wrappedBuffers); } + /** + * Creates a new composite buffer which wraps the specified buffers without + * copying them. A modification on the specified buffers' content will be + * visible to the returned buffer. + * + * @throws IllegalArgumentException + * if the specified buffers' endianness are different from each + * other + */ public static ChannelBuffer wrappedBuffer(ChannelBuffer... buffers) { switch (buffers.length) { case 0: @@ -229,6 +324,15 @@ public class ChannelBuffers { } } + /** + * Creates a new composite buffer which wraps the specified NIO buffers + * without copying them. A modification on the specified buffers' content + * will be visible to the returned buffer. + * + * @throws IllegalArgumentException + * if the specified buffers' endianness are different from each + * other + */ public static ChannelBuffer wrappedBuffer(ByteBuffer... buffers) { switch (buffers.length) { case 0: