Bulk Put and Get

You've already seen the relative put and get methods, which insert or retrieve data at the current position. Bulk versions of these methods operate on arrays of the buffer's element type. For instance, ByteBuffer has these two bulk put methods:

public final ByteBuffer put(byte[] data)
public ByteBuffer put(byte[] data, int offset, int length)

The first puts the entire contents of the array data into the buffer beginning at its current position. The position is incremented by the length of the array. The second puts only the sub-array of data beginning at offset and continuing for length bytes. These methods copy the array. Changing the data array after calling put( ) does not change the data in the buffer.

For example, this code fragment creates the buffer shown in Figure 14-12:

Figure 14-12. A byte buffer with position 3

ByteBuffer buffer = ByteBuffer.allocate(8)
buffer.put((byte) 5);
buffer.put((byte) 23);
buffer.put((byte) 5);

If we now put a byte array with length 4 in it, the position will move forward to 7, as shown in Figure 14-13:

byte[] data = {(byte) 67, (byte) -23, (byte) -5, (byte) 17};
buffer.put(data);

Figure 14-13. A byte buffer with position 7

From this point, we can put one more byte in the buffer, flip the buffer and drain it, clear the buffer and write eight more bytes, or do anything else we want. How the data was put in the bufferwhether with bulk or single methods, or relative or absolute methodsis irrelevant. All that matters is the state of the buffer.

Two corresponding bulk get methods copy bytes from the buffer starting at the current position into a provided array:

public ByteBuffer get(byte[] data)
public ByteBuffer get(byte[] data, int offset, int length)

Both methods update the position by the number of bytes returned.

For both put and get, the array must fit into the available space. If you try to put a larger array (or sub-array) into the buffer than it has space left for, put( ) throws a BufferOverflowException. If you try to get a larger array (or sub-array) than the buffer has data remaining, get( ) tHRows a BufferUnderflowException. In both cases, the buffer is left in its original state and no data is transferred.

Other buffers have these same methods. All that differs are the return and argument types. For instance, the IntBuffer class has these four methods:

public final IntBuffer put(int[] data)
public IntBuffer put(int[] data, int offset, int length)
public IntBuffer get(int[] data)
public IntBuffer get(int[] data, int offset, int length)

DoubleBuffer has these four methods:

public final DoubleBuffer put(double[] data)
public DoubleBuffer put(double[] data, int offset, int length)
public DoubleBuffer get(double[] data)
public DoubleBuffer get(double[] data, int offset, int length)

The other buffer classes are similar.