try (Resource r = new Resource()) {
    // use r
}
// r is already closed here, whatever happens

// BEFORE JAVA 7: manual management
public int countLines(String path) throws IOException {
    BufferedReader reader = null;              // 1. declare outside
    try {
        reader = new BufferedReader(new FileReader(path));
        int lines = 0;
        while (reader.readLine() != null) {
            lines++;
        }
        return lines;
    } finally {
        if (reader != null) {                  // 2. check for null
            try {
                reader.close();                // 3. close() throws IOException
            } catch (IOException closeError) {
                // 4. do not rethrow: we would lose the original exception
                System.err.println("Warning: " + closeError.getMessage());
            }
        }
    }
}

// SINCE JAVA 7: automatic management
public int countLines(String path) throws IOException {
    try (BufferedReader reader = new BufferedReader(new FileReader(path))) {
        int lines = 0;
        while (reader.readLine() != null) {
            lines++;
        }
        return lines;
    }
}

// What the compiler generates (simplified sketch)
BufferedReader reader = new BufferedReader(new FileReader(path));
Throwable primaryException = null;
try {
    // ... body of the try ...
} catch (Throwable t) {
    primaryException = t;
    throw t;
} finally {
    if (reader != null) {
        if (primaryException != null) {
            try {
                reader.close();
            } catch (Throwable closeThrowable) {
                primaryException.addSuppressed(closeThrowable);   // <-- the key
            }
        } else {
            reader.close();          // no previous exception: if this throws, it propagates
        }
    }
}

// Java 7, java.lang
public interface AutoCloseable {
    void close() throws Exception;
}

// Java 5, java.io
public interface Closeable extends AutoCloseable {
    void close() throws IOException;
}

// close() declares Exception: the user has to catch Exception, far too broad
class BroadSession implements AutoCloseable {
    @Override
    public void close() throws Exception { }
}

try (BroadSession s = new BroadSession()) {
    // ...
} catch (Exception e) {          // forced to catch Exception: horrible
    // ...
}

// GOOD: close() with no throws. Whoever uses it will not have to catch anything.
class CleanSession implements AutoCloseable {
    @Override
    public void close() {            // no throws: more restrictive, perfectly legal
        // release resources without throwing
    }
}

try (CleanSession s = new CleanSession()) {
    // ...
}
// No compulsory catch. Much better.

package com.nexussoftware.bibliotech.presentation;

/**
 * Demonstrates the opening and closing order with three resources.
 * The resources are simulated: there is no real I/O, so that the focus is
 * exclusively on the ORDER.
 */
public class ClosingOrder {

    /** Toy resource that announces its opening and its closing. */
    static class TracedResource implements AutoCloseable {
        private final String name;

        TracedResource(String name) {
            this.name = name;
            System.out.println("  OPEN  " + name);
        }

        void use() {
            System.out.println("  USE   " + name);
        }

        @Override
        public void close() {                  // no throws: more convenient for the user
            System.out.println("  CLOSE " + name);
        }
    }

    public static void main(String[] args) {
        System.out.println("=== No exception ===");
        try (TracedResource a = new TracedResource("A-file");
             TracedResource b = new TracedResource("B-buffer");
             TracedResource c = new TracedResource("C-parser")) {

            a.use();
            b.use();
            c.use();
        }

        System.out.println("\n=== With an exception in the body ===");
        try (TracedResource a = new TracedResource("A-file");
             TracedResource b = new TracedResource("B-buffer")) {

            a.use();
            throw new IllegalStateException("failure in the middle of the process");

        } catch (IllegalStateException e) {
            System.out.println("  CATCH " + e.getMessage());
        }

        System.out.println("\n=== With an exception OPENING the second resource ===");
        try (TracedResource a = new TracedResource("A-file");
             TracedResource b = createFailing("B-buffer")) {
            a.use();
        } catch (IllegalStateException e) {
            System.out.println("  CATCH " + e.getMessage());
        }
    }

    static TracedResource createFailing(String name) {
        throw new IllegalStateException("could not open " + name);
    }
}

=== No exception ===
  OPEN  A-file
  OPEN  B-buffer
  OPEN  C-parser
  USE   A-file
  USE   B-buffer
  USE   C-parser
  CLOSE C-parser
  CLOSE B-buffer
  CLOSE A-file

=== With an exception in the body ===
  OPEN  A-file
  OPEN  B-buffer
  USE   A-file
  CLOSE B-buffer
  CLOSE A-file
  CATCH failure in the middle of the process

=== With an exception OPENING the second resource ===
  OPEN  A-file
  CLOSE A-file
  CATCH could not open B-buffer

try (BufferedReader reader = new BufferedReader(new FileReader("catalog.txt"))) {
    reader = new BufferedReader(new FileReader("other.txt"));   // DOES NOT COMPILE
    // error: auto-closeable resource reader may not be assigned
}

try (final BufferedReader reader = new BufferedReader(new FileReader(path))) {
    // ...
}

try (TracedResource r = new TracedResource("A")) {
    r.use();
} catch (Exception e) {
    r.use();                       // DOES NOT COMPILE: cannot find symbol
} finally {
    r.use();                       // DOES NOT COMPILE: cannot find symbol
}

// Java 7/8: you have to create a new variable just to be able to use it
public void process(BufferedReader receivedReader) throws IOException {
    try (BufferedReader reader = receivedReader) {     // redundant variable
        System.out.println(reader.readLine());
    }
}

// Java 9+: the variable is used as it is
public void process(BufferedReader receivedReader) throws IOException {
    try (receivedReader) {                             // no new declaration
        System.out.println(receivedReader.readLine());
    }
}

