net.gleamynode.netty.buffer
Interface ChannelBuffer

All Superinterfaces:

Comparable<ChannelBuffer>

All Known Subinterfaces:

WrappedChannelBuffer

All Known Implementing Classes:

AbstractChannelBuffer, BigEndianHeapChannelBuffer, ByteBufferBackedChannelBuffer, CompositeChannelBuffer, DuplicatedChannelBuffer, DynamicChannelBuffer, HeapChannelBuffer, LittleEndianHeapChannelBuffer, ReadOnlyChannelBuffer, SlicedChannelBuffer, TruncatedChannelBuffer

public interface ChannelBuffer
extends Comparable<ChannelBuffer>

A random and sequential accessible sequence of zero or more bytes (octets). This interface provides an abstract view for one or more primitive byte arrays (byte[]) and NIO buffers.

Creation of a buffer

It is common for a user to create a new buffer using ChannelBuffers utility class rather than calling an individual implementation's constructor.

Random Access Indexing

Just like an ordinary primitive byte array, ChannelBuffer uses zero-based indexing. It means the index of the first byte is always 0 and the index of the last byte is always 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

ChannelBuffer provides two pointer variables to support sequential read and write operations - readerIndex for a read operation and writerIndex for a write operation respectively. The following diagram shows how a buffer is segmented into three areas by the two pointers:

      +-------------------+------------------+------------------+
      | discardable bytes |  readable bytes  |  writable space  |
      |                   |     (CONTENT)    |                  |
      +-------------------+------------------+------------------+
      |                   |                  |                  |
      0      <=      readerIndex   <=   writerIndex    <=    capacity
 

Readable bytes (the actual 'content' of the buffer)

This segment, so called 'the content of a buffer', is where the actual data is stored. Any operation whose name starts with read or skip will get or skip the data at the current readerIndex and increase it by the number of read bytes. If the argument of the read operation is also a ChannelBuffer and no start index is specified, the specified buffer's readerIndex is increased together.

If there's not enough content left, IndexOutOfBoundsException is raised. The default value of newly allocated, wrapped or copied buffer's readerIndex is 0.

 // Iterates the readable bytes of a buffer.
 ChannelBuffer buffer = ...;
 while (buffer.readable()) {
     System.out.println(buffer.readByte());
 }
 

Writable space

This segment is a undefined space which needs to be filled. Any operation whose name ends with write will write the data at the current writerIndex and increase it by the number of written bytes. If the argument of the write operation is also a ChannelBuffer, and no start index is specified, the specified buffer's readerIndex is increased together.

If there's not enough writable space left, IndexOutOfBoundsException is raised. The default value of newly allocated buffer's writerIndex is 0. The default value of wrapped or copied buffer's writerIndex is the 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 0, but its size increases up to the writerIndex as read operations are executed. The read bytes can be discarded by calling discardReadBytes() to reclaim unused area as depicted by the following diagram:

  BEFORE discardReadBytes()

      +-------------------+------------------+------------------+
      | discardable bytes |  readable bytes  |  writable space  |
      |                   |     (CONTENT)    |                  |
      +-------------------+------------------+------------------+
      |                   |                  |                  |
      0      <=      readerIndex   <=   writerIndex    <=    capacity


  AFTER discardReadBytes()

      +------------------+--------------------------------------+
      |  readable bytes  |    writable space (got more space)   |
      |     (CONTENT)    |                                      |
      +------------------+--------------------------------------+
      |                  |                                      |
 readerIndex (0) <= writerIndex (decreased)        <=        capacity
 

Clearing the buffer indexes

You can set both readerIndex and writerIndex to 0 by calling clear(). It doesn't clear the buffer content (e.g. filling with 0) but just clears the two pointers. Please also note that the semantic of this operation is different from Buffer.clear().

  BEFORE clear()

      +-------------------+------------------+------------------+
      | discardable bytes |  readable bytes  |  writable space  |
      |                   |     (CONTENT)    |                  |
      +-------------------+------------------+------------------+
      |                   |                  |                  |
      0      <=      readerIndex   <=   writerIndex    <=    capacity


  AFTER clear()

      +---------------------------------------------------------+
      |             writable space (got more space)             |
      +---------------------------------------------------------+
      |                                                         |
      0 = readerIndex = writerIndex            <=            capacity
 

Search operations

Various indexOf() methods help you locate an index of a value which meets a certain criteria. Complicated dynamic sequential search can be done with ChannelBufferIndexFinder as well as simple static single byte search.

Conversion to existing JDK types

Various toByteBuffer() and toByteBuffers() methods convert a ChannelBuffer into one 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 or that an explicit memory copy will be involved.

In case you need to convert a ChannelBuffer into an InputStream or an OutputStream, please refer to ChannelBufferInputStream and ChannelBufferOutputStream.

Version:

$Rev$, $Date$

Author:

The Netty Project (netty@googlegroups.com), Trustin Lee (trustin@gmail.com)

Field Summary

static ChannelBuffer

EMPTY_BUFFER A buffer whose capacity is 0.

Method Summary

