org.jboss.netty.buffer
Class ChannelBuffers

java.lang.Object
  org.jboss.netty.buffer.ChannelBuffers

public class ChannelBuffers
extends Object

Creates a new ChannelBuffer by allocating new space or by wrapping or copying existing byte arrays, byte buffers and a string.

Use static import

This classes is intended to be used with Java 5 static import statement:

 import static org.jboss.netty.buffer.ChannelBuffers.*;

 ChannelBuffer heapBuffer = buffer(128);
 ChannelBuffer directBuffer = directBuffer(256);
 ChannelBuffer dynamicBuffer = dynamicBuffer(512);
 ChannelBuffer wrappedBuffer = wrappedBuffer(new byte[128], new byte[256]);
 ChannelBuffer copiedBuffer = copiedBuffer(ByteBuffer.allocate(128));
 

Allocating a new buffer

Three buffer types are provided out of the box.

• buffer(int) allocates a new fixed-capacity heap buffer.
• directBuffer(int) allocates a new fixed-capacity direct buffer.
• dynamicBuffer(int) allocates a new dynamic-capacity heap buffer, whose capacity increases automatically as needed by a write operation.

Creating a wrapped buffer

Wrapped buffer is a buffer which is a view of one or more existing byte arrays and byte buffers. Any changes in the content of the original array or buffer will be reflected in the wrapped buffer. Various wrapper methods are provided and their name is all wrappedBuffer(). You might want to take a look at this method closely if you want to create a buffer which is composed of more than one array to reduce the number of memory copy.

Creating a copied buffer

Copied buffer is a deep copy of one or more existing byte arrays, byte buffers or a string. Unlike a wrapped buffer, there's no shared data between the original data and the copied buffer. Various copy methods are provided and their name is all copiedBuffer(). It is also convenient to use this operation to merge multiple buffers into one buffer.

Miscellaneous utility methods

This class also provides various utility methods to help implementation of a new buffer type, generation of hex dump and swapping an integer's byte order.

Version:

$Rev: 472 $, $Date: 2008-11-14 16:45:53 +0900 (Fri, 14 Nov 2008) $

Author:

The Netty Project (netty-dev@lists.jboss.org), Trustin Lee (tlee@redhat.com)

Field Summary

static ByteOrder	BIG_ENDIAN Big endian byte order.
static ChannelBuffer	EMPTY_BUFFER A buffer whose capacity is 0.
static ByteOrder	LITTLE_ENDIAN Little endian byte order.

Method Summary

