File f = new File("/data/catalog.txt");
if (!f.delete()) {
    // Why? Did it not exist? Do I not have permission? Was it open?
    // Was it a non-empty directory? The API does not say.
}

File[] children = directory.listFiles();
for (File c : children) {       // NullPointerException if the directory does not exist
    // ...
}

// java.io: copying a file
try (InputStream in = new BufferedInputStream(new FileInputStream(source));
     OutputStream out = new BufferedOutputStream(new FileOutputStream(target))) {
    byte[] block = new byte[8192];
    int read;
    while ((read = in.read(block)) != -1) {
        out.write(block, 0, read);
    }
}

// NIO.2: the same thing
Files.copy(source, target, StandardCopyOption.REPLACE_EXISTING);

import java.nio.file.Path;
import java.nio.file.Paths;

public class BuildingPaths {

    public static void main(String[] args) {
        // Java 11+: the recommended form
        Path p1 = Path.of("data", "catalog.txt");

        // Java 7-10: equivalent, still very common in existing code
        Path p2 = Paths.get("data", "catalog.txt");

        // A complete path in one string
        Path p3 = Path.of("data/reports/2026/january.txt");

        // An absolute path
        Path p4 = Path.of("/home/marta/bibliotech/data/catalog.txt");

        // From a URI
        Path p5 = Path.of(java.net.URI.create("file:///home/marta/catalog.txt"));

        System.out.println(p1);              // data/catalog.txt
        System.out.println(p1.equals(p2));   // true
    }
}

import java.nio.file.Path;

public class QueryingPaths {

    public static void main(String[] args) {
        Path p = Path.of("/home/marta/bibliotech/data/catalog.txt");

        System.out.println("Full path      : " + p);
        System.out.println("Name           : " + p.getFileName());     // catalog.txt
        System.out.println("Directory      : " + p.getParent());       // .../data
        System.out.println("Root           : " + p.getRoot());         // /
        System.out.println("Absolute?      : " + p.isAbsolute());      // true
        System.out.println("Segments       : " + p.getNameCount());    // 5

        // Iterating the segments: Path is Iterable<Path>
        System.out.println("  Walk-through:");
        for (Path segment : p) {
            System.out.println("    " + segment);
        }

        // Access by index
        System.out.println("Segment 0      : " + p.getName(0));        // home
        System.out.println("Segment 3      : " + p.getName(3));        // data

        // Subpath [start, end)
        System.out.println("Subpath 1..3   : " + p.subpath(1, 3));     // marta/bibliotech

        // Checks
        System.out.println("Starts with /home?  " + p.startsWith("/home"));   // true
        System.out.println("Ends with .txt?     "
                + p.getFileName().toString().endsWith(".txt"));               // true
    }
}

Path p = Path.of("/home/marta/data");
p.startsWith("/home/mar");      // false: "mar" is not a complete segment
p.startsWith("/home/marta");    // true

Path base = Path.of("/home/marta/bibliotech");

base.resolve("data/catalog.txt");
// /home/marta/bibliotech/data/catalog.txt

base.resolve("/etc/config");
// /etc/config   <-- if the argument is ABSOLUTE, it replaces the base

base.resolve("");
// /home/marta/bibliotech

Path catalog = Path.of("/home/marta/bibliotech/data/catalog.txt");

catalog.resolveSibling("catalog.txt.tmp");
// /home/marta/bibliotech/data/catalog.txt.tmp

catalog.resolveSibling("catalog.bak");
// /home/marta/bibliotech/data/catalog.bak

Path base   = Path.of("/home/marta/bibliotech");
Path report = Path.of("/home/marta/bibliotech/data/reports/january.txt");

base.relativize(report);
// data/reports/january.txt

report.relativize(base);
// ../../..

Path ugly = Path.of("/home/marta/./bibliotech/../bibliotech/data/../data/catalog.txt");
ugly.normalize();
// /home/marta/bibliotech/data/catalog.txt

/**
 * Checks that a path requested by the user stays INSIDE the data
 * directory.
 *
 * Without this check, a name like "../../etc/passwd" would allow escaping
 * from the permitted directory. It is the vulnerability known as "path
 * traversal", and it is one of the most frequent in applications that accept
 * file names from the user. Application security is covered in 12-07.
 */
public static Path resolveSafely(Path baseDirectory, String requestedName) {
    Path base = baseDirectory.toAbsolutePath().normalize();
    Path candidate = base.resolve(requestedName).normalize();

    if (!candidate.startsWith(base)) {
        throw new IllegalArgumentException(
                "Path outside the permitted directory: " + requestedName);
    }
    return candidate;
}

import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.LinkOption;

Path p = Path.of("data/catalog.txt");

Files.exists(p);            // true if it exists and can be checked
Files.notExists(p);         // true if it does NOT exist and can be checked
Files.isRegularFile(p);     // an ordinary file (not a directory, not a link)
Files.isDirectory(p);
Files.isSymbolicLink(p);
Files.isReadable(p);
Files.isWritable(p);
Files.isExecutable(p);
Files.isHidden(p);          // throws IOException

// Without following symbolic links
Files.exists(p, LinkOption.NOFOLLOW_LINKS);

// An empty file. Throws FileAlreadyExistsException if it already exists.
Files.createFile(Path.of("data/new.txt"));

// A directory. Throws NoSuchFileException if the parent is missing.
Files.createDirectory(Path.of("data"));

// A directory AND ALL ITS PARENTS. It does not fail if they already exist.
Files.createDirectories(Path.of("data/reports/2026/january"));

// java.io (07-02)
File parent = target.getAbsoluteFile().getParentFile();
if (parent != null && !parent.exists() && !parent.mkdirs()) {
    throw new IOException("Could not create the directory " + parent.getAbsolutePath());
}

// NIO.2: one line, idempotent, and with an informative exception if it fails
Files.createDirectories(target.getParent());

// Deletes. Throws NoSuchFileException if it does not exist.
Files.delete(p);

// Deletes if it exists. Returns true if it deleted something. Does NOT throw if absent.
boolean deleted = Files.deleteIfExists(p);

// java.io: you know it failed, not why
if (!file.delete()) {
    System.err.println("Could not delete it");
}

// NIO.2: you know exactly what happened and can act accordingly
try {
    Files.delete(path);
} catch (NoSuchFileException e) {
    LOG.fine(() -> "It was already gone: " + path);       // not a problem
} catch (DirectoryNotEmptyException e) {
    LOG.warning(() -> "The directory has content: " + path);
} catch (AccessDeniedException e) {
    LOG.severe(() -> "No permission to delete " + path);  // this does need looking at
} catch (IOException e) {
    LOG.log(Level.SEVERE, "Failure deleting " + path, e);
}

import java.nio.file.StandardCopyOption;

// Copies. Throws FileAlreadyExistsException if the target exists.
Files.copy(source, target);

// Overwrites the target
Files.copy(source, target, StandardCopyOption.REPLACE_EXISTING);