int	capacity() Returns the number of bytes (octets) this buffer can contain.
void	clear()
int	compareTo(ChannelBuffer buffer) Compares the content of the specified buffer to the content of this buffer.
ChannelBuffer	copy()
ChannelBuffer	copy(int index, int length)
void	discardReadBytes()
ChannelBuffer	duplicate()
boolean	equals(Object obj) Determines if the content of the specified buffer is identical to the content of this array.
byte	getByte(int index)
void	getBytes(int index, byte[] dst)
void	getBytes(int index, byte[] dst, int dstIndex, int length)
void	getBytes(int index, ByteBuffer dst)
void	getBytes(int index, ChannelBuffer dst)
void	getBytes(int index, ChannelBuffer dst, int dstIndex, int length)
int	getBytes(int index, GatheringByteChannel out, int length)
void	getBytes(int index, OutputStream out, int length)
int	getInt(int index)
long	getLong(int index)
int	getMedium(int index)
short	getShort(int index)
int	hashCode() Returns a hash code which was calculated from the content of this buffer.
int	indexOf(int fromIndex, int toIndex, byte value)
int	indexOf(int fromIndex, int toIndex, ChannelBufferIndexFinder indexFinder)
void	markReaderIndex()
void	markWriterIndex()
ByteOrder	order() Returns the endianness of this buffer.
boolean	readable()
int	readableBytes()
byte	readByte()
ChannelBuffer	readBytes()
void	readBytes(byte[] dst)
void	readBytes(byte[] dst, int dstIndex, int length)
void	readBytes(ByteBuffer dst)
void	readBytes(ChannelBuffer dst)
ChannelBuffer	readBytes(ChannelBufferIndexFinder endIndexFinder)
void	readBytes(ChannelBuffer dst, int length)
void	readBytes(ChannelBuffer dst, int dstIndex, int length)
int	readBytes(GatheringByteChannel out, int length)
ChannelBuffer	readBytes(int length)
void	readBytes(OutputStream out, int length)
int	readerIndex()
void	readerIndex(int readerIndex)
int	readInt()
long	readLong()
int	readMedium()
short	readShort()
void	resetReaderIndex()
void	resetWriterIndex()
void	setByte(int index, byte value)
void	setBytes(int index, byte[] src)
void	setBytes(int index, byte[] src, int srcIndex, int length)
void	setBytes(int index, ByteBuffer src)
void	setBytes(int index, ChannelBuffer src)
void	setBytes(int index, ChannelBuffer src, int srcIndex, int length)
void	setBytes(int index, InputStream in, int length)
int	setBytes(int index, ScatteringByteChannel in, int length)
void	setIndex(int readerIndex, int writerIndex)
void	setInt(int index, int value)
void	setLong(int index, long value)
void	setMedium(int index, int value)
void	setShort(int index, short value)
int	skipBytes(ChannelBufferIndexFinder firstIndexFinder)
void	skipBytes(int length)
ChannelBuffer	slice()
ChannelBuffer	slice(int index, int length)
ByteBuffer	toByteBuffer()
ByteBuffer	toByteBuffer(int index, int length)
ByteBuffer[]	toByteBuffers()
ByteBuffer[]	toByteBuffers(int index, int length)
String	toString() Returns the string representation of this buffer.
boolean	writable()
int	writableBytes()
void	writeByte(byte value)
void	writeBytes(byte[] src)
void	writeBytes(byte[] src, int srcIndex, int length)
void	writeBytes(ByteBuffer src)
void	writeBytes(ChannelBuffer src)
void	writeBytes(ChannelBuffer src, int length)
void	writeBytes(ChannelBuffer src, int srcIndex, int length)
void	writeBytes(InputStream in, int length)
int	writeBytes(ScatteringByteChannel in, int length)
void	writeInt(int value)
void	writeLong(long value)
void	writeMedium(int value)
void	writePlaceholder(int length)
int	writerIndex()
void	writerIndex(int writerIndex)
void	writeShort(short value)

Field Detail

EMPTY_BUFFER

static final ChannelBuffer EMPTY_BUFFER

A buffer whose capacity is 0.

Method Detail

capacity

int capacity()

Returns the number of bytes (octets) this buffer can contain.

order

ByteOrder order()

Returns the endianness of this buffer.

readerIndex

int readerIndex()

readerIndex

void readerIndex(int readerIndex)

writerIndex

int writerIndex()

writerIndex

void writerIndex(int writerIndex)

setIndex

void setIndex(int readerIndex,
              int writerIndex)

readableBytes

int readableBytes()

writableBytes

int writableBytes()

readable

boolean readable()

writable

boolean writable()

clear

void clear()

markReaderIndex

void markReaderIndex()

resetReaderIndex

void resetReaderIndex()

markWriterIndex

void markWriterIndex()

resetWriterIndex

void resetWriterIndex()

discardReadBytes

void discardReadBytes()

getByte

byte getByte(int index)

getShort

short getShort(int index)

getMedium

int getMedium(int index)

getInt

int getInt(int index)

getLong

long getLong(int index)

getBytes

void getBytes(int index,
              ChannelBuffer dst)

getBytes

void getBytes(int index,
              ChannelBuffer dst,
              int dstIndex,
              int length)