static ChannelBuffer	buffer(ByteOrder endianness, int capacity) Creates a new Java heap buffer with the specified endianness and capacity.
static ChannelBuffer	buffer(int capacity) Creates a new big-endian Java heap buffer with the specified capacity.
static int	compare(ChannelBuffer bufferA, ChannelBuffer bufferB) Compares the two specified buffers as described in ChannelBuffer.compareTo(ChannelBuffer).
static ChannelBuffer	copiedBuffer(byte[]... arrays) Creates a new big-endian buffer whose content is a merged copy of the specified arrays.
static ChannelBuffer	copiedBuffer(byte[] array) Creates a new big-endian buffer whose content is a copy of the specified array.
static ChannelBuffer	copiedBuffer(byte[] array, int offset, int length) Creates a new big-endian buffer whose content is a copy of the specified array's sub-region.
static ChannelBuffer	copiedBuffer(ByteBuffer... buffers) Creates a new buffer whose content is a merged copy of the specified buffers' slices.
static ChannelBuffer	copiedBuffer(ByteBuffer buffer) Creates a new buffer whose content is a copy of the specified buffer's current slice.
static ChannelBuffer	copiedBuffer(ByteOrder endianness, byte[]... arrays) Creates a new buffer with the specified endianness whose content is a merged copy of the specified arrays.
static ChannelBuffer	copiedBuffer(ByteOrder endianness, byte[] array) Creates a new buffer with the specified endianness whose content is a copy of the specified array.
static ChannelBuffer	copiedBuffer(ByteOrder endianness, byte[] array, int offset, int length) Creates a new buffer with the specified endianness whose content is a copy of the specified array's sub-region.
static ChannelBuffer	copiedBuffer(ByteOrder endianness, String string, String charsetName) Creates a new buffer with the specified endianness whose content is the specified string encoded by the specified charsetName.
static ChannelBuffer	copiedBuffer(ChannelBuffer... buffers) Creates a new buffer whose content is a merged copy of the specified buffers' readable bytes.
static ChannelBuffer	copiedBuffer(ChannelBuffer buffer) Creates a new buffer whose content is a copy of the specified buffer's readable bytes.
static ChannelBuffer	copiedBuffer(String string, String charsetName) Creates a new big-endian buffer whose content is the specified string encoded by the specified charsetName.
static ChannelBuffer	directBuffer(ByteOrder endianness, int capacity) Creates a new direct buffer with the specified endianness and capacity.
static ChannelBuffer	directBuffer(int capacity) Creates a new big-endian direct buffer with the specified capacity.
static ChannelBuffer	dynamicBuffer() Creates a new big-endian dynamic buffer whose estimated data length is 256 bytes.
static ChannelBuffer	dynamicBuffer(ByteOrder endianness, int estimatedLength) Creates a new dynamic buffer with the specified endianness and the specified estimated data length.
static ChannelBuffer	dynamicBuffer(int estimatedLength) Creates a new big-endian dynamic buffer with the specified estimated data length.
static boolean	equals(ChannelBuffer bufferA, ChannelBuffer bufferB) Returns true if and only if the two specified buffers are identical to each other as described in ChannelBuffer#equals(Object).
static int	hashCode(ChannelBuffer buffer) Calculates the hash code of the specified buffer.
static String	hexDump(ChannelBuffer buffer) Returns a hex dump of the specified buffer's readable bytes.
static String	hexDump(ChannelBuffer buffer, int fromIndex, int length) Returns a hex dump of the specified buffer's sub-region.
static int	indexOf(ChannelBuffer buffer, int fromIndex, int toIndex, byte value) The default implementation of ChannelBuffer.indexOf(int, int, byte).
static int	indexOf(ChannelBuffer buffer, int fromIndex, int toIndex, ChannelBufferIndexFinder indexFinder) The default implementation of ChannelBuffer.indexOf(int, int, ChannelBufferIndexFinder).
static int	swapInt(int value) Toggles the endianness of the specified 32-bit integer.
static long	swapLong(long value) Toggles the endianness of the specified 64-bit long integer.
static int	swapMedium(int value) Toggles the endianness of the specified 24-bit medium integer.
static short	swapShort(short value) Toggles the endianness of the specified 16-bit short integer.
static ChannelBuffer	unmodifiableBuffer(ChannelBuffer buffer) Creates a read-only buffer which disallows any modification operations on the specified buffer.
static ChannelBuffer	wrappedBuffer(byte[]... arrays) Creates a new big-endian composite buffer which wraps the specified arrays without copying them.
static ChannelBuffer	wrappedBuffer(byte[] array) Creates a new big-endian buffer which wraps the specified array.
static ChannelBuffer	wrappedBuffer(byte[] array, int offset, int length) Creates a new big-endian buffer which wraps the sub-region of the specified array.
static ChannelBuffer	wrappedBuffer(ByteBuffer... buffers) Creates a new composite buffer which wraps the specified NIO buffers without copying them.
static ChannelBuffer	wrappedBuffer(ByteBuffer buffer) Creates a new buffer which wraps the specified NIO buffer's current slice.
static ChannelBuffer	wrappedBuffer(ByteOrder endianness, byte[]... arrays) Creates a new composite buffer which wraps the specified arrays without copying them.
static ChannelBuffer	wrappedBuffer(ByteOrder endianness, byte[] array) Creates a new buffer which wraps the specified array with the specified endianness.
static ChannelBuffer	wrappedBuffer(ByteOrder endianness, byte[] array, int offset, int length) Creates a new buffer which wraps the sub-region of the specified array with the specified endianness.
static ChannelBuffer	wrappedBuffer(ChannelBuffer... buffers) Creates a new composite buffer which wraps the specified buffers without copying them.
static ChannelBuffer	wrappedBuffer(ChannelBuffer buffer) Creates a new buffer which wraps the specified buffer's readable bytes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BIG_ENDIAN