// Keeps modification date, owner and permissions
Files.copy(source, target,
        StandardCopyOption.REPLACE_EXISTING,
        StandardCopyOption.COPY_ATTRIBUTES);

// From an InputStream to a file (07-03)
Files.copy(input, target, StandardCopyOption.REPLACE_EXISTING);

// From a file to an OutputStream
Files.copy(source, output);

// Moves or renames
Files.move(source, target);

// Overwriting the target
Files.move(source, target, StandardCopyOption.REPLACE_EXISTING);

// ATOMIC: either it is complete or it is not there. Never half done.
Files.move(temp, target,
        StandardCopyOption.REPLACE_EXISTING,
        StandardCopyOption.ATOMIC_MOVE);

// 07-02, with java.io: TWO operations, with a dangerous gap between them
if (target.exists() && !target.delete()) {      // 1. delete
    return false;
}
return temp.renameTo(target);                   // 2. rename
// Between 1 and 2, the target file DOES NOT EXIST. If the process dies there,
// you are left with nothing. And another process reading at that instant does
// not find the file.

// NIO.2: ONE atomic operation. There is no gap.
Files.move(temp, target, REPLACE_EXISTING, ATOMIC_MOVE);

package com.nexussoftware.bibliotech.infrastructure;

import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.logging.Logger;

/**
 * Atomic writing with NIO.2.
 *
 * It replaces the 07-02 version written with java.io. Same guarantee
 * —the target is never left half done— in a fraction of the code, and
 * with REAL atomicity instead of the delete-then-rename sequence.
 */
public final class AtomicWrite {

    private static final Logger LOG = Logger.getLogger(AtomicWrite.class.getName());

    private AtomicWrite() { }

    @FunctionalInterface
    public interface Content {
        void writeTo(BufferedWriter output) throws IOException;
    }

    public static void write(Path target, Content content) throws IOException {
        // 1. Create the directory if it is missing. Idempotent.
        Path directory = target.toAbsolutePath().getParent();
        Files.createDirectories(directory);

        // 2. The temporary file, IN THE SAME DIRECTORY: ATOMIC_MOVE demands it.
        //    resolveSibling does exactly this (section 3).
        Path temp = target.resolveSibling(target.getFileName() + ".tmp");

        boolean completed = false;
        try {
            // 3. Write everything to the temporary file. BufferedWriter, not
            //    PrintWriter: its methods DO throw IOException (07-04).
            try (BufferedWriter output = Files.newBufferedWriter(
                    temp, StandardCharsets.UTF_8,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE)) {

                content.writeTo(output);
            }

            // 4. Replace ATOMICALLY. A single operation.
            Files.move(temp, target,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);

            completed = true;
            LOG.fine(() -> "Atomic write completed: " + target);

        } catch (AtomicMoveNotSupportedException e) {
            // It can happen if the temporary file and the target are on
            // different file systems. It degrades to a non-atomic move, warning.
            LOG.warning(() -> "The file system does not support ATOMIC_MOVE; "
                    + "replacing non-atomically: " + target);
            Files.move(temp, target, StandardCopyOption.REPLACE_EXISTING);
            completed = true;

        } finally {
            // 5. Compensation (06-05): no rubbish if something failed.
            if (!completed) {
                Files.deleteIfExists(temp);           // does not throw if already gone
            }
        }
    }
}

import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

Path p = Path.of("data/catalog.txt");

// Java 11+: the whole file as a String
String everything = Files.readString(p, StandardCharsets.UTF_8);

// All the lines in a list
List<String> lines = Files.readAllLines(p, StandardCharsets.UTF_8);

// All the bytes (for binary)
byte[] bytes = Files.readAllBytes(p);

// A ready-built BufferedReader (07-04)
try (java.io.BufferedReader reader =
             Files.newBufferedReader(p, StandardCharsets.UTF_8)) {
    String line;
    while ((line = reader.readLine()) != null) {
        process(line);
    }
}

// An InputStream (07-03)
try (java.io.InputStream input = Files.newInputStream(p)) {
    // ...
}

// Java 11+: writing a string
Files.writeString(p, "content", StandardCharsets.UTF_8);

// Appending at the end
Files.writeString(p, "one more line\n", StandardCharsets.UTF_8,
        StandardOpenOption.CREATE, StandardOpenOption.APPEND);

// Writing a collection of lines (it adds the break to each one)
Files.write(p, lines, StandardCharsets.UTF_8);

// Writing bytes
Files.write(p, bytes);

// A ready-built BufferedWriter
try (java.io.BufferedWriter output =
             Files.newBufferedWriter(p, StandardCharsets.UTF_8)) {
    output.write("...");
    output.newLine();
}

// 07-02, with java.io
try (PrintWriter output = new PrintWriter(
        new BufferedWriter(new FileWriter(path, StandardCharsets.UTF_8)))) {
    for (String line : lines) {
        output.println(line);
    }
    if (output.checkError()) {
        throw new IOException("Failed to write");
    }
}

// NIO.2
Files.write(Path.of(path), lines, StandardCharsets.UTF_8);

// OVERWRITE: create if missing, empty if it exists
Files.newBufferedWriter(p, UTF_8,
        StandardOpenOption.CREATE,
        StandardOpenOption.TRUNCATE_EXISTING,
        StandardOpenOption.WRITE);

// APPEND: create if missing, write at the end
Files.newBufferedWriter(p, UTF_8,
        StandardOpenOption.CREATE,
        StandardOpenOption.APPEND);

// CREATE NEW: fail if it already exists. Useful as a lock (07-02)
Files.newBufferedWriter(p, UTF_8,
        StandardOpenOption.CREATE_NEW,
        StandardOpenOption.WRITE);

import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.stream.Stream;

public class ReadWithLines {

    public static void show(Path file) throws IOException {
        // try-with-resources COMPULSORY: the stream keeps the file open
        try (Stream<String> lines = Files.lines(file, StandardCharsets.UTF_8)) {

            // forEach: processes each line. The complete API, in 10-04.
            lines.forEach(System.out::println);
        }
    }
}

public static void count(Path file) throws IOException {
    // The counters have to be effectively final to be used in a lambda
    // (04-05). A one-element array is the classic trick; in 10-04 you
    // will see better ways.
    int[] counters = new int[2];        // [0] = lines, [1] = with data

    try (Stream<String> lines = Files.lines(file, StandardCharsets.UTF_8)) {
        lines.forEach(line -> {
            counters[0]++;
            if (!line.isBlank() && !line.startsWith("#")) {
                counters[1]++;
            }
        });
    }
    System.out.printf("%d lines, %d with data%n", counters[0], counters[1]);
}

public static void list(Path directory) throws IOException {
    try (Stream<Path> children = Files.list(directory)) {
        children.forEach(child -> System.out.println("  " + child.getFileName()));
    }
}

public static void walk(Path root) throws IOException {
    try (Stream<Path> tree = Files.walk(root)) {
        tree.forEach(p -> System.out.println("  " + p));
    }
}

