Package org.apache.mina.common

Class ByteBuffer

java.lang.Object
org.apache.mina.common.ByteBuffer
All Implemented Interfaces:
Comparable<ByteBuffer>
Direct Known Subclasses:
BaseByteBuffer, ByteBufferProxy
public abstract class ByteBuffer extends Object implements Comparable<ByteBuffer>
A 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:

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:

You can change the allocator by calling setAllocator(ByteBufferAllocator).

See Also: