From b2cc6c264cd24fe3ef3c274b5467e044e6176585 Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Mon, 11 Aug 2008 04:08:41 +0000 Subject: [PATCH] More JavaDoc --- .../org/jboss/netty/buffer/ChannelBuffer.java | 89 ++++++++++++++++++- .../jboss/netty/buffer/ChannelBuffers.java | 17 ++-- 2 files changed, 97 insertions(+), 9 deletions(-) diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java b/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java index f550a567fa..40d6843e89 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBuffer.java @@ -886,10 +886,66 @@ public interface ChannelBuffer extends Comparable { */ long readLong(); + /** + * Transfers this buffer's data to a newly created buffer starting at + * the current {@code readerIndex} and increases the {@code readerIndex} + * by the number of the transferred bytes (= {@code length}). + * The returned buffer's {@code readerIndex} and {@code writerIndex} are + * {@code 0} and {@code length} respectively. + * + * @param length the number of bytes to transfer + * + * @return the newly created buffer which contains the transferred bytes + * + * @throws IndexOutOfBoundsException + * if {@code length} is greater than {@code this.readableBytes} + */ ChannelBuffer readBytes(int length); - ChannelBuffer readBytes(ChannelBufferIndexFinder endIndexFinder); + + /** + * Transfers this buffer's data to a newly created buffer starting at + * the current {@code readerIndex} until the specified {@code indexFinder} + * returns {@code true} and increases the {@code readerIndex} + * by the number of the transferred bytes. The returned buffer's + * {@code readerIndex} and {@code writerIndex} are {@code 0} and + * the number of the transferred bytes respectively. + * + * @param length the number of bytes to transfer + * + * @return the newly created buffer which contains the transferred bytes + * + * @throws NoSuchElementException + * if {@code indexFinder} didn't return {@code true} at all + */ + ChannelBuffer readBytes(ChannelBufferIndexFinder indexFinder); + + /** + * Returns a new slice of this buffer's sub-region starting at the current + * {@code readerIndex} and increases the {@code readerIndex} by the size + * of the new slice (= {@code length}). + * + * @param length the size of the new slice + * + * @return the newly created slice + * + * @throws IndexOutOfBoundsException + * if {@code length} is greater than {@code this.readableBytes} + */ ChannelBuffer readSlice(int length); - ChannelBuffer readSlice(ChannelBufferIndexFinder endIndexFinder); + + /** + * Returns a new slice of this buffer's sub-region starting at the current + * {@code readerIndex} and increases the {@code readerIndex} by the size + * of the new slice (determined by {@code indexFinder}). + * + * @param indexFinder finds the end index of the sub-region to be sliced + * + * @return the newly created slice + * + * @throws NoSuchElementException + * if {@code indexFinder} didn't return {@code true} at all + */ + ChannelBuffer readSlice(ChannelBufferIndexFinder indexFinder); /** * Transfers this buffer's data to the specified destination starting at @@ -1014,14 +1070,14 @@ public interface ChannelBuffer extends Comparable { /** * Increases the current {@code readerIndex} until the specified - * {@code firstIndexFinder} returns {@code true} in this buffer. + * {@code indexFinder} returns {@code true} in this buffer. * * @return the number of skipped bytes * * @throws NoSuchElementException * if {@code firstIndexFinder} didn't return {@code true} at all */ - int skipBytes(ChannelBufferIndexFinder firstIndexFinder); + int skipBytes(ChannelBufferIndexFinder indexFinder); /** * Sets the specified byte at the current {@code writerIndex} @@ -1201,7 +1257,32 @@ public interface ChannelBuffer extends Comparable { */ void writeZero(int length); + /** + * Locates the first occurrence of the specified {@code value} in this + * buffer. The search takes place from the specified {@code fromIndex} + * (inclusive) to the specified {@code toIndex} (exclusive). + *

+ * If {@code fromIndex} is greater than {@code toIndex}, the search is + * performed in a reversed order. + * + * @return the absolute index of the first occurrence if found. + * {@code -1} otherwise. + */ int indexOf(int fromIndex, int toIndex, byte value); + + /** + * Locates the first index where the specified {@code indexFinder} + * returns {@code true}. The search takes place from the specified + * {@code fromIndex} (inclusive) to the specified {@code toIndex} + * (exclusive). + *

+ * If {@code fromIndex} is greater than {@code toIndex}, the search is + * performed in a reversed order. + * + * @return the absolute index where the specified {@code indexFinder} + * returned {@code true} if the {@code indexFinder} returned + * {@code true}. {@code -1} otherwise. + */ int indexOf(int fromIndex, int toIndex, ChannelBufferIndexFinder indexFinder); /** diff --git a/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java b/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java index 266de1ad0a..edc9dd5c71 100644 --- a/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java +++ b/src/main/java/org/jboss/netty/buffer/ChannelBuffers.java @@ -630,10 +630,9 @@ public class ChannelBuffers { } /** - * Returns {@code true} if and only if the two specified buffers have the - * same content and the same readable bytes. They don't need to have the - * same {@code readerIndex}. This method is useful when implementing a - * new buffer type. + * Returns {@code true} if and only if the two specified buffers are + * identical to each other as described in {@code ChannelBuffer#equals(Object)}. + * This method is useful when implementing a new buffer type. */ public static boolean equals(ChannelBuffer bufferA, ChannelBuffer bufferB) { final int aLen = bufferA.readableBytes(); @@ -666,7 +665,7 @@ public class ChannelBuffers { } /** - * Compares the two specified buffers as described in {@link Comparable}. + * Compares the two specified buffers as described in {@link ChannelBuffer#compareTo(ChannelBuffer)}. * This method is useful when implementing a new buffer type. */ public static int compare(ChannelBuffer bufferA, ChannelBuffer bufferB) { @@ -705,6 +704,10 @@ public class ChannelBuffers { return aLen - bLen; } + /** + * The default implementation of {@link ChannelBuffer#indexOf(int, int, byte)}. + * This method is useful when implementing a new buffer type. + */ public static int indexOf(ChannelBuffer buffer, int fromIndex, int toIndex, byte value) { if (fromIndex <= toIndex) { return firstIndexOf(buffer, fromIndex, toIndex, value); @@ -713,6 +716,10 @@ public class ChannelBuffers { } } + /** + * The default implementation of {@link ChannelBuffer#indexOf(int, int, ChannelBufferIndexFinder)}. + * This method is useful when implementing a new buffer type. + */ public static int indexOf(ChannelBuffer buffer, int fromIndex, int toIndex, ChannelBufferIndexFinder indexFinder) { if (fromIndex <= toIndex) { return firstIndexOf(buffer, fromIndex, toIndex, indexFinder);