io.netty.buffer

Class Unpooled

java.lang.Object

io.netty.buffer.Unpooled

public final class Unpooled
extends java.lang.Object

Creates a new ByteBuf 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 io.netty.buffer.Unpooled.*;

 ByteBuf heapBuffer    = buffer(128);
 ByteBuf directBuffer  = directBuffer(256);
 ByteBuf wrappedBuffer = wrappedBuffer(new byte[128], new byte[256]);
 ByteBuf 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.

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 visible in the wrapped buffer. Various wrapper methods are provided and their name is all wrappedBuffer(). You might want to take a look at the methods that accept varargs 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.

Field Summary

Fields

Modifier and Type	Field and Description
static java.nio.ByteOrder	BIG_ENDIAN Big endian byte order.
static ByteBuf	EMPTY_BUFFER A buffer whose capacity is 0.
static java.nio.ByteOrder	LITTLE_ENDIAN Little endian byte order.

Method Summary

Modifier and Type	Method and Description
static ByteBuf	buffer() Creates a new big-endian Java heap buffer with reasonably small initial capacity, which expands its capacity boundlessly on demand.
static ByteBuf	buffer(int initialCapacity) Creates a new big-endian Java heap buffer with the specified capacity, which expands its capacity boundlessly on demand.
static ByteBuf	buffer(int initialCapacity, int maxCapacity) Creates a new big-endian Java heap buffer with the specified initialCapacity, that may grow up to maxCapacity The new buffer's readerIndex and writerIndex are 0.
static CompositeByteBuf	compositeBuffer() Returns a new big-endian composite buffer with no components.
static CompositeByteBuf	compositeBuffer(int maxNumComponents) Returns a new big-endian composite buffer with no components.
static ByteBuf	copiedBuffer(byte[]... arrays) Creates a new big-endian buffer whose content is a merged copy of the specified arrays.
static ByteBuf	copiedBuffer(byte[] array) Creates a new big-endian buffer whose content is a copy of the specified array.
static ByteBuf	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 ByteBuf	copiedBuffer(ByteBuf... buffers) Creates a new buffer whose content is a merged copy of the specified buffers' readable bytes.
static ByteBuf	copiedBuffer(ByteBuf buffer) Creates a new buffer whose content is a copy of the specified buffer's readable bytes.
static ByteBuf	copiedBuffer(java.nio.ByteBuffer... buffers) Creates a new buffer whose content is a merged copy of the specified buffers' slices.
static ByteBuf	copiedBuffer(java.nio.ByteBuffer buffer) Creates a new buffer whose content is a copy of the specified buffer's current slice.
static ByteBuf	copiedBuffer(char[] array, java.nio.charset.Charset charset) Creates a new big-endian buffer whose content is the specified array encoded in the specified charset.
static ByteBuf	copiedBuffer(char[] array, int offset, int length, java.nio.charset.Charset charset) Creates a new big-endian buffer whose content is a subregion of the specified array encoded in the specified charset.
static ByteBuf	copiedBuffer(java.lang.CharSequence string, java.nio.charset.Charset charset) Creates a new big-endian buffer whose content is the specified string encoded in the specified charset.
static ByteBuf	copiedBuffer(java.lang.CharSequence string, int offset, int length, java.nio.charset.Charset charset) Creates a new big-endian buffer whose content is a subregion of the specified string encoded in the specified charset.
static ByteBuf	copyBoolean(boolean... values) Create a new big-endian buffer that holds a sequence of the specified boolean values.
static ByteBuf	copyBoolean(boolean value) Creates a new single-byte big-endian buffer that holds the specified boolean value.
static ByteBuf	copyDouble(double... values) Create a new big-endian buffer that holds a sequence of the specified 64-bit floating point numbers.
static ByteBuf	copyDouble(double value) Creates a new 8-byte big-endian buffer that holds the specified 64-bit floating point number.
static ByteBuf	copyFloat(float... values) Create a new big-endian buffer that holds a sequence of the specified 32-bit floating point numbers.
static ByteBuf	copyFloat(float value) Creates a new 4-byte big-endian buffer that holds the specified 32-bit floating point number.
static ByteBuf	copyInt(int... values) Create a big-endian buffer that holds a sequence of the specified 32-bit integers.
static ByteBuf	copyInt(int value) Creates a new 4-byte big-endian buffer that holds the specified 32-bit integer.
static ByteBuf	copyLong(long... values) Create a new big-endian buffer that holds a sequence of the specified 64-bit integers.
static ByteBuf	copyLong(long value) Creates a new 8-byte big-endian buffer that holds the specified 64-bit integer.
static ByteBuf	copyMedium(int... values) Create a new big-endian buffer that holds a sequence of the specified 24-bit integers.
static ByteBuf	copyMedium(int value) Creates a new 3-byte big-endian buffer that holds the specified 24-bit integer.
static ByteBuf	copyShort(int... values) Create a new big-endian buffer that holds a sequence of the specified 16-bit integers.
static ByteBuf	copyShort(int value) Creates a new 2-byte big-endian buffer that holds the specified 16-bit integer.
static ByteBuf	copyShort(short... values) Create a new big-endian buffer that holds a sequence of the specified 16-bit integers.
static ByteBuf	directBuffer() Creates a new big-endian direct buffer with reasonably small initial capacity, which expands its capacity boundlessly on demand.
static ByteBuf	directBuffer(int initialCapacity) Creates a new big-endian direct buffer with the specified capacity, which expands its capacity boundlessly on demand.
static ByteBuf	directBuffer(int initialCapacity, int maxCapacity) Creates a new big-endian direct buffer with the specified initialCapacity, that may grow up to maxCapacity.
static ByteBuf	unmodifiableBuffer(ByteBuf... buffers) Wrap the given ByteBufs in an unmodifiable ByteBuf.
static ByteBuf	unmodifiableBuffer(ByteBuf buffer) Creates a read-only buffer which disallows any modification operations on the specified buffer.
static ByteBuf	unreleasableBuffer(ByteBuf buf) Return a unreleasable view on the given ByteBuf which will just ignore release and retain calls.
static ByteBuf	wrappedBuffer(byte[]... arrays) Creates a new big-endian composite buffer which wraps the specified arrays without copying them.
static ByteBuf	wrappedBuffer(byte[] array) Creates a new big-endian buffer which wraps the specified array.
static ByteBuf	wrappedBuffer(byte[] array, int offset, int length) Creates a new big-endian buffer which wraps the sub-region of the specified array.
static ByteBuf	wrappedBuffer(ByteBuf... buffers) Creates a new big-endian composite buffer which wraps the readable bytes of the specified buffers without copying them.
static ByteBuf	wrappedBuffer(ByteBuf buffer) Creates a new buffer which wraps the specified buffer's readable bytes.
static ByteBuf	wrappedBuffer(java.nio.ByteBuffer... buffers) Creates a new big-endian composite buffer which wraps the slices of the specified NIO buffers without copying them.
static ByteBuf	wrappedBuffer(java.nio.ByteBuffer buffer) Creates a new buffer which wraps the specified NIO buffer's current slice.
static ByteBuf	wrappedBuffer(int maxNumComponents, byte[]... arrays) Creates a new big-endian composite buffer which wraps the specified arrays without copying them.
static ByteBuf	wrappedBuffer(int maxNumComponents, ByteBuf... buffers) Creates a new big-endian composite buffer which wraps the readable bytes of the specified buffers without copying them.
static ByteBuf	wrappedBuffer(int maxNumComponents, java.nio.ByteBuffer... buffers) Creates a new big-endian composite buffer which wraps the slices of the specified NIO buffers without copying them.
static ByteBuf	wrappedBuffer(long memoryAddress, int size, boolean doFree) Creates a new buffer which wraps the specified memory address.

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 java.nio.ByteOrder BIG_ENDIAN