/** Limiting the depth. */
public static void walkTo(Path root, int depth) throws IOException {
    try (Stream<Path> tree = Files.walk(root, depth)) {
        tree.forEach(System.out::println);
    }
}

/** Locates all the reports in a directory tree. */
public static void locateReports(Path root) throws IOException {
    try (Stream<Path> tree = Files.walk(root)) {
        tree.forEach(p -> {
            if (Files.isRegularFile(p) && p.getFileName().toString().endsWith(".report")) {
                System.out.println("  " + root.relativize(p));
            }
        });
    }
}

package com.nexussoftware.bibliotech.util;

import java.io.IOException;
import java.nio.file.*;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.logging.Logger;

/**
 * Tree walking with complete control, using walkFileTree.
 *
 * A decisive advantage over Files.walk: it can DECIDE what to do with each
 * element and each failure, instead of aborting the whole walk when a
 * single directory is not accessible.
 */
public class ControlledWalk {

    private static final Logger LOG = Logger.getLogger(ControlledWalk.class.getName());

    /** Computes the total size of a tree, skipping what is inaccessible. */
    public static Result calculateSize(Path root) throws IOException {
        Result result = new Result();

        Files.walkFileTree(root, new SimpleFileVisitor<Path>() {

            /** Before entering a directory. */
            @Override
            public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
                // Skip hidden and working directories without entering them
                String name = dir.getFileName().toString();
                if (name.startsWith(".") || name.equals("tmp")) {
                    return FileVisitResult.SKIP_SUBTREE;
                }
                result.directories++;
                return FileVisitResult.CONTINUE;
            }

            /** For each file. */
            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
                result.files++;
                result.bytes += attrs.size();

                if (attrs.size() > result.largestSize) {
                    result.largestSize = attrs.size();
                    result.largestFile = file;
                }
                return FileVisitResult.CONTINUE;
            }

            /**
             * When a file or directory CANNOT be visited.
             *
             * THIS is the method that makes walkFileTree superior: by
             * returning CONTINUE, the walk CARRIES ON. With Files.walk, a
             * single directory without permissions aborts everything.
             */
            @Override
            public FileVisitResult visitFileFailed(Path file, IOException e) {
                result.inaccessible++;
                LOG.fine(() -> "Not accessible: " + file + " (" + e.getMessage() + ")");
                return FileVisitResult.CONTINUE;
            }

            /** On leaving a directory, after visiting all its content. */
            @Override
            public FileVisitResult postVisitDirectory(Path dir, IOException e) {
                return FileVisitResult.CONTINUE;
            }
        });

        return result;
    }

    public static class Result {
        int directories = 0;
        int files = 0;
        int inaccessible = 0;
        long bytes = 0;
        long largestSize = 0;
        Path largestFile = null;

        public String report() {
            return String.format(
                    "%d directories, %d files, %.2f MB, %d inaccessible.%n"
                            + "  Largest: %s (%.2f MB)",
                    directories, files, bytes / 1024.0 / 1024.0, inaccessible,
                    largestFile == null ? "(none)" : largestFile.getFileName(),
                    largestSize / 1024.0 / 1024.0);
        }
    }
}

/** Deletes a directory and all its content. USE WITH GREAT CARE. */
public static void deleteTree(Path root) throws IOException {
    if (Files.notExists(root)) {
        return;
    }
    Files.walkFileTree(root, new SimpleFileVisitor<Path>() {

        @Override
        public FileVisitResult visitFile(Path f, BasicFileAttributes attrs)
                throws IOException {
            Files.delete(f);
            return FileVisitResult.CONTINUE;
        }

        /**
         * The directory is deleted AFTER its content: that is why it goes in
         * postVisitDirectory and not in pre. The other way round, Files.delete
         * would throw DirectoryNotEmptyException.
         */
        @Override
        public FileVisitResult postVisitDirectory(Path dir, IOException e)
                throws IOException {
            if (e != null) {
                throw e;                  // do not delete if the walk failed
            }
            Files.delete(dir);
            return FileVisitResult.CONTINUE;
        }
    });
}

import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.attribute.BasicFileAttributes;
import java.nio.file.attribute.FileTime;

Path p = Path.of("data/catalog.txt");

// One at a time: each call queries the file system
long size = Files.size(p);
FileTime modified = Files.getLastModifiedTime(p);

// ALL AT ONCE: a single query. More efficient and CONSISTENT.
BasicFileAttributes attrs = Files.readAttributes(p, BasicFileAttributes.class);

System.out.println("Size          : " + attrs.size());
System.out.println("Created       : " + attrs.creationTime());
System.out.println("Modified      : " + attrs.lastModifiedTime());
System.out.println("Last access   : " + attrs.lastAccessTime());
System.out.println("File?         : " + attrs.isRegularFile());
System.out.println("Directory?    : " + attrs.isDirectory());
System.out.println("Link?         : " + attrs.isSymbolicLink());

FileTime moment = Files.getLastModifiedTime(p);

System.out.println(moment);               // 2026-08-05T14:23:11.482Z
System.out.println(moment.toMillis());    // 1785943391482

// Comparing two files
FileTime a = Files.getLastModifiedTime(pathA);
FileTime b = Files.getLastModifiedTime(pathB);
if (a.compareTo(b) > 0) {
    System.out.println("A is more recent than B");
}

// Age in days, with millisecond arithmetic
long ageInDays = (System.currentTimeMillis() - moment.toMillis())
        / (1000L * 60 * 60 * 24);

// Changing the modification date
Files.setLastModifiedTime(p, FileTime.fromMillis(System.currentTimeMillis()));

import java.nio.file.attribute.PosixFilePermission;
import java.nio.file.attribute.PosixFilePermissions;
import java.util.Set;

try {
    Set<PosixFilePermission> permissions = Files.getPosixFilePermissions(p);
    System.out.println(PosixFilePermissions.toString(permissions));   // rw-r--r--

    // Setting permissions: only the owner can read and write
    Files.setPosixFilePermissions(p,
            PosixFilePermissions.fromString("rw-------"));

} catch (UnsupportedOperationException e) {
    // On Windows the POSIX model does not exist: ACLs must be used
    LOG.fine("System without POSIX permissions");
}

// Create the file ALREADY with restricted permissions, in one operation
Files.createFile(p, PosixFilePermissions.asFileAttribute(
        PosixFilePermissions.fromString("rw-------")));

// A temporary file in the system temporary directory
Path temp = Files.createTempFile("bibliotech-", ".tmp");

// In a particular directory: necessary if you are then going to ATOMIC_MOVE
Path localTemp = Files.createTempFile(Path.of("data"), "catalog-", ".tmp");

// A temporary directory
Path tempDir = Files.createTempDirectory("bibliotech-import-");

Path temp = Files.createTempFile("bibliotech-", ".tmp");