public void demo() throws Exception {
    TracedResource a = new TracedResource("A");    // effectively final: never reassigned
    TracedResource b = new TracedResource("B");

    try (a; b) {                                    // several, separated by ;
        a.use();
        b.use();
    }
    // B is closed and then A
}

TracedResource r = new TracedResource("A");
r = new TracedResource("B");                        // reassigned: no longer effectively final

try (r) {                                            // DOES NOT COMPILE
    // error: local variables referenced from a resource specification
    //        must be final or effectively final
}

// SUSPICIOUS: I close something I did not open
public void process(BufferedReader reader) throws IOException {
    try (reader) {                     // do I have the right to close it?
        // ...
    }
}
// The caller will not be able to use their reader again, and may not have expected that.

package com.nexussoftware.bibliotech.presentation;

/**
 * Compares what happens when the body AND the closing fail:
 *  - with a manual try-finally: the closing exception REPLACES the original.
 *  - with try-with-resources: the original is preserved and the closing one is SUPPRESSED.
 */
public class SuppressedExceptions {

    /** Resource whose closing also fails. */
    static class FragileResource implements AutoCloseable {
        private final String name;

        FragileResource(String name) {
            this.name = name;
        }

        void read() {
            throw new IllegalStateException("REAL FAILURE: " + name + " is corrupt");
        }

        @Override
        public void close() {
            throw new IllegalStateException("CLOSING FAILURE: " + name + " was not released");
        }
    }

    public static void main(String[] args) {

        System.out.println("=== A) MANUAL try-finally ===");
        try {
            withManualFinally();
        } catch (IllegalStateException e) {
            System.out.println("  Received  : " + e.getMessage());
            System.out.println("  Cause     : " + e.getCause());
            System.out.println("  Suppressed: " + e.getSuppressed().length);
            System.out.println("  >> The REAL FAILURE has disappeared");
        }

        System.out.println("\n=== B) try-with-resources ===");
        try {
            withTryWithResources();
        } catch (IllegalStateException e) {
            System.out.println("  Received  : " + e.getMessage());
            System.out.println("  Cause     : " + e.getCause());
            System.out.println("  Suppressed: " + e.getSuppressed().length);
            for (Throwable suppressed : e.getSuppressed()) {
                System.out.println("    - " + suppressed.getMessage());
            }
            System.out.println("  >> BOTH are preserved");
        }

        System.out.println("\n=== C) Only the closing fails ===");
        try {
            onlyTheCloseFails();
        } catch (IllegalStateException e) {
            System.out.println("  Received  : " + e.getMessage());
            System.out.println("  Suppressed: " + e.getSuppressed().length);
            System.out.println("  >> With no previous exception, the closing one propagates normally");
        }
    }

    static void withManualFinally() {
        FragileResource resource = new FragileResource("catalog.txt");
        try {
            resource.read();
        } finally {
            resource.close();         // this exception REPLACES the try's
        }
    }

    static void withTryWithResources() {
        try (FragileResource resource = new FragileResource("catalog.txt")) {
            resource.read();
        }
    }

    static void onlyTheCloseFails() {
        try (FragileResource resource = new FragileResource("loans.txt")) {
            System.out.println("  (the body finishes fine)");
        }
    }
}

=== A) MANUAL try-finally ===
  Received  : CLOSING FAILURE: catalog.txt was not released
  Cause     : null
  Suppressed: 0
  >> The REAL FAILURE has disappeared

=== B) try-with-resources ===
  Received  : REAL FAILURE: catalog.txt is corrupt
  Cause     : null
  Suppressed: 1
    - CLOSING FAILURE: catalog.txt was not released
  >> BOTH are preserved

=== C) Only the closing fails ===
  (the body finishes fine)
  Received  : CLOSING FAILURE: loans.txt was not released
  Suppressed: 0
  >> With no previous exception, the closing one propagates normally

Exception in thread "main" java.lang.IllegalStateException: REAL FAILURE: catalog.txt is corrupt
	at com.nexussoftware.bibliotech.presentation.SuppressedExceptions$FragileResource.read(SuppressedExceptions.java:22)
	at com.nexussoftware.bibliotech.presentation.SuppressedExceptions.withTryWithResources(SuppressedExceptions.java:70)
	at com.nexussoftware.bibliotech.presentation.SuppressedExceptions.main(SuppressedExceptions.java:38)
	Suppressed: java.lang.IllegalStateException: CLOSING FAILURE: catalog.txt was not released
		at com.nexussoftware.bibliotech.presentation.SuppressedExceptions$FragileResource.close(SuppressedExceptions.java:27)
		at com.nexussoftware.bibliotech.presentation.SuppressedExceptions.withTryWithResources(SuppressedExceptions.java:71)
		... 1 more

package com.nexussoftware.bibliotech.presentation;

/** Dumps an exception with its causes and its suppressed ones, indented. */
public final class ExceptionReport {

    private ExceptionReport() { }

    public static String describe(Throwable t) {
        StringBuilder sb = new StringBuilder();
        describe(t, sb, 0, "");
        return sb.toString();
    }

    private static void describe(Throwable t, StringBuilder sb, int level, String label) {
        if (t == null || level > 10) {                 // anti-circular protection
            return;
        }
        String indent = "  ".repeat(level);
        sb.append(indent).append(label)
          .append(t.getClass().getSimpleName()).append(": ")
          .append(t.getMessage() != null ? t.getMessage() : "(no message)")
          .append('\n');

        // First own frame, to locate the failure
        for (StackTraceElement f : t.getStackTrace()) {
            if (f.getClassName().startsWith("com.nexussoftware")) {
                sb.append(indent).append("    at ").append(f.getMethodName())
                  .append(" (").append(f.getFileName()).append(':')
                  .append(f.getLineNumber()).append(")\n");
                break;
            }
        }

        // Suppressed: they happened AS WELL (same logical level, indented)
        for (Throwable suppressed : t.getSuppressed()) {
            describe(suppressed, sb, level + 1, "Suppressed: ");
        }

        // Cause: it TRIGGERED the previous one
        if (t.getCause() != null && t.getCause() != t) {
            describe(t.getCause(), sb, level + 1, "Caused by: ");
        }
    }
}

// Legal: try-with-resources with no catch and no finally
try (TracedResource r = new TracedResource("A")) {
    r.use();
}

// Legal: with catch
try (TracedResource r = new TracedResource("A")) {
    r.use();
} catch (IllegalStateException e) {
    System.out.println("Failure: " + e.getMessage());
}

// Legal: with catch and finally
try (TracedResource r = new TracedResource("A")) {
    r.use();
} catch (IllegalStateException e) {
    System.out.println("Failure: " + e.getMessage());
} finally {
    System.out.println("Extra clean-up, unrelated to resources");
}

package com.nexussoftware.bibliotech.presentation;

public class CompleteOrder {

    static class Resource implements AutoCloseable {
        Resource() { System.out.println("1. open"); }
        void use() { throw new IllegalStateException("failure in the body"); }
        @Override public void close() { System.out.println("3. close"); }
    }

    public static void main(String[] args) {
        try (Resource r = new Resource()) {
            System.out.println("2. body");
            r.use();
        } catch (IllegalStateException e) {
            System.out.println("4. catch: " + e.getMessage());
        } finally {
            System.out.println("5. finally");
        }
        System.out.println("6. after");
    }
}

1. open
2. body
3. close
4. catch: failure in the body
5. finally
6. after

// REAL PROBLEM: it closes System.in for the WHOLE application
public int readOption() {
    try (Scanner scanner = new Scanner(System.in)) {     // BAD
        return Integer.parseInt(scanner.nextLine());
    }
}

// From here on, any other Scanner over System.in fails:
// NoSuchElementException: No line found

// CORRECT: a single instance Scanner, no try-with-resources
public class BiblioTechMenu {

    private final Scanner scanner = new Scanner(System.in);   // created once

    public int readOption() {
        // No try-with-resources: System.in is NOT closed
        return Integer.parseInt(scanner.nextLine().trim());
    }
    // It is never closed: the JVM closes System.in when the process ends
}

// BAD: the resource is closed right before returning it
public BufferedReader openCatalog(String path) throws IOException {
    try (BufferedReader reader = new BufferedReader(new FileReader(path))) {
        return reader;             // closed BEFORE returning (06-05: the finally runs first)
    }
}
// Whoever receives it will get "Stream closed" on the first read.

public class MyResource implements AutoCloseable {

    private boolean closed = false;

    public MyResource() {
        // acquire whatever is needed
    }

    public void operation() {
        checkOpen();                 // protect against use after closing
        // ...
    }

    private void checkOpen() {
        if (closed) {
            throw new IllegalStateException("The resource is already closed");
        }
    }

    @Override
    public void close() {            // no throws: more convenient for the user
        if (closed) {
            return;                  // IDEMPOTENT: closing twice does not fail
        }
        closed = true;
        // release what was acquired
    }
}

try (MyResource r = new MyResource()) {
    r.operation();
    r.close();                // early explicit closing
}                             // ...and the try-with-resources closes it AGAIN

@Override
public void close() {
    if (closed) { return; }
    closed = true;
    try {
        releaseUnderlyingResource();
    } catch (RuntimeException e) {
        // Logged, not propagated: closing must not break a correct operation.
        // In 06-07 this will be logger.log(Level.WARNING, "...", e).
        System.err.println("Warning: failed to release the resource: " + e.getMessage());
    }
}

package com.nexussoftware.bibliotech.service;

import java.util.ArrayList;
import java.util.List;
import java.util.Objects;

/**
 * An employee's work shift over BiblioTech.
 *
 * On closing:
 *   1. it consolidates the shift's statistics,
 *   2. it releases the catalogue lock,
 *   3. it leaves the session unusable.
 *
 * It implements AutoCloseable, not Closeable, because it is not an I/O resource.
 * And its close() does NOT declare throws: that way its users are not forced to catch anything.
 */
public class LibrarySession implements AutoCloseable {

    private final String employeeId;
    private final int openingDay;
    private final Catalog catalog;

    private final List<String> operations = new ArrayList<>();
    private int loansMade = 0;
    private int returnsMade = 0;
    private double finesCollected = 0.0;

    private boolean closed = false;

    /** Accumulated statistics of every shift (static: 03-02). */
    private static int shiftsCompleted = 0;
    private static int totalOperations = 0;

    public LibrarySession(String employeeId, int openingDay, Catalog catalog) {
        this.employeeId = Objects.requireNonNull(employeeId, "The employee cannot be null");
        this.catalog = Objects.requireNonNull(catalog, "The catalogue cannot be null");
        if (openingDay < 1) {
            throw new IllegalArgumentException("The day must be 1 or later, and it was: " + openingDay);
        }
        this.openingDay = openingDay;

        catalog.lock(employeeId);               // resource acquisition
        System.out.println("  [session of " + employeeId + " opened on day " + openingDay + "]");
    }

    // ---------- Shift operations ----------

    public void recordLoan(String reference) {
        checkOpen();
        loansMade++;
        operations.add("LOAN " + reference);
    }

