A byte buffer used by MINA applications.
This is a replacement for
java.nio.ByteBuffer
. Please refer to
java.nio.ByteBuffer
and
java.nio.Buffer
documentation for
usage. MINA does not use NIO
java.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:
And, you don't need to release any
ByteBuffer
which is passed as a parameter
of
IoHandler.messageReceived(IoSession,Object)
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 and
its limit will increase to the last position the string is written.
Derived Buffers
Derived buffers are the buffers which were created by
duplicate()
,
slice()
, or
asReadOnlyBuffer()
.
They are useful especially when you broadcast the same messages to
multiple
IoSession
s. Please note that the derived buffers are
neither pooled nor auto-expandable. Trying to expand a derived buffer will
raise
IllegalStateException
.
Changing Buffer Allocation and Management Policy
MINA provides a
ByteBufferAllocator
interface to let you override
the default buffer management behavior. There are two allocators provided
out-of-the-box:
You can change the allocator by calling
setAllocator(ByteBufferAllocator)
.
String toString
public @Override String toString()
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.
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.
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.
capacity
- the capacity of the bufferdirect
- true to get a direct buffer,
false to get a heap buffer.
array
public abstract byte[] array()
java.nio.ByteBuffer.array()
arrayOffset
public abstract int arrayOffset()
java.nio.ByteBuffer.arrayOffset()
asCharBuffer
public abstract CharBuffer asCharBuffer()
java.nio.ByteBuffer.asCharBuffer()
asDoubleBuffer
public abstract DoubleBuffer asDoubleBuffer()
java.nio.ByteBuffer.asDoubleBuffer()
asFloatBuffer
public abstract FloatBuffer asFloatBuffer()
java.nio.ByteBuffer.asFloatBuffer()
asInputStream
public InputStream asInputStream()
Returns an InputStream
that reads the data from this buffer.
InputStream.read()
returns -1 if the buffer position
reaches to the limit.
asIntBuffer
public abstract IntBuffer asIntBuffer()
java.nio.ByteBuffer.asIntBuffer()
asLongBuffer
public abstract LongBuffer asLongBuffer()
java.nio.ByteBuffer.asLongBuffer()
asOutputStream
public OutputStream asOutputStream()
Returns an
OutputStream
that appends the data into this buffer.
Please note that the
OutputStream.write(int)
will throw a
BufferOverflowException
instead of an
IOException
in case of buffer overflow. Please set
autoExpand property by
calling
setAutoExpand(boolean)
to prevent the unexpected runtime
exception.
asReadOnlyBuffer
public abstract ByteBuffer asReadOnlyBuffer()
java.nio.ByteBuffer.asReadOnlyBuffer()
asShortBuffer
public abstract ShortBuffer asShortBuffer()
java.nio.ByteBuffer.asShortBuffer()
autoExpand
protected ByteBuffer autoExpand(int expectedRemaining)
This method forwards the call to
expand(int)
only when
autoExpand property is
true.
autoExpand
protected ByteBuffer autoExpand(int pos,
int expectedRemaining)
This method forwards the call to
expand(int)
only when
autoExpand property is
true.
boolean equals
public @Override boolean equals(Object o)
buf
public abstract java.nio.ByteBuffer buf()
Returns the underlying NIO buffer instance.
capacity
public abstract int capacity()
java.nio.ByteBuffer.capacity()
capacity
public abstract ByteBuffer capacity(int newCapacity)
Changes the capacity of this buffer.
compact
public abstract ByteBuffer compact()
java.nio.ByteBuffer.compact()
duplicate
public abstract ByteBuffer duplicate()
java.nio.ByteBuffer.duplicate()
expand
public ByteBuffer expand(int expectedRemaining)
Changes the capacity and limit of this buffer so this buffer get
the specified expectedRemaining room from the current position.
This method works even if you didn't set autoExpand to
true.
expand
public abstract ByteBuffer expand(int pos,
int expectedRemaining)
Changes the capacity and limit of this buffer so this buffer get
the specified expectedRemaining room from the specified
pos.
This method works even if you didn't set autoExpand to
true.
fill
public ByteBuffer fill(byte value,
int size)
Fills this buffer with the specified value.
This method moves buffer position forward.
fill
public ByteBuffer fill(int size)
Fills this buffer with NUL (0x00)
.
This method moves buffer position forward.
fillAndReset
public ByteBuffer fillAndReset(byte value,
int size)
Fills this buffer with the specified value.
This method does not change buffer position.
fillAndReset
public ByteBuffer fillAndReset(int size)
Fills this buffer with NUL (0x00)
.
This method does not change buffer position.
get
public abstract byte get()
java.nio.ByteBuffer.get()
get
public ByteBuffer get(byte[] dst)
java.nio.ByteBuffer.get(byte[])
get
public abstract ByteBuffer get(byte[] dst,
int offset,
int length)
java.nio.ByteBuffer.get(byte[], int, int)
get
public abstract byte get(int index)
java.nio.ByteBuffer.get(int)
getAllocator
public static ByteBufferAllocator getAllocator()
Returns the current allocator which manages the allocated buffers.
getChar
public abstract char getChar()
java.nio.ByteBuffer.getChar()
getChar
public abstract char getChar(int index)
java.nio.ByteBuffer.getChar(int)
getDouble
public abstract double getDouble()
java.nio.ByteBuffer.getDouble()
getDouble
public abstract double getDouble(int index)
java.nio.ByteBuffer.getDouble(int)
getFloat
public abstract float getFloat()
java.nio.ByteBuffer.getFloat()
getFloat
public abstract float getFloat(int index)
java.nio.ByteBuffer.getFloat(int)
getHexDump
public String getHexDump()
Returns hexdump of this buffer.
getInt
public abstract int getInt()
java.nio.ByteBuffer.getInt()
getInt
public abstract int getInt(int index)
java.nio.ByteBuffer.getInt(int)
getLong
public abstract long getLong()
java.nio.ByteBuffer.getLong()
getLong
public abstract long getLong(int index)
java.nio.ByteBuffer.getLong(int)
getObject
public Object getObject()
throws ClassNotFoundException
Reads a Java object from the buffer using the context ClassLoader
of the current thread.
getObject
public Object getObject(ClassLoader classLoader)
throws ClassNotFoundException
Reads a Java object from the buffer using the specified classLoader.
getPrefixedString
public String getPrefixedString(CharsetDecoder decoder)
throws CharacterCodingException
Reads a string which has a 16-bit length field before the actual
encoded string, using the specified decoder
and returns it.
This method is a shortcut for getPrefixedString(2, decoder).
getPrefixedString
public String getPrefixedString(int prefixLength,
CharsetDecoder decoder)
throws CharacterCodingException
Reads a string which has a length field before the actual
encoded string, using the specified decoder
and returns it.
prefixLength
- the length of the length field (1, 2, or 4)
getShort
public abstract short getShort()
java.nio.ByteBuffer.getShort()
getShort
public abstract short getShort(int index)
java.nio.ByteBuffer.getShort()
getString
public 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.
getString
public String getString(int fieldSize,
CharsetDecoder decoder)
throws CharacterCodingException
Reads a NUL
-terminated string from this buffer using the
specified decoder
and returns it.
fieldSize
- the maximum number of bytes to read
getUnsigned
public short getUnsigned()
Reads one unsigned byte as a short integer.
getUnsigned
public short getUnsigned(int index)
Reads one byte as an unsigned short integer.
getUnsignedInt
public long getUnsignedInt()
Reads four bytes unsigned integer.
getUnsignedInt
public long getUnsignedInt(int index)
Reads four bytes unsigned integer.
getUnsignedShort
public int getUnsignedShort()
Reads two bytes unsigned integer.
getUnsignedShort
public int getUnsignedShort(int index)
Reads two bytes unsigned integer.
hasRemaining
public boolean hasRemaining()
java.nio.Buffer.hasRemaining()
int hashCode
public @Override int hashCode()
isAutoExpand
public abstract boolean isAutoExpand()
Returns true if and only if autoExpand is turned on.
isDirect
public abstract boolean isDirect()
java.nio.ByteBuffer.isDirect()
isPooled
public abstract boolean isPooled()
isReadOnly
public abstract boolean isReadOnly()
java.nio.ByteBuffer.isReadOnly()
isUseDirectBuffers
public static boolean isUseDirectBuffers()
limit
public abstract int limit()
limit
public abstract ByteBuffer limit(int newLimit)
java.nio.Buffer.limit(int)
markValue
public abstract int markValue()
Returns the position of the current mark. This method returns -1 if no
mark is set.
order
public abstract ByteOrder order()
java.nio.ByteBuffer.order()
order
public abstract ByteBuffer order(ByteOrder bo)
java.nio.ByteBuffer.order(ByteOrder)
position
public abstract int position()
java.nio.Buffer.position()
position
public abstract ByteBuffer position(int newPosition)
java.nio.Buffer.position(int)
prefixedDataAvailable
public boolean prefixedDataAvailable(int prefixLength)
Returns
true if this buffer contains a data which has a data
length as a prefix and the buffer has remaining data as enough as
specified in the data length field. This method is identical with
prefixedDataAvailable( prefixLength, Integer.MAX_VALUE ).
Please not that using this method can allow DoS (Denial of Service)
attack in case the remote peer sends too big data length value.
It is recommended to use
prefixedDataAvailable(int,int)
instead.
prefixLength
- the length of the prefix field (1, 2, or 4)
prefixedDataAvailable
public boolean prefixedDataAvailable(int prefixLength,
int maxDataLength)
Returns true if this buffer contains a data which has a data
length as a prefix and the buffer has remaining data as enough as
specified in the data length field.
prefixLength
- the length of the prefix field (1, 2, or 4)maxDataLength
- the allowed maximum of the read data length
put
public abstract ByteBuffer put(byte b)
java.nio.ByteBuffer.put(byte)
put
public ByteBuffer put(byte[] src)
java.nio.ByteBuffer.put(byte[])
put
public abstract ByteBuffer put(byte[] src,
int offset,
int length)
java.nio.ByteBuffer.put(byte[], int, int)
put
public abstract ByteBuffer put(int index,
byte b)
java.nio.ByteBuffer.put(int, byte)
put
public abstract ByteBuffer put(java.nio.ByteBuffer src)
Writes the content of the specified src into this buffer.
putChar
public abstract ByteBuffer putChar(char value)
java.nio.ByteBuffer.putChar(char)
putChar
public abstract ByteBuffer putChar(int index,
char value)
java.nio.ByteBuffer.putChar(int, char)
putDouble
public abstract ByteBuffer putDouble(double value)
java.nio.ByteBuffer.putDouble(double)
putDouble
public abstract ByteBuffer putDouble(int index,
double value)
java.nio.ByteBuffer.putDouble(int, double)
putFloat
public abstract ByteBuffer putFloat(float value)
java.nio.ByteBuffer.putFloat(float)
putFloat
public abstract ByteBuffer putFloat(int index,
float value)
java.nio.ByteBuffer.putFloat(int, float)
putInt
public abstract ByteBuffer putInt(int value)
java.nio.ByteBuffer.putInt(int)
putInt
public abstract ByteBuffer putInt(int index,
int value)
java.nio.ByteBuffer.putInt(int, int)
putLong
public abstract ByteBuffer putLong(int index,
long value)
java.nio.ByteBuffer.putLong(int, long)
putLong
public abstract ByteBuffer putLong(long value)
java.nio.ByteBuffer.putLong(int, long)
putObject
public ByteBuffer putObject(Object o)
Writes the specified Java object to the buffer.
putPrefixedString
public ByteBuffer putPrefixedString(CharSequence in,
CharsetEncoder encoder)
throws CharacterCodingException
Writes the content of in
into this buffer as a
string which has a 16-bit length field before the actual
encoded string, using the specified encoder
.
This method is a shortcut for putPrefixedString(in, 2, 0, encoder).
putPrefixedString
public ByteBuffer putPrefixedString(CharSequence in,
int prefixLength,
CharsetEncoder encoder)
throws CharacterCodingException
Writes the content of in
into this buffer as a
string which has a 16-bit length field before the actual
encoded string, using the specified encoder
.
This method is a shortcut for putPrefixedString(in, prefixLength, 0, encoder).
prefixLength
- the length of the length field (1, 2, or 4)
putPrefixedString
public ByteBuffer putPrefixedString(CharSequence in,
int prefixLength,
int padding,
CharsetEncoder encoder)
throws CharacterCodingException
Writes the content of in
into this buffer as a
string which has a 16-bit length field before the actual
encoded string, using the specified encoder
.
This method is a shortcut for putPrefixedString(in, prefixLength, padding, ( byte ) 0, encoder).
prefixLength
- the length of the length field (1, 2, or 4)padding
- the number of padded NULs (1 (or 0), 2, or 4)
putPrefixedString
public ByteBuffer putPrefixedString(CharSequence val,
int prefixLength,
int padding,
byte padValue,
CharsetEncoder encoder)
throws CharacterCodingException
Writes the content of in
into this buffer as a
string which has a 16-bit length field before the actual
encoded string, using the specified encoder
.
prefixLength
- the length of the length field (1, 2, or 4)padding
- the number of padded bytes (1 (or 0), 2, or 4)padValue
- the value of padded bytes
putShort
public abstract ByteBuffer putShort(int index,
short value)
java.nio.ByteBuffer.putShort(int, short)
putShort
public abstract ByteBuffer putShort(short value)
java.nio.ByteBuffer.putShort(short)
putString
public ByteBuffer putString(CharSequence val,
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.
putString
public ByteBuffer putString(CharSequence val,
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
NUL
s as a terminator.
Please note that this method doesn't terminate with
NUL
if the input string is longer than
fieldSize.
fieldSize
- the maximum number of bytes to write
release
public abstract void release()
Releases the specified buffer to buffer pool.
remaining
public int remaining()
java.nio.Buffer.remaining()
setAllocator
public static void setAllocator(ByteBufferAllocator newAllocator)
Changes the current allocator with the specified one to manage
the allocated buffers from now.
setAutoExpand
public abstract ByteBuffer setAutoExpand(boolean autoExpand)
Turns on or off autoExpand.
setPooled
public abstract void setPooled(boolean pooled)
setUseDirectBuffers
public static void setUseDirectBuffers(boolean useDirectBuffers)
skip
public ByteBuffer skip(int size)
Forwards the position of this buffer as the specified size
bytes.
slice
public abstract ByteBuffer slice()
java.nio.ByteBuffer.slice()
sweep
public ByteBuffer sweep()
Clears this buffer and fills its content with NUL.
The position is set to zero, the limit is set to the capacity,
and the mark is discarded.
sweep
public ByteBuffer sweep(byte value)
Clears this buffer and fills its content with value.
The position is set to zero, the limit is set to the capacity,
and the mark is discarded.
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.
wrap
public static ByteBuffer wrap(java.nio.ByteBuffer nioBuffer)
Wraps the specified NIO java.nio.ByteBuffer
into MINA buffer.