Java NIO.2 Path and Files API: Build, Traverse, Read and Write (1Z0-831)

A java.nio.file.Path is an immutable object that holds a sequence of name elements, with an optional root, describing a location in a file system; creating one never touches the disk, so the file it names does not have to exist. You build one with Path.of(...) (Java 11+), the older Paths.get(...), or FileSystems.getDefault().getPath(...) — all three return an equal Path for the same arguments on the default file system.

• Varargs are joined with the separator: Path.of("music", "jazz", "live.flac") is music/jazz/live.flac on a Unix-style system. The result is absolute only if the joined string starts with a root, so this one is relative and isAbsolute() is false.
• Empty strings are skipped and redundant or trailing separators collapse: Path.of("/etc", "", "nginx/", "sites") is /etc/nginx/sites, with three name elements.
• The empty path — built from an empty string — is a special case: it has one (empty) name element rather than none, so its name count is not 0. It stands for the current directory when used to access a file.
• From a URI: Path.of(URI) needs an absolute, hierarchical URI such as file:///opt/app; a URI without a scheme throws IllegalArgumentException ("Missing scheme").
• Interop with the legacy API: file.toPath() and path.toFile() convert between java.io.File and Path.

toString() uses the platform separator (/ on Unix-style systems, \ on Windows), which is why output-based reasoning always assumes a particular style of file system. Every Path belongs to one FileSystem; mixing Paths from different providers (say a ZIP file system and the default one) in resolve, relativize or Files.copy throws ProviderMismatchException — a provider problem, not a path-shape problem.

Every Path is a root (or none) followed by zero-based name elements, and the root is not a name element. For /opt/shop/static/img/logo.png the root is /, the names are opt, shop, static, img, logo.png, and getNameCount() is 5.

Path p = Path.of("/opt/shop/static/img/logo.png");
p.getRoot();        // /
p.getFileName();    // logo.png  (last element, relative)
p.getParent();      // /opt/shop/static/img
p.getNameCount();   // 5
p.getName(0);       // opt  (index 0 is the first name, not the root)
p.subpath(2, 4);    // static/img  (relative, end-exclusive)

Missing components give null rather than an exception, so string concatenation of them prints null; calling a method on that null is what throws NullPointerException. Because the root is not a name, the root path on its own has a name count of 0. A Path is also Iterable<Path>: for (Path n : Path.of("/x/y")) visits x then y — the root is skipped there too. isAbsolute() reports whether the path has a root (on Unix).

base.resolve(other) appends a relative other to base, returns other itself when it is absolute, and returns base when other is empty. It is purely syntactic: it never checks the disk and never normalizes, so .. and . stay in the result.

Path base = Path.of("/home/kim");
base.resolve("notes/todo.md"); // /home/kim/notes/todo.md
base.resolve("/etc/motd");     // /etc/motd  (absolute wins)
base.resolve("../shared");     // /home/kim/../shared  (as is)

Path dump = Path.of("/backup/db.dump");
dump.resolveSibling("db.dump.old"); // /backup/db.dump.old
dump.resolve("db.dump.old");  // /backup/db.dump/db.dump.old

A trailing separator in the base, as in Path.of("/web/"), is dropped when the Path is built, so resolving css/site.css against it gives /web/css/site.css with a single separator. resolveSibling(x) resolves x against the parent — it is shorthand for getParent().resolve(x), the idiom for "same directory, different file name" — and, like resolve, returns x unchanged when it is absolute. Plain resolve on a path that names a file simply nests the argument beneath it, because a Path does not know whether it names a file or a directory.

relativize: the path between two paths

p.relativize(q) returns the relative path that, resolved against p, leads to q: it climbs from p up to the common ancestor with one .. per element, then descends to q. Both paths must be of the same type — both absolute or both relative.

Path from = Path.of("/home/kim/projects/web");
from.relativize(Path.of("/home/lee/music"));
// ../../../lee/music
Path.of("x/y").relativize(Path.of("x/y/z"));  // z
Path.of("x/y/z").relativize(Path.of("x"));    // ../..
Path.of("x/y").relativize(Path.of("x/y"));    // empty path

Path.of("reports").relativize(Path.of("/reports/q3"));
// IllegalArgumentException: 'other' is different type of Path

To relate an absolute and a relative path, convert the relative one first with toAbsolutePath(). Count the climbs carefully: from /home/kim/projects/web three steps (web, projects, kim) reach the common ancestor /home. The documented identity runs this way: for a normalized p and a relative q with no root, p.relativize(p.resolve(q)) equals q. The reverse trip does not give back an equal Path: from.resolve(from.relativize(target)) here is /home/kim/projects/web/../../../lee/music, which only reads as /home/lee/music after normalize() — and with symbolic links on the way even that is implementation-dependent. Like resolve, relativize works on the names alone and needs no file to exist.