    public void recordReturn(String reference, double fine) {
        checkOpen();
        if (fine < 0) {
            throw new IllegalArgumentException("The fine cannot be negative: " + fine);
        }
        returnsMade++;
        finesCollected += fine;
        operations.add(String.format("RETURN %s (fine %.2f)", reference, fine));
    }

    public List<String> getOperations() {
        checkOpen();
        return List.copyOf(operations);
    }

    /**
     * Every usage method checks the state.
     * It is IllegalStateException, not IllegalArgumentException: the problem
     * is WHEN it is asked, not what is asked (06-03).
     */
    private void checkOpen() {
        if (closed) {
            throw new IllegalStateException(
                    "The session of " + employeeId + " is already closed");
        }
    }

    // ---------- Closing ----------

    /**
     * Consolidates and releases. IDEMPOTENT and with no checked throws.
     *
     * It runs on success and on failure of the body, because try-with-resources
     * guarantees it just like a finally (06-05).
     */
    @Override
    public void close() {
        if (closed) {
            return;                              // idempotent
        }
        closed = true;

        // 1. Consolidate statistics
        shiftsCompleted++;
        totalOperations += operations.size();

        System.out.printf("  [session of %s closed] %d loans, %d returns, %.2f EUR%n",
                employeeId, loansMade, returnsMade, finesCollected);

        // 2. Release the lock, protected so as not to break a correct operation
        try {
            catalog.unlock(employeeId);
        } catch (RuntimeException e) {
            // Not propagated: closing must not turn a correct shift into a failure.
            // In 06-07 this will be logger.log(Level.WARNING, ..., e).
            System.err.println("  Warning: could not release the catalogue lock: "
                    + e.getMessage());
        }
    }

    public boolean isClosed() { return closed; }

    public static int getShiftsCompleted()  { return shiftsCompleted; }
    public static int getTotalOperations()  { return totalOperations; }
}

package com.nexussoftware.bibliotech.service;

import java.io.BufferedWriter;
import java.io.FileWriter;
import java.io.IOException;
import java.util.List;

import com.nexussoftware.bibliotech.domain.Material;

/**
 * Exports the catalogue to a text file.
 *
 * It implements Closeable (not AutoCloseable) because it IS an I/O resource and its
 * close() can legitimately throw IOException: on closing, the buffer is flushed
 * to disk, and if that fails, the data has NOT been written. That failure
 * MUST reach the caller.
 *
 * (The writing API is developed in module 7.)
 */
public class CatalogExporter implements java.io.Closeable {

    private final String path;
    private final BufferedWriter writer;

    private int materialsWritten = 0;
    private boolean closed = false;

    public CatalogExporter(String path) throws IOException {
        this.path = path;
        this.writer = new BufferedWriter(new FileWriter(path));
        writeHeader();
    }

    private void writeHeader() throws IOException {
        writer.write("# BiblioTech catalogue - Nexus Software");
        writer.newLine();
        writer.write("# reference;title;available");
        writer.newLine();
    }

    public void export(Material material) throws IOException {
        if (closed) {
            throw new IllegalStateException("The exporter for '" + path + "' is already closed");
        }
        writer.write(material.getReference() + ";" + material.getTitle() + ";"
                + material.isAvailable());
        writer.newLine();
        materialsWritten++;
    }

    public void exportAll(List<Material> materials) throws IOException {
        for (Material m : materials) {
            export(m);
        }
    }

    public int getMaterialsWritten() { return materialsWritten; }

    /**
     * Closes the file.
     *
     * HERE the IOException IS propagated: a writer's close() flushes the
     * buffer to disk. If it fails, the data is not saved and the caller
     * has to find out. It is the exception to the "close does not throw" rule.
     */
    @Override
    public void close() throws IOException {
        if (closed) {
            return;                              // idempotent
        }
        closed = true;
        try {
            writer.write("# Total: " + materialsWritten + " materials");
            writer.newLine();
        } finally {
            writer.close();                      // flushes the buffer and releases the descriptor
        }
    }
}

package com.nexussoftware.bibliotech.presentation;

import java.io.IOException;

import com.nexussoftware.bibliotech.domain.Book;
import com.nexussoftware.bibliotech.service.Catalog;
import com.nexussoftware.bibliotech.service.CatalogExporter;
import com.nexussoftware.bibliotech.service.LibrarySession;

public class SessionAndExporterDemo {

