kipedia.org/wiki/Index_(information_technology)#Array_element_identifier">zero-based indexing. It means the index of the first byte is always {@code 0} and the index ofthe 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:
ChannelBuffer buffer = ...; for (int i = 0; i < buffer.capacity(); i ++) { byte b = array.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 space | +-------------------+------------------+------------------+ | | | | 0 <= readerIndex <= writerIndex <= capacity
Readable bytes
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 specific start index is specified, thespecified buffer's {@link #readerIndex() readerIndex} is increased together.
If there's no more readable bytes left, {@link IndexOutOfBoundsException}is raised. The default value of newly allocated, wrapped or copied buffer's {@link #readerIndex() readerIndex} is {@code 0}.
// Iterates the readable bytes of a buffer. ChannelBuffer buffer = ...; while (buffer.isReadable()) { System.out.println(buffer.readByte()); } Writable space
This segment is 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 writtenbytes. If the argument of the write operation is also a {@link ChannelBuffer}, and no specific start index is specified, the specified buffer's {@link #readerIndex() readerIndex} is increased together.
If there's no more writable space 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 space of a buffer with random integers. 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 space | +-------------------+------------------+------------------+ | | | | 0 <= readerIndex <= writerIndex <= capacity AFTER discardReadBytes() +------------------+--------------------------------------+ | readable bytes | writable space (got more space) | +------------------+--------------------------------------+ | | | readerIndex (0) <= writerIndex (decreased) <= capacity
Search operations
Various {@code indexOf()} methods help you locate an index of a value whichmeets a certain criteria. Complicated dynamic sequential search can be done with {@link ChannelBufferIndexFinder} as well as simple static single bytesearch.
Conversion to a NIO buffer
Various {@code toByteBuffer()} and {@code toByteBuffers()} methods converta {@link ChannelBuffer} into one or more NIO buffers. These methods avoidbuffer allocation and memory copy whenever possible, but there's no guarantee that memory copy will not be involved or that an explicit memory copy will be involved.
@author The Netty Project (netty@googlegroups.com)
@author Trustin Lee (trustin@gmail.com)
@version $Rev: 558 $, $Date: 2008-07-16 21:28:27 +0900 (Wed, 16 Jul 2008) $
@apiviz.landmark