org.apache.mina.common
Class ByteBuffer

java.lang.Object
  org.apache.mina.common.ByteBuffer

Direct Known Subclasses:

ByteBufferProxy

public abstract class ByteBuffer
extends Object

A pooled byte buffer used by MINA applications.

This is a replacement for ByteBuffer. Please refer to ByteBuffer and Buffer documentation for usage. MINA does not use NIO ByteBuffer directly for two reasons:

• It doesn't provide useful getters and putters such as fill, get/putString, and get/putAsciiInt() enough.
• It is hard to distinguish if the buffer is created from MINA buffer pool or not. MINA have to return used buffers back to pool.
• It is difficult to write variable-length data due to its fixed capacity

Allocation

You can get a heap buffer from buffer pool:

 ByteBuffer buf = ByteBuffer.allocate(1024, false);
 

you can also get a direct buffer from buffer pool:

 ByteBuffer buf = ByteBuffer.allocate(1024, true);
 

or you can let MINA choose:

 ByteBuffer buf = ByteBuffer.allocate(1024);
 

Acquire/Release

Please note that you never need to release the allocated buffer because MINA will release it automatically when:

• You pass the buffer by calling IoSession.write(ByteBuffer, Object).
• You pass the buffer by calling ProtocolEncoderOutput.write(ByteBuffer).

And, you don't need to release any ByteBuffer which is passed as a parameter of IoHandler.dataRead(IoSession, ByteBuffer) method. They are released automatically when the method returns.

You have to release buffers manually by calling release() when:

• You allocated a buffer, but didn't pass the buffer to any of two methods above.
• You called acquire() to prevent the buffer from being released.

Wrapping existing NIO buffers and arrays

This class provides a few wrap(...) methods that wraps any NIO buffers and byte arrays. Wrapped MINA buffers are not returned to the buffer pool by default to prevent unexpected memory leakage by default. In case you want to make it pooled, you can call setPooled(boolean) with true flag to enable pooling.

AutoExpand

Writing variable-length data using NIO ByteBuffers is not really easy, and it is because its size is fixed. MINA ByteBuffer introduces autoExpand property. If autoExpand property is true, you never get BufferOverflowException or IndexOutOfBoundsException (except when index is negative). It automatically expands its capacity and limit value. For example:

 String greeting = messageBundle.getMessage( "hello" );
 ByteBuffer buf = ByteBuffer.allocate( 16 );
 // Turn on autoExpand (it is off by default)
 buf.setAutoExpand( true );
 buf.putString( greeting, utf8encoder );
 

NIO ByteBuffer is reallocated by MINA ByteBuffer behind the scene if the encoded data is larger than 16 bytes. Its capacity will increase by two times, and its limit will increase to the last position the string is written.

Version:

$Rev: 332218 $, $Date: 2005-11-10 12:52:42 +0900 $

Author:

The Apache Directory Project (dev@directory.apache.org)

Constructor Summary

protected

ByteBuffer()

Method Summary