try (var output = Files.newBufferedWriter(temp, StandardCharsets.UTF_8,
        StandardOpenOption.WRITE,
        StandardOpenOption.DELETE_ON_CLOSE)) {    // deleted on closing

    output.write("working data");
}
// Here the file NO LONGER EXISTS

import java.nio.file.*;

/**
 * Watching a directory.
 *
 * NOTE: this loop is BLOCKING. In a real application it runs in a separate
 * thread, and that is module 8. Here it stands as a demonstration of the
 * mechanism, not as code you would put in your main.
 */
public static void watch(Path directory) throws IOException, InterruptedException {

    try (WatchService watcher = FileSystems.getDefault().newWatchService()) {

        directory.register(watcher,
                StandardWatchEventKinds.ENTRY_CREATE,
                StandardWatchEventKinds.ENTRY_MODIFY,
                StandardWatchEventKinds.ENTRY_DELETE);

        System.out.println("Watching " + directory + "...");

        while (true) {
            WatchKey key = watcher.take();           // BLOCKS until something happens

            for (WatchEvent<?> event : key.pollEvents()) {
                System.out.printf("  %s: %s%n", event.kind().name(), event.context());
            }

            if (!key.reset()) {                      // the directory no longer exists
                break;
            }
        }
    }
}

// From File to Path
File f = new File("data/catalog.txt");
Path p = f.toPath();

// From Path to File
Path p2 = Path.of("data/catalog.txt");
File f2 = p2.toFile();

package com.nexussoftware.bibliotech.infrastructure;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.nio.file.attribute.BasicFileAttributes;
import java.nio.file.attribute.FileTime;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Objects;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.stream.Stream;

/**
 * BiblioTech's persistence layer on NIO.2.
 *
 * It replaces all the java.io code from 07-01 to 07-05:
 *   - directory creation      -> Files.createDirectories
 *   - atomic writing          -> Files.move with ATOMIC_MOVE
 *   - rotating backups        -> Files.move and Files.deleteIfExists
 *   - locating reports        -> Files.walk
 *   - failures                -> specific exceptions, not mute booleans
 *
 * The directory structure it manages:
 *   data/
 *     catalog.txt
 *     audit.txt
 *     backups/
 *       catalog.bak.1  (the most recent)
 *       catalog.bak.2
 *       catalog.bak.3
 *     reports/
 *       2026/
 *         01/ *.report
 *     sessions/
 */
public class BiblioTechStore {

    private static final Logger LOG = Logger.getLogger(BiblioTechStore.class.getName());

    private static final java.nio.charset.Charset CHARSET = StandardCharsets.UTF_8;

    private static final String CATALOG    = "catalog.txt";
    private static final String AUDIT      = "audit.txt";
    private static final String REPORT_EXT = ".report";

    private static final int BACKUPS_KEPT = 3;

    private final Path root;
    private final Path backups;
    private final Path reports;
    private final Path sessions;

    /**
     * Prepares the directory structure.
     *
     * createDirectories is IDEMPOTENT: if they exist, it does nothing and does
     * not fail. That is the end of "if (!exists) create" with its mute boolean.
     */
    public BiblioTechStore(String rootDirectory) throws IOException {
        this.root = Path.of(Objects.requireNonNull(rootDirectory,
                "The directory cannot be null")).toAbsolutePath().normalize();

        this.backups  = root.resolve("backups");
        this.reports  = root.resolve("reports");
        this.sessions = root.resolve("sessions");

        Files.createDirectories(backups);
        Files.createDirectories(reports);
        Files.createDirectories(sessions);

        LOG.config(() -> "BiblioTech store prepared at " + root);
    }

    // ---------------------- ATOMIC WRITING ----------------------

    @FunctionalInterface
    public interface Content {
        void writeTo(BufferedWriter output) throws IOException;
    }