    public static void main(String[] args) {
        Catalog catalog = new Catalog();
        catalog.register(new Book("BK-0001", "Effective Java", "Bloch", 2018, "978-0000000001"));
        catalog.register(new Book("BK-0002", "Design Patterns", "GoF", 1994, "978-0000000002"));
        catalog.register(new Book("BK-0003", "Refactoring", "Fowler", 1999, "978-0000000003"));

        // === 1. A shift that goes well ===
        System.out.println("=== 1. Marta's correct shift ===");
        try (LibrarySession session = new LibrarySession("EMP-001", 10, catalog)) {
            session.recordLoan("BK-0001");
            session.recordLoan("BK-0002");
            session.recordReturn("BK-0003", 1.25);
            System.out.println("  Shift operations: " + session.getOperations());
        }
        System.out.println("  Catalogue locked: " + catalog.isLocked());

        // === 2. A shift that fails halfway ===
        System.out.println("\n=== 2. Diego's shift that fails ===");
        try (LibrarySession session = new LibrarySession("EMP-002", 11, catalog)) {
            session.recordLoan("BK-0001");
            session.recordReturn("BK-0002", -5.0);            // throws
            System.out.println("  this line does not run");
        } catch (IllegalArgumentException e) {
            System.out.println("  Failure caught: " + e.getMessage());
        }
        System.out.println("  Catalogue locked: " + catalog.isLocked());
        System.out.println("  (the session closed and consolidated all the same)");

        // === 3. Using the session after closing it ===
        System.out.println("\n=== 3. Use after closing ===");
        LibrarySession outside;
        try (LibrarySession session = new LibrarySession("EMP-003", 12, catalog)) {
            session.recordLoan("BK-0003");
            outside = session;                                // the reference is kept
        }
        try {
            outside.recordLoan("BK-0001");
        } catch (IllegalStateException e) {
            System.out.println("  " + e.getMessage());
        }
        System.out.println("  close() twice: ");
        outside.close();                                      // idempotent: does not fail
        System.out.println("  no errors");

        // === 4. Two nested resources ===
        System.out.println("\n=== 4. Session + exporter (two resources) ===");
        try (LibrarySession session = new LibrarySession("EMP-001", 13, catalog);
             CatalogExporter exporter = new CatalogExporter("catalog-export.txt")) {

            exporter.exportAll(catalog.list());
            session.recordLoan("BK-0002");
            System.out.println("  Exported: " + exporter.getMaterialsWritten());

        } catch (IOException e) {
            System.out.println("  Export failure: " + e.getMessage());
        }
        // Closing in REVERSE order: first the exporter, then the session

        System.out.println("\n=== Global statistics ===");
        System.out.println("  Shifts completed : " + LibrarySession.getShiftsCompleted());
        System.out.println("  Total operations : " + LibrarySession.getTotalOperations());
    }
}

=== 1. Marta's correct shift ===
  [session of EMP-001 opened on day 10]
  Shift operations: [LOAN BK-0001, LOAN BK-0002, RETURN BK-0003 (fine 1.25)]
  [session of EMP-001 closed] 2 loans, 1 returns, 1.25 EUR
  Catalogue locked: false

=== 2. Diego's shift that fails ===
  [session of EMP-002 opened on day 11]
  [session of EMP-002 closed] 1 loans, 0 returns, 0.00 EUR
  Failure caught: The fine cannot be negative: -5.0
  Catalogue locked: false
  (the session closed and consolidated all the same)

=== 3. Use after closing ===
  [session of EMP-003 opened on day 12]
  [session of EMP-003 closed] 1 loans, 0 returns, 0.00 EUR
  The session of EMP-003 is already closed
  close() twice:
  no errors

=== 4. Session + exporter (two resources) ===
  [session of EMP-001 opened on day 13]
  Exported: 3
  [session of EMP-001 closed] 1 loans, 0 returns, 0.00 EUR

=== Global statistics ===
  Shifts completed : 4
  Total operations : 5

package com.nexussoftware.bibliotech.service;

import java.util.Objects;

/**
 * Exclusion lock over the catalogue, reentrant and closeable.
 *
 * Intended use:
 *   try (CatalogLock l = new CatalogLock("EMP-001")) {
 *       // exclusive operations
 *   }   // always released
 *
 * Note: this is NOT thread-safe; real locks between threads are the subject
 * of module 8. Here it is a logical single-threaded lock.
 */
public class CatalogLock implements AutoCloseable {

    private static String currentOwner = null;
    private static int depth = 0;
    private static int locksGranted = 0;
    private static int momentCounter = 0;

    private final String ownerId;
    private final int acquisitionMoment;
    private final boolean reentrant;

    private boolean closed = false;

    /**
     * Acquires the lock.
     *
     * @throws IllegalStateException if ANOTHER owner has it
     */
    public CatalogLock(String ownerId) {
        this.ownerId = Objects.requireNonNull(ownerId,
                "The owner identifier cannot be null");

        if (currentOwner != null && !currentOwner.equals(ownerId)) {
            throw new IllegalStateException(
                    "The catalogue is locked by " + currentOwner
                            + "; " + ownerId + " cannot acquire it");
        }

        this.reentrant = (currentOwner != null);          // same owner again
        currentOwner = ownerId;
        depth++;
        locksGranted++;
        this.acquisitionMoment = ++momentCounter;

        System.out.println("    [lock " + (reentrant ? "REENTRANT " : "")
                + "acquired by " + ownerId + " (depth " + depth
                + ", moment " + acquisitionMoment + ")]");
    }

    /**
     * Releases the lock. Only the outermost one REALLY releases it.
     * Idempotent: closing twice does nothing the second time.
     */
    @Override
    public void close() {
        if (closed) {
            return;                              // idempotent
        }
        closed = true;
        depth--;

        if (depth == 0) {
            currentOwner = null;
            System.out.println("    [lock RELEASED by " + ownerId + "]");
        } else {
            System.out.println("    [reentrant level closed; depth " + depth + "]");
        }
    }

    /**
     * Checks that whoever operates is the owner of the lock.
     *
     * @throws IllegalStateException if they are not, or if there is no lock
     */
    public static void checkOwnership(String id) {
        if (currentOwner == null) {
            throw new IllegalStateException(
                    "There is no active lock over the catalogue; " + id + " cannot operate");
        }
        if (!currentOwner.equals(id)) {
            throw new IllegalStateException(
                    "The catalogue is locked by " + currentOwner + ", not by " + id);
        }
    }

    public String getOwnerId()          { return ownerId; }
    public int getAcquisitionMoment()   { return acquisitionMoment; }
    public boolean isClosed()           { return closed; }

    public static String getCurrentOwner()  { return currentOwner; }
    public static int getDepth()            { return depth; }
    public static int getLocksGranted()     { return locksGranted; }

    // ------------------------------------------------------------------

