// With standard exceptions
try {
    manager.lend("BK-0001", "EMP-001", 12);
} catch (IllegalStateException e) {
    // What happened? Is the material on loan? Has the employee hit the limit?
    // Was the loan already returned? You have to read the MESSAGE to find out.
    if (e.getMessage().contains("limit")) {       // fragile, horrible, and it breaks on translation
        // ...
    }
}

// With domain exceptions
try {
    manager.lend("BK-0001", "EMP-001", 12);
} catch (MaterialNotAvailableException e) {
    offerReservation(e.getReference(), e.getExpectedReturnDay());
} catch (LoanLimitExceededException e) {
    showActiveLoans(e.getEmployeeId());
}

throw new IllegalStateException(
        "The employee EMP-001 (Marta Ruiz) already has 3 loans, the maximum is 3");

throw new LoanLimitExceededException(employee, Employee.MAX_CONCURRENT_LOANS);

// And whoever catches it:
} catch (LoanLimitExceededException e) {
    String emp  = e.getEmployeeId();              // the identifier, not its name in a string
    int limit   = e.getLimit();                   // the number, not a piece of text
    int current = e.getCurrentLoans();

    System.out.printf("%s has %d of %d loans.%n",
            e.getEmployeeName(), current, limit);
    offerEarlyReturn(emp);                        // the data can be USED
}

package com.nexussoftware.bibliotech.domain;

/** Minimal version: just the name and the message. */
public class MaterialNotFoundException extends RuntimeException {

    public MaterialNotFoundException(String message) {
        super(message);
    }
}

throw new MaterialNotFoundException("Material BK-9999 does not exist");

// BAD: extending Throwable directly
public class MyException extends Throwable { }      // legal, but never correct

// BAD: extending Error
public class MyException extends Error { }          // Error is for JVM failures

// BAD: extending a very specific standard exception for no reason
public class MyException extends NumberFormatException { }   // inherits alien semantics

package com.nexussoftware.bibliotech.domain;

/** Exception with the four canonical constructors. */
public class BiblioTechException extends RuntimeException {

    /** 1. No message, no cause. Not very useful, but it completes the contract. */
    public BiblioTechException() {
        super();
    }

    /** 2. With a message. The most used when ORIGINATING a failure. */
    public BiblioTechException(String message) {
        super(message);
    }

    /** 3. With a message and a cause. The one you must use when WRAPPING (06-03). */
    public BiblioTechException(String message, Throwable cause) {
        super(message, cause);
    }

    /** 4. Cause only: the message is derived from cause.toString(). */
    public BiblioTechException(Throwable cause) {
        super(cause);
    }
}

protected Throwable(String message, Throwable cause,
                    boolean enableSuppression, boolean writableStackTrace)

package com.nexussoftware.bibliotech.domain;

/**
 * The requested material does not exist in the catalogue.
 *
 * It carries the searched reference so that whoever catches it can
 * offer it in a message, look for alternatives or record it, without
 * having to parse the text message.
 */
public class MaterialNotFoundException extends BiblioTechException {

    private static final long serialVersionUID = 1L;

    /** An exception's fields must be final: an exception is immutable. */
    private final String searchedReference;
    private final int catalogSize;

    public MaterialNotFoundException(String searchedReference, int catalogSize) {
        // The message is built from the data: a single source of truth
        super("There is no material with the reference '" + searchedReference
                + "' (the catalogue has " + catalogSize + " materials)");
        this.searchedReference = searchedReference;
        this.catalogSize = catalogSize;
    }

    /** Variant for when another failure is wrapped. */
    public MaterialNotFoundException(String searchedReference, int catalogSize,
                                     Throwable cause) {
        super("There is no material with the reference '" + searchedReference
                + "' (the catalogue has " + catalogSize + " materials)", cause);
        this.searchedReference = searchedReference;
        this.catalogSize = catalogSize;
    }

    public String getSearchedReference() { return searchedReference; }
    public int getCatalogSize()          { return catalogSize; }

    /** Convenience method: the exception can contribute useful logic. */
    public boolean isCatalogEmpty() {
        return catalogSize == 0;
    }
}

try {
    Material m = catalog.getByReference(userInput);
    manager.lend(m.getReference(), "EMP-001", day);
} catch (MaterialNotFoundException e) {

    if (e.isCatalogEmpty()) {
        System.out.println("The catalogue is empty. Have you loaded the materials file?");
    } else {
        System.out.println("'" + e.getSearchedReference() + "' was not found.");
        // The DATA can be used to help: suggestions by prefix
        List<Material> similar = catalog.findByPrefix(
                e.getSearchedReference().substring(0, 3));
        if (!similar.isEmpty()) {
            System.out.println("Did you perhaps mean one of these?");
            similar.forEach(m -> System.out.println("  " + m.getReference()));
        }
    }
}

// Level 1: any BiblioTech domain failure (error boundary)
catch (BiblioTechException e) { ... }

// Level 2: any failure related to loans
catch (LoanException e) { ... }

// Level 3: this specific failure, with its data
catch (LoanLimitExceededException e) { use(e.getLimit()); }

try {
    manager.lend(reference, employeeId, day);
} catch (LoanLimitExceededException e) {            // leaf
    offerEarlyReturn(e.getEmployeeId());
} catch (LoanException e) {                          // branch
    System.out.println("The loan could not be completed: " + e.getMessage());
} catch (BiblioTechException e) {                    // root
    System.out.println("BiblioTech failure: " + e.getMessage());
}

