Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท I/O and Files

Channels and ByteBuffer

Reference for java.nio channels and buffers: ByteBuffer position, limit and flip, FileChannel reads and writes, byte order, slices and memory-mapped files.

Java NIO ("new I/O", from Java 1.4) reads and writes data through two cooperating types. A buffer (ByteBuffer, CharBuffer, IntBuffer, ...) is a block of memory with a cursor. A channel (FileChannel, SocketChannel, ...) moves data between a buffer and a file, socket or pipe. Where a stream hands you one byte or array at a time, a channel reads a whole buffer in one call.

The buffer is the part you will use most, because it is also a convenient way to build and parse binary data in memory: it reads and writes int, long, double and so on at positions you control, in either byte order. The most important thing to understand is its state: position, limit and capacity.

Java
ByteBuffer buf = ByteBuffer.allocate(16);
buf.putInt(1).putInt(2);
buf.flip();                 // switch from writing to reading
int a = buf.getInt();

Try it

Java Position, limit and flip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java FileChannel read and write

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Copying channels and slicing a buffer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
static ByteBuffer ByteBuffer.allocate(int capacity)          // heap buffer
static ByteBuffer ByteBuffer.allocateDirect(int capacity)    // native memory
static ByteBuffer ByteBuffer.wrap(byte[] array)

static FileChannel FileChannel.open(Path path, OpenOption... options) throws IOException
int read(ByteBuffer dst) throws IOException
int write(ByteBuffer src) throws IOException
Buffer member Description
capacity() Fixed size; never changes.
position() Index of the next byte to read or write.
limit() First index that must not be read or written.
flip() Sets limit = position and position = 0: switch from filling to draining.
clear() position = 0, limit = capacity: ready to fill again. Does not erase data.
rewind() position = 0; keeps the limit.
compact() Moves unread bytes to the start, ready to continue filling.
put, get, putInt, getInt, ... Relative (move position) or absolute (index argument) access.
order(ByteOrder) Byte order for multi-byte values; the default is big-endian.
slice(), duplicate(), asReadOnlyBuffer() Views that share the same memory.
Channel member Description
read(ByteBuffer) Returns the bytes read, or -1 at the end.
write(ByteBuffer) Writes the remaining bytes; may not write them all on non-blocking channels.
position(), position(long), size(), truncate(long) File cursor and size.
transferTo, transferFrom Copy between channels without going through your buffers.
map(MapMode, long, long) Memory-maps a region of the file as a MappedByteBuffer.
lock(), tryLock() File locks between processes.

Usage notes

  • Forgetting flip() is the number one bug: after writing into a buffer, position is at the end, so reads return nothing (or throw BufferUnderflowException). Read and write loops usually follow flip() ... compact() or clear().
  • Overflow and underflow: putting past the limit throws BufferOverflowException; getting past it throws BufferUnderflowException.
  • read can return less than the buffer holds, and -1 at end of file; loop until the buffer is full or -1.
  • Heap versus direct buffers: allocate is on the Java heap and has a backing array(); allocateDirect lives outside the heap, is faster to hand to the OS but expensive to create. Reuse direct buffers.
  • Method chaining of position and limit: they return ByteBuffer since Java 9 (flip() too), so chaining is allowed.
  • Memory mapping (FileChannel.map) gives random access to large files; the mapping is released only when the buffer is garbage collected, so be careful deleting mapped files on Windows.
  • Thread safety: buffers are not thread-safe; channels are.
  • Everyday file work is simpler with Files; channels pay off with large files, non-blocking sockets and binary formats.
  • Charsets: StandardCharsets.UTF_8.decode(buf) and encode(string) convert between text and buffers.