bufferedreader: read a file line by line module (BufferedReader vs Scanner vs Files.lines vs readAllLines on a 1 GB file; heap at -Xmx64m, timings, read-call counts, one-huge-line OOM, charset/BOM/line-terminator pitfalls, Scanner swallowing IOException), 10 contract tests

Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_017ic4b3pDoGLiWk6LLBeHjW
2026-11-15 01:20:37 +05:30
parent 5faa57bb2d
commit f8c9e244a3
25 changed files with 809 additions and 0 deletions
@@ -0,0 +1,41 @@
+# bufferedreader
+
+Companion code for the ankurm.com post *"Java BufferedReader: Read a File Line by Line (vs Scanner, Files.lines and readAllLines)."*
+Module `bufferedreader` in `java-core-examples`. The explanation lives in the post; this module holds the runnable evidence and the captured output.
+
+## Versions
+
+| Component | Version |
+|---|---|
+| JDK | 25.0.5+8 (Temurin, LTS) |
+| JUnit Jupiter | 5.11.0 |
+| OS | Linux 6.18, 2 vCPU x86-64 VM (timings are indicative, not a leaderboard) |
+| Big file | 1,000,000,064 bytes, 9,623,347 ASCII log lines, generated then deleted by the script |
+
+## Quickstart
+
+```bash
+export JDK25_HOME=/path/to/jdk-25
+./scripts/run-all.sh                      # needs ~1.3 GB free in /tmp/bufferedreader-data and ~6 GB RAM; regenerates output/
+BIG_BYTES=200000000 ./scripts/run-all.sh  # smaller "big" file if disk or RAM is tight
+mvn -q -pl bufferedreader -am test        # 10 assertions, tiny files only
+```
+
+## What is in here
+
+| File | Shows | Output |
+|---|---|---|
+| `TestData` | deterministic generator: ~100-byte log lines, or one giant line with no newline | `02` |
+| `LineCount` | `BufferedReader`, `Scanner`, `Files.lines`, `Files.readAllLines` on the same file: which survive `-Xmx64m`, what `readAllLines` needs, time and GC | `03`, `04` |
+| `ReadCalls` | read calls that reach the underlying stream, and per-character vs `readLine()` time | `05` |
+| `LongLineDemo` | `readLine()` on one 200 MB line at `-Xmx128m` vs chunked `read(char[])` | `06` |
+| `CharsetDemo` | invalid UTF-8 through five readers, the JDK 18+ default charset, `-Dfile.encoding=COMPAT`, and a UTF-8 BOM | `07`, `08` |
+| `LineEndingsDemo` | `\n`, `\r\n`, `\r`, final newline, empty file: what counts as a line | `09` |
+| `ScannerSwallowsDemo` | a reader that fails mid-file: `BufferedReader` throws, `Scanner` looks like end of file | `10` |
+| `ReadLineContractTest` | 10 assertions behind the claims above | `11` |
+
+`01` records the environment. Timings move with whatever else the machine is doing; counts, exceptions, line totals and heap outcomes do not.
+
+## License
+
+MIT - see [LICENSE](../LICENSE).