try {
    application.start();
} catch (BiblioTechException e) {
    // EXPECTED domain failure: a clean message for the user
    System.out.println("Operation not completed: " + e.getMessage());
} catch (RuntimeException e) {
    // UNEXPECTED failure: it is a bug. Generic message + full log entry
    System.out.println("Internal error. Check the log (incident " + id + ").");
    logger.log(Level.SEVERE, "Unhandled failure", e);
}

public abstract class BiblioTechException extends RuntimeException {

    /** Stable code for the log and for support documentation. */
    public String getCode() {
        return getClass().getSimpleName().replace("Exception", "").toUpperCase();
    }

    /**
     * Is this a failure the user can fix themselves?
     * Subclasses redefine it when that is not the case.
     */
    public boolean isUserFixable() {
        return true;
    }

    /** Message suitable for showing on screen, with no internal details. */
    public String getUserMessage() {
        return getMessage();
    }
}

// What + data + expected
"The employee EMP-001 (Marta Ruiz) has 3 active loans and the limit is 3"

// What + data + context useful for acting
"The material BK-0001 ('Effective Java') is on loan to EMP-002 since day 12"

// What + the two colliding pieces of data
"A material with the reference BK-0001 already exists: 'Effective Java'"

warning: [serial] serializable class MaterialNotFoundException has no definition
of serialVersionUID

public class MaterialNotFoundException extends BiblioTechException {
    private static final long serialVersionUID = 1L;
    // ...
}

// PROBLEMATIC if the exception travels over the network and Employee is not Serializable
private final Employee employee;

// SAFE: String and int are always serialisable
private final String employeeId;
private final int limit;

// STANDARD: technical validation with no business meaning
Objects.requireNonNull(reference, "The reference cannot be null");
if (day < 1) {
    throw new IllegalArgumentException("The day must be 1 or later, and it was: " + day);
}
if (!reference.matches("BK-\\d{4}")) {
    throw new IllegalArgumentException("Invalid reference format: " + reference);
}

// YOUR OWN: a business rule with a name and with data
if (!material.isAvailable()) {
    throw new MaterialNotAvailableException(reference, material.getTitle(),
                                            material.getExpectedReturnDay());
}

protected Throwable(String message, Throwable cause,
                    boolean enableSuppression,      // does it accept suppressed exceptions? (06-06)
                    boolean writableStackTrace)     // does it capture the stack?

package com.nexussoftware.bibliotech.service;

/**
 * Signal exception, with no stack trace.
 *
 * WARNING: use ONLY when the three conditions hold:
 *   1. It is thrown in a very hot loop (thousands of times per second).
 *   2. It is caught immediately in the same method or very close by.
 *   3. The stack trace contributes NOTHING, because the throwing point is unique.
 *
 * If the three do not hold, this optimisation only manages to make a real
 * failure impossible to diagnose. It is the definition of premature optimisation.
 */
public class SearchInterruptedException extends RuntimeException {

    private static final long serialVersionUID = 1L;

    private final int position;

    public SearchInterruptedException(int position) {
        //      message, cause, suppression, stackTrace
        super("Search interrupted at position " + position, null, false, false);
        this.position = position;
    }

    public int getPosition() { return position; }
}

/** A single reused instance: zero memory allocations. */
private static final SearchInterruptedException SIGNAL =
        new SearchInterruptedException(-1);

// ...
throw SIGNAL;                         // builds nothing

package com.nexussoftware.bibliotech.domain;

/**
 * Root of all BiblioTech domain exceptions.
 *
 * It is abstract because nobody should throw it directly: it would be as
 * uninformative as the mute 'false' this module is eliminating.
 *
 * It is UNCHECKED (it extends RuntimeException) because it represents business
 * rules the caller normally cannot solve on the spot, and because forcing them
 * to be declared would pollute the whole application, lambdas included.
 */
public abstract class BiblioTechException extends RuntimeException {

    private static final long serialVersionUID = 1L;

    protected BiblioTechException(String message) {
        super(message);
    }

    protected BiblioTechException(String message, Throwable cause) {
        super(message, cause);
    }

    /**
     * Stable code for the failure, derived from the class name.
     * Useful for the log and for support documentation:
     * MATERIALNOTFOUND, LOANLIMITEXCEEDED, etc.
     */
    public String getCode() {
        return getClass().getSimpleName()
                .replace("Exception", "")
                .toUpperCase();
    }

    /**
     * Can the user fix this themselves?
     * By default yes; subclasses representing system failures redefine it.
     */
    public boolean isUserFixable() {
        return true;
    }
}

package com.nexussoftware.bibliotech.domain;

/** Failures related to the catalogue of materials. */
public abstract class CatalogException extends BiblioTechException {

    private static final long serialVersionUID = 1L;

    protected CatalogException(String message) { super(message); }

    protected CatalogException(String message, Throwable cause) { super(message, cause); }
}

package com.nexussoftware.bibliotech.domain;

/** Failures related to loans and returns. */
public abstract class LoanException extends BiblioTechException {

    private static final long serialVersionUID = 1L;

    protected LoanException(String message) { super(message); }

    protected LoanException(String message, Throwable cause) { super(message, cause); }
}

package com.nexussoftware.bibliotech.domain;

/** There is no material with the searched reference. */
public class MaterialNotFoundException extends CatalogException {

    private static final long serialVersionUID = 1L;

    private final String searchedReference;
    private final int catalogSize;

