java-core-examples/nio2/README.md

nio2

Companion code for the ankurm.com post "Java NIO.2 File API: Files, Path, WatchService, and Streaming Large Files Without OOM." Module nio2 in java-core-examples.

All explanation lives in the post; this module holds the runnable evidence and the captured output.

Versions

Component	Version
JDK	25.0.4.1+1 (Temurin, LTS)
JUnit Jupiter	5.11.0
OS	Linux 6.18 (WatchService and /proc/self/fd results are Linux-specific)
Hardware	2 vCPU x86-64 VM shared with other jobs (timings are indicative, not a leaderboard)
Big file	5,000,000,069 bytes (the full 5 GB fit; the file is generated, then deleted by the script)

Quickstart

export JDK25_HOME=/path/to/jdk-25
./scripts/run-all.sh                     # needs ~5.3 GB free in /tmp/nio2-data; regenerates output/
BIG_BYTES=500000000 ./scripts/run-all.sh # smaller "big" file if disk is tight
mvn -q -pl nio2 -am test                 # 12 assertions, small files only

What is in here

File	Shows	Output
LogFile	deterministic generator for the synthetic log file	02
StreamLines	Files.lines and Files.newBufferedReader over 5 GB at -Xmx64m, heap and GC evidence	03, 04
ReadAllFail	readAllLines / readString / readAllBytes at the same -Xmx, and how much heap they need	05
HandleLeakDemo	open file descriptors around unclosed Files.lines and Files.walk	06
HandleExhaustion	what an unclosed Files.walk becomes under ulimit -n 64	07
WalkFindDemo	list / walk / find / walkFileTree / DirectoryStream, symlink loop	08
LinesCharsetDemo	a bad byte fails lazily inside Files.lines	09
WatchDemo	WatchService events, coalescing, no recursion, OVERFLOW at 513 pending events	10, 11
(JDK source excerpt)	AbstractWatchKey.signalEvent from the JDK's own src.zip	12
MappedDemo	2 GiB classic map limit, Arena mapping, resident memory	13
Nio2BehaviourTest	12 assertions behind the claims above	14

01 records the environment (kernel, JDK, ulimit -n, inotify limit, free disk). Timings move with whatever else the machine is doing; counts, exceptions and GC figures do not.