    public static void main(String[] args) {

        System.out.println("=== 1. Normal acquisition and release ===");
        try (CatalogLock l = new CatalogLock("EMP-001")) {
            System.out.println("  operating as " + l.getOwnerId());
            checkOwnership("EMP-001");
        }
        System.out.println("  Owner after closing: " + getCurrentOwner());

        System.out.println("\n=== 2. Two-level reentrancy ===");
        try (CatalogLock outer = new CatalogLock("EMP-001")) {
            System.out.println("  outer level");

            try (CatalogLock inner = new CatalogLock("EMP-001")) {
                System.out.println("  inner level");
                System.out.println("  Depth inside: " + getDepth());
            }
            System.out.println("  After closing the inner one, depth: " + getDepth());
            System.out.println("  Owner is still: " + getCurrentOwner());
        }
        System.out.println("  After closing the outer one: " + getCurrentOwner());

        System.out.println("\n=== 3. Another employee tries to lock ===");
        try (CatalogLock l = new CatalogLock("EMP-001")) {
            try (CatalogLock other = new CatalogLock("EMP-002")) {
                System.out.println("  this should not happen");
            } catch (IllegalStateException e) {
                System.out.println("  Rejected: " + e.getMessage());
            }
            System.out.println("  EMP-001's lock is still alive: " + getCurrentOwner());
        }

        System.out.println("\n=== 4. Exception in the body ===");
        try (CatalogLock l = new CatalogLock("EMP-003")) {
            System.out.println("  operating...");
            throw new IllegalArgumentException("failure in the middle of the operation");
        } catch (IllegalArgumentException e) {
            System.out.println("  Exception received INTACT: " + e.getMessage());
        }
        System.out.println("  Owner after the failure: " + getCurrentOwner()
                + " (correctly released)");

        System.out.println("\n=== 5. Double close() ===");
        CatalogLock manual = new CatalogLock("EMP-001");
        manual.close();
        manual.close();
        System.out.println("  No errors. Depth: " + getDepth());

        System.out.println("\n=== 6. Operating with no lock ===");
        try {
            checkOwnership("EMP-002");
        } catch (IllegalStateException e) {
            System.out.println("  " + e.getMessage());
        }

        System.out.println("\nLocks granted in total: " + getLocksGranted());
    }
}

=== 1. Normal acquisition and release ===
    [lock acquired by EMP-001 (depth 1, moment 1)]
  operating as EMP-001
    [lock RELEASED by EMP-001]
  Owner after closing: null

=== 2. Two-level reentrancy ===
    [lock acquired by EMP-001 (depth 1, moment 2)]
  outer level
    [lock REENTRANT acquired by EMP-001 (depth 2, moment 3)]
  inner level
  Depth inside: 2
    [reentrant level closed; depth 1]
  After closing the inner one, depth: 1
  Owner is still: EMP-001
    [lock RELEASED by EMP-001]
  After closing the outer one: null

=== 3. Another employee tries to lock ===
    [lock acquired by EMP-001 (depth 1, moment 4)]
  Rejected: The catalogue is locked by EMP-001; EMP-002 cannot acquire it
  EMP-001's lock is still alive: EMP-001
    [lock RELEASED by EMP-001]

=== 4. Exception in the body ===
    [lock acquired by EMP-003 (depth 1, moment 5)]
  operating...
    [lock RELEASED by EMP-003]
  Exception received INTACT: failure in the middle of the operation
  Owner after the failure: null (correctly released)

=== 5. Double close() ===
    [lock acquired by EMP-001 (depth 1, moment 6)]
    [lock RELEASED by EMP-001]
  No errors. Depth: 0

=== 6. Operating with no lock ===
  There is no active lock over the catalogue; EMP-002 cannot operate

Locks granted in total: 6

package com.nexussoftware.bibliotech.presentation;

/**
 * Explores the suppressed exception mechanism with three resources.
 */
public class FailureCascade {

    static class FailingResource implements AutoCloseable {
        private final String name;
        private final boolean failsOnUse;
        private final boolean failsOnClose;

        FailingResource(String name, boolean failsOnUse, boolean failsOnClose) {
            this(name, failsOnUse, failsOnClose, false);
        }

        FailingResource(String name, boolean failsOnUse, boolean failsOnClose,
                        boolean failsOnOpen) {
            if (failsOnOpen) {
                throw new IllegalStateException("OPENING of " + name + " failed");
            }
            this.name = name;
            this.failsOnUse = failsOnUse;
            this.failsOnClose = failsOnClose;
            System.out.println("    open  " + name);
        }

        void use() {
            System.out.println("    use   " + name);
            if (failsOnUse) {
                throw new IllegalStateException("USE of " + name + " failed");
            }
        }

        @Override
        public void close() {
            System.out.println("    close " + name);
            if (failsOnClose) {
                throw new IllegalStateException("CLOSING of " + name + " failed");
            }
        }
    }

    public static void main(String[] args) {

        scenario("1. Nothing fails", false, false, false, false, false, false);
        scenario("2. Only the body fails", true, false, false, false, false, false);
        scenario("3. Only the middle one's closing fails", false, false, false, false, true, false);
        scenario("4. The body AND all three closings fail", true, false, false, true, true, true);
        failedOpeningScenario();
    }

    /**
     * @param bodyFails       whether the body throws after using the resources
     * @param close1/2/3      whether each resource's closing fails
     */
    static void scenario(String title, boolean bodyFails,
                         boolean useA, boolean useB,
                         boolean close1, boolean close2, boolean close3) {
        System.out.println("\n=== " + title + " ===");
        try (FailingResource r1 = new FailingResource("R1", useA, close1);
             FailingResource r2 = new FailingResource("R2", useB, close2);
             FailingResource r3 = new FailingResource("R3", false, close3)) {

            r1.use();
            r2.use();
            r3.use();

            if (bodyFails) {
                throw new IllegalStateException("BODY failed");
            }
            System.out.println("  (no exception)");

        } catch (IllegalStateException e) {
            System.out.println("  --- Propagated exception ---");
            System.out.println(dump(e));
        }
    }

