Java Doc for IoBuffer.java in  » Net » mina-2.0.0-M1 » org » apache » mina » common » Java Source Code / Java DocumentationJava Source Code and Java Documentation

This is a replacement for ByteBuffer . Please refer to ByteBuffer documentation for preliminary 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 difficult to write variable-length data due to its fixed capacity

Allocation

You can allocate a new heap buffer.

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

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

 // Allocate heap buffer by default.
 IoBuffer.setUseDirectBuffer(false);
 // A new heap buffer is returned.
 IoBuffer buf = IoBuffer.allocate(1024);
 

Wrapping existing NIO buffers and arrays

This class provides a few wrap(...) methods that wraps any NIO buffers and byte arrays.

AutoExpand

Writing variable-length data using NIO ByteBuffers is not really easy, and it is because its size is fixed. IoBuffer 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" );
 IoBuffer buf = IoBuffer.allocate( 16 );
 // Turn on autoExpand (it is off by default)
 buf.setAutoExpand( true );
 buf.putString( greeting, utf8encoder );
 

AutoShrink

You might also want to decrease the capacity of the buffer when most of the allocated memory area is not being used. IoBuffer provides autoShrink property to take care of this issue. If autoShrink is turned on, IoBuffer halves the capacity of the buffer when IoBuffer.compact() is invoked and only 1/4 or less of the current capacity is being used.

You can also IoBuffer.shrink() method manually to shrink the capacity of the buffer.

The underlying ByteBuffer is reallocated by IoBuffer behind the scene, and therefore IoBuffer.buf() will return a different ByteBuffer instance once capacity changes. Please also note IoBuffer.compact() or IoBuffer.shrink() will not decrease the capacity if the new capacity is less than the IoBuffer.minimumCapacity() of the buffer.

Derived Buffers

Derived buffers are the buffers which were created by IoBuffer.duplicate() , IoBuffer.slice() , or IoBuffer.asReadOnlyBuffer() . They are useful especially when you broadcast the same messages to multiple IoSession s. Please note that the buffer derived from and its derived buffers are not both auto-expandable neither auto-shrinkable. Trying to call IoBuffer.setAutoExpand(boolean) or IoBuffer.setAutoShrink(boolean) with true parameter will raise an IllegalStateException .

Changing Buffer Allocation Policy

IoBufferAllocator interface lets you override the default buffer management behavior. There are two allocators provided out-of-the-box:

• SimpleBufferAllocator (default)
• CachedBufferAllocator

Each bit is mapped to a value in the specified enum.

Each bit is mapped to a value in the specified enum. The least significant bit maps to the first entry in the specified enum and each subsequent bit maps to each subsequent bit as mapped to the subsequent enum value.

Reads the next three bytes at this buffer's current position, composing them into an int value according to the current byte order, and then increments the position by three.

Reads the next three bytes at this buffer's current position, composing them into an int value according to the current byte order.

Reads the next three bytes at this buffer's current position, composing them into an int value according to the current byte order, and then increments the position by three.

Reads the next three bytes at this buffer's current position, composing them into an int value according to the current byte order.

Writes three bytes containing the given int value, in the current byte order, into this buffer at the current position, and then increments the position by three.

Writes three bytes containing the given int value, in the current byte order, into this buffer at the given index.

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