Java's ByteBuffer

In the buffer, capacity refers to the total size. Position refers to the current position in the buffer. Limit refers to the end of the buffer's capacity in write mode, to the end of the range of bytes written in write mode—which might not be the whole buffer if writing never reached total capacity. A buffer has mode—either read or write.

A word on direct versus not-direct...

This class offers method allocate() and allocateDirect(). The former is the more frequently used one and its allocations live in the JVM's garbage-collectible heap. The latter, however, is not garbage-collectible. This sort of allocation is also very expensive, but the result is faster and more appropriate usage for certain types of native I/O operations (that I don't discuss here). See Direct vs. non-direct buffers in the Javadoc for java.nio.ByteBuffer.

Java (java.nio) ByteBuffer is useful whenever one needs to perform fast, low-level I/O such as when implementing a TCP/IP protocol, writing a database, etc. (This is what we're doing.) Here's a good summary. Here are some useful operations:

• Create from byte[]:

  byte[]     bytes  = new byte[10];
  ByteBuffer buffer = ByteBuffer.wrap( bytes );
  

• Create with a 10-byte capacity:

  ByteBuffer buffer = ByteBuffer.allocate( 10 );
  

• Determine a buffer's capacity:

  int capacity = buffer.capacity();
  

• Establish the current position in the buffer:

  buffer.position( 5 );
  

• Get a byte from an absolute offset (doesn't affect current position):

  byte byte = buffer.get( 5 );
  

• Get a byte from the current position:

  byte byte = buffer.get();
  

• Get the new position:

  int position = buffer.position();
  

• Get the remaining count of bytes; this is calculated as limit - position:

  int remaining = buffer.remaining();
  

• Set/reset the limit (number of bytes in buffer—will affect remaining):

  buffer.limit( 7 );
  

• Put a byte to an absolute offset (doesn't affect current position):

  buffer.put( position, byte );
  

• Rewind to position 0:

  buffer.rewind();
  

• Put a multibyte value:

  buffer.putShort( position, ( short ) 123 );
  byte a = buffer.get( position );   // yields 0
  byte b = buffer.get( position+1 ); // yields 123
  

• Toggle buffer to read mode:

  buffer.flip();
  

• Toggle buffer to write mode:

  buffer.clear();   // empties buffer putting position at 0
  buffer.compact(); // clears those bytes that have been read prior to current position
  

Examples: testing a ByteBuffer

ByteBuffers are not typically used to hold string per se, though they can. Usually, you put "data" into a buffer (integers, longs, floats, etc.). However, here is a test that illustrates putting a string into a ByteBuffer:

@Test
public void testByteBufferWithAString()
{
  final String TEST_STRING = "This is a test.";
  final int    LENGTH      = TEST_STRING.length();
  System.out.println( "         TEST_STRING=" + TEST_STRING );
  System.out.println( "              LENGTH=" + LENGTH );
  System.out.println( "  Allocate the ByteBuffer:");
  ByteBuffer buffer = ByteBuffer.allocate( LENGTH );
  System.out.println( "  buffer.remaining()=" + buffer.remaining() ); // this is limit-position
  System.out.println( "      buffer.limit()=" + buffer.limit() );
  System.out.println( "  Copy the test string contents into the buffer:" );
  buffer.put( TEST_STRING.getBytes() );
  System.out.println( "  Now, flip the buffer, then print its contents:" );
  buffer.flip();
  while( buffer.hasRemaining() )                                     // as long as position < limit
    System.out.print( ( char ) buffer.get() );
  System.out.println();
  System.out.println( "  buffer.remaining()=" + buffer.remaining() );
  System.out.println( "      buffer.limit()=" + buffer.limit() );
}

Output:

         TEST_STRING=This is a test.
              LENGTH=15
  Allocate the ByteBuffer:
  buffer.remaining()=15
      buffer.limit()=15
  Copy the test string contents into the buffer:
  Now, flip the buffer, then print its contents:
This is a test.
  buffer.remaining()=0
      buffer.limit()=15

Here a ByteBuffer is used to store a short integer:

@Test
public void testByteBufferWithAShortInside()
{
  final Short aShort = 23;
  System.out.println( "  Allocate the ByteBuffer:");
  ByteBuffer buffer = ByteBuffer.allocate( Short.SIZE );
  System.out.println( "  buffer.remaining()=" + buffer.remaining() );
  System.out.println( "      buffer.limit()=" + buffer.limit() );
  System.out.println( "  Copy the test short into the buffer:" );
  buffer.putShort( aShort );
  System.out.println( "  Now, flip the buffer, then print its contents:" );
  buffer.flip();
  while( buffer.hasRemaining() )
    System.out.print( buffer.getShort() + "" );
  System.out.println();
  System.out.println( "  buffer.remaining()=" + buffer.remaining() );
  System.out.println( "      buffer.limit()=" + buffer.limit() );
}

Output:

  Allocate the ByteBuffer:
  buffer.remaining()=16
      buffer.limit()=16
  Copy the test short into the buffer:
  Now, flip the buffer, then print its contents:
23
  buffer.remaining()=0
      buffer.limit()=2