abstract void	acquire() Increases the internal reference count of this buffer to defer automatic release.
static ByteBuffer	allocate(int capacity) Returns the direct or heap buffer which is capable of the specified size.
static ByteBuffer	allocate(int capacity, boolean direct) Returns the buffer which is capable of the specified size.
abstract CharBuffer	asCharBuffer()
abstract DoubleBuffer	asDoubleBuffer()
abstract FloatBuffer	asFloatBuffer()
abstract IntBuffer	asIntBuffer()
abstract LongBuffer	asLongBuffer()
abstract ShortBuffer	asShortBuffer()
abstract ByteBuffer	buf() Returns the underlying NIO buffer instance.
abstract int	capacity()
abstract ByteBuffer	clear()
abstract ByteBuffer	compact()
abstract int	compareTo(ByteBuffer that)
abstract boolean	equals(Object ob)
abstract ByteBuffer	fill(byte value, int size) Fills this buffer with the specified value.
abstract ByteBuffer	fill(int size) Fills this buffer with NUL (0x00).
abstract ByteBuffer	fillAndReset(byte value, int size) Fills this buffer with the specified value.
abstract ByteBuffer	fillAndReset(int size) Fills this buffer with NUL (0x00).
abstract ByteBuffer	flip()
abstract byte	get()
abstract ByteBuffer	get(byte[] dst)
abstract ByteBuffer	get(byte[] dst, int offset, int length)
abstract byte	get(int index)
abstract char	getChar()
abstract char	getChar(int index)
abstract double	getDouble()
abstract double	getDouble(int index)
abstract float	getFloat()
abstract float	getFloat(int index)
abstract String	getHexDump() Returns hexdump of this buffer.
abstract int	getInt()
abstract int	getInt(int index)
abstract long	getLong()
abstract long	getLong(int index)
abstract short	getShort()
abstract short	getShort(int index)
abstract String	getString(CharsetDecoder decoder) Reads a NUL-terminated string from this buffer using the specified decoder and returns it.
abstract String	getString(int fieldSize, CharsetDecoder decoder) Reads a NUL-terminated string from this buffer using the specified decoder and returns it.
abstract short	getUnsigned()
abstract short	getUnsigned(int index)
abstract long	getUnsignedInt()
abstract long	getUnsignedInt(int index)
abstract int	getUnsignedShort()
abstract int	getUnsignedShort(int index)
abstract int	hashCode()
abstract boolean	hasRemaining()
abstract boolean	isAutoExpand() Returns true if and only if autoExpand is turned on.
abstract boolean	isDirect()
abstract boolean	isPooled() Returns true if and only if this buffer is returned back to the buffer pool when released.
abstract int	limit()
abstract ByteBuffer	limit(int newLimit)
abstract ByteBuffer	mark()
abstract ByteOrder	order()
abstract ByteBuffer	order(ByteOrder bo)
abstract int	position()
abstract ByteBuffer	position(int newPosition)
abstract ByteBuffer	put(byte b)
abstract ByteBuffer	put(byte[] src)
abstract ByteBuffer	put(byte[] src, int offset, int length)
abstract ByteBuffer	put(ByteBuffer src)
abstract ByteBuffer	put(ByteBuffer src)
abstract ByteBuffer	put(int index, byte b)
abstract ByteBuffer	putChar(char value)
abstract ByteBuffer	putChar(int index, char value)
abstract ByteBuffer	putDouble(double value)
abstract ByteBuffer	putDouble(int index, double value)
abstract ByteBuffer	putFloat(float value)
abstract ByteBuffer	putFloat(int index, float value)
abstract ByteBuffer	putInt(int value)
abstract ByteBuffer	putInt(int index, int value)
abstract ByteBuffer	putLong(int index, long value)
abstract ByteBuffer	putLong(long value)
abstract ByteBuffer	putShort(int index, short value)
abstract ByteBuffer	putShort(short value)
abstract ByteBuffer	putString(CharSequence in, CharsetEncoder encoder) Writes the content of in into this buffer using the specified encoder.
abstract ByteBuffer	putString(CharSequence in, int fieldSize, CharsetEncoder encoder) Writes the content of in into this buffer as a NUL-terminated string using the specified encoder.
abstract void	release() Releases the specified buffer to buffer pool.
abstract int	remaining()
abstract ByteBuffer	reset()
abstract ByteBuffer	rewind()
abstract ByteBuffer	setAutoExpand(boolean autoExpand) Turns on or off autoExpand.
abstract void	setPooled(boolean pooled) Sets whether this buffer is returned back to the buffer pool when released.
abstract ByteBuffer	skip(int size) Forwards the position of this buffer as the specified size bytes.
abstract String	toString()
static ByteBuffer	wrap(byte[] byteArray) Wraps the specified byte array into MINA heap buffer.
static ByteBuffer	wrap(byte[] byteArray, int offset, int length) Wraps the specified byte array into MINA heap buffer.
static ByteBuffer	wrap(ByteBuffer nioBuffer) Wraps the specified NIO ByteBuffer into MINA buffer.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ByteBuffer

protected ByteBuffer()

Method Detail

allocate

public static ByteBuffer allocate(int capacity)

