Why does Java NIO use a Buffer rather than a byte[] and two ints, and what do hasArray() and array() mean for a direct buffer?
answer
- memory a byte array cannot be
- the cursor lives with the data
- limit checked on get and put
- backed by an array and writable
- unspecified for direct, false in practice
basics
~20 sA Buffer keeps position and limit with the memory, checks them on every get and put, and can wrap off-heap memory a byte[] cannot. A direct buffer normally has no accessible array, so hasArray() returns false and array() throws UnsupportedOperationException.
solid answer
~50 sThree reasons. A `ByteBuffer` can sit on memory that is not a Java array: a **direct** buffer, a mapped file region, foreign memory. The JVM tries to do native I/O directly on that memory, while for a heap buffer the JDK's channel code copies through a temporary direct buffer. Second, `position` and `limit` are just `int`s, but they travel **with** the data: a channel read advances `position` by however many bytes arrived, so short reads need no bookkeeping, and relative `get`/`put` throw `BufferUnderflowException`/`BufferOverflowException` at the limit instead of trusting caller-held indexes. Third, typed access and slices share that model. For a direct buffer the spec leaves the backing array unspecified; in the JDK `hasArray()` returns `false` and `array()` throws `UnsupportedOperationException`. So check `hasArray()`, index with `arrayOffset() + position()`, and otherwise copy out with a bulk `get`.
code
java · 30 linesimport java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.ByteBuffer;
import java.util.Arrays;
public class AnyBuffer {
// Writes src's remaining bytes to out without moving src's position.
static void writeTo(OutputStream out, ByteBuffer src) throws IOException {
if (src.hasArray()) {
out.write(src.array(), src.arrayOffset() + src.position(), src.remaining());
} else {
byte[] copy = new byte[src.remaining()];
src.get(src.position(), copy);
out.write(copy);
}
}
public static void main(String[] args) throws IOException {
ByteBuffer slice = ByteBuffer.wrap(new byte[] {9, 1, 2, 3, 9}, 1, 3).slice();
ByteBuffer direct = ByteBuffer.allocateDirect(3).put(new byte[] {1, 2, 3}).flip();
System.out.println(slice.arrayOffset() + " " + direct.hasArray()); // 1 false
ByteArrayOutputStream out = new ByteArrayOutputStream();
writeTo(out, slice);
writeTo(out, direct);
System.out.println(Arrays.toString(out.toByteArray())); // [1, 2, 3, 1, 2, 3]
}
}go deeper
Recall that a ByteBuffer can be heap or direct, that channels read and write through it, and that hasArray() tells you whether array() is safe to call.
Explain why the cursor lives in the buffer: a partial channel read advances position for you, and relative get and put stop at the limit instead of trusting indexes the caller holds.
Write buffer-agnostic code: branch on hasArray(), index with arrayOffset() plus position(), copy direct buffers with a bulk get, and remember that a heap buffer pays a copy on each channel call.
Set a rule for buffer types at module boundaries, weighing direct buffers' allocation cost and off-heap footprint against the per-call copy that heap buffers pay in channel I/O.
## What a `Buffer` is `java.nio.Buffer` (since 1.4) is a fixed-size container of one primitive type. It is a sealed class with one subclass per non-boolean primitive (`ByteBuffer`, `CharBuffer`, `ShortBuffer`, `IntBuffer`, `LongBuffer`, `FloatBuffer`, `DoubleBuffer`), and channels move data through `ByteBuffer`. Besides its elements it carries **capacity**, **limit**, **position** and an optional **mark**, always ordered `0 <= mark <= position <= limit <= capacity`. Each marker is just an `int`, which is what `capacity()`, `limit()` and `position()` return. The design's value is not in the numbers but in where they live and who checks them. ## Reason one: memory that is not a Java array - A `byte[]` lives on the garbage-collected heap, and the collector may move it while compacting. A blocking system call needs memory whose address stays put. - The contents of a **direct** `ByteBuffer` from `allocateDirect()` may reside outside the normal garbage-collected heap, in the Javadoc's words; in the JDK they are allocated as native memory. The `ByteBuffer` Javadoc says the JVM will make a best effort to perform native I/O directly on it, avoiding a copy to or from an intermediate buffer. - A heap buffer still works with every channel, at the price of a copy: the JDK's internal `sun.nio.ch.IOUtil` copies its remaining bytes into a temporary direct buffer before a write, and copies them back after a read. - The same type also covers a file region mapped by `FileChannel.map()` and foreign memory wrapped by `MemorySegment.asByteBuffer()`. A `byte[]` parameter could express none of these. ## Reason two: the cursor travels with the data | Concern | `byte[]` plus offset and length | `ByteBuffer` | |---|---|---| | Partial transfer | caller adds the returned count to its own offset | a channel's `read`/`write` advance `position` by the count | | Bounds | only the array's length is checked | relative `get`/`put` stop at `limit` and throw, transferring nothing | | Multi-byte values | manual shifting and masking | `getInt()`, `putLong()` in the buffer's byte order | | Sharing a region | pass three values everywhere | `slice()` and `duplicate()` share content, keep their own markers | | Kind of memory | heap only | heap, direct, mapped, foreign | What that means in practice: - A channel read fills the buffer from `position` towards `limit` and advances `position` by however many bytes arrived, so a short read needs no extra bookkeeping: you call it again. - A relative `put` past `limit` throws `BufferOverflowException` and a relative `get` past it throws `BufferUnderflowException`; in either case no data is transferred. An absolute `get(i)` at or beyond the limit throws `IndexOutOfBoundsException`, even when the backing array is larger. - The costs are real too. A buffer is mutable state, you must switch it from filling to draining (the `flip()` idiom, covered with buffer operations), and the Javadoc says buffers are not safe for use by multiple concurrent threads. ## `hasArray()`, `array()` and `arrayOffset()` - `hasArray()` returns `true` if, and only if, the buffer is backed by an array **and is not read-only**. Only then may `array()` and `arrayOffset()` be called safely. - `array()` returns the **whole** backing array, ignoring position and limit, and writes through it change the buffer. It throws `UnsupportedOperationException` when there is no accessible array, and `ReadOnlyBufferException` when there is one but the buffer is read-only. - `arrayOffset()` maps positions to indexes: buffer position `p` is array index `p + arrayOffset()`. It is non-zero for a slice taken at a non-zero position, or of a buffer that already had an offset; `allocate(8).slice()` still has offset 0. For a direct buffer, `allocateDirect()`'s Javadoc says whether it has a backing array is **unspecified**. In the JDK a direct buffer is never array-backed, so `hasArray()` returns `false` and `array()` throws `UnsupportedOperationException`. Test `hasArray()`, not `isDirect()`, before touching the array; and `false` does not prove a buffer is direct. | Buffer | `hasArray()` | `array()` | |---|---|---| | `ByteBuffer.allocate(10)` or `wrap(bytes)` | `true` | the array; `arrayOffset()` is 0 | | `allocate(10).position(4).slice()` | `true` | the same 10-byte array; `arrayOffset()` is 4 | | `allocateDirect(10)`, a mapped buffer | `false` | `UnsupportedOperationException` | | `allocate(10).asReadOnlyBuffer()` | `false` | `ReadOnlyBufferException` | | `allocate(8).asIntBuffer()` | `false` | `UnsupportedOperationException` | ## Writing code that accepts any buffer 1. If `hasArray()` is `true`, use `array()` with index `arrayOffset() + position()` and length `remaining()`; nothing is copied. 2. Otherwise copy the remaining bytes out with a bulk `get`. The absolute form `get(position(), dst)`, added in JDK 13, leaves the position where it was. 3. Decide, and document, whether your method advances the caller's position. Channel methods do; a helper of your own may reasonably not, as long as it says so. The example below follows those steps and works the same for a heap slice and a direct buffer.
- array() hands out the live backing array. What can go wrong when you pass it to another method on its own?The callee sees the whole array, not just `position` to `limit`: stale bytes past the limit and, for a slice, data that belongs to other parts of the shared array. Its writes also change the buffer and every buffer sharing that array. Pass `array()`, `arrayOffset() + position()` and `remaining()` together, or copy the bytes out with a bulk `get` when the callee must not touch the original.
- In a heap ByteBuffer sliced at position 4 of its array, why is array()[position()] the wrong element?`array()` returns the whole backing array, and the slice starts somewhere inside it. The element at the slice's position is `array()[arrayOffset() + position()]`. `arrayOffset()` is the slice's starting index in that array, here 4; it is zero for a buffer from `allocate()` or `wrap(array)`, and for a slice taken at position 0 of one.
- Does hasArray() returning false prove that a buffer is direct?No. A read-only heap buffer reports `false` because `hasArray()` also requires the buffer to be writable, a view such as `asIntBuffer()` over a heap `ByteBuffer` reports `false`, and so does `CharBuffer.wrap(String)`. Ask `isDirect()` about directness and `hasArray()` about array access.
- Calling array() on a direct ByteBuffer returns a copy of its bytes.
- If hasArray() returns false, the buffer must be a direct buffer.
- array() returns only the bytes between position and limit.
- Channels accept only direct buffers; a heap ByteBuffer cannot be used for I/O.
- A read-only heap buffer still lets you read its bytes through array().
- java.nio.Buffer and direct ByteBuffers
- Java 1.4
- ByteBuffer.hasArray(), array() and arrayOffset()
- Java 1.4
- Absolute bulk get(int, byte[]) on ByteBuffer
- Java 13
context
- Buffer (Java SE 27 & JDK 27)docs.oracle.com
- ByteBuffer (Java SE 27 & JDK 27)docs.oracle.com
- Direct-X-Buffer.java.template at jdk-27-gagithub.com