The three methods differ in one crucial way — only toRealPath looks at the file system. normalize() removes . elements and cancels each name/.. pair as text; toAbsolutePath() prefixes the current working directory; toRealPath() resolves the path against the actual disk.

Path.of("/var/www/./cache/../html/index.php").normalize();
// /var/www/html/index.php
Path.of("a/b/../../../shared/x.txt").normalize();
// ../shared/x.txt   (the third .. has nothing to cancel)
Path.of("/../../tmp/x").normalize();
// /tmp/x            (nothing exists above the root)

Note the edge cases: in a relative path a leading .. that has nothing to cancel survives normalization, but directly after the root of an absolute path it is removed, because you cannot go above the root. And because toRealPath declares IOException, code that calls it must catch or declare it; for a missing file the exception arrives at the toRealPath call itself, so whatever the program printed before that statement — including anything computed with normalize or toAbsolutePath, which cannot fail — still appears first.

Path.equals, startsWith and endsWith compare roots and whole name elements, not characters, and none of them normalizes or checks the disk. The String overloads convert the argument to a Path first.

Path h = Path.of("/home/kim/music");
h.startsWith("/home/ki");    // false  (ki is not an element)
h.endsWith("kim/music");     // true   (last two elements)
h.endsWith("/music");        // false  (/music is absolute)

Path.of("x/y").equals(Path.of("x/./y"));  // false

The rules behind those results: an absolute argument to startsWith must match the root as well as the leading names, so a relative argument never matches an absolute path (and vice versa); an absolute argument to endsWith only matches the whole path, while a relative argument matches trailing whole elements. For a character prefix or suffix use p.toString().startsWith(...). To ask whether two different spellings name the same file, use Files.isSameFile (below) or compare normalized absolute paths.

Paths are immutable. resolve, resolveSibling, relativize, normalize, toAbsolutePath and subpath return a Path — sometimes the same object, for example toAbsolutePath on a path that is already absolute — and never modify the receiver. Calling one as a statement and discarding the result, as in q.toAbsolutePath();, leaves q exactly as it was. Assign the result: q = q.toAbsolutePath();.

The java.nio.file.Files class holds static methods that act on the file a Path names; the creation methods differ in whether they need the parent to exist and whether an existing target is an error.

All of them return the Path they created and throw checked IOException subtypes. createDirectories is idempotent for directories, so calling it twice on the same path succeeds. The legacy File.mkdir() signals failure by returning false rather than throwing, and mkdir (unlike mkdirs) does not create parents. The exceptions that matter here all live in java.nio.file and extend FileSystemException (an IOException); a similarly named class that concerns whole FileSystem instances, created with FileSystems.newFileSystem, plays no part in creating files.

Files.copy(source, target) and Files.move(source, target) treat target as the full path of the result — never as a directory to drop the file into — and both fail with FileAlreadyExistsException if the target exists, unless you pass StandardCopyOption.REPLACE_EXISTING.

Path photo = dir.resolve("img.png");
Path album = dir.resolve("album");     // an existing directory

Files.copy(photo, album);  // FileAlreadyExistsException
Files.copy(photo, album.resolve(photo.getFileName())); // works
Files.move(photo, dir.resolve("cover.png"));  // a rename

• Copying a directory is not recursive: Files.copy(srcDir, dst) creates an empty directory dst; the entries are not copied. Copy a tree by walking it and copying each entry.
• REPLACE_EXISTING replaces a regular file or an empty directory; replacing a non-empty directory throws DirectoryNotEmptyException.
• ATOMIC_MOVE asks for the move to happen as one file-system operation (or fail with AtomicMoveNotSupportedException); COPY_ATTRIBUTES and NOFOLLOW_LINKS are the other copy options.
• Stream overloads: Files.copy(InputStream, Path) and Files.copy(Path, OutputStream) bridge to the classic I/O streams covered in the console and file streams lesson.

Neither delete is recursive: empty a directory before deleting it (typically walking the tree and deleting in postVisitDirectory, or deleting a Files.walk stream in reverse order).

Files offers one-call methods for small files and streaming methods for large ones, The character-based methods use UTF-8 unless you pass a Charset; the byte-based ones (readAllBytes, write(p, bytes)) involve no charset at all.

readAllLines splits on line terminators, counts a final line even when it has no terminator, and does not add an empty element for a trailing one: "north\nsouth" and "north\nsouth\n" both give a two-element list. For a file too large to hold in memory, readAllLines and readString are ruled out, and a Files.lines stream used without try-with-resources leaves its file handle open — no terminal operation closes the stream. The correct shape is a lazy stream inside try-with-resources:

try (Stream<String> s = Files.lines(log)) {
    return s.anyMatch(line -> line.contains("timeout"));
}

