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.
ByteBuffer buf = ByteBuffer.allocate(16); buf.putInt(1).putInt(2); buf.flip(); // switch from writing to reading int a = buf.getInt();
Try it
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.
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.
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
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 throwBufferUnderflowException). Read and write loops usually followflip()...compact()orclear(). - Overflow and underflow: putting past the limit throws
BufferOverflowException; getting past it throwsBufferUnderflowException. readcan return less than the buffer holds, and-1at end of file; loop until the buffer is full or-1.- Heap versus direct buffers:
allocateis on the Java heap and has a backingarray();allocateDirectlives outside the heap, is faster to hand to the OS but expensive to create. Reuse direct buffers. - Method chaining of
positionandlimit: they returnByteBuffersince 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)andencode(string)convert between text and buffers.
Related
DataInputStream,InputStream,Files.copy(),RandomAccessFile- Lessons: I/O streams, Files