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:
- You pass the buffer by calling
IoSession#write(Object).
- You pass the buffer by calling
IoFilter.NextFilter#filterWrite(IoSession,IoFilter.WriteRequest).
- 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#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
IoSessions. 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:
-
PooledByteBufferAllocator (Default)
-
SimpleByteBufferAllocator
You can change the allocator by calling
#setAllocator(ByteBufferAllocator).