getBytes

void getBytes(int index,
              byte[] dst)

getBytes

void getBytes(int index,
              byte[] dst,
              int dstIndex,
              int length)

getBytes

void getBytes(int index,
              ByteBuffer dst)

getBytes

void getBytes(int index,
              OutputStream out,
              int length)
              throws IOException

Throws:

IOException

getBytes

int getBytes(int index,
             GatheringByteChannel out,
             int length)
             throws IOException

Throws:

IOException

setByte

void setByte(int index,
             byte value)

setShort

void setShort(int index,
              short value)

setMedium

void setMedium(int index,
               int value)

setInt

void setInt(int index,
            int value)

setLong

void setLong(int index,
             long value)

setBytes

void setBytes(int index,
              ChannelBuffer src)

setBytes

void setBytes(int index,
              ChannelBuffer src,
              int srcIndex,
              int length)

setBytes

void setBytes(int index,
              byte[] src)

setBytes

void setBytes(int index,
              byte[] src,
              int srcIndex,
              int length)

setBytes

void setBytes(int index,
              ByteBuffer src)

setBytes

void setBytes(int index,
              InputStream in,
              int length)
              throws IOException

Throws:

IOException

setBytes

int setBytes(int index,
             ScatteringByteChannel in,
             int length)
             throws IOException

Throws:

IOException

readByte

byte readByte()

readShort

short readShort()

readMedium

int readMedium()

readInt

int readInt()

readLong

long readLong()

readBytes

ChannelBuffer readBytes()

readBytes

ChannelBuffer readBytes(int length)

readBytes

ChannelBuffer readBytes(ChannelBufferIndexFinder endIndexFinder)

readBytes

void readBytes(ChannelBuffer dst)

readBytes

void readBytes(ChannelBuffer dst,
               int length)

readBytes

void readBytes(ChannelBuffer dst,
               int dstIndex,
               int length)

readBytes

void readBytes(byte[] dst)

readBytes

void readBytes(byte[] dst,
               int dstIndex,
               int length)

readBytes

void readBytes(ByteBuffer dst)

readBytes

void readBytes(OutputStream out,
               int length)
               throws IOException

Throws:

IOException

readBytes

int readBytes(GatheringByteChannel out,
              int length)
              throws IOException

Throws:

IOException

skipBytes

void skipBytes(int length)

skipBytes

int skipBytes(ChannelBufferIndexFinder firstIndexFinder)

writeByte

void writeByte(byte value)

writeShort

void writeShort(short value)

writeMedium

void writeMedium(int value)

writeInt

void writeInt(int value)

writeLong

void writeLong(long value)

writeBytes

void writeBytes(ChannelBuffer src)

writeBytes

void writeBytes(ChannelBuffer src,
                int length)

writeBytes

void writeBytes(ChannelBuffer src,
                int srcIndex,
                int length)

writeBytes

void writeBytes(byte[] src)

writeBytes

void writeBytes(byte[] src,
                int srcIndex,
                int length)

writeBytes

void writeBytes(ByteBuffer src)

writeBytes

void writeBytes(InputStream in,
                int length)
                throws IOException

Throws:

IOException

writeBytes

int writeBytes(ScatteringByteChannel in,
               int length)
               throws IOException

Throws:

IOException

writePlaceholder

void writePlaceholder(int length)

indexOf

int indexOf(int fromIndex,
            int toIndex,
            byte value)

indexOf

int indexOf(int fromIndex,
            int toIndex,
            ChannelBufferIndexFinder indexFinder)

copy

ChannelBuffer copy()

copy

ChannelBuffer copy(int index,
                   int length)

slice

ChannelBuffer slice()

slice

ChannelBuffer slice(int index,
                    int length)

duplicate

ChannelBuffer duplicate()

toByteBuffer

ByteBuffer toByteBuffer()

toByteBuffer

ByteBuffer toByteBuffer(int index,
                        int length)

toByteBuffers

ByteBuffer[] toByteBuffers()

toByteBuffers

ByteBuffer[] toByteBuffers(int index,
                           int length)

hashCode

int hashCode()

Returns a hash code which was calculated from the content of this buffer. If there's a byte array which is equal to this array, both arrays should return the same value.

Overrides:

hashCode in class Object

equals

boolean equals(Object obj)

Determines if the content of the specified buffer is identical to the content of this array. 'Identical' here means:

• the size of the contents of the two buffers are same and
• every single byte of the content of the two buffers are same.

Please note that it doesn't compare readerIndex() nor writerIndex(). This method also returns false for null and an object which is not an instance of ChannelBuffer type.

Overrides:

equals in class Object

compareTo

int compareTo(ChannelBuffer buffer)

Compares the content of the specified buffer to the content of this buffer. Comparison is performed in the same manner with the string comparison functions of various languages such as strcmp, memcmp and String.compareTo(String).

Specified by:

compareTo in interface Comparable<ChannelBuffer>

toString

String toString()

Returns the string representation of this buffer. This method doesn't necessarily return the whole content of the buffer but returns the values of the key properties such as readerIndex(), writerIndex() and capacity()..

Overrides:

toString in class Object