    public MaterialNotFoundException(String searchedReference, int catalogSize) {
        super("There is no material with the reference '" + searchedReference
                + "' (the catalogue has " + catalogSize + " materials)");
        this.searchedReference = searchedReference;
        this.catalogSize = catalogSize;
    }

    public String getSearchedReference() { return searchedReference; }
    public int getCatalogSize()          { return catalogSize; }
    public boolean isCatalogEmpty()      { return catalogSize == 0; }
}

package com.nexussoftware.bibliotech.domain;

/** An attempt to register a material with a reference or an ISBN that already exist. */
public class DuplicateReferenceException extends CatalogException {

    private static final long serialVersionUID = 1L;

    /** Kind of identifier that collides. An enum (04-07) avoids magic strings. */
    public enum Kind { REFERENCE, ISBN }

    private final Kind kind;
    private final String duplicateValue;
    private final String existingTitle;

    public DuplicateReferenceException(Kind kind, String duplicateValue, String existingTitle) {
        super("A material already exists with " + (kind == Kind.ISBN ? "the ISBN " : "the reference ")
                + duplicateValue + ": '" + existingTitle + "'");
        this.kind = kind;
        this.duplicateValue = duplicateValue;
        this.existingTitle = existingTitle;
    }

    public Kind getKind()             { return kind; }
    public String getDuplicateValue() { return duplicateValue; }
    public String getExistingTitle()  { return existingTitle; }
}

package com.nexussoftware.bibliotech.domain;

/** The material exists but is on loan to another employee. */
public class MaterialNotAvailableException extends LoanException {

    private static final long serialVersionUID = 1L;

    private final String reference;
    private final String title;
    private final String currentBorrowerId;
    private final int expectedReturnDay;

    public MaterialNotAvailableException(String reference, String title,
                                         String currentBorrowerId, int expectedReturnDay) {
        super("The material " + reference + " ('" + title + "') is on loan to "
                + currentBorrowerId + " and its return is expected on day " + expectedReturnDay);
        this.reference = reference;
        this.title = title;
        this.currentBorrowerId = currentBorrowerId;
        this.expectedReturnDay = expectedReturnDay;
    }

    public String getReference()         { return reference; }
    public String getTitle()             { return title; }
    public String getCurrentBorrowerId() { return currentBorrowerId; }
    public int getExpectedReturnDay()    { return expectedReturnDay; }

    /** Days remaining until the material is free again. */
    public int waitDays(int currentDay) {
        return Math.max(0, expectedReturnDay - currentDay);
    }
}

package com.nexussoftware.bibliotech.domain;

/** The employee has reached the maximum of concurrent loans. */
public class LoanLimitExceededException extends LoanException {

    private static final long serialVersionUID = 1L;

    private final String employeeId;
    private final String employeeName;
    private final int currentLoans;
    private final int limit;

    public LoanLimitExceededException(String employeeId, String employeeName,
                                      int currentLoans, int limit) {
        super("The employee " + employeeId + " (" + employeeName + ") has "
                + currentLoans + " active loans and the limit is " + limit);
        this.employeeId = employeeId;
        this.employeeName = employeeName;
        this.currentLoans = currentLoans;
        this.limit = limit;
    }

    public String getEmployeeId()   { return employeeId; }
    public String getEmployeeName() { return employeeName; }
    public int getCurrentLoans()    { return currentLoans; }
    public int getLimit()           { return limit; }

    /** How many materials must be returned before another can be borrowed. */
    public int returnsNeeded() {
        return Math.max(1, currentLoans - limit + 1);
    }
}

package com.nexussoftware.bibliotech.domain;

/** An attempt to return a loan that had already been returned. */
public class LoanAlreadyReturnedException extends LoanException {

    private static final long serialVersionUID = 1L;

    private final String loanReference;
    private final int originalReturnDay;

    public LoanAlreadyReturnedException(String loanReference, int originalReturnDay) {
        super("The loan " + loanReference + " was already returned on day "
                + originalReturnDay);
        this.loanReference = loanReference;
        this.originalReturnDay = originalReturnDay;
    }

    public String getLoanReference()  { return loanReference; }
    public int getOriginalReturnDay() { return originalReturnDay; }

    /**
     * This failure almost always indicates a sequencing problem in the code
     * or a double click by the user, not something the user can "fix".
     */
    @Override
    public boolean isUserFixable() {
        return false;
    }
}

package com.nexussoftware.bibliotech.service;

/**
 * The persisted catalogue cannot be read or written.
 *
 * It is CHECKED because it represents an environment failure (disk, permissions,
 * missing file) for which the application DOES have a reasonable alternative:
 * starting with an empty catalogue. Forcing that to be decided explicitly is
 * exactly what we want.
 *
 * It does not extend BiblioTechException because that root is unchecked and
 * represents business rules; this is an infrastructure failure.
 * Module 7 will develop the I/O part.
 */
public class CatalogNotAccessibleException extends Exception {

    private static final long serialVersionUID = 1L;

    private final String path;

    public CatalogNotAccessibleException(String path, Throwable cause) {
        super("Could not access the catalogue at '" + path + "'", cause);
        this.path = path;
    }

    public String getPath() { return path; }
}

package com.nexussoftware.bibliotech.service;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;

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

/** BiblioTech's catalogue with domain exceptions. */
public class Catalog {

    private final List<Material> materials = new ArrayList<>();
    private final Map<String, Material> indexByReference = new HashMap<>();
    private final Map<String, String> titlesByIsbn = new HashMap<>();

    /**
     * Registers a material.
     *
     * @throws NullPointerException           if the material is null (technical failure)
     * @throws DuplicateReferenceException    if the reference or the ISBN already exist
     */
    public void register(Material material) {
        // Technical validation: STANDARD exception
        Objects.requireNonNull(material, "The material to register cannot be null");

        String reference = material.getReference();

        // Business rule: OUR OWN exception, with data
        Material existing = indexByReference.get(reference);
        if (existing != null) {
            throw new DuplicateReferenceException(
                    DuplicateReferenceException.Kind.REFERENCE,
                    reference, existing.getTitle());
        }

        if (material instanceof Book book) {
            String titleWithThatIsbn = titlesByIsbn.get(book.getIsbn());
            if (titleWithThatIsbn != null) {
                throw new DuplicateReferenceException(
                        DuplicateReferenceException.Kind.ISBN,
                        book.getIsbn(), titleWithThatIsbn);
            }
            titlesByIsbn.put(book.getIsbn(), book.getTitle());
        }

        materials.add(material);
        indexByReference.put(reference, material);
    }

    /**
     * Gets a material REQUIRING that it exists. Never returns null.
     *
     * @throws MaterialNotFoundException if it does not exist
     */
    public Material getByReference(String reference) {
        Objects.requireNonNull(reference, "The reference cannot be null");

        Material found = indexByReference.get(reference);
        if (found == null) {
            throw new MaterialNotFoundException(reference, materials.size());
        }
        return found;
    }

    /** Searches ALLOWING that it does not exist. Never returns null: returns Optional. */
    public Optional<Material> findByReference(String reference) {
        if (reference == null) { return Optional.empty(); }
        return Optional.ofNullable(indexByReference.get(reference));
    }

    public List<Material> findByPrefix(String prefix) {
        List<Material> result = new ArrayList<>();
        for (Material m : materials) {
            if (m.getReference().startsWith(prefix)) {
                result.add(m);
            }
        }
        return result;
    }

    public boolean exists(String reference) {
        return reference != null && indexByReference.containsKey(reference);
    }

    public int size()               { return materials.size(); }
    public List<Material> list()    { return List.copyOf(materials); }
}

package com.nexussoftware.bibliotech.presentation;

import com.nexussoftware.bibliotech.domain.*;
import com.nexussoftware.bibliotech.service.Catalog;
import com.nexussoftware.bibliotech.service.LoanManager;

/**
 * Demonstrates the difference between catching by TYPE with structured data
 * and catching standard types by reading the message.
 */
public class DomainExceptionsDemo {

    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"));

        LoanManager manager = new LoanManager(catalog);
        manager.enrol(new Employee("Marta Ruiz", "EMP-001"));
        manager.enrol(new Employee("Diego Alonso", "EMP-002"));

        // Marta uses up her allowance
        manager.lend("BK-0001", "EMP-001", 10);
        manager.lend("BK-0002", "EMP-001", 10);
        manager.lend("BK-0003", "EMP-001", 10);

        System.out.println("=== Failures, each with ITS handler ===\n");

        operate(manager, catalog, "BK-9999", "EMP-001", 12);   // not found
        operate(manager, catalog, "BK-0001", "EMP-002", 12);   // not available
        operate(manager, catalog, "BK-0001", "EMP-001", 12);   // not available (and limit)

        System.out.println("\n=== Duplicates ===\n");
        register(catalog, new Book("BK-0001", "Another title", "X", 2020, "978-0000000009"));
        register(catalog, new Book("BK-0004", "Copy", "Bloch", 2018, "978-0000000001"));

        System.out.println("\n=== Catching by the ROOT: the whole domain in one go ===\n");
        try {
            catalog.getByReference("BK-7777");
        } catch (BiblioTechException e) {
            System.out.println("Code: " + e.getCode());
            System.out.println("Message: " + e.getMessage());
            System.out.println("User fixable? " + e.isUserFixable());
        }
    }

    /** Each kind of failure is handled DIFFERENTLY using its data. */
    private static void operate(LoanManager manager, Catalog catalog,
                                String reference, String employeeId, int day) {
        System.out.println("--- lend(" + reference + ", " + employeeId + ") ---");
        try {
            manager.lend(reference, employeeId, day);
            System.out.println("  OK");

        } catch (MaterialNotFoundException e) {
            // Uses the exception's DATA to help the user
            System.out.println("  '" + e.getSearchedReference() + "' was not found.");
            if (e.isCatalogEmpty()) {
                System.out.println("  The catalogue is empty: load the materials first.");
            } else {
                var similar = catalog.findByPrefix(
                        e.getSearchedReference().substring(0, 3));
                System.out.println("  Materials with a similar prefix: " + similar.size());
            }

        } catch (MaterialNotAvailableException e) {
            System.out.println("  '" + e.getTitle() + "' is held by " + e.getCurrentBorrowerId() + ".");
            System.out.println("  Back in " + e.waitDays(day) + " days.");
            System.out.println("  -> Added to the reservation queue for " + e.getReference());

        } catch (LoanLimitExceededException e) {
            System.out.println("  " + e.getEmployeeName() + " has "
                    + e.getCurrentLoans() + "/" + e.getLimit() + " loans.");
            System.out.println("  They must return " + e.returnsNeeded()
                    + " material(s) before borrowing another.");
        }
    }

    private static void register(Catalog catalog, Material material) {
        try {
            catalog.register(material);
            System.out.println("Registered: " + material.getReference());
        } catch (DuplicateReferenceException e) {
            // The KIND of duplicate allows a precise message, with no text parsing
            String whatCollides = (e.getKind() == DuplicateReferenceException.Kind.ISBN)
                    ? "The ISBN" : "The reference";
            System.out.println(whatCollides + " " + e.getDuplicateValue()
                    + " is already used by '" + e.getExistingTitle() + "'. Registration rejected.");
        }
    }
}

=== Failures, each with ITS handler ===

--- lend(BK-9999, EMP-001) ---
  'BK-9999' was not found.
  Materials with a similar prefix: 3
--- lend(BK-0001, EMP-002) ---
  'Effective Java' is held by EMP-001.
  Back in 13 days.
  -> Added to the reservation queue for BK-0001
--- lend(BK-0001, EMP-001) ---
  'Effective Java' is held by EMP-001.
  Back in 13 days.
  -> Added to the reservation queue for BK-0001

=== Duplicates ===

The reference BK-0001 is already used by 'Effective Java'. Registration rejected.
The ISBN 978-0000000001 is already used by 'Effective Java'. Registration rejected.

=== Catching by the ROOT: the whole domain in one go ===

Code: MATERIALNOTFOUND
Message: There is no material with the reference 'BK-7777' (the catalogue has 3 materials)
User fixable? true

public class ReservationError extends Throwable {
    public ReservationError() { }
}

public class InvalidReservation extends ReservationError {
    public String message;
    public InvalidReservation(String m) { this.message = m; }
}

public class ReservationDateError extends Exception {
    public ReservationDateError(String m) { super(m); }
}

public class DuplicateReservationError extends InvalidReservation {
    public DuplicateReservationError() { super("Error"); }
}

// Typical use in the code:
// try {
//     reservationQueue.reserve(reference, employeeId, day);
// } catch (Throwable t) {
//     if (t.getMessage() != null && t.getMessage().startsWith("Error")) {
//         System.out.println("Reservation failure");
//     }
// }

package com.nexussoftware.bibliotech.domain;

import java.util.List;

/**
 * The employee has accrued a fine that stops them taking out more loans
 * until it is settled.
 *
 * It carries the complete breakdown so that the presentation layer can
 * show a receipt, and so that the service layer can decide whether to grant
 * an exception to the rule.
 */
public class ExcessiveFineException extends LoanException {

    private static final long serialVersionUID = 1L;

    public static final double MAX_FINE = 20.0;

    private final String employeeId;
    private final String employeeName;
    private final double accruedAmount;
    private final double allowedThreshold;
    private final List<String> finedMaterials;

    public ExcessiveFineException(String employeeId, String employeeName,
                                  double accruedAmount, double allowedThreshold,
                                  List<String> finedMaterials) {
        super(buildMessage(employeeId, employeeName, accruedAmount,
                allowedThreshold, finedMaterials));
        this.employeeId = employeeId;
        this.employeeName = employeeName;
        this.accruedAmount = accruedAmount;
        this.allowedThreshold = allowedThreshold;
        // Defensive copy: the exception must be immutable even if the original
        // list changes afterwards (03-07)
        this.finedMaterials = List.copyOf(finedMaterials);
    }

    public ExcessiveFineException(String employeeId, String employeeName,
                                  double accruedAmount, double allowedThreshold,
                                  List<String> finedMaterials, Throwable cause) {
        super(buildMessage(employeeId, employeeName, accruedAmount,
                allowedThreshold, finedMaterials), cause);
        this.employeeId = employeeId;
        this.employeeName = employeeName;
        this.accruedAmount = accruedAmount;
        this.allowedThreshold = allowedThreshold;
        this.finedMaterials = List.copyOf(finedMaterials);
    }

    /**
     * The message is built in a static method because it has to be called
     * inside the super(...), before the fields exist.
     */
    private static String buildMessage(String employeeId, String employeeName,
                                       double amount, double threshold,
                                       List<String> materials) {
        return String.format(
                "The employee %s (%s) has accrued %.2f EUR in fines, above the threshold of %.2f EUR, "
                        + "on %d material(s)",
                employeeId, employeeName, amount, threshold, materials.size());
    }

    public String getEmployeeId()      { return employeeId; }
    public String getEmployeeName()    { return employeeName; }
    public double getAccruedAmount()   { return accruedAmount; }
    public double getAllowedThreshold(){ return allowedThreshold; }

    /** Already immutable thanks to List.copyOf, but returned explicitly this way. */
    public List<String> getFinedMaterials() {
        return finedMaterials;
    }

    // ---------- Convenience methods ----------

    /** The minimum that must be paid to get back below the threshold. */
    public double getExcess() {
        return Math.max(0.0, accruedAmount - allowedThreshold);
    }

    /** Has the system's absolute fine cap been reached? */
    public boolean overMaxFine() {
        return accruedAmount >= MAX_FINE;
    }

    /** Readable breakdown, one line per material. */
    public String getSummary() {
        StringBuilder sb = new StringBuilder();
        sb.append(String.format("Fine for %s: %.2f EUR (threshold %.2f, excess %.2f)%n",
                employeeName, accruedAmount, allowedThreshold, getExcess()));
        for (String reference : finedMaterials) {
            sb.append("  - ").append(reference).append('\n');
        }
        if (overMaxFine()) {
            sb.append(String.format("  ATTENTION: the maximum fine has been reached (%.2f EUR)%n",
                    MAX_FINE));
        }
        return sb.toString();
    }

    /** The employee can solve it by paying: it is fixable by them. */
    @Override
    public boolean isUserFixable() {
        return true;
    }

    // ---------- Demonstration ----------

    public static void main(String[] args) {
        try {
            throw new ExcessiveFineException(
                    "EMP-001", "Marta Ruiz",
                    23.75, 10.0,
                    List.of("BK-0001", "BK-0002", "REV-0007"));

        } catch (ExcessiveFineException e) {
            System.out.println("=== Specific catch ===");
            System.out.println("Code              : " + e.getCode());
            System.out.println("Message           : " + e.getMessage());
            System.out.println("Employee          : " + e.getEmployeeId()
                    + " (" + e.getEmployeeName() + ")");
            System.out.printf ("Accrued amount    : %.2f EUR%n", e.getAccruedAmount());
            System.out.printf ("Allowed threshold : %.2f EUR%n", e.getAllowedThreshold());
            System.out.printf ("Excess to pay     : %.2f EUR%n", e.getExcess());
            System.out.println("Over the maximum  : " + e.overMaxFine());
            System.out.println("Materials         : " + e.getFinedMaterials());
            System.out.println("User fixable: " + e.isUserFixable());

            System.out.println("\n=== Summary for the receipt ===");
            System.out.print(e.getSummary());

            // Demonstration that the list is IMMUTABLE
            System.out.println("=== Immutability ===");
            try {
                e.getFinedMaterials().add("BK-9999");
            } catch (UnsupportedOperationException uoe) {
                System.out.println("The list of materials cannot be modified. Correct.");
            }
        }

        // Catching by the branch and by the root
        System.out.println("\n=== Catching by the LoanException branch ===");
        try {
            throw new ExcessiveFineException("EMP-002", "Diego Alonso",
                    12.5, 10.0, List.of("BK-0003"));
        } catch (LoanException e) {
            System.out.println("Loan failure [" + e.getCode() + "]: " + e.getMessage());
        }
    }
}

=== Specific catch ===
Code              : EXCESSIVEFINE
Message           : The employee EMP-001 (Marta Ruiz) has accrued 23.75 EUR in fines, above the threshold of 10.00 EUR, on 3 material(s)
Employee          : EMP-001 (Marta Ruiz)
Accrued amount    : 23.75 EUR
Allowed threshold : 10.00 EUR
Excess to pay     : 13.75 EUR
Over the maximum  : true
Materials         : [BK-0001, BK-0002, REV-0007]
User fixable: true

=== Summary for the receipt ===
Fine for Marta Ruiz: 23.75 EUR (threshold 10.00, excess 13.75)
  - BK-0001
  - BK-0002
  - REV-0007
  ATTENTION: the maximum fine has been reached (20.00 EUR)
=== Immutability ===
The list of materials cannot be modified. Correct.

=== Catching by the LoanException branch ===
Loan failure [EXCESSIVEFINE]: The employee EMP-002 (Diego Alonso) has accrued 12.50 EUR in fines, above the threshold of 10.00 EUR, on 1 material(s)

package com.nexussoftware.bibliotech.domain;

/** Root of the reservation subsystem's failures. */
public abstract class ReservationException extends BiblioTechException {

    private static final long serialVersionUID = 1L;

    private final String reference;
    private final String employeeId;

    protected ReservationException(String message, String reference, String employeeId) {
        super(message);
        this.reference = reference;
        this.employeeId = employeeId;
    }

    protected ReservationException(String message, String reference, String employeeId,
                                   Throwable cause) {
        super(message, cause);
        this.reference = reference;
        this.employeeId = employeeId;
    }

    /** Data common to the whole family: declared once, in the root. */
    public String getReference()  { return reference; }
    public String getEmployeeId() { return employeeId; }
}

package com.nexussoftware.bibliotech.domain;

/** The employee already has an active reservation for that material. */
public class DuplicateReservationException extends ReservationException {

    private static final long serialVersionUID = 1L;

    private final int currentPosition;

    public DuplicateReservationException(String reference, String employeeId, int currentPosition) {
        super("The employee " + employeeId + " already has a reservation for " + reference
                + " at position " + currentPosition + " of the queue",
                reference, employeeId);
        this.currentPosition = currentPosition;
    }

    public int getCurrentPosition() { return currentPosition; }
}

package com.nexussoftware.bibliotech.domain;

/** The reservation day is not valid for that material. */
public class InvalidReservationDayException extends ReservationException {

    private static final long serialVersionUID = 1L;

    private final int requestedDay;
    private final int minimumDay;

    public InvalidReservationDayException(String reference, String employeeId,
                                          int requestedDay, int minimumDay) {
        super("The reservation for " + reference + " was requested for day " + requestedDay
                + ", but the material will not be available until day " + minimumDay,
                reference, employeeId);
        this.requestedDay = requestedDay;
        this.minimumDay = minimumDay;
    }

    public int getRequestedDay() { return requestedDay; }
    public int getMinimumDay()   { return minimumDay; }
    public int getWaitDays()     { return Math.max(0, minimumDay - requestedDay); }
}

