kipedia.org/wiki/Index_(information_technology)#Array_element_identifier">zero-based indexing. It means the index of the first byte is always {@code 0} andthe index of the last byte is always {@link #capacity() capacity - 1}. For example, to iterate all bytes of a buffer, you can do the following, regardless of its internal implementation:
{@link ChannelBuffer} buffer = ...;for (int i = 0; i < buffer.capacity(); i ++) { byte b = buffer.getByte(i); System.out.println((char) b); } Sequential Access Indexing
{@link ChannelBuffer} provides two pointer variables to support sequentialread and write operations - {@link #readerIndex() readerIndex} for a readoperation and {@link #writerIndex() writerIndex} for a write operationrespectively. The following diagram shows how a buffer is segmented into three areas by the two pointers:
+-------------------+------------------+------------------+ | discardable bytes | readable bytes | writable bytes | | | (CONTENT) | | +-------------------+------------------+------------------+ | | | | 0 <= readerIndex <= writerIndex <= capacity
Readable bytes (the actual content)
This segment is where the actual data is stored. Any operation whose name starts with {@code read} or {@code skip} will get or skip the data at thecurrent {@link #readerIndex() readerIndex} and increase it by the number ofread bytes. If the argument of the read operation is also a {@link ChannelBuffer} and no destination index is specified, the specified buffer's{@link #readerIndex() readerIndex} is increased together.
If there's not enough content left, {@link IndexOutOfBoundsException} israised. The default value of newly allocated, wrapped or copied buffer's {@link #readerIndex() readerIndex} is {@code 0}.
// Iterates the readable bytes of a buffer. {@link ChannelBuffer} buffer = ...;while (buffer.readable()) { System.out.println(buffer.readByte()); } Writable bytes
This segment is a undefined space which needs to be filled. Any operation whose name ends with {@code write} will write the data at the current {@link #writerIndex() writerIndex} and increase it by the number of written bytes.If the argument of the write operation is also a {@link ChannelBuffer}, and no source index is specified, the specified buffer's {@link #readerIndex() readerIndex} is increased together.
If there's not enough writable bytes left, {@link IndexOutOfBoundsException}is raised. The default value of newly allocated buffer's {@link #writerIndex() writerIndex} is {@code 0}. The default value of wrapped or copied buffer's {@link #writerIndex() writerIndex} is the {@link #capacity() capacity} of the buffer.
// Fills the writable bytes of a buffer with random integers. {@link ChannelBuffer} buffer = ...;while (buffer.writableBytes() >= 4) { buffer.writeInt(random.nextInt()); } Discardable bytes
This segment contains the bytes which were read already by a read operation. Initially, the size of this segment is {@code 0}, but its size increases up to the {@link #writerIndex() writerIndex} as read operations are executed.The read bytes can be discarded by calling {@link #discardReadBytes()} toreclaim unused area as depicted by the following diagram:
BEFORE discardReadBytes() +-------------------+------------------+------------------+ | discardable bytes | readable bytes | writable bytes | +-------------------+------------------+------------------+ | | | | 0 <= readerIndex <= writerIndex <= capacity AFTER discardReadBytes() +------------------+--------------------------------------+ | readable bytes | writable bytes (got more space) | +------------------+--------------------------------------+ | | | readerIndex (0) <= writerIndex (decreased) <= capacity
Please note that there is no guarantee about the content of writable bytes after calling {@link #discardReadBytes()}. The writable bytes will not be moved in most cases and could even be filled with completely different data depending on the underlying buffer implementation.
Clearing the buffer indexes
You can set both {@link #readerIndex() readerIndex} and {@link #writerIndex() writerIndex} to {@code 0} by calling {@link #clear()}. It does not clear the buffer content (e.g. filling with {@code 0}) but just clears the two pointers. Please also note that the semantic of this operation is different from {@link ByteBuffer#clear()}.
BEFORE clear() +-------------------+------------------+------------------+ | discardable bytes | readable bytes | writable bytes | +-------------------+------------------+------------------+ | | | | 0 <= readerIndex <= writerIndex <= capacity AFTER clear() +---------------------------------------------------------+ | writable bytes (got more space) | +---------------------------------------------------------+ | | 0 = readerIndex = writerIndex <= capacity
Mark and reset
There are two marker indexes in every buffer. One is for storing {@link #readerIndex() readerIndex} and the other is for storing {@link #writerIndex() writerIndex}. You can always reposition one of the two indexes by calling a reset method. It works in a similar fashion to the mark and reset methods in {@link InputStream} except that there's no {@code readlimit}.
Conversion to existing JDK types
Byte array
If a {@link ChannelBuffer} is backed by a byte array (i.e. {@code byte[]}), you can access it directly via the {@link #array()} method. To determine ifa buffer is backed by a byte array, {@link #hasArray()} should be used.
NIO Buffers
Various {@link #toByteBuffer()} methods convert a {@link ChannelBuffer} intoone or more NIO buffers. These methods avoid buffer allocation and memory copy whenever possible, but there's no guarantee that memory copy will not be involved.
I/O Streams
Please refer to {@link ChannelBufferInputStream} and {@link ChannelBufferOutputStream}.
@author
kimi