Returns the direct or heap buffer which is capable of the specified size. This method tries to allocate direct buffer first, and then tries heap buffer if direct buffer memory is exhausted. Please use allocate(int, boolean) to allocate buffers of specific type.

Parameters:

capacity - the capacity of the buffer

allocate

public static ByteBuffer allocate(int capacity,
                                  boolean direct)

Returns the buffer which is capable of the specified size.

Parameters:

capacity - the capacity of the buffer

direct - true to get a direct buffer, false to get a heap buffer.

wrap

public static ByteBuffer wrap(ByteBuffer nioBuffer)

Wraps the specified NIO ByteBuffer into MINA buffer.

wrap

public static ByteBuffer wrap(byte[] byteArray)

Wraps the specified byte array into MINA heap buffer.

wrap

public static ByteBuffer wrap(byte[] byteArray,
                              int offset,
                              int length)

Wraps the specified byte array into MINA heap buffer. Please note that MINA buffers are going to be pooled, and therefore there can be waste of memory if you wrap your byte array specifying offset and length.

acquire

public abstract void acquire()

Increases the internal reference count of this buffer to defer automatic release. You have to invoke release() as many as you invoked this method to release this buffer.

Throws:

IllegalStateException - if you attempt to acquire already released buffer.

release

public abstract void release()

Releases the specified buffer to buffer pool.

Throws:

IllegalStateException - if you attempt to release already released buffer.

buf

public abstract ByteBuffer buf()

Returns the underlying NIO buffer instance.

isDirect

public abstract boolean isDirect()

capacity

public abstract int capacity()

isAutoExpand

public abstract boolean isAutoExpand()

Returns true if and only if autoExpand is turned on.

setAutoExpand

public abstract ByteBuffer setAutoExpand(boolean autoExpand)

Turns on or off autoExpand.

isPooled

public abstract boolean isPooled()

Returns true if and only if this buffer is returned back to the buffer pool when released.

The default value of this property is true if and only if you allocated this buffer using allocate(int) or allocate(int, boolean), or false otherwise. (i.e. wrap(byte[]), wrap(byte[], int, int), and wrap(java.nio.ByteBuffer))

setPooled

public abstract void setPooled(boolean pooled)

Sets whether this buffer is returned back to the buffer pool when released.

The default value of this property is true if and only if you allocated this buffer using allocate(int) or allocate(int, boolean), or false otherwise. (i.e. wrap(byte[]), wrap(byte[], int, int), and wrap(java.nio.ByteBuffer))

position

public abstract int position()

position

public abstract ByteBuffer position(int newPosition)

limit

public abstract int limit()

limit

public abstract ByteBuffer limit(int newLimit)

mark

public abstract ByteBuffer mark()

reset

public abstract ByteBuffer reset()

clear

public abstract ByteBuffer clear()

flip

public abstract ByteBuffer flip()

rewind

public abstract ByteBuffer rewind()

remaining

public abstract int remaining()

hasRemaining

public abstract boolean hasRemaining()

get

public abstract byte get()

getUnsigned

public abstract short getUnsigned()

put

public abstract ByteBuffer put(byte b)

get

public abstract byte get(int index)

getUnsigned

public abstract short getUnsigned(int index)

put

public abstract ByteBuffer put(int index,
                               byte b)

get

public abstract ByteBuffer get(byte[] dst,
                               int offset,
                               int length)

get

public abstract ByteBuffer get(byte[] dst)

put

public abstract ByteBuffer put(ByteBuffer src)

put

public abstract ByteBuffer put(ByteBuffer src)

put

public abstract ByteBuffer put(byte[] src,
                               int offset,
                               int length)

put

public abstract ByteBuffer put(byte[] src)

compact

public abstract ByteBuffer compact()

toString

public abstract String toString()

Overrides:

toString in class Object

hashCode

public abstract int hashCode()

Overrides:

hashCode in class Object

equals

public abstract boolean equals(Object ob)

Overrides:

equals in class Object

compareTo

public abstract int compareTo(ByteBuffer that)

order

public abstract ByteOrder order()

order

public abstract ByteBuffer order(ByteOrder bo)

getChar

public abstract char getChar()

putChar

