Absolute Put and Get

The putters and getters you've seen so far have all been relative. That is, they put or got the data at the current position, and incremented the position accordingly. Some buffers also support absolute puts and gets. That is, they store or retrieve an element at a particular location in the buffer, irrespective of the position (though the limit and the capacity are still respected). For example, these are the absolute put( ) and get( ) methods for the ByteBuffer class. Each takes an index that is used instead of the current position:

public abstract ByteBuffer put(int index, byte b)
public abstract byte get(int index)

If the index is less than zero or greater than or equal to the buffer's limit, these methods throw an IndexOutOfBoundsException. Otherwise, their use is straightforward. For example, this code fragment creates the holey buffer shown in Figure 14-14. Notice that these methods have no effect on the position or the limit:

Figure 14-14. A byte buffer that's been filled out of order

ByteBuffer buffer = ByteBuffer.allocate(8);
buffer.put(3, (byte) 1);
buffer.put(7, (byte) 2);
buffer.put(1, (byte) 3);

The absolute methods for the other six buffer classes are similar, aside from the obvious type changes. For instance, these are the equivalent methods for DoubleBuffer:

public abstract DoubleBuffer put(int index, double x)
public abstract double get(int index)

There are no absolute bulk get and put methods.

The absolute get and put operations are optional. Buffer objects are not guaranteed to support them. If a particular buffer object does not allow absolute gets or puts, and you attempt one anyway, the method will throw an UnsupportedOperationException. However, I've never encountered this in practice, and all buffers included with the JDK do support these methods.

As an example, suppose you've stored a GIF file into a ByteBuffer named gifBuffer, and you want to find the width and height of the image. The width is always found in the seventh and eighth bytes of the file (i.e., bytes 6 and 7, since the first byte is byte 0). The height is always found in the ninth and tenth bytes of the file. Both are unsigned little-endian shorts. We can read those values like this:

byte width1 = gifBuffer.get(6);
byte width2 = gifBuffer.get(7);
byte height1 = gifBuffer.get(8);
byte height2= gifBuffer.get(9);
int width = (width2 << 8) | width1;
int height = (height2 << 8) | height1;

The current position in the buffer is irrelevant. The width and the height are always found in bytes 6 to 9.