    /**
     * Writes a file atomically, after making a backup.
     *
     * Sequence:
     *   1. rotate the existing backups
     *   2. copy the current file to backups/name.bak.1
     *   3. write the new content to a temporary SIBLING of the target
     *   4. move it over the target with ATOMIC_MOVE
     */
    public void writeWithBackup(String name, Content content) throws IOException {
        Path target = root.resolve(name);

        // 1 and 2: rotating backup
        if (Files.exists(target)) {
            rotateBackups(name);
            Files.copy(target, backups.resolve(name + ".bak.1"),
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.COPY_ATTRIBUTES);
        }

        // 3: a SIBLING temporary file. ATOMIC_MOVE demands the same file system.
        Path temp = target.resolveSibling(target.getFileName() + ".tmp");
        boolean completed = false;

        try {
            try (BufferedWriter output = Files.newBufferedWriter(temp, CHARSET,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE)) {

                content.writeTo(output);
            }

            // 4: a genuinely atomic replacement
            Files.move(temp, target,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            completed = true;

            LOG.info(() -> String.format("Written %s (%d bytes)",
                    target.getFileName(), safeSize(target)));

        } catch (AtomicMoveNotSupportedException e) {
            LOG.warning(() -> "No ATOMIC_MOVE support; non-atomic replacement");
            Files.move(temp, target, StandardCopyOption.REPLACE_EXISTING);
            completed = true;

        } finally {
            if (!completed) {
                Files.deleteIfExists(temp);          // compensation (06-05)
            }
        }
    }

    /**
     * Backup rotation: .bak.2 becomes .bak.3, .bak.1 becomes .bak.2, and the
     * oldest one is lost.
     *
     * From HIGHEST to LOWEST, as in 07-02: the other way round, each rename
     * would crush the next backup before it had been shifted.
     */
    private void rotateBackups(String name) throws IOException {
        Files.deleteIfExists(backups.resolve(name + ".bak." + BACKUPS_KEPT));

        for (int i = BACKUPS_KEPT - 1; i >= 1; i--) {
            Path source = backups.resolve(name + ".bak." + i);
            Path target = backups.resolve(name + ".bak." + (i + 1));

            if (Files.exists(source)) {
                Files.move(source, target, StandardCopyOption.REPLACE_EXISTING);
            }
        }
    }

    // ---------------------- READING ----------------------

    /**
     * Reads the catalogue line by line, with constant memory.
     *
     * Files.newBufferedReader returns the BufferedReader of 07-04, with a
     * mandatory charset and a specific exception if the file is missing.
     */
    public List<String> readCatalog() throws IOException {
        Path file = root.resolve(CATALOG);
        List<String> lines = new ArrayList<>();

        if (Files.notExists(file)) {
            // GRACEFUL DEGRADATION (06-07, 07-01): the first run has no
            // catalogue, and that is normal, not a failure.
            LOG.warning(() -> "There is no catalogue at " + file
                    + "; starting with an empty catalogue");
            return lines;
        }

        try (BufferedReader reader = Files.newBufferedReader(file, CHARSET)) {
            String line;
            while ((line = reader.readLine()) != null) {       // canonical loop (07-04)
                String clean = line.trim();
                if (!clean.isEmpty() && !clean.startsWith("#")) {
                    lines.add(clean);
                }
            }
        }

        LOG.info(() -> "Catalogue read: " + lines.size() + " lines from " + file);
        return lines;
    }

    /** Appends a line to the audit log. Explicit APPEND: the file GROWS. */
    public void audit(String line) {
        Path file = root.resolve(AUDIT);

        try (BufferedWriter output = Files.newBufferedWriter(file, CHARSET,
                StandardOpenOption.CREATE,
                StandardOpenOption.APPEND)) {          // impossible to confuse

            output.write(line);
            output.write('\n');                        // data file: fixed '\n'

        } catch (IOException e) {
            // The audit does not bring down the business operation (07-02)
            LOG.log(Level.WARNING, "Could not audit: " + line, e);
        }
    }

    // ---------------------- REPORTS ----------------------

    /** Saves a report in reports/YYYY/MM/name.report. */
    public Path saveReport(String year, String month, String name, String content)
            throws IOException {

        Path directory = reports.resolve(year).resolve(month);
        Files.createDirectories(directory);

        Path file = directory.resolve(name + REPORT_EXT);
        Files.writeString(file, content, CHARSET,
                StandardOpenOption.CREATE,
                StandardOpenOption.TRUNCATE_EXISTING,
                StandardOpenOption.WRITE);

        LOG.info(() -> "Report saved: " + root.relativize(file));
        return file;
    }

    /**
     * Locates all the reports in the tree, sorted from the most recent to the
     * oldest.
     *
     * Files.walk returns a LAZY stream that MUST BE CLOSED: it keeps directory
     * descriptors open. Hence the try-with-resources.
     * Only forEach is used; the complete Streams API is 10-04.
     */
    public List<ReportInfo> locateReports() throws IOException {
        List<ReportInfo> found = new ArrayList<>();

        try (Stream<Path> tree = Files.walk(reports)) {
            tree.forEach(p -> {
                if (!Files.isRegularFile(p)
                        || !p.getFileName().toString().endsWith(REPORT_EXT)) {
                    return;
                }
                try {
                    // readAttributes: ONE query for all the attributes,
                    // instead of three independent calls (section 10)
                    BasicFileAttributes attrs =
                            Files.readAttributes(p, BasicFileAttributes.class);

                    found.add(new ReportInfo(
                            reports.relativize(p).toString(),
                            attrs.size(),
                            attrs.lastModifiedTime()));

                } catch (IOException e) {
                    LOG.fine(() -> "Could not read the attributes of " + p);
                }
            });
        }

        // Most recent first (05-09)
        found.sort(Comparator.comparing(ReportInfo::modified).reversed());
        return found;
    }

    /**
     * Information about a located report.
     *
     * FileTime is shown with toString() and compared with compareTo().
     * Converting it into readable dates is java.time, which is 10-05.
     */
    public record ReportInfo(String relativePath, long bytes, FileTime modified) {

        public String line() {
            return String.format("%-40s %8d bytes  %s",
                    relativePath, bytes, modified);
        }

        /** Age in days, with millisecond arithmetic (10-05 will do it better). */
        public long ageInDays() {
            return (System.currentTimeMillis() - modified.toMillis())
                    / (1000L * 60 * 60 * 24);
        }
    }

    // ---------------------- MAINTENANCE ----------------------

    /**
     * Deletes the reports older than N days.
     *
     * @return how many were deleted
     */
    public int cleanOldReports(int maxDays) throws IOException {
        int deleted = 0;

        for (ReportInfo info : locateReports()) {
            if (info.ageInDays() > maxDays) {
                Path file = reports.resolve(info.relativePath());
                if (Files.deleteIfExists(file)) {
                    deleted++;
                    LOG.fine(() -> "Old report deleted: " + info.relativePath());
                }
            }
        }

        final int total = deleted;
        LOG.info(() -> "Clean-up: " + total + " reports older than "
                + maxDays + " days");
        return deleted;
    }

    /** Summary of the space used, with walkFileTree so a failure does not abort it. */
    public String spaceReport() throws IOException {
        long[] data = new long[2];       // [0] bytes, [1] files

        Files.walkFileTree(root, new SimpleFileVisitor<Path>() {
            @Override
            public FileVisitResult visitFile(Path f, BasicFileAttributes attrs) {
                data[0] += attrs.size();
                data[1]++;
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult visitFileFailed(Path f, IOException e) {
                LOG.fine(() -> "Not accessible: " + f);
                return FileVisitResult.CONTINUE;      // does not abort the walk
            }
        });

        return String.format("%s: %d files, %.2f MB",
                root.getFileName(), data[1], data[0] / 1024.0 / 1024.0);
    }

    private long safeSize(Path p) {
        try {
            return Files.size(p);
        } catch (IOException e) {
            return -1;
        }
    }

    public Path getRoot()     { return root; }
    public Path getSessions() { return sessions; }
}

package com.nexussoftware.bibliotech.presentation;

import java.io.IOException;
import com.nexussoftware.bibliotech.infrastructure.BiblioTechStore;

public class StoreDemo {

    public static void main(String[] args) throws IOException {
        BiblioTechStore store = new BiblioTechStore("data");

        // 1. Write the catalogue with a backup and atomicity
        store.writeWithBackup("catalog.txt", output -> {
            output.write("# BiblioTech catalogue - Nexus Software");
            output.newLine();
            output.write("BOOK;978-0000000001;Effective Java;Bloch;2018");
            output.newLine();
            output.write("BOOK;978-0000000002;Design Patterns;Gamma;1994");
            output.newLine();
            output.write("BOOK;978-0000000003;Refactoring;Fowler;1999");
            output.newLine();
        });

        // 2. Read
        System.out.println("=== CATALOGUE ===");
        for (String line : store.readCatalog()) {
            System.out.println("  " + line);
        }

        // 3. Audit (APPEND mode)
        store.audit("LOAN;LN-0001;978-0000000001;EMP-001");
        store.audit("RETURN;LN-0001;978-0000000001;EMP-001");

        // 4. Reports in a directory tree
        store.saveReport("2026", "01", "fines-january", "Total: 142.50 EUR");
        store.saveReport("2026", "02", "fines-february", "Total: 98.25 EUR");
        store.saveReport("2026", "08", "fines-august", "Total: 210.00 EUR");

        System.out.println();
        System.out.println("=== REPORTS LOCATED ===");
        for (BiblioTechStore.ReportInfo info : store.locateReports()) {
            System.out.println("  " + info.line());
        }

        // 5. Space used
        System.out.println();
        System.out.println("=== SPACE ===");
        System.out.println("  " + store.spaceReport());
    }
}

=== CATALOGUE ===
  BOOK;978-0000000001;Effective Java;Bloch;2018
  BOOK;978-0000000002;Design Patterns;Gamma;1994
  BOOK;978-0000000003;Refactoring;Fowler;1999

=== REPORTS LOCATED ===
  2026/08/fines-august.report                    17 bytes  2026-08-05T09:14:22.331Z
  2026/02/fines-february.report                  16 bytes  2026-08-05T09:14:22.329Z
  2026/01/fines-january.report                   17 bytes  2026-08-05T09:14:22.327Z

=== SPACE ===
  data: 9 files, 0.01 MB

package com.nexussoftware.bibliotech.util;

import java.io.IOException;
import java.nio.file.*;
import java.nio.file.attribute.BasicFileAttributes;
import java.nio.file.attribute.PosixFilePermissions;

/**
 * Complete report of a path using NIO.2 only.
 *
 * It replaces the PathDiagnostic of 07-01, which used java.io: here every
 * failure says WHY, instead of returning a mute boolean.
 */
public class PathExplorer {

    public static void analyse(String path) {
        Path p = Path.of(path);

        System.out.println("========================================");
        System.out.println("ANALYSIS OF: " + path);
        System.out.println("========================================");

        // ---- 1. Forms of the path ----
        System.out.println("  As given        : " + p);
        System.out.println("  Absolute        : " + p.toAbsolutePath());
        System.out.println("  Normalised      : " + p.toAbsolutePath().normalize());

        try {
            // toRealPath DOES consult the disk and resolves symbolic links
            System.out.println("  Real            : " + p.toRealPath());
        } catch (NoSuchFileException e) {
            System.out.println("  Real            : (does not exist, cannot be resolved)");
        } catch (IOException e) {
            System.out.println("  Real            : (error: " + e.getMessage() + ")");
        }

        // ---- 2. Structure ----
        System.out.println("  Name            : " + p.getFileName());
        System.out.println("  Parent          : " + p.getParent());
        System.out.println("  Root            : " + p.getRoot());
        System.out.println("  Absolute?       : " + p.isAbsolute());
        System.out.println("  Segments        : " + p.getNameCount());

        StringBuilder segments = new StringBuilder();
        for (Path s : p) {                       // Path is Iterable<Path>
            segments.append('[').append(s).append(']');
        }
        System.out.println("  Walk-through    : " + segments);

        // ---- 5. exists / notExists ----
        boolean exists = Files.exists(p);
        boolean notExists = Files.notExists(p);

        System.out.println("  ----");
        System.out.println("  exists()        : " + exists);
        System.out.println("  notExists()     : " + notExists);
        System.out.println("  Interpretation  : " + interpret(exists, notExists));

        if (!exists) {
            System.out.println();
            return;
        }

        // ---- 3. Attributes: a SINGLE query ----
        try {
            BasicFileAttributes attrs = Files.readAttributes(p, BasicFileAttributes.class);

            System.out.println("  ----");
            System.out.println("  Type            : " + type(attrs));
            System.out.println("  Size            : " + attrs.size() + " bytes");
            System.out.println("  Created         : " + attrs.creationTime());
            System.out.println("  Modified        : " + attrs.lastModifiedTime());
            System.out.println("  Last access     : " + attrs.lastAccessTime());
            System.out.println("  Readable?       : " + Files.isReadable(p));
            System.out.println("  Writable?       : " + Files.isWritable(p));

            // ---- 4. Age ----
            long days = (System.currentTimeMillis() - attrs.lastModifiedTime().toMillis())
                    / (1000L * 60 * 60 * 24);
            System.out.println("  Age             : " + days + " days");

            // POSIX permissions if the system has them
            try {
                System.out.println("  POSIX perms     : " + PosixFilePermissions.toString(
                        Files.getPosixFilePermissions(p)));
            } catch (UnsupportedOperationException e) {
                System.out.println("  POSIX perms     : (system without support, e.g. Windows)");
            }

        } catch (IOException e) {
            System.out.println("  ERROR reading attributes: " + e.getMessage());
        }

        System.out.println();
    }

    private static String type(BasicFileAttributes a) {
        if (a.isDirectory())     { return "directory"; }
        if (a.isRegularFile())   { return "file"; }
        if (a.isSymbolicLink())  { return "symbolic link"; }
        return "other";
    }

    /** The THREE possible states, not two. */
    private static String interpret(boolean exists, boolean notExists) {
        if (exists && !notExists) {
            return "EXISTS, and it could be checked";
        }
        if (!exists && notExists) {
            return "DOES NOT EXIST, and it could be checked";
        }
        if (!exists && !notExists) {
            return "CANNOT BE DETERMINED (probably no permission on the "
                    + "directory containing it). That is why !exists() does NOT "
                    + "mean 'it does not exist'.";
        }
        return "impossible state";
    }

    public static void main(String[] args) {
        analyse("data/catalog.txt");
        analyse("data");
        analyse("data/does-not-exist.txt");
        analyse("data/../data/./reports/../catalog.txt");   // unnormalised
    }
}

========================================
ANALYSIS OF: data/../data/./reports/../catalog.txt
========================================
  As given        : data/../data/./reports/../catalog.txt
  Absolute        : /home/marta/bibliotech/data/../data/./reports/../catalog.txt
  Normalised      : /home/marta/bibliotech/data/catalog.txt
  Real            : /home/marta/bibliotech/data/catalog.txt
  Name            : catalog.txt
  Segments        : 7
  Walk-through    : [data][..][data][.][reports][..][catalog.txt]
  ----
  exists()        : true
  notExists()     : false
  Interpretation  : EXISTS, and it could be checked

package com.nexussoftware.bibliotech.util;

import java.io.IOException;
import java.nio.file.*;
import java.nio.file.attribute.BasicFileAttributes;
import java.nio.file.attribute.FileTime;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.logging.Logger;

/**
 * Synchronises a target directory with a source, copying only what is needed.
 *
 * It is the core of any incremental backup tool: not copying what is already
 * the same saves most of the work.
 */
public class DirectorySynchroniser {

    private static final Logger LOG =
            Logger.getLogger(DirectorySynchroniser.class.getName());

    public record Result(int copied, int updated, int unchanged,
                         int onlyInTarget, int errors,
                         List<String> onlyInTargetDetail) {

        public String report() {
            StringBuilder sb = new StringBuilder();
            sb.append("=== SYNCHRONISATION ===\n");
            sb.append(String.format("  Copied (new)      : %d%n", copied));
            sb.append(String.format("  Updated           : %d%n", updated));
            sb.append(String.format("  Unchanged         : %d%n", unchanged));
            sb.append(String.format("  Only in target    : %d%n", onlyInTarget));
            sb.append(String.format("  Errors            : %d%n", errors));

            if (!onlyInTargetDetail.isEmpty()) {
                sb.append("  --- Only in target (candidates for deletion) ---\n");
                int n = Math.min(10, onlyInTargetDetail.size());
                for (int i = 0; i < n; i++) {
                    sb.append("    ").append(onlyInTargetDetail.get(i)).append('\n');
                }
                if (onlyInTargetDetail.size() > n) {
                    sb.append(String.format("    ... and %d more%n",
                            onlyInTargetDetail.size() - n));
                }
            }
            return sb.toString();
        }
    }

    /** Synchronises source into target. It NEVER deletes anything in the target. */
    public Result synchronise(Path source, Path target) throws IOException {
        Path sourceRoot = source.toAbsolutePath().normalize();
        Path targetRoot = target.toAbsolutePath().normalize();

        if (!Files.isDirectory(sourceRoot)) {
            throw new NotDirectoryException(sourceRoot.toString());
        }
        Files.createDirectories(targetRoot);

        int[] counters = new int[4];          // copied, updated, same, errors
        Set<Path> seenInSource = new HashSet<>();

        // ---- PHASE 1: walk the source and synchronise ----
        Files.walkFileTree(sourceRoot, new SimpleFileVisitor<Path>() {

            @Override
            public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs)
                    throws IOException {

                // relativize gives the equivalent path in the target (section 3)
                Path equivalent = targetRoot.resolve(sourceRoot.relativize(dir));
                Files.createDirectories(equivalent);        // idempotent
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes sourceAttrs) {
                Path relative = sourceRoot.relativize(file);
                Path equivalent = targetRoot.resolve(relative);

                seenInSource.add(relative);

                try {
                    if (Files.notExists(equivalent)) {
                        // NEW: copy keeping the attributes
                        Files.copy(file, equivalent,
                                StandardCopyOption.COPY_ATTRIBUTES);
                        counters[0]++;
                        LOG.fine(() -> "New: " + relative);
                        return FileVisitResult.CONTINUE;
                    }

                    BasicFileAttributes targetAttrs =
                            Files.readAttributes(equivalent, BasicFileAttributes.class);

                    FileTime tSource = sourceAttrs.lastModifiedTime();
                    FileTime tTarget = targetAttrs.lastModifiedTime();

                    // compareTo > 0 means the source is MORE RECENT.
                    // The size is compared too: a file with the same date but a
                    // different size also has to be copied.
                    if (tSource.compareTo(tTarget) > 0
                            || sourceAttrs.size() != targetAttrs.size()) {

                        Files.copy(file, equivalent,
                                StandardCopyOption.REPLACE_EXISTING,
                                StandardCopyOption.COPY_ATTRIBUTES);
                        counters[1]++;
                        LOG.fine(() -> "Updated: " + relative);
                    } else {
                        counters[2]++;
                    }

                } catch (IOException e) {
                    counters[3]++;
                    LOG.warning(() -> "Error synchronising " + relative
                            + ": " + e.getMessage());
                }
                return FileVisitResult.CONTINUE;
            }

            /**
             * KEY: an inaccessible file does NOT abort the synchronisation.
             * With Files.walk this would not be possible.
             */
            @Override
            public FileVisitResult visitFileFailed(Path file, IOException e) {
                counters[3]++;
                LOG.warning(() -> "Not accessible in the source: " + file);
                return FileVisitResult.CONTINUE;
            }
        });

        // ---- PHASE 2: detect what is only in the target ----
        List<String> onlyTarget = new ArrayList<>();

        Files.walkFileTree(targetRoot, new SimpleFileVisitor<Path>() {
            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
                Path relative = targetRoot.relativize(file);
                if (!seenInSource.contains(relative)) {
                    onlyTarget.add(relative.toString());
                }
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult visitFileFailed(Path f, IOException e) {
                return FileVisitResult.CONTINUE;
            }
        });

        onlyTarget.sort(null);

        return new Result(counters[0], counters[1], counters[2],
                onlyTarget.size(), counters[3], onlyTarget);
    }

    public static void main(String[] args) throws IOException {
        Result r = new DirectorySynchroniser()
                .synchronise(Path.of("data"), Path.of("backup/data"));
        System.out.println(r.report());
    }
}

=== SYNCHRONISATION ===
  Copied (new)      : 0
  Updated           : 1
  Unchanged         : 11
  Only in target    : 2
  Errors            : 0
  --- Only in target (candidates for deletion) ---
    old-catalog.txt
    reports/2025/12/fines-december.report

package com.nexussoftware.bibliotech.infrastructure;

import java.io.IOException;
import java.nio.file.*;
import java.nio.file.attribute.BasicFileAttributes;
import java.nio.file.attribute.FileTime;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.Date;
import java.util.List;
import java.util.Objects;
import java.util.logging.Logger;
import java.util.stream.Stream;

/**
 * Rotating timestamped backups, on NIO.2.
 *
 * Each backup is named file.YYYYMMDD-HHMMSS.bak. The N most recent ones are
 * kept; the rest are deleted.
 *
 * NOTE: the dated name is composed with SimpleDateFormat because java.time is
 * lesson 10-05. With LocalDateTime and DateTimeFormatter this looks rather
 * better, and there you will see it.
 */
public class BackupManager {