Open options. With no options, the write methods use CREATE, TRUNCATE_EXISTING and WRITE. Once you pass any StandardOpenOption, CREATE and TRUNCATE_EXISTING are no longer implied — only those you list apply — but WRITE still is, because write and writeString always open the file for writing. Without truncation, writing starts at position 0 and overwrites only as many bytes as it writes:

Files.writeString(f, "12345");       // 12345  (defaults)
Files.writeString(f, "67", APPEND);  // 1234567
Files.writeString(f, "xy", WRITE);   // xy34567 — overwrites
                                     // the first two bytes
Files.writeString(f, "z", CREATE, TRUNCATE_EXISTING); // z

Other rules worth knowing: APPEND alone on a missing file throws NoSuchFileException (no CREATE); CREATE_NEW throws FileAlreadyExistsException if the file exists. The write methods return the Path, so Path f = Files.writeString(dir.resolve("a.txt"), "x"); is common. The reader and writer classes themselves (BufferedReader, PrintWriter, byte streams, Console) belong to the console and file streams topic.

Files.list returns one level of entries without the start directory; Files.walk returns every level, depth-first, starting with the start path itself; Files.find walks like walk but filters with a BiPredicate<Path, BasicFileAttributes>. All three are lazy streams holding open directory handles, so use them in try-with-resources, and their iteration order is not guaranteed — sort before relying on it.

For a tree holding root/notes.md, root/img/a.png, root/img/b.png and root/img/raw/c.dng, list(root) yields 2 entries (notes.md, img), walk(root) yields 7 (the root, notes.md, img, a.png, b.png, raw, c.dng) and walk(root, 1) yields 3 — the root plus the same entries list returns. A file two levels down is only reached when maxDepth is at least 2, and c.dng above needs 3.

Files.walkFileTree(start, visitor) drives a FileVisitor — usually a SimpleFileVisitor subclass overriding only what you need — calling preVisitDirectory before a directory's entries, visitFile for each non-directory, visitFileFailed when an entry cannot be read, and postVisitDirectory after the entries. Each callback returns a FileVisitResult:

The overload walkFileTree(start, Set<FileVisitOption>, maxDepth, visitor) limits depth, and a directory found exactly at maxDepth is reported through visitFile — not entered. In the tree above, walkFileTree(root, Set.of(), 1, visitor) passes both notes.md and the directory img to visitFile (its attributes report isDirectory() true), never calls preVisitDirectory for img, and never visits a.png, b.png or anything below. Symbolic links are not followed by walk, find or walkFileTree unless you pass FileVisitOption.FOLLOW_LINKS.

File properties come from Files, not from Path: exists, notExists, isDirectory, isRegularFile, isSymbolicLink, isReadable/isWritable/isExecutable, isHidden, size, getLastModifiedTime, and readAttributes(p, BasicFileAttributes.class) to read several at once in a single operation.

Path f = Files.writeString(dir.resolve("n.txt"), "naïve");
BasicFileAttributes a =
    Files.readAttributes(f, BasicFileAttributes.class);
a.size();             // 6 — bytes, and ï is 2 bytes in UTF-8
a.isRegularFile();    // true
a.lastModifiedTime(); // a FileTime

• Size is in bytes, so a non-ASCII character written as UTF-8 makes it larger than the character count.
• exists and notExists are not always opposites: if existence cannot be determined (for example, no permission), both return false. For a missing file, notExists returns true.
• Which methods throw for a missing file: exists, notExists, isDirectory, isRegularFile, isSymbolicLink, isReadable, isWritable and isExecutable never throw — they answer false (or true for notExists). isHidden is different: it declares IOException, and on Windows, where it reads the DOS hidden attribute, it throws for a missing file. size, getLastModifiedTime and readAttributes throw NoSuchFileException.
• Files.isSameFile(a, b) returns true immediately when the two Paths are equal, without checking the disk — so it is true even for a file that does not exist. For different spellings, such as Path.of("ghost.cfg") and Path.of("conf/../ghost.cfg"), it must look both files up, and it throws NoSuchFileException when they do not exist.
• Symbolic links are followed by default. Passing LinkOption.NOFOLLOW_LINKS asks about the link entry itself. For a link shortcut that points at a regular file, isRegularFile(shortcut) is true but isRegularFile(shortcut, NOFOLLOW_LINKS) is false, while exists(shortcut, NOFOLLOW_LINKS) is true; a link to a directory behaves the same way with isDirectory. isSymbolicLink never follows links, so it is true for the link and false for the file it points at. Files.createSymbolicLink(link, target) creates one.

View-specific attributes (PosixFileAttributes, DosFileAttributes) and Files.setLastModifiedTime/setAttribute extend the same model, but BasicFileAttributes is the portable set every file system supports.