Path and Files (NIO.2)

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Path

An object holding the name of a file or folder, like reports/2024/june.csv. It is only a name; the file may not exist.

Absolute path

A path that starts from the top of the file system, like /home/asha/notes.txt or C:\Users\asha\notes.txt.

Relative path

A path with no root, like data/orders.csv. Java resolves it against the working directory.

Working directory

The folder the program was started from. Path.of("").toAbsolutePath() shows it.

NIO.2

The java.nio.file package added in Java 7: Path, Files and related classes. NIO stands for "New I/O".

Open option

A flag that says how to open a file, such as APPEND or CREATE_NEW.

Atomic move

A rename that happens in one indivisible step, so nobody can ever see the file half-moved or half-written.

TOCTOU

"Time of check to time of use": a bug where something changes between checking a condition and acting on it.

Path traversal

An attack where input like ../../secret.txt makes a program reach files outside the folder it meant to use.

1. 1

   Predict normalize and relativize

   In "Path anatomy", add show(Path.of("a/b").relativize(Path.of("a/b/c/d"))) and show(Path.of("../x/./y/..").normalize()). Predict both results before you run. (A leading .. can't be removed, because there's no name before it.)

2. 2

   Attack your own guard

   In "Block path traversal", add the inputs "uploads/../uploads/ok.txt", "./././x" and "..". Predict ALLOW or REJECT for each, then run it.

3. 3

   Run the real-files example locally

   Save "Everyday Files operations" as Main.java, run java Main.java twice, and compare the output. Then delete the REPLACE_EXISTING option and run it again: which exception appears, and why only on the second run?

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   Before Java 7 there was only java.io.File, which mixed both jobs and had real problems: methods like delete() and mkdir() returned false without saying why, it had no support for symbolic links or file attributes, and listing a large directory loaded everything at once. NIO.2 (JSR 203, Java 7) added java.nio.file: Path, Paths, Files, FileSystem. Its methods throw specific exceptions such as NoSuchFileException, FileAlreadyExistsException, AccessDeniedException and DirectoryNotEmptyException, so you learn exactly what went wrong.

2. 2

   You create a Path with Path.of("data", "orders.csv") (Java 11; in Java 7 and 8 use Paths.get(...), which does the same). A path has a root (/ or C:\, or none for a relative path) and a list of name elements. Pure path methods work on the text only: getFileName(), getParent(), resolve("child") (join), resolveSibling, normalize() (remove . and name/..), relativize (the path from one to another), startsWith and toAbsolutePath(). A relative path is resolved against the current working directory, the folder the JVM was started in.

3. 3

   For small files, read and write in one call: Files.readString(path) and Files.writeString(path, text) (Java 11), Files.readAllLines(path) and Files.write(path, lines) (Java 7), Files.readAllBytes(path). They open, read or write, and close for you, and they use UTF-8 by default. They load the whole file into memory, so don't use them on a 5 GB log.

4. 4

   For big files, stream: Files.newBufferedReader(path) (Topic 12.2), or Files.lines(path) (Java 8), a lazy Stream<String>. Files.lines keeps the file open until the stream is closed, so it must be used in try-with-resources: try (Stream<String> lines = Files.lines(path)) { ... }. The same is true for Files.list and Files.walk, which stream a directory's entries and a whole folder tree.

5. 5

   Writes take open options (StandardOpenOption). The default for writeString/write/newBufferedWriter is CREATE, TRUNCATE_EXISTING, WRITE: create the file if needed and replace its content. Use APPEND to add to the end and CREATE_NEW to fail with FileAlreadyExistsException if it exists. Checking Files.exists(p) and then creating is a race: another process can create the file in between (a TOCTOU bug, time-of-check to time-of-use). Let the operation itself check, using CREATE_NEW or Files.createFile.

6. 6

   Files.copy, Files.move and Files.delete throw if something is in the way unless you pass options like REPLACE_EXISTING; deleteIfExists returns false instead of throwing. Files.move(tmp, target, ATOMIC_MOVE) renames in one step, so readers see the old file or the new one but never half a file: the standard atomic write pattern is "write to a temp file in the same folder, then atomically move it over the target". Paths built from user input must be checked against path traversal (../../etc/passwd): resolve, normalize, then confirm the result still startsWith your base folder.

• ↔

  readString/readAllLines are the simplest and fastest for small files but load everything into memory; streaming APIs scale to any size but need careful closing and more code.

• ↔

  Atomic write-then-rename protects readers and survives crashes, but costs an extra file, needs write permission on the folder, and changes the file's identity (inode), which breaks tools that hold the old file open, like tail -f without -F.

• ↔

  Relative paths make programs portable between machines but depend on the working directory, which differs between your IDE, a terminal and a service manager. Production code usually derives paths from configuration.

• Done when you can explain why creating a Path never touches the disk and which Files methods do.

• Done when you can use resolve, normalize, relativize and startsWith correctly, including the difference from String.startsWith.

• Done when you choose between whole-file methods and streaming methods based on file size.

• Done when every Files.lines/list/walk stream is in try-with-resources.

• Done when you can write a file atomically and block path traversal from user input.