    private static final Logger LOG = Logger.getLogger(BackupManager.class.getName());

    private static final String SUFFIX = ".bak";
    private static final int DEFAULT_MAX_BACKUPS = 3;

    private final Path backupDirectory;
    private final int maxBackups;

    public BackupManager(Path backupDirectory) throws IOException {
        this(backupDirectory, DEFAULT_MAX_BACKUPS);
    }

    public BackupManager(Path backupDirectory, int maxBackups) throws IOException {
        this.backupDirectory = Objects.requireNonNull(backupDirectory)
                .toAbsolutePath().normalize();

        if (maxBackups < 1) {
            throw new IllegalArgumentException(
                    "At least one backup must be kept, and the request was: " + maxBackups);
        }
        this.maxBackups = maxBackups;

        Files.createDirectories(this.backupDirectory);
    }

    /** Information about an existing backup. */
    public record BackupInfo(Path path, String name, long bytes, FileTime created) {

        public String line() {
            return String.format("%-45s %8d bytes  %s", name, bytes, created);
        }
    }

    // ---------------------- CREATING ----------------------

    /**
     * Creates a timestamped backup and applies the rotation.
     *
     * @return the path of the backup created
     */
    public Path createBackup(Path file) throws IOException {
        Objects.requireNonNull(file, "The file cannot be null");

        if (Files.notExists(file)) {
            throw new NoSuchFileException(file.toString(),
                    null, "A file that does not exist cannot be copied");
        }

        String baseName = file.getFileName().toString();
        String stamp = new java.text.SimpleDateFormat("yyyyMMdd-HHmmss")
                .format(new Date(System.currentTimeMillis()));

        Path backup = backupDirectory.resolve(baseName + "." + stamp + SUFFIX);

        // If another backup is requested in the same second, a suffix is added
        int attempt = 1;
        while (Files.exists(backup)) {
            backup = backupDirectory.resolve(
                    baseName + "." + stamp + "-" + attempt + SUFFIX);
            attempt++;
        }

        // COPY_ATTRIBUTES keeps the original date of the copied file
        Files.copy(file, backup, StandardCopyOption.COPY_ATTRIBUTES);

        final Path created = backup;
        LOG.info(() -> "Backup created: " + created.getFileName());

        applyRotation(baseName);
        return backup;
    }