    static void failedOpeningScenario() {
        System.out.println("\n=== 5. The OPENING of the third resource fails ===");
        try (FailingResource r1 = new FailingResource("R1", false, false);
             FailingResource r2 = new FailingResource("R2", false, false);
             FailingResource r3 = new FailingResource("R3", false, false, true)) {

            r1.use();
            System.out.println("  this line does NOT run");

        } catch (IllegalStateException e) {
            System.out.println("  --- Propagated exception ---");
            System.out.println(dump(e));
        }
    }

    /** Dumps the tree of causes and suppressed ones with indentation. */
    static String dump(Throwable t) {
        StringBuilder sb = new StringBuilder();
        dump(t, sb, 1, "");
        return sb.toString();
    }

    private static void dump(Throwable t, StringBuilder sb, int level, String label) {
        if (t == null || level > 10) { return; }

        sb.append("  ".repeat(level)).append(label)
          .append(t.getClass().getSimpleName()).append(": ")
          .append(t.getMessage()).append('\n');

        for (Throwable s : t.getSuppressed()) {
            dump(s, sb, level + 1, "Suppressed: ");
        }
        if (t.getCause() != null && t.getCause() != t) {
            dump(t.getCause(), sb, level + 1, "Caused by: ");
        }
    }
}

=== 1. Nothing fails ===
    open  R1
    open  R2
    open  R3
    use   R1
    use   R2
    use   R3
  (no exception)
    close R3
    close R2
    close R1

=== 2. Only the body fails ===
    open  R1 / R2 / R3 ... use R1 / R2 / R3
    close R3
    close R2
    close R1
  --- Propagated exception ---
    IllegalStateException: BODY failed

=== 3. Only the middle one's closing fails ===
    ... close R3
    close R2
  --- Propagated exception ---
    IllegalStateException: CLOSING of R2 failed

=== 4. The body AND all three closings fail ===
    close R3
    close R2
    close R1
  --- Propagated exception ---
    IllegalStateException: BODY failed
      Suppressed: IllegalStateException: CLOSING of R3 failed
      Suppressed: IllegalStateException: CLOSING of R2 failed
      Suppressed: IllegalStateException: CLOSING of R1 failed

=== 5. The OPENING of the third resource fails ===
    open  R1
    open  R2
    close R2
    close R1
  --- Propagated exception ---
    IllegalStateException: OPENING of R3 failed

package com.nexussoftware.bibliotech.service;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

import com.nexussoftware.bibliotech.domain.Book;
import com.nexussoftware.bibliotech.domain.DuplicateReferenceException;

/**
 * Imports materials from a text file into the catalogue.
 *
 * NOTE ON THE I/O API: here only FileReader, BufferedReader and
 * BufferedWriter are used, to open, read/write lines and close. Complete
 * input/output (streams, NIO.2, formats) is MODULE 7. This class's focus
 * is on the guaranteed CLOSING with try-with-resources.
 */
public class CatalogImporter {

    public record ImportReport(int linesRead, int accepted, int rejected,
                               List<String> reasons) {

        public String summary() {
            StringBuilder sb = new StringBuilder();
            sb.append("=== IMPORT REPORT ===\n");
            sb.append("Lines read : ").append(linesRead).append('\n');
            sb.append("Accepted   : ").append(accepted).append('\n');
            sb.append("Rejected   : ").append(rejected).append('\n');
            for (String r : reasons) {
                sb.append("  * ").append(r).append('\n');
            }
            return sb.toString();
        }
    }

    private final Catalog catalog;

    public CatalogImporter(Catalog catalog) {
        this.catalog = catalog;
    }

    /**
     * Imports a file into the catalogue.
     *
     * It does NOT catch the opening IOException: it declares it so that the
     * caller decides whether to start with an empty catalogue or abort (06-03).
     */
    public ImportReport importFile(String path) throws IOException {
        List<String> reasons = new ArrayList<>();
        int linesRead = 0;
        int accepted = 0;

        // try-with-resources: the reader is always closed, even if
        // the loop throws. With a manual try-finally 8 more lines would be needed.
        try (BufferedReader reader = new BufferedReader(new FileReader(path))) {

            String line;
            while ((line = reader.readLine()) != null) {
                linesRead++;

                if (line.isBlank() || line.startsWith("#")) {
                    continue;                    // blanks and comments: skipped quietly
                }

                // try INSIDE the loop: a bad line does not abort the import (06-02)
                try {
                    String[] c = line.split(";");
                    Book book = new Book(c[0].trim(), c[1].trim(), c[2].trim(),
                            Integer.parseInt(c[3].trim()), c[4].trim());
                    catalog.register(book);
                    accepted++;

                } catch (ArrayIndexOutOfBoundsException e) {
                    reasons.add("Line " + linesRead + ": missing fields -> '" + line + "'");

                } catch (NumberFormatException e) {
                    reasons.add("Line " + linesRead + ": non-numeric year -> " + e.getMessage());

                } catch (DuplicateReferenceException e) {
                    // DOMAIN exception (06-04): use its data, not its message
                    reasons.add("Line " + linesRead + ": " + e.getKind() + " duplicate "
                            + e.getDuplicateValue() + ", already used by '"
                            + e.getExistingTitle() + "'");

                } catch (IllegalArgumentException e) {
                    // Book's validations (reference format, year, ISBN)
                    reasons.add("Line " + linesRead + ": invalid data -> " + e.getMessage());
                }
            }
        }
        // The reader is already closed here, on success or on failure

        return new ImportReport(linesRead, accepted, linesRead - accepted, reasons);
    }