try {
    int position = reservationQueue.reserve(reference, employeeId, day);
    System.out.println("Reserved. Position in the queue: " + position);

} catch (DuplicateReservationException e) {
    // The DATA is used, not the text
    System.out.println("You already had a reservation for " + e.getReference()
            + ", at position " + e.getCurrentPosition() + ". It has not been duplicated.");

} catch (InvalidReservationDayException e) {
    System.out.println("That material will not be free for another "
            + e.getWaitDays() + " days.");
    System.out.println("Do you want to reserve it for day " + e.getMinimumDay() + "? (y/n)");

} catch (ReservationException e) {
    // Safety net at the BRANCH, not at Throwable
    System.out.println("The reservation could not be completed [" + e.getCode() + "]: "
            + e.getMessage());
}

package com.nexussoftware.bibliotech.domain;

/** Root of the reservation queue's failures. */
public abstract class ReservationException extends BiblioTechException {
    private static final long serialVersionUID = 1L;
    protected ReservationException(String message) { super(message); }
}

package com.nexussoftware.bibliotech.domain;

public class DuplicateReservationException extends ReservationException {

    private static final long serialVersionUID = 1L;

    private final String reference;
    private final String employeeId;
    private final int currentPosition;

    public DuplicateReservationException(String reference, String employeeId, int currentPosition) {
        super("The employee " + employeeId + " has already reserved " + reference
                + " (position " + currentPosition + " of the queue)");
        this.reference = reference;
        this.employeeId = employeeId;
        this.currentPosition = currentPosition;
    }

    public String getReference()    { return reference; }
    public String getEmployeeId()   { return employeeId; }
    public int getCurrentPosition() { return currentPosition; }
}

package com.nexussoftware.bibliotech.domain;

public class ReservationQueueFullException extends ReservationException {

    private static final long serialVersionUID = 1L;

    private final String reference;
    private final int maximum;
    private final int estimatedAvailabilityDay;

    public ReservationQueueFullException(String reference, int maximum,
                                         int estimatedAvailabilityDay) {
        super("The reservation queue for " + reference + " is full (" + maximum
                + " reservations). Estimated availability: day " + estimatedAvailabilityDay);
        this.reference = reference;
        this.maximum = maximum;
        this.estimatedAvailabilityDay = estimatedAvailabilityDay;
    }

    public String getReference()               { return reference; }
    public int getMaximum()                    { return maximum; }
    public int getEstimatedAvailabilityDay()   { return estimatedAvailabilityDay; }

    @Override
    public boolean isUserFixable() {
        return false;   // the user can do nothing: the queue is full
    }
}

package com.nexussoftware.bibliotech.domain;

public class ReservationNotFoundException extends ReservationException {

    private static final long serialVersionUID = 1L;

    private final String reference;
    private final String employeeId;

    public ReservationNotFoundException(String reference, String employeeId) {
        super("The employee " + employeeId + " has no reservation for " + reference);
        this.reference = reference;
        this.employeeId = employeeId;
    }

    public String getReference()  { return reference; }
    public String getEmployeeId() { return employeeId; }
}

package com.nexussoftware.bibliotech.service;

import java.util.ArrayDeque;
import java.util.Deque;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;

import com.nexussoftware.bibliotech.domain.ReservationQueueFullException;
import com.nexussoftware.bibliotech.domain.DuplicateReservationException;
import com.nexussoftware.bibliotech.domain.ReservationException;
import com.nexussoftware.bibliotech.domain.ReservationNotFoundException;

/**
 * FIFO reservation queue per material (picks up the ArrayDeque from 05-07).
 *
 * Error policy:
 *  - Invalid arguments        -> STANDARD exceptions (NPE, IllegalArgument).
 *  - Business rules           -> OUR OWN exceptions with data.
 */
public class ReservationQueue {

    public static final int MAX_RESERVATIONS_PER_MATERIAL = 5;
    private static final int ESTIMATED_DAYS_PER_TURN = 15;

    /** An employee's reservation of a material (record, 04-07). */
    public record Reservation(String reference, String employeeId, int day) { }

    private final Map<String, Deque<Reservation>> queuesByMaterial = new HashMap<>();

    /**
     * Adds a reservation to the end of the material's queue.
     *
     * @return position in the queue, 1 being the next one to be served
     * @throws NullPointerException              if any argument is null
     * @throws IllegalArgumentException          if the day is less than 1
     * @throws DuplicateReservationException     if that employee already reserved that material
     * @throws ReservationQueueFullException     if the queue has reached the maximum
     */
    public int reserve(String reference, String employeeId, int day) {
        // Technical validation: standard exceptions
        Objects.requireNonNull(reference, "The reference cannot be null");
        Objects.requireNonNull(employeeId, "The employee identifier cannot be null");
        if (day < 1) {
            throw new IllegalArgumentException("The day must be 1 or later, and it was: " + day);
        }

        Deque<Reservation> queue = queuesByMaterial.computeIfAbsent(reference, r -> new ArrayDeque<>());

        // Business rule 1: no duplicates
        int already = positionIn(queue, employeeId);
        if (already > 0) {
            throw new DuplicateReservationException(reference, employeeId, already);
        }

        // Business rule 2: queue full
        if (queue.size() >= MAX_RESERVATIONS_PER_MATERIAL) {
            int estimatedDay = day + queue.size() * ESTIMATED_DAYS_PER_TURN;
            throw new ReservationQueueFullException(reference, MAX_RESERVATIONS_PER_MATERIAL, estimatedDay);
        }

        queue.addLast(new Reservation(reference, employeeId, day));
        return queue.size();
    }