    /** Deletes the surplus backups, starting with the oldest. */
    private void applyRotation(String baseName) throws IOException {
        List<BackupInfo> backups = listBackups(baseName);

        for (int i = maxBackups; i < backups.size(); i++) {
            BackupInfo surplus = backups.get(i);        // they come newest to oldest
            if (Files.deleteIfExists(surplus.path())) {
                LOG.fine(() -> "Old backup deleted: " + surplus.name());
            }
        }
    }

    // ---------------------- LISTING ----------------------

    /** Backups of a file, from the MOST RECENT to the oldest. */
    public List<BackupInfo> listBackups(String baseName) throws IOException {
        List<BackupInfo> found = new ArrayList<>();
        String prefix = baseName + ".";

        // Files.list returns a LAZY stream: try-with-resources compulsory
        try (Stream<Path> children = Files.list(backupDirectory)) {
            children.forEach(p -> {
                String name = p.getFileName().toString();
                if (!name.startsWith(prefix) || !name.endsWith(SUFFIX)) {
                    return;
                }
                try {
                    BasicFileAttributes attrs =
                            Files.readAttributes(p, BasicFileAttributes.class);
                    found.add(new BackupInfo(p, name, attrs.size(),
                            attrs.lastModifiedTime()));
                } catch (IOException e) {
                    LOG.fine(() -> "Could not read " + p);
                }
            });
        }

        // Most recent first (05-09)
        found.sort(Comparator.comparing(BackupInfo::created).reversed());
        return found;
    }