    /**
     * Imports inside a work session: TWO resources in the same
     * try-with-resources, closed in the reverse order of opening.
     */
    public ImportReport importWithSession(String path, String employeeId, int day)
            throws IOException {

        try (LibrarySession session = new LibrarySession(employeeId, day, catalog);
             BufferedReader reader = new BufferedReader(new FileReader(path))) {

            List<String> reasons = new ArrayList<>();
            int linesRead = 0;
            int accepted = 0;
            String line;

            while ((line = reader.readLine()) != null) {
                linesRead++;
                if (line.isBlank() || line.startsWith("#")) { continue; }

                try {
                    String[] c = line.split(";");
                    catalog.register(new Book(c[0].trim(), c[1].trim(), c[2].trim(),
                            Integer.parseInt(c[3].trim()), c[4].trim()));
                    accepted++;
                    session.recordLoan("REGISTER " + c[0].trim());   // recorded in the shift

                } catch (RuntimeException e) {
                    reasons.add("Line " + linesRead + ": " + e.getClass().getSimpleName()
                            + " - " + e.getMessage());
                }
            }
            return new ImportReport(linesRead, accepted, linesRead - accepted, reasons);
        }
        // REVERSE closing: first the reader, then the session (which consolidates
        // its statistics and releases the catalogue lock).
    }

    /** Creates a sample file if it does not exist. Another try-with-resources. */
    public static void createSampleFile(String path) throws IOException {
        File file = new File(path);
        if (file.exists()) {
            return;
        }
        try (BufferedWriter writer = new BufferedWriter(new FileWriter(path))) {
            writer.write("# BiblioTech sample catalogue");             writer.newLine();
            writer.write("# reference;title;author;year;isbn");        writer.newLine();
            writer.write("BK-0001;Effective Java;Bloch;2018;978-0000000001");     writer.newLine();
            writer.write("BK-0002;Design Patterns;GoF;1994;978-0000000002");      writer.newLine();
            writer.write("BK-0003;Refactoring;Fowler;1999;978-0000000003");       writer.newLine();
            writer.write("BK-0004;No author");                                    writer.newLine();
            writer.write("BK-0005;Bad year;Author;thousand;978-0000000005");      writer.newLine();
            writer.write("BK-0001;Duplicate;Other;2020;978-0000000006");          writer.newLine();
            writer.write("BK-0007;Absurd year;Author;1200;978-0000000007");       writer.newLine();
        }
        System.out.println("  (sample file created at " + path + ")");
    }

    // ------------------------------------------------------------------

    public static void main(String[] args) {
        String path = "catalog-input.txt";

        Catalog catalog = new Catalog();
        CatalogImporter importer = new CatalogImporter(catalog);

        System.out.println("=== 1. Preparation ===");
        try {
            createSampleFile(path);
        } catch (IOException e) {
            System.out.println("  Could not create the sample file: " + e.getMessage());
            return;
        }

        System.out.println("\n=== 2. Normal import ===");
        try {
            ImportReport report = importer.importFile(path);
            System.out.print(report.summary());
            System.out.println("Catalogue: " + catalog.size() + " materials");
        } catch (IOException e) {
            System.out.println("  I/O failure: " + e.getMessage());
        }

        System.out.println("\n=== 3. Non-existent file ===");
        try {
            importer.importFile("does-not-exist.txt");
        } catch (java.io.FileNotFoundException e) {
            // Subclass of IOException: it can be caught separately
            System.out.println("  The file does not exist. Continuing with the current catalogue.");
            System.out.println("  Detail: " + e.getMessage());
        } catch (IOException e) {
            System.out.println("  Another I/O failure: " + e.getMessage());
        }

        System.out.println("\n=== 4. Import inside a session (two resources) ===");
        Catalog other = new Catalog();
        CatalogImporter withSession = new CatalogImporter(other);
        try {
            ImportReport report = withSession.importWithSession(path, "EMP-001", 20);
            System.out.print(report.summary());
        } catch (IOException e) {
            System.out.println("  Failure: " + e.getMessage());
        }

        System.out.println("\n=== Final state ===");
        System.out.println("  Main catalogue: " + catalog.size() + " materials");
        System.out.println("  Shifts completed: " + LibrarySession.getShiftsCompleted());
    }
}

=== 1. Preparation ===
  (sample file created at catalog-input.txt)

=== 2. Normal import ===
=== IMPORT REPORT ===
Lines read : 10
Accepted   : 3
Rejected   : 7
  * Line 6: missing fields -> 'BK-0004;No author'
  * Line 7: non-numeric year -> For input string: "thousand"
  * Line 8: REFERENCE duplicate BK-0001, already used by 'Effective Java'
  * Line 9: invalid data -> The publication year must be between 1450 and 2100, and it was: 1200
Catalogue: 3 materials

=== 3. Non-existent file ===
  The file does not exist. Continuing with the current catalogue.
  Detail: does-not-exist.txt (No such file or directory)

=== 4. Import inside a session (two resources) ===
  [session of EMP-001 opened on day 20]
  [session of EMP-001 closed] 3 loans, 0 returns, 0.00 EUR
=== IMPORT REPORT ===
Lines read : 10
Accepted   : 3
Rejected   : 7
...

=== Final state ===
  Main catalogue: 3 materials
  Shifts completed: 1