public static final ByteOrder BIG_ENDIAN

Big endian byte order.

LITTLE_ENDIAN

public static final ByteOrder LITTLE_ENDIAN

Little endian byte order.

EMPTY_BUFFER

public static final ChannelBuffer EMPTY_BUFFER

A buffer whose capacity is 0.

Method Detail

buffer

public static ChannelBuffer buffer(int capacity)

Creates a new big-endian Java heap buffer with the specified capacity. The new buffer's readerIndex and writerIndex are 0.

buffer

public static ChannelBuffer buffer(ByteOrder endianness,
                                   int capacity)

Creates a new Java heap buffer with the specified endianness and capacity. The new buffer's readerIndex and writerIndex are 0.

directBuffer

public static ChannelBuffer directBuffer(int capacity)

Creates a new big-endian direct buffer with the specified capacity. The new buffer's readerIndex and writerIndex are 0.

directBuffer

public static ChannelBuffer directBuffer(ByteOrder endianness,
                                         int capacity)

Creates a new direct buffer with the specified endianness and capacity. The new buffer's readerIndex and writerIndex are 0.

dynamicBuffer

public static ChannelBuffer dynamicBuffer()

Creates a new big-endian dynamic buffer whose estimated data length is 256 bytes. The new buffer's readerIndex and writerIndex are 0.

dynamicBuffer

public static ChannelBuffer dynamicBuffer(int estimatedLength)

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 readerIndex and writerIndex are 0.

dynamicBuffer

public static ChannelBuffer dynamicBuffer(ByteOrder endianness,
                                          int 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 readerIndex and writerIndex are 0.

wrappedBuffer

public static ChannelBuffer wrappedBuffer(byte[] array)

Creates a new big-endian buffer which wraps the specified array. A modification on the specified array's content will be visible to the returned buffer.

wrappedBuffer

public static ChannelBuffer wrappedBuffer(ByteOrder endianness,
                                          byte[] array)

Creates a new buffer which wraps the specified array with the specified endianness. A modification on the specified array's content will be visible to the returned buffer.

wrappedBuffer

public static ChannelBuffer wrappedBuffer(byte[] array,
                                          int offset,
                                          int length)

Creates a new big-endian buffer which wraps the sub-region of the specified array. A modification on the specified array's content will be visible to the returned buffer.

wrappedBuffer

public static ChannelBuffer wrappedBuffer(ByteOrder endianness,
                                          byte[] array,
                                          int offset,
                                          int length)

Creates a new buffer which wraps the sub-region of the specified array with the specified endianness. A modification on the specified array's content will be visible to the returned buffer.

wrappedBuffer

public static ChannelBuffer wrappedBuffer(ByteBuffer buffer)

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.

wrappedBuffer

public static ChannelBuffer wrappedBuffer(ChannelBuffer buffer)

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.

wrappedBuffer

public static ChannelBuffer wrappedBuffer(byte[]... arrays)

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.

wrappedBuffer

public static ChannelBuffer wrappedBuffer(ByteOrder endianness,
                                          byte[]... 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.

Parameters:

endianness - the endianness of the new buffer

wrappedBuffer

public static ChannelBuffer wrappedBuffer(ChannelBuffer... buffers)

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

wrappedBuffer

public static ChannelBuffer wrappedBuffer(ByteBuffer... buffers)

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

copiedBuffer

public static ChannelBuffer copiedBuffer(byte[] array)

Creates a new big-endian buffer whose content is a copy of the specified array. The new buffer's readerIndex and writerIndex are 0 and array.length respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(ByteOrder endianness,
                                         byte[] array)

Creates a new buffer with the specified endianness whose content is a copy of the specified array. The new buffer's readerIndex and writerIndex are 0 and array.length respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(byte[] array,
                                         int offset,
                                         int length)

Creates a new big-endian buffer whose content is a copy of the specified array's sub-region. The new buffer's readerIndex and writerIndex are 0 and the specified length respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(ByteOrder endianness,
                                         byte[] array,
                                         int offset,
                                         int length)

Creates a new buffer with the specified endianness whose content is a copy of the specified array's sub-region. The new buffer's readerIndex and writerIndex are 0 and the specified length respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(ByteBuffer buffer)

Creates a new buffer whose content is a copy of the specified buffer's current slice. The new buffer's readerIndex and writerIndex are 0 and buffer.remaining respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(ChannelBuffer buffer)

Creates a new buffer whose content is a copy of the specified buffer's readable bytes. The new buffer's readerIndex and writerIndex are 0 and buffer.readableBytes respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(byte[]... arrays)

Creates a new big-endian buffer whose content is a merged copy of the specified arrays. The new buffer's readerIndex and writerIndex are 0 and the sum of all arrays' length respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(ByteOrder endianness,
                                         byte[]... arrays)

Creates a new buffer with the specified endianness whose content is a merged copy of the specified arrays. The new buffer's readerIndex and writerIndex are 0 and the sum of all arrays' length respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(ChannelBuffer... buffers)

Creates a new buffer whose content is a merged copy of the specified buffers' readable bytes. The new buffer's readerIndex and writerIndex are 0 and the sum of all buffers' readableBytes respectively.

Throws:

IllegalArgumentException - if the specified buffers' endianness are different from each other

copiedBuffer

public static ChannelBuffer copiedBuffer(ByteBuffer... buffers)

Creates a new buffer whose content is a merged copy of the specified buffers' slices. The new buffer's readerIndex and writerIndex are 0 and the sum of all buffers' remaining respectively.

Throws:

IllegalArgumentException - if the specified buffers' endianness are different from each other

copiedBuffer

public static ChannelBuffer copiedBuffer(String string,
                                         String charsetName)

Creates a new big-endian buffer whose content is the specified string encoded by the specified charsetName. The new buffer's readerIndex and writerIndex are 0 and the length of the encoded string respectively.

copiedBuffer

public static ChannelBuffer copiedBuffer(ByteOrder endianness,
                                         String string,
                                         String charsetName)

Creates a new buffer with the specified endianness whose content is the specified string encoded by the specified charsetName. The new buffer's readerIndex and writerIndex are 0 and the length of the encoded string respectively.

unmodifiableBuffer

public static ChannelBuffer unmodifiableBuffer(ChannelBuffer buffer)

Creates a read-only buffer which disallows any modification operations on the specified buffer. The new buffer has the same readerIndex and writerIndex with the specified buffer.

hexDump

public static String hexDump(ChannelBuffer buffer)

Returns a hex dump of the specified buffer's readable bytes.

hexDump

public static String hexDump(ChannelBuffer buffer,
                             int fromIndex,
                             int length)

Returns a hex dump of the specified buffer's sub-region.

hashCode

public static int hashCode(ChannelBuffer buffer)

Calculates the hash code of the specified buffer. This method is useful when implementing a new buffer type.

equals

public static boolean equals(ChannelBuffer bufferA,
                             ChannelBuffer bufferB)

Returns true if and only if the two specified buffers are identical to each other as described in ChannelBuffer#equals(Object). This method is useful when implementing a new buffer type.

compare

public static int compare(ChannelBuffer bufferA,
                          ChannelBuffer bufferB)

Compares the two specified buffers as described in ChannelBuffer.compareTo(ChannelBuffer). This method is useful when implementing a new buffer type.

indexOf

public static int indexOf(ChannelBuffer buffer,
                          int fromIndex,
                          int toIndex,
                          byte value)

The default implementation of ChannelBuffer.indexOf(int, int, byte). This method is useful when implementing a new buffer type.

indexOf

public static int indexOf(ChannelBuffer buffer,
                          int fromIndex,
                          int toIndex,
                          ChannelBufferIndexFinder indexFinder)

The default implementation of ChannelBuffer.indexOf(int, int, ChannelBufferIndexFinder). This method is useful when implementing a new buffer type.

swapShort

public static short swapShort(short value)

Toggles the endianness of the specified 16-bit short integer.

swapMedium

public static int swapMedium(int value)

Toggles the endianness of the specified 24-bit medium integer.

swapInt

public static int swapInt(int value)

Toggles the endianness of the specified 32-bit integer.

swapLong

public static long swapLong(long value)

Toggles the endianness of the specified 64-bit long integer.