    public List<BackupInfo> listBackups(Path file) throws IOException {
        return listBackups(file.getFileName().toString());
    }

    // ---------------------- RESTORING ----------------------

    /**
     * Restores backup number 'index' (0 = the most recent).
     *
     * BEFORE restoring, it takes a backup of the CURRENT state: if the
     * restoration turns out to be a mistake, it can be undone. Restoring
     * without that net is a common way of losing the day's work.
     *
     * The replacement is ATOMIC: the file is never left half done.
     */
    public void restore(Path file, int index) throws IOException {
        List<BackupInfo> backups = listBackups(file);

        if (backups.isEmpty()) {
            throw new NoSuchFileException(file.toString(),
                    null, "There is no backup of this file");
        }
        if (index < 0 || index >= backups.size()) {
            throw new IllegalArgumentException(String.format(
                    "Index %d out of range: there are %d backups (0..%d)",
                    index, backups.size(), backups.size() - 1));
        }

        BackupInfo chosen = backups.get(index);

        // 1. Safety net: back up the current state before overwriting it
        if (Files.exists(file)) {
            createBackup(file);
        }

        // 2. A temporary SIBLING of the target: ATOMIC_MOVE demands it
        Path temp = file.resolveSibling(file.getFileName() + ".restoring");
        boolean completed = false;

        try {
            Files.copy(chosen.path(), temp,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.COPY_ATTRIBUTES);

            Files.move(temp, file,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            completed = true;

            LOG.info(() -> "Restored " + file.getFileName()
                    + " from " + chosen.name());

        } catch (AtomicMoveNotSupportedException e) {
            LOG.warning(() -> "No ATOMIC_MOVE; non-atomic restoration");
            Files.move(temp, file, StandardCopyOption.REPLACE_EXISTING);
            completed = true;

        } finally {
            if (!completed) {
                Files.deleteIfExists(temp);            // compensation (06-05)
            }
        }
    }

    // ---------------------- SPACE ----------------------

    /** Total space used by the backups. */
    public long spaceUsed() throws IOException {
        long[] total = new long[1];

        Files.walkFileTree(backupDirectory, new SimpleFileVisitor<Path>() {
            @Override
            public FileVisitResult visitFile(Path f, BasicFileAttributes attrs) {
                if (f.getFileName().toString().endsWith(SUFFIX)) {
                    total[0] += attrs.size();
                }
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult visitFileFailed(Path f, IOException e) {
                return FileVisitResult.CONTINUE;       // do not abort on a failure
            }
        });
        return total[0];
    }

    // ---------------------- DEMONSTRATION ----------------------

    public static void main(String[] args) throws IOException, InterruptedException {
        Path file = Path.of("data/catalog.txt");
        Files.createDirectories(file.getParent());

        BackupManager manager = new BackupManager(Path.of("data/backups"), 3);

        // 1. Five different versions, with a maximum of 3 backups
        System.out.println("=== CREATING 5 BACKUPS (maximum 3) ===");
        for (int v = 1; v <= 5; v++) {
            Files.writeString(file,
                    "# Catalogue version " + v + "\n"
                            + "BOOK;978-000000000" + v + ";Book " + v + ";Author;2020\n",
                    java.nio.charset.StandardCharsets.UTF_8,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE);

            Path backup = manager.createBackup(file);
            System.out.println("  v" + v + " -> " + backup.getFileName());

            Thread.sleep(1100);        // so that the timestamp changes
        }

        // 2. List: only the last 3 should remain
        System.out.println();
        System.out.println("=== BACKUPS KEPT ===");
        List<BackupInfo> backups = manager.listBackups(file);
        for (int i = 0; i < backups.size(); i++) {
            System.out.printf("  [%d] %s%n", i, backups.get(i).line());
        }

        // 3. Current content
        System.out.println();
        System.out.println("=== CURRENT CONTENT ===");
        System.out.print(Files.readString(file));

        // 4. Restore backup [1] (the second-newest, that is, version 4)
        System.out.println();
        System.out.println("=== RESTORING BACKUP [1] ===");
        manager.restore(file, 1);
        System.out.print(Files.readString(file));

        // 5. Space
        System.out.println();
        System.out.printf("=== SPACE USED: %.2f KB in %d backups ===%n",
                manager.spaceUsed() / 1024.0,
                manager.listBackups(file).size());
    }
}

=== CREATING 5 BACKUPS (maximum 3) ===
  v1 -> catalog.txt.20260805-091422.bak
  v2 -> catalog.txt.20260805-091423.bak
  v3 -> catalog.txt.20260805-091424.bak
  v4 -> catalog.txt.20260805-091425.bak
  v5 -> catalog.txt.20260805-091426.bak

=== BACKUPS KEPT ===
  [0] catalog.txt.20260805-091426.bak                  61 bytes  2026-08-05T09:14:26.118Z
  [1] catalog.txt.20260805-091425.bak                  61 bytes  2026-08-05T09:14:25.012Z
  [2] catalog.txt.20260805-091424.bak                  61 bytes  2026-08-05T09:14:23.907Z

=== CURRENT CONTENT ===
# Catalogue version 5
BOOK;978-0000000005;Book 5;Author;2020

=== RESTORING BACKUP [1] ===
# Catalogue version 4
BOOK;978-0000000004;Book 4;Author;2020

=== SPACE USED: 0.18 KB in 3 backups ===