public abstract ByteBuffer putChar(char value)

getChar

public abstract char getChar(int index)

putChar

public abstract ByteBuffer putChar(int index,
                                   char value)

asCharBuffer

public abstract CharBuffer asCharBuffer()

getShort

public abstract short getShort()

getUnsignedShort

public abstract int getUnsignedShort()

putShort

public abstract ByteBuffer putShort(short value)

getShort

public abstract short getShort(int index)

getUnsignedShort

public abstract int getUnsignedShort(int index)

putShort

public abstract ByteBuffer putShort(int index,
                                    short value)

asShortBuffer

public abstract ShortBuffer asShortBuffer()

getInt

public abstract int getInt()

getUnsignedInt

public abstract long getUnsignedInt()

putInt

public abstract ByteBuffer putInt(int value)

getInt

public abstract int getInt(int index)

getUnsignedInt

public abstract long getUnsignedInt(int index)

putInt

public abstract ByteBuffer putInt(int index,
                                  int value)

asIntBuffer

public abstract IntBuffer asIntBuffer()

getLong

public abstract long getLong()

putLong

public abstract ByteBuffer putLong(long value)

getLong

public abstract long getLong(int index)

putLong

public abstract ByteBuffer putLong(int index,
                                   long value)

asLongBuffer

public abstract LongBuffer asLongBuffer()

getFloat

public abstract float getFloat()

putFloat

public abstract ByteBuffer putFloat(float value)

getFloat

public abstract float getFloat(int index)

putFloat

public abstract ByteBuffer putFloat(int index,
                                    float value)

asFloatBuffer

public abstract FloatBuffer asFloatBuffer()

getDouble

public abstract double getDouble()

putDouble

public abstract ByteBuffer putDouble(double value)

getDouble

public abstract double getDouble(int index)

putDouble

public abstract ByteBuffer putDouble(int index,
                                     double value)

asDoubleBuffer

public abstract DoubleBuffer asDoubleBuffer()

getHexDump

public abstract String getHexDump()

Returns hexdump of this buffer.

getString

public abstract String getString(CharsetDecoder decoder)
                          throws CharacterCodingException

Reads a NUL-terminated string from this buffer using the specified decoder and returns it. This method reads until the limit of this buffer if no NUL is found.

Throws:

CharacterCodingException

getString

public abstract String getString(int fieldSize,
                                 CharsetDecoder decoder)
                          throws CharacterCodingException

Reads a NUL-terminated string from this buffer using the specified decoder and returns it.

Parameters:

fieldSize - the maximum number of bytes to read

Throws:

CharacterCodingException

putString

public abstract ByteBuffer putString(CharSequence in,
                                     CharsetEncoder encoder)
                              throws CharacterCodingException

Writes the content of in into this buffer using the specified encoder. This method doesn't terminate string with NUL. You have to do it by yourself.

Throws:

BufferOverflowException - if the specified string doesn't fit

CharacterCodingException

putString

public abstract ByteBuffer putString(CharSequence in,
                                     int fieldSize,
                                     CharsetEncoder encoder)
                              throws CharacterCodingException

Writes the content of in into this buffer as a NUL-terminated string using the specified encoder.

If the charset name of the encoder is UTF-16, you cannot specify odd fieldSize, and this method will append two NULs as a terminator.

Please note that this method doesn't terminate with NUL if the input string is longer than fieldSize.

Parameters:

fieldSize - the maximum number of bytes to write

Throws:

CharacterCodingException

skip

public abstract ByteBuffer skip(int size)

Forwards the position of this buffer as the specified size bytes.

fill

public abstract ByteBuffer fill(byte value,
                                int size)

Fills this buffer with the specified value. This method moves buffer position forward.

fillAndReset

public abstract ByteBuffer fillAndReset(byte value,
                                        int size)

Fills this buffer with the specified value. This method does not change buffer position.

fill

public abstract ByteBuffer fill(int size)

Fills this buffer with NUL (0x00). This method moves buffer position forward.

fillAndReset

public abstract ByteBuffer fillAndReset(int size)

Fills this buffer with NUL (0x00). This method does not change buffer position.