    /**
     * Cancels an employee's reservation of a material.
     *
     * @throws ReservationNotFoundException if there was no such reservation
     */
    public void cancel(String reference, String employeeId) {
        Objects.requireNonNull(reference, "The reference cannot be null");
        Objects.requireNonNull(employeeId, "The employee identifier cannot be null");

        Deque<Reservation> queue = queuesByMaterial.get(reference);
        if (queue == null) {
            throw new ReservationNotFoundException(reference, employeeId);
        }

        // removeIf on a Deque: the safe way to remove while iterating (05-04)
        boolean removed = queue.removeIf(r -> r.employeeId().equals(employeeId));
        if (!removed) {
            throw new ReservationNotFoundException(reference, employeeId);
        }
        if (queue.isEmpty()) {
            queuesByMaterial.remove(reference);        // do not leave empty queues in the map
        }
    }

    /**
     * Takes the first one out of the queue. Returns an empty Optional if nobody is
     * waiting: here absence is a NORMAL case, not a failure.
     */
    public Optional<Reservation> serveNext(String reference) {
        Deque<Reservation> queue = queuesByMaterial.get(reference);
        if (queue == null || queue.isEmpty()) {
            return Optional.empty();
        }
        Reservation first = queue.pollFirst();
        if (queue.isEmpty()) {
            queuesByMaterial.remove(reference);
        }
        return Optional.of(first);
    }

    /** The employee's position in that material's queue, or -1 if not there. */
    public int positionOf(String reference, String employeeId) {
        Deque<Reservation> queue = queuesByMaterial.get(reference);
        if (queue == null) { return -1; }
        int p = positionIn(queue, employeeId);
        return (p > 0) ? p : -1;
    }

    /** Returns the position 1..n, or 0 if not there. */
    private int positionIn(Deque<Reservation> queue, String employeeId) {
        int position = 1;
        for (Iterator<Reservation> it = queue.iterator(); it.hasNext(); position++) {
            if (it.next().employeeId().equals(employeeId)) {
                return position;
            }
        }
        return 0;
    }

    public int queueSize(String reference) {
        Deque<Reservation> queue = queuesByMaterial.get(reference);
        return (queue == null) ? 0 : queue.size();
    }

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

    public static void main(String[] args) {
        ReservationQueue queues = new ReservationQueue();
        String BOOK = "BK-0001";

        System.out.println("=== Correct reservations ===");
        System.out.println("Marta -> position " + queues.reserve(BOOK, "EMP-001", 10));
        System.out.println("Diego -> position " + queues.reserve(BOOK, "EMP-002", 11));
        System.out.println("Nuria -> position " + queues.reserve(BOOK, "EMP-003", 12));

        System.out.println("\n=== Failures ===");
        attempt("Duplicate reservation", () -> queues.reserve(BOOK, "EMP-001", 13));
        attempt("Cancel a non-existent one", () -> queues.cancel(BOOK, "EMP-009"));
        attempt("Invalid day", () -> queues.reserve(BOOK, "EMP-004", 0));
        attempt("Null reference", () -> queues.reserve(null, "EMP-004", 5));

        // Fill the queue up to the maximum
        queues.reserve(BOOK, "EMP-004", 13);
        queues.reserve(BOOK, "EMP-005", 14);
        System.out.println("\nQueue for " + BOOK + ": " + queues.queueSize(BOOK)
                + "/" + MAX_RESERVATIONS_PER_MATERIAL);
        attempt("Queue full", () -> queues.reserve(BOOK, "EMP-006", 15));

        System.out.println("\n=== FIFO service ===");
        Optional<Reservation> next;
        while ((next = queues.serveNext(BOOK)).isPresent()) {
            Reservation r = next.get();
            System.out.println("  Served " + r.employeeId() + " (reserved on day " + r.day() + ")");
        }
        System.out.println("Queue empty: " + (queues.queueSize(BOOK) == 0));
    }

    /** Handler that catches by the BRANCH and uses getCode() from the root. */
    private static void attempt(String description, Runnable action) {
        try {
            action.run();
            System.out.println("[" + description + "] -> did not fail (unexpected)");
        } catch (ReservationException e) {
            System.out.println("[" + description + "] [" + e.getCode() + "] " + e.getMessage()
                    + " | fixable: " + e.isUserFixable());
        } catch (NullPointerException | IllegalArgumentException e) {
            System.out.println("[" + description + "] [TECHNICAL] "
                    + e.getClass().getSimpleName() + ": " + e.getMessage());
        }
    }
}

=== Correct reservations ===
Marta -> position 1
Diego -> position 2
Nuria -> position 3

=== Failures ===
[Duplicate reservation] [DUPLICATERESERVATION] The employee EMP-001 has already reserved BK-0001 (position 1 of the queue) | fixable: true
[Cancel a non-existent one] [RESERVATIONNOTFOUND] The employee EMP-009 has no reservation for BK-0001 | fixable: true
[Invalid day] [TECHNICAL] IllegalArgumentException: The day must be 1 or later, and it was: 0
[Null reference] [TECHNICAL] NullPointerException: The reference cannot be null

Queue for BK-0001: 5/5
[Queue full] [RESERVATIONQUEUEFULL] The reservation queue for BK-0001 is full (5 reservations). Estimated availability: day 90 | fixable: false

=== FIFO service ===
  Served EMP-001 (reserved on day 10)
  Served EMP-002 (reserved on day 11)
  Served EMP-003 (reserved on day 12)
  Served EMP-004 (reserved on day 13)
  Served EMP-005 (reserved on day 14)
Queue empty: true