Big endian byte order.

LITTLE_ENDIAN

public static final java.nio.ByteOrder LITTLE_ENDIAN

Little endian byte order.

EMPTY_BUFFER

public static final ByteBuf EMPTY_BUFFER

A buffer whose capacity is 0.

Method Detail

buffer

public static ByteBuf buffer()

Creates a new big-endian Java heap buffer with reasonably small initial capacity, which expands its capacity boundlessly on demand.

directBuffer

public static ByteBuf directBuffer()

Creates a new big-endian direct buffer with reasonably small initial capacity, which expands its capacity boundlessly on demand.

buffer

public static ByteBuf buffer(int initialCapacity)

Creates a new big-endian Java heap buffer with the specified capacity, which expands its capacity boundlessly on demand. The new buffer's readerIndex and writerIndex are 0.

directBuffer

public static ByteBuf directBuffer(int initialCapacity)

Creates a new big-endian direct buffer with the specified capacity, which expands its capacity boundlessly on demand. The new buffer's readerIndex and writerIndex are 0.

buffer

public static ByteBuf buffer(int initialCapacity,
                             int maxCapacity)

Creates a new big-endian Java heap buffer with the specified initialCapacity, that may grow up to maxCapacity The new buffer's readerIndex and writerIndex are 0.

directBuffer

public static ByteBuf directBuffer(int initialCapacity,
                                   int maxCapacity)

Creates a new big-endian direct buffer with the specified initialCapacity, that may grow up to maxCapacity. The new buffer's readerIndex and writerIndex are 0.

wrappedBuffer

public static ByteBuf 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 ByteBuf 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 ByteBuf wrappedBuffer(java.nio.ByteBuffer buffer)

Creates a new buffer which wraps the specified NIO buffer's current slice. A modification on the specified buffer's content will be visible to the returned buffer.

wrappedBuffer

public static ByteBuf wrappedBuffer(long memoryAddress,
                                    int size,
                                    boolean doFree)

Creates a new buffer which wraps the specified memory address. If doFree is true the memoryAddress will automatically be freed once the reference count of the ByteBuf reaches 0.

wrappedBuffer

public static ByteBuf wrappedBuffer(ByteBuf 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.

Parameters:

buffer - The buffer to wrap. Reference count ownership of this variable is transfered to this method.

Returns:

The readable portion of the buffer, or an empty buffer if there is no readable portion. The caller is responsible for releasing this buffer.

wrappedBuffer

public static ByteBuf 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 ByteBuf wrappedBuffer(ByteBuf... buffers)

Creates a new big-endian composite buffer which wraps the readable bytes of the specified buffers without copying them. A modification on the content of the specified buffers will be visible to the returned buffer.

Parameters:

buffers - The buffers to wrap. Reference count ownership of all variables is transfered to this method.

Returns:

The readable portion of the buffers. The caller is responsible for releasing this buffer.

wrappedBuffer

public static ByteBuf wrappedBuffer(java.nio.ByteBuffer... buffers)

Creates a new big-endian composite buffer which wraps the slices of the specified NIO buffers without copying them. A modification on the content of the specified buffers will be visible to the returned buffer.

wrappedBuffer

public static ByteBuf wrappedBuffer(int maxNumComponents,
                                    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 ByteBuf wrappedBuffer(int maxNumComponents,
                                    ByteBuf... buffers)

Creates a new big-endian composite buffer which wraps the readable bytes of the specified buffers without copying them. A modification on the content of the specified buffers will be visible to the returned buffer.

Parameters:

maxNumComponents - Advisement as to how many independent buffers are allowed to exist before consolidation occurs.

buffers - The buffers to wrap. Reference count ownership of all variables is transfered to this method.

Returns:

The readable portion of the buffers. The caller is responsible for releasing this buffer.

wrappedBuffer

public static ByteBuf wrappedBuffer(int maxNumComponents,
                                    java.nio.ByteBuffer... buffers)

Creates a new big-endian composite buffer which wraps the slices of the specified NIO buffers without copying them. A modification on the content of the specified buffers will be visible to the returned buffer.

compositeBuffer

public static CompositeByteBuf compositeBuffer()

Returns a new big-endian composite buffer with no components.

compositeBuffer

public static CompositeByteBuf compositeBuffer(int maxNumComponents)

Returns a new big-endian composite buffer with no components.

copiedBuffer

public static ByteBuf 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 ByteBuf 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 ByteBuf copiedBuffer(java.nio.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 ByteBuf copiedBuffer(ByteBuf 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 ByteBuf 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 ByteBuf copiedBuffer(ByteBuf... 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:

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

copiedBuffer

public static ByteBuf copiedBuffer(java.nio.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:

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

copiedBuffer

public static ByteBuf copiedBuffer(java.lang.CharSequence string,
                                   java.nio.charset.Charset charset)

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

copiedBuffer

public static ByteBuf copiedBuffer(java.lang.CharSequence string,
                                   int offset,
                                   int length,
                                   java.nio.charset.Charset charset)

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

copiedBuffer

public static ByteBuf copiedBuffer(char[] array,
                                   java.nio.charset.Charset charset)

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

copiedBuffer

public static ByteBuf copiedBuffer(char[] array,
                                   int offset,
                                   int length,
                                   java.nio.charset.Charset charset)

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

unmodifiableBuffer

public static ByteBuf unmodifiableBuffer(ByteBuf 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.

copyInt

public static ByteBuf copyInt(int value)

Creates a new 4-byte big-endian buffer that holds the specified 32-bit integer.

copyInt

public static ByteBuf copyInt(int... values)

Create a big-endian buffer that holds a sequence of the specified 32-bit integers.

copyShort

public static ByteBuf copyShort(int value)

Creates a new 2-byte big-endian buffer that holds the specified 16-bit integer.

copyShort

public static ByteBuf copyShort(short... values)

Create a new big-endian buffer that holds a sequence of the specified 16-bit integers.

copyShort

public static ByteBuf copyShort(int... values)

Create a new big-endian buffer that holds a sequence of the specified 16-bit integers.

copyMedium

public static ByteBuf copyMedium(int value)

Creates a new 3-byte big-endian buffer that holds the specified 24-bit integer.

copyMedium

public static ByteBuf copyMedium(int... values)

Create a new big-endian buffer that holds a sequence of the specified 24-bit integers.

copyLong

public static ByteBuf copyLong(long value)

Creates a new 8-byte big-endian buffer that holds the specified 64-bit integer.

copyLong

public static ByteBuf copyLong(long... values)

Create a new big-endian buffer that holds a sequence of the specified 64-bit integers.

copyBoolean

public static ByteBuf copyBoolean(boolean value)

Creates a new single-byte big-endian buffer that holds the specified boolean value.

copyBoolean

public static ByteBuf copyBoolean(boolean... values)

Create a new big-endian buffer that holds a sequence of the specified boolean values.

copyFloat

public static ByteBuf copyFloat(float value)

Creates a new 4-byte big-endian buffer that holds the specified 32-bit floating point number.

copyFloat

public static ByteBuf copyFloat(float... values)

Create a new big-endian buffer that holds a sequence of the specified 32-bit floating point numbers.

copyDouble

public static ByteBuf copyDouble(double value)

Creates a new 8-byte big-endian buffer that holds the specified 64-bit floating point number.

copyDouble

public static ByteBuf copyDouble(double... values)

Create a new big-endian buffer that holds a sequence of the specified 64-bit floating point numbers.

unreleasableBuffer

public static ByteBuf unreleasableBuffer(ByteBuf buf)

Return a unreleasable view on the given ByteBuf which will just ignore release and retain calls.

unmodifiableBuffer

public static ByteBuf unmodifiableBuffer(ByteBuf... buffers)

Wrap the given ByteBufs in an unmodifiable ByteBuf. Be aware the returned ByteBuf will not try to slice the given ByteBufs to reduce GC-Pressure.