// BAD: catches where it happens, unable to decide anything
public Material find(String reference) {
    try {
        return catalog.getByReference(reference);
    } catch (MaterialNotFoundException e) {
        e.printStackTrace();       // not a decision
        return null;               // and now we return the null that took so much effort to remove
    }
}

// GOOD: nothing is caught. It goes up to whoever can decide.
public Material find(String reference) {
    return catalog.getByReference(reference);
}

package com.nexussoftware.bibliotech.presentation;

import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.domain.BiblioTechException;

/**
 * BiblioTech's entry point with an error boundary.
 *
 * Structure of the boundary, from most specific to most general:
 *   1. BiblioTechException : expected domain failure -> clean message, exit 1
 *   2. RuntimeException    : bug -> generic message with an incident, full log, exit 2
 *   3. Error               : JVM failure -> minimal log and immediate exit, exit 3
 */
public class BiblioTechApp {

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

    public static void main(String[] args) {
        LogConfiguration.initialise();
        installGlobalHandler();

        LOG.info("BiblioTech starting up");

        try {
            new BiblioTechMenu().start();
            LOG.info("BiblioTech finished correctly");

        } catch (BiblioTechException e) {
            // EXPECTED domain failure that nobody handled. Rare, but readable.
            System.err.println();
            System.err.println("The operation could not be completed: " + e.getMessage());
            LOG.log(Level.WARNING, "Unhandled domain exception [" + e.getCode() + "]", e);
            System.exit(1);

        } catch (RuntimeException e) {
            // UNEXPECTED failure: it is a bug. The user must not see the details.
            String incident = generateIncidentId();
            System.err.println();
            System.err.println("An internal error has occurred.");
            System.err.println("Incident: " + incident);
            System.err.println("Please report this code to the Nexus Software support team.");
            LOG.log(Level.SEVERE, "Unhandled error. Incident " + incident, e);
            System.exit(2);

        } catch (Error e) {
            // JVM failure: it cannot be recovered from. Log the minimum and leave.
            // It is caught HERE and only here, to leave a record before dying.
            System.err.println();
            System.err.println("Unrecoverable virtual machine error: "
                    + e.getClass().getSimpleName());
            try {
                LOG.log(Level.SEVERE, "Unrecoverable error", e);
            } catch (Throwable ignored) {
                // If it cannot even be logged (e.g. OutOfMemoryError),
                // there is nothing more to do. It is not propagated so as not to hide the Error.
            }
            System.exit(3);
        }
    }

    /** Short identifier the user can report to support. */
    private static String generateIncidentId() {
        return "INC-" + Long.toHexString(System.nanoTime()).toUpperCase().substring(0, 8);
    }

    private static void installGlobalHandler() {
        Thread.setDefaultUncaughtExceptionHandler((thread, failure) ->
                LOG.log(Level.SEVERE, "Uncaught exception in thread '"
                        + thread.getName() + "'", failure));
    }
}

package com.nexussoftware.bibliotech.presentation;

import java.util.logging.Level;
import java.util.logging.Logger;

public final class GlobalHandler {

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

    private GlobalHandler() { }

    public static void install() {
        Thread.setDefaultUncaughtExceptionHandler((thread, failure) -> {
            // This code runs when an exception escapes from ANY thread
            LOG.log(Level.SEVERE,
                    "Uncaught exception in thread '" + thread.getName()
                            + "' (id " + thread.threadId() + ")", failure);

            if (failure instanceof Error) {
                LOG.severe("Unrecoverable error: application shutdown requested");
                System.exit(3);
            }
        });

        // Shutdown hook: last chance for clean-up (06-05)
        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            LOG.info("BiblioTech shutting down: consolidating state");
            // In module 7, the catalogue will be persisted here
        }, "bibliotech-shutdown"));
    }

    public static void main(String[] args) {
        install();

        Thread secondaryThread = new Thread(() -> {
            throw new IllegalStateException("Failure in the maintenance task");
        }, "maintenance");

        secondaryThread.start();

        try { secondaryThread.join(); } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }

        System.out.println("The main thread is still alive, but the failure WAS LOGGED");
    }
}

// What the user sees
System.err.println("The loan could not be completed.");
System.err.println("Incident: INC-A3F91C0B");
System.err.println("Please report this code to the support team.");

// What goes to the log
LOG.log(Level.SEVERE, "Failure lending BK-0001 to EMP-001 on day 12. Incident INC-A3F91C0B", e);

package com.nexussoftware.bibliotech.service;

import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * BiblioTech start-up with graceful degradation: the application works
 * even if optional components are missing, and it only aborts if something essential is.
 */
public class BiblioTechStartup {

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

    private boolean noticesAvailable = true;
    private boolean exportAvailable = true;

    public Catalog start(String catalogPath) {
        Catalog catalog = new Catalog();

        // --- OPTIONAL component 1: previous catalogue ---
        try {
            loadCatalog(catalog, catalogPath);
            LOG.info(() -> "Catalogue loaded: " + catalog.size() + " materials");

        } catch (CatalogNotAccessibleException e) {
            // DEGRADATION: work is possible with no previous catalogue; we start empty.
            LOG.log(Level.WARNING,
                    "Could not load the catalogue from '" + e.getPath()
                            + "'. Starting with an empty catalogue.", e);
            System.out.println("Notice: there was no previous catalogue. Starting from scratch.");
        }

        // --- OPTIONAL component 2: notice service ---
        try {
            connectNoticeService();
            LOG.info("Notice service available");
        } catch (RuntimeException e) {
            noticesAvailable = false;
            LOG.log(Level.WARNING, "Notice service unavailable; notices will queue up", e);
            System.out.println("Notice: due-date notices will not be sent in this session.");
        }

        // --- ESSENTIAL component: configuration ---
        // If this fails, there is NO degradation: it aborts. Carrying on with an
        // unknown rate would produce incorrect fines, which is worse than not starting.
        int loanDays = readRequiredConfiguration("loan.days");
        LOG.config(() -> "Configuration: loan.days=" + loanDays);

        return catalog;
    }

    public boolean canSendNotices()  { return noticesAvailable; }
    public boolean canExport()       { return exportAvailable; }

    private void loadCatalog(Catalog catalog, String path) throws CatalogNotAccessibleException {
        throw new CatalogNotAccessibleException(path,
                new java.io.FileNotFoundException(path + " (No such file or directory)"));
    }

    private void connectNoticeService() {
        throw new IllegalStateException("The notice service is not responding on port 8080");
    }

    private int readRequiredConfiguration(String key) {
        return 15;   // in module 7 this will come from a .properties file
    }
}

// PRIOR VALIDATION: cheap, the case is frequent and there is no race
if (catalog.exists(reference)) {
    Material m = catalog.getByReference(reference);
    // ...
}

// Better still with the method returning Optional
catalog.findByReference(reference)
       .ifPresent(m -> System.out.println(m.getTitle()));

// EXCEPTION: the conversion cannot be validated without doing it
try {
    int days = Integer.parseInt(input);
} catch (NumberFormatException e) {
    // Writing a correct integer validator (sign, range, overflow)
    // is more error-prone than catching
}

// COMPULSORY EXCEPTION: race condition
// With files or shared resources, "check then use" is not atomic:
// between the exists() and the open() another process may have deleted the file.
try (BufferedReader r = new BufferedReader(new FileReader(path))) {
    // ...
} catch (FileNotFoundException e) {
    // The only reliable way
}

// You have already been using it in BiblioTech since 06-03
public Optional<Material> findByReference(String reference) {
    return Optional.ofNullable(indexByReference.get(reference));
}

package com.nexussoftware.bibliotech.service;

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

/**
 * Result of an operation that can fail, WITHOUT throwing.
 *
 * Useful when you want to accumulate SEVERAL errors instead of aborting on the first:
 * validating a form, importing a file, checking business rules.
 */
public class Result {

    private final boolean success;
    private final List<String> errors;

    private Result(boolean success, List<String> errors) {
        this.success = success;
        this.errors = List.copyOf(errors);
    }

    public static Result ok() {
        return new Result(true, List.of());
    }

    public static Result withErrors(List<String> errors) {
        return new Result(false, errors);
    }

    public boolean isSuccess()       { return success; }
    public List<String> getErrors()  { return errors; }

    public String describe() {
        if (success) { return "OK"; }
        return "Rejected (" + errors.size() + " problems):\n  - "
                + String.join("\n  - ", errors);
    }

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

    /** Example: validating a registration accumulating ALL the problems. */
    public static Result validateRegistration(String reference, String title, int year, String isbn) {
        List<String> errors = new ArrayList<>();

        if (reference == null || !reference.matches("BK-\\d{4}")) {
            errors.add("The reference must have the format BK-NNNN, and it was: " + reference);
        }
        if (title == null || title.isBlank()) {
            errors.add("The title cannot be empty");
        }
        if (year < 1450 || year > 2100) {
            errors.add("The year must be between 1450 and 2100, and it was: " + year);
        }
        if (isbn == null || !isbn.matches("97[89]-\\d{10}")) {
            errors.add("The ISBN must have the format 978-NNNNNNNNNN, and it was: " + isbn);
        }

        return errors.isEmpty() ? ok() : withErrors(errors);
    }

    public static void main(String[] args) {
        System.out.println(validateRegistration("BK-0001", "Effective Java", 2018, "978-0000000001")
                .describe());
        System.out.println();
        System.out.println(validateRegistration("B-1", "", 1200, "12345").describe());
    }
}

OK

Rejected (4 problems):
  - The reference must have the format BK-NNNN, and it was: B-1
  - The title cannot be empty
  - The year must be between 1450 and 2100, and it was: 1200
  - The ISBN must have the format 978-NNNNNNNNNN, and it was: 12345

// NOT idempotent: two calls, two loans
manager.lend("BK-0001", "EMP-001", 12);

// Idempotent: the second call does nothing
session.close();
reservationQueue.cancel("BK-0001", "EMP-001");   // if there was none, nothing happens

public Loan lend(String operationId, String reference, String employeeId, int day) {
    // If this operation was already processed, the previous result is returned
    Loan alreadyDone = processedOperations.get(operationId);
    if (alreadyDone != null) {
        LOG.info(() -> "Operation " + operationId + " already processed; returning the previous result");
        return alreadyDone;
    }
    // ... normal processing ...
}

// System.out.println
System.out.println("WARNING: duplicate reference");

WARNING: duplicate reference

// Logger
LOG.warning("Registration rejected: reference BK-0001 duplicate, already used by 'Effective Java'");

2026-08-05 11:42:07.312 [main] WARNING com.nexussoftware.bibliotech.service.Catalog register
  Registration rejected: reference BK-0001 duplicate, already used by 'Effective Java'

package com.nexussoftware.bibliotech.service;

import java.util.logging.Logger;

public class Catalog {

    /**
     * One Logger per class, static and final, named with the class's full
     * name. It is the universal convention, and it allows filtering by package:
     * switching on level FINE for com.nexussoftware.bibliotech.service and leaving
     * the rest at INFO.
     */
    private static final Logger LOG = Logger.getLogger(Catalog.class.getName());

    // ...
}

LOG.severe("Serious message");
LOG.warning("Warning");
LOG.info("Information");
LOG.config("Configuration");
LOG.fine("Debugging detail");

// General form, with the explicit level
LOG.log(Level.INFO, "Message");

// WITH AN EXCEPTION: the correct way to log a failure
LOG.log(Level.SEVERE, "Descriptive message", exception);

// BAD: the concatenation is done ALWAYS, even if FINE is disabled
LOG.fine("Searching for " + reference + " in a catalogue of " + materials.size()
        + " materials, index with " + index.size() + " entries");

// GOOD: the lambda is only evaluated if level FINE is active
LOG.fine(() -> "Searching for " + reference + " in a catalogue of " + materials.size()
        + " materials, index with " + index.size() + " entries");

if (LOG.isLoggable(Level.FINE)) {
    LOG.fine("Expensive message: " + computeDiagnostics());
}

// Switch on the detail ONLY in the service layer
Logger.getLogger("com.nexussoftware.bibliotech.service").setLevel(Level.FINE);
// The rest stays at INFO

package com.nexussoftware.bibliotech.presentation;

import java.io.IOException;
import java.util.logging.ConsoleHandler;
import java.util.logging.FileHandler;
import java.util.logging.Formatter;
import java.util.logging.Handler;
import java.util.logging.Level;
import java.util.logging.LogRecord;
import java.util.logging.Logger;

/**
 * Configuration of BiblioTech's logging system.
 *
 * Two destinations:
 *   - CONSOLE: only INFO and above, in a compact one-line format.
 *   - FILE: everything from FINE, with rotation, for later diagnosis.
 */
public final class LogConfiguration {

    private static final String LOG_PATH = "bibliotech-%g.log";   // %g = rotation number
    private static final int MAX_SIZE = 1_000_000;                // 1 MB per file
    private static final int ROTATION_FILES = 5;                  // 5 files at most

    private static boolean initialised = false;

    private LogConfiguration() { }

    public static synchronized void initialise() {
        if (initialised) {
            return;                          // idempotent (06-06)
        }
        initialised = true;

        Logger root = Logger.getLogger("");

        // 1. Remove the default handlers: we replace them with our own
        for (Handler h : root.getHandlers()) {
            root.removeHandler(h);
        }

        // 2. The root logger accepts everything; each handler filters on its own
        root.setLevel(Level.ALL);

        // 3. CONSOLE: only the important things, compact format
        ConsoleHandler console = new ConsoleHandler();
        console.setLevel(Level.INFO);
        console.setFormatter(new CompactFormat());
        root.addHandler(console);

        // 4. FILE: all the detail, with rotation
        try {
            FileHandler file = new FileHandler(LOG_PATH, MAX_SIZE, ROTATION_FILES, true);
            file.setLevel(Level.FINE);
            file.setFormatter(new DetailedFormat());
            root.addHandler(file);
        } catch (IOException e) {
            // If the file cannot be created, the application must NOT fall over:
            // it degrades to console only and warns. Graceful degradation.
            root.log(Level.WARNING,
                    "Could not create the log file; there will only be console logging", e);
        }

        // 5. Specific level per package
        Logger.getLogger("com.nexussoftware.bibliotech.service").setLevel(Level.FINE);
        Logger.getLogger("com.nexussoftware.bibliotech.domain").setLevel(Level.INFO);

        Logger.getLogger(LogConfiguration.class.getName()).config("Logging system initialised");
    }

    /** One line per event: level, short class name and message. */
    private static class CompactFormat extends Formatter {
        @Override
        public String format(LogRecord logRecord) {
            String className = logRecord.getSourceClassName();
            String shortName = (className == null) ? "?" : className.substring(className.lastIndexOf('.') + 1);

            StringBuilder sb = new StringBuilder();
            sb.append(String.format("[%-7s] %-18s %s%n",
                    logRecord.getLevel().getName(), shortName, formatMessage(logRecord)));

            if (logRecord.getThrown() != null) {
                sb.append("          cause: ").append(logRecord.getThrown()).append('\n');
            }
            return sb.toString();
        }
    }

    /** Full format for the file, with timestamp, thread and stack trace. */
    private static class DetailedFormat extends Formatter {
        @Override
        public String format(LogRecord logRecord) {
            StringBuilder sb = new StringBuilder();

            // Timestamp. The instant in milliseconds is used and formatted
            // without java.time, which is the subject of 10-05.
            sb.append(String.format("%tF %<tT.%<tL", logRecord.getMillis()));
            sb.append(String.format(" [%-6d] %-7s ",
                    logRecord.getLongThreadID(), logRecord.getLevel().getName()));
            sb.append(logRecord.getSourceClassName()).append('.')
              .append(logRecord.getSourceMethodName()).append(" - ");
            sb.append(formatMessage(logRecord)).append('\n');

            // The complete stack trace, indented
            Throwable t = logRecord.getThrown();
            if (t != null) {
                sb.append("    ").append(t).append('\n');
                for (StackTraceElement frame : t.getStackTrace()) {
                    sb.append("        at ").append(frame).append('\n');
                }
                // Causes and suppressed ones (06-01, 06-06)
                Throwable cause = t.getCause();
                int level = 1;
                while (cause != null && level <= 5) {
                    sb.append("    Caused by: ").append(cause).append('\n');
                    cause = cause.getCause();
                    level++;
                }
                for (Throwable suppressed : t.getSuppressed()) {
                    sb.append("    Suppressed: ").append(suppressed).append('\n');
                }
            }
            return sb.toString();
        }
    }
}

# BiblioTech's logging.properties

# Global handlers
handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler

# Root logger level: let everything through, the handlers filter
.level = ALL

# --- Console: only INFO and above ---
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

# --- File: everything from FINE, with rotation ---
java.util.logging.FileHandler.pattern = bibliotech-%g.log
java.util.logging.FileHandler.limit = 1000000
java.util.logging.FileHandler.count = 5
java.util.logging.FileHandler.append = true
java.util.logging.FileHandler.level = FINE
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter

# SimpleFormatter format: date, level, class.method, message, exception
java.util.logging.SimpleFormatter.format = %1$tF %1$tT.%1$tL %4$-7s [%2$s] %5$s%6$s%n

# --- Levels per package ---
com.nexussoftware.bibliotech.level = INFO
com.nexussoftware.bibliotech.service.level = FINE
com.nexussoftware.bibliotech.domain.level = INFO

java -Djava.util.logging.config.file=logging.properties \
     -cp . com.nexussoftware.bibliotech.presentation.BiblioTechApp

try {
    manager.lend(reference, employeeId, day);

} catch (BiblioTechException e) {

    // ==================== CORRECT ====================
    // The Throwable goes as the THIRD argument: the Formatter prints the complete
    // stack trace, with its causes and suppressed ones, in the same log event.
    LOG.log(Level.WARNING, "Could not lend " + reference + " to " + employeeId, e);

    // ==================== INCORRECT ====================

    // 1. printStackTrace: goes to System.err, no level, no date, no filter
    e.printStackTrace();

    // 2. Only the message: loses the stack trace and all the causes
    LOG.warning("Error: " + e.getMessage());

    // 3. Concatenating the exception: gives only toString(), no stack
    LOG.warning("Error: " + e);

    // 4. Logging AND rethrowing: the same failure will appear twice
    LOG.log(Level.SEVERE, "Error", e);
    throw e;
}

// Today: Employee.toString() returns "EMP-001 (Marta Ruiz)". It looks harmless.
LOG.fine(() -> "Processing " + employee);

// In a year's time somebody adds the ID number and the phone to toString()...
// and suddenly you are logging personal data into every log file,
// without anybody having touched this line.

LOG.fine(() -> "Processing employee " + employee.getIdentifier());

/** Leaves the last 4 characters visible: 978-0000000001 -> ***0001 */
private static String mask(String value) {
    if (value == null || value.length() <= 4) {
        return "****";
    }
    return "***" + value.substring(value.length() - 4);
}

LOG.info(() -> "[" + operationId + "] Loan " + loanReference + " completed");

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Catalog {

    private static final Logger LOG = LoggerFactory.getLogger(Catalog.class);

    public void register(Material material) {
        // Placeholder syntax {}: no concatenation and no lambda.
        // The message is only composed if the level is active.
        LOG.debug("Registering {} in a catalogue of {} materials",
                  material.getReference(), materials.size());
        // ...
    }
}

package com.nexussoftware.bibliotech.service;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.logging.Level;
import java.util.logging.Logger;

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, final version of module 6.
 *
 * Changes with respect to 06-04:
 *   - Zero System.out.println: all the diagnostics go to the Logger.
 *   - The log messages carry identifiers, not people's names.
 *   - Expensive messages use Supplier so they are not built if the level is disabled.
 */
public class Catalog {

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

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

    private String lockOwner = null;

    public void register(Material material) {
        Objects.requireNonNull(material, "The material to register cannot be null");
        String reference = material.getReference();

        // FINE: debugging detail, disabled in production.
        // With a Supplier, the concatenation does not run if FINE is off.
        LOG.fine(() -> "Registering " + reference + " (current catalogue: "
                + materials.size() + " materials)");

        Material existing = indexByReference.get(reference);
        if (existing != null) {
            // It is logged at FINE and THROWN. It is not logged at a higher level
            // because whoever catches it will decide its severity: in a bulk import
            // a duplicate is routine, in a manual registration it is a warning.
            LOG.fine(() -> "Registration rejected: reference " + reference + " duplicate");
            throw new DuplicateReferenceException(
                    DuplicateReferenceException.Kind.REFERENCE, reference,
                    existing.getTitle());
        }

        if (material instanceof Book book) {
            String existingTitle = titlesByIsbn.get(book.getIsbn());
            if (existingTitle != null) {
                LOG.fine(() -> "Registration rejected: duplicate ISBN in " + reference);
                throw new DuplicateReferenceException(
                        DuplicateReferenceException.Kind.ISBN, book.getIsbn(), existingTitle);
            }
            titlesByIsbn.put(book.getIsbn(), book.getTitle());
        }

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

        // INFO: a business milestone. It reads as the story of what the application does.
        LOG.info(() -> "Material registered: " + reference
                + " (total " + materials.size() + ")");
    }

    public Material getByReference(String reference) {
        Objects.requireNonNull(reference, "The reference cannot be null");

        Material found = indexByReference.get(reference);
        if (found == null) {
            LOG.fine(() -> "Reference not found: " + reference);
            throw new MaterialNotFoundException(reference, materials.size());
        }
        return found;
    }

    public Optional<Material> findByReference(String reference) {
        if (reference == null) { return Optional.empty(); }
        return Optional.ofNullable(indexByReference.get(reference));
    }

    public void lock(String ownerId) {
        if (lockOwner != null && !lockOwner.equals(ownerId)) {
            LOG.warning(() -> "Lock denied to " + ownerId
                    + ": it is held by " + lockOwner);
            throw new IllegalStateException(
                    "The catalogue is locked by " + lockOwner);
        }
        lockOwner = ownerId;
        LOG.fine(() -> "Catalogue lock acquired by " + ownerId);
    }

    public void unlock(String ownerId) {
        if (!Objects.equals(lockOwner, ownerId)) {
            // WARNING: something odd is going on, but it does not stop us carrying on
            LOG.warning(() -> "Unlock attempt by " + ownerId
                    + " who is not the owner (" + lockOwner + ")");
            return;
        }
        lockOwner = null;
        LOG.fine(() -> "Catalogue lock released by " + ownerId);
    }

    public boolean isLocked()       { return lockOwner != null; }
    public boolean exists(String r) { return r != null && indexByReference.containsKey(r); }
    public int size()               { return materials.size(); }
    public List<Material> list()    { return List.copyOf(materials); }
}

package com.nexussoftware.bibliotech.service;

import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.domain.*;

/** Orchestrates loans with complete logging and consistent state. */
public class LoanManager {

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

    private final Catalog catalog;
    private final Map<String, Employee> employees = new HashMap<>();
    private final Map<String, Loan> loans = new HashMap<>();

    private int counter = 0;

    public LoanManager(Catalog catalog) {
        this.catalog = Objects.requireNonNull(catalog, "The catalogue cannot be null");
    }

    public void enrol(Employee employee) {
        Objects.requireNonNull(employee, "The employee cannot be null");
        employees.put(employee.getIdentifier(), employee);
        // The IDENTIFIER is logged, not the name: the name is personal data
        LOG.info(() -> "Employee enrolled: " + employee.getIdentifier());
    }

    public Loan lend(String operationId, String reference, String employeeId, int day) {
        Objects.requireNonNull(operationId, "The operation identifier cannot be null");
        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);
        }

        LOG.fine(() -> "[" + operationId + "] Starting loan of " + reference
                + " to " + employeeId + " on day " + day);

        // --- Phase 1: reading and validation (modifies nothing) ---
        Material material = catalog.getByReference(reference);
        Employee employee = employees.get(employeeId);
        if (employee == null) {
            throw new MaterialNotFoundException(employeeId, employees.size());
        }
        if (!material.isAvailable()) {
            throw new MaterialNotAvailableException(reference, material.getTitle(),
                    "another employee", day + Loan.LOAN_DAYS);
        }
        if (!employee.canBorrow()) {
            throw new LoanLimitExceededException(employeeId, employee.getName(),
                    employee.getTotalLoans(), Employee.MAX_CONCURRENT_LOANS);
        }

        // --- Phase 2: modification with compensation (06-05) ---
        boolean materialMarked = false;
        boolean allowanceUsed = false;
        boolean completed = false;
        String loanReference = nextReference();

        try {
            material.lend();
            materialMarked = true;

            employee.registerLoan();
            allowanceUsed = true;

            Loan loan = new Loan(loanReference, material, employee, day);
            loans.put(loanReference, loan);
            completed = true;

            LOG.info(() -> "[" + operationId + "] Loan " + loanReference
                    + " registered: " + reference + " -> " + employeeId + " (day " + day + ")");
            return loan;

        } finally {
            if (!completed) {
                // WARNING, not SEVERE: compensation is the planned behaviour
                LOG.warning(() -> "[" + operationId + "] Incomplete loan of " + reference
                        + "; compensating");
                try {
                    if (allowanceUsed)   { employee.registerReturn(); }
                    if (materialMarked)  { material.returnItem(); }
                    LOG.fine(() -> "[" + operationId + "] State restored");
                } catch (RuntimeException failure) {
                    // A real SEVERE: the compensation failed and the state may
                    // have been left inconsistent. This DOES require intervention.
                    LOG.log(Level.SEVERE, "[" + operationId
                            + "] THE COMPENSATION FAILED. State possibly inconsistent in "
                            + reference, failure);
                }
            }
        }
    }

    public void returnItem(String operationId, String loanReference, int day) {
        Loan loan = loans.get(loanReference);
        if (loan == null) {
            throw new MaterialNotFoundException(loanReference, loans.size());
        }
        if (loan.isReturned()) {
            throw new LoanAlreadyReturnedException(loanReference, loan.getStartDay());
        }

        loan.registerReturn(day);
        loan.getBorrower().registerReturn();

        int daysLate = loan.calculateDaysLate(day);
        if (daysLate > 0) {
            LOG.info(() -> "[" + operationId + "] Return of " + loanReference
                    + " with " + daysLate + " days late");
        } else {
            LOG.info(() -> "[" + operationId + "] Return of " + loanReference + " on time");
        }
    }

    private String nextReference() {
        counter++;
        return String.format("LN-%04d", counter);
    }

    public int registeredLoans() { return loans.size(); }
}

package com.nexussoftware.bibliotech.presentation;

import java.util.logging.Level;
import java.util.logging.Logger;

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

/**
 * Presentation layer: the ONLY one that catches for the user, the only one that
 * prints to the console what the user asked to see, and the only one that decides
 * which message to show in each case.
 */
public class ConsoleOperations {

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

    private final LoanManager manager;
    private int operationCounter = 0;

    public ConsoleOperations(LoanManager manager) {
        this.manager = manager;
    }

    /**
     * Runs a loan translating every failure into an understandable message.
     *
     * HERE things are caught: it is the boundary with the user and there are decisions to take.
     */
    public void lend(String reference, String employeeId, int day) {
        String operationId = nextOperationId();

        try {
            manager.lend(operationId, reference, employeeId, day);
            // Program OUTPUT, not a log: it is what the user asked to see
            System.out.println("Lent " + reference + " to " + employeeId
                    + ". Return expected: day " + (day + Loan.LOAN_DAYS));

        } catch (MaterialNotFoundException e) {
            // Expected and fixable failure: friendly message, low-level log
            System.out.println("Material '" + e.getSearchedReference() + "' does not exist.");
            if (e.isCatalogEmpty()) {
                System.out.println("The catalogue is empty: load the materials first.");
            }
            LOG.fine(() -> "[" + operationId + "] Non-existent reference: "
                    + e.getSearchedReference());

        } catch (MaterialNotAvailableException e) {
            System.out.println("'" + e.getTitle() + "' is on loan.");
            System.out.println("Expected to be available in " + e.waitDays(day) + " days.");
            System.out.println("You can reserve it with option 5.");
            LOG.fine(() -> "[" + operationId + "] Material unavailable: " + e.getReference());

        } catch (LoanLimitExceededException e) {
            System.out.printf("You have reached the limit of %d concurrent loans.%n",
                    e.getLimit());
            System.out.printf("You must return %d material(s) before borrowing another.%n",
                    e.returnsNeeded());
            LOG.fine(() -> "[" + operationId + "] Limit exceeded by " + e.getEmployeeId());

        } catch (BiblioTechException e) {
            // Domain safety net: catchable thanks to the common root (06-04)
            System.out.println("The operation could not be completed: " + e.getMessage());
            LOG.log(Level.WARNING, "[" + operationId + "] Unforeseen domain failure ["
                    + e.getCode() + "]", e);

        } catch (RuntimeException e) {
            // BUG: the user does not see the details, the log sees them all
            System.out.println("An internal error has occurred.");
            System.out.println("Incident: " + operationId);
            LOG.log(Level.SEVERE, "[" + operationId + "] Unhandled error lending "
                    + reference + " to " + employeeId, e);
        }
    }

    private String nextOperationId() {
        operationCounter++;
        return String.format("OP-%05d", operationCounter);
    }

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

    public static void main(String[] args) {
        LogConfiguration.initialise();

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

        ConsoleOperations console = new ConsoleOperations(manager);

        System.out.println("\n----- Operations -----");
        console.lend("BK-0001", "EMP-001", 10);
        console.lend("BK-0001", "EMP-002", 11);        // not available
        console.lend("BK-9999", "EMP-001", 11);        // not found
        console.lend("BK-0002", "EMP-001", 11);
        console.lend("BK-0003", "EMP-001", 11);
        console.lend("BK-0002", "EMP-001", 12);        // not available (already has it)
    }
}

[INFO   ] Catalog            Material registered: BK-0001 (total 1)
[INFO   ] Catalog            Material registered: BK-0002 (total 2)
[INFO   ] Catalog            Material registered: BK-0003 (total 3)
[INFO   ] LoanManager        Employee enrolled: EMP-001
[INFO   ] LoanManager        Employee enrolled: EMP-002

----- Operations -----
[INFO   ] LoanManager        [OP-00001] Loan LN-0001 registered: BK-0001 -> EMP-001 (day 10)
Lent BK-0001 to EMP-001. Return expected: day 25
'Effective Java' is on loan.
Expected to be available in 14 days.
You can reserve it with option 5.
Material 'BK-9999' does not exist.
[INFO   ] LoanManager        [OP-00004] Loan LN-0002 registered: BK-0002 -> EMP-001 (day 11)
Lent BK-0002 to EMP-001. Return expected: day 26
[INFO   ] LoanManager        [OP-00005] Loan LN-0003 registered: BK-0003 -> EMP-001 (day 11)
Lent BK-0003 to EMP-001. Return expected: day 26
'Design Patterns' is on loan.
Expected to be available in 14 days.
You can reserve it with option 5.

2026-08-05 11:42:07.104 [1     ] CONFIG  ...LogConfiguration.initialise - Logging system initialised
2026-08-05 11:42:07.118 [1     ] FINE    ...Catalog.register - Registering BK-0001 (current catalogue: 0 materials)
2026-08-05 11:42:07.119 [1     ] INFO    ...Catalog.register - Material registered: BK-0001 (total 1)
...
2026-08-05 11:42:07.201 [1     ] FINE    ...LoanManager.lend - [OP-00002] Starting loan of BK-0001 to EMP-002 on day 11
2026-08-05 11:42:07.202 [1     ] FINE    ...ConsoleOperations.lend - [OP-00002] Material unavailable: BK-0001
2026-08-05 11:42:07.205 [1     ] FINE    ...Catalog.getByReference - Reference not found: BK-9999
2026-08-05 11:42:07.206 [1     ] FINE    ...ConsoleOperations.lend - [OP-00003] Non-existent reference: BK-9999

public class BiblioTechMenu {

    public void start() {
        while (true) {
            try {
                System.out.print("Option: ");
                int option = Integer.parseInt(new Scanner(System.in).nextLine());
                switch (option) {
                    case 1: lend(); break;
                    case 2: returnItem(); break;
                    case 0: System.exit(0);
                }
            } catch (Throwable t) {
                t.printStackTrace();
            }
        }
    }

    private void lend() throws Exception {
        Scanner sc = new Scanner(System.in);
        System.out.print("Reference: ");
        String ref = sc.nextLine();
        System.out.print("Employee: ");
        String emp = sc.nextLine();

        try {
            manager.lend(ref, emp, 1);
        } catch (Exception e) {
            System.out.println("Error: " + e.getMessage());
            System.out.println(e.getStackTrace()[0]);
            throw e;
        } finally {
            sc.close();
        }
    }

    private void returnItem() {
        try {
            manager.returnItem(readReference(), 1);
        } catch (Exception e) {
        }
        System.out.println("Return processed");
    }
}

package com.nexussoftware.bibliotech.service;

import java.io.IOException;
import java.util.NoSuchElementException;
import java.util.logging.Level;

import com.nexussoftware.bibliotech.domain.BiblioTechException;

/**
 * Classifies a Throwable and recommends how to treat it.
 * It materialises this lesson's table of decisions.
 */
public final class ErrorPolicy {

    /** Complete recommendation for a specific failure (record, 04-07). */
    public record Recommendation(Level level, boolean userSafeMessage,
                                 boolean requiresIncident, String action) {

        @Override
        public String toString() {
            return String.format("level=%-7s | user=%-5s | incident=%-5s | %s",
                    level.getName(), userSafeMessage, requiresIncident, action);
        }
    }

    private ErrorPolicy() { }

    public static Recommendation decide(Throwable t) {
        if (t == null) {
            return new Recommendation(Level.INFO, false, false, "Nothing to do");
        }

        // 1. JVM error: unrecoverable
        if (t instanceof Error) {
            return new Recommendation(Level.SEVERE, false, true,
                    "Log (protected) and terminate in an orderly way. Do NOT carry on.");
        }

        // 2. Domain exception: expected failure, message already written for the user
        if (t instanceof BiblioTechException bte) {
            if (bte.isUserFixable()) {
                return new Recommendation(Level.FINE, true, false,
                        "Show the message as it is and allow a retry.");
            }
            return new Recommendation(Level.WARNING, true, false,
                    "Show the message and state that it does not depend on the user.");
        }

        // 3. I/O failures: an environment condition
        if (t instanceof IOException) {
            return new Recommendation(Level.SEVERE, false, true,
                    "Degrade if there is an alternative; if not, abort the operation. Alert operations.");
        }

        // 4. Technical validations frequent at the boundary with the user
        if (t instanceof NumberFormatException) {
            return new Recommendation(Level.FINE, true, false,
                    "Ask for the data again stating the expected format.");
        }
        if (t instanceof NoSuchElementException) {
            return new Recommendation(Level.FINE, true, false,
                    "Report that it was not found and offer alternatives.");
        }

        // 5. Programming failures: the user must not see the details
        if (t instanceof NullPointerException
                || t instanceof IndexOutOfBoundsException
                || t instanceof ClassCastException) {
            return new Recommendation(Level.SEVERE, false, true,
                    "BUG: generic message with an incident, full stack trace to the log.");
        }

        // 6. Remaining unchecked ones: probably a bug too
        if (t instanceof RuntimeException) {
            return new Recommendation(Level.SEVERE, false, true,
                    "Treat as a bug until proven otherwise.");
        }

        // 7. Checked ones not covered
        return new Recommendation(Level.WARNING, false, true,
                "External condition: log in detail and decide in the layer above.");
    }

    public static void main(String[] args) {
        Throwable[] cases = {
                new NumberFormatException("For input string: \"twelve\""),
                new IllegalArgumentException("The year must be between 1450 and 2100, and it was: 1200"),
                new IOException("catalog.txt (No such file or directory)"),
                new NullPointerException("Cannot invoke \"Employee.getName()\""),
                new OutOfMemoryError("Java heap space"),
                new NoSuchElementException("No line found")
        };

        System.out.printf("%-32s %s%n", "EXCEPTION", "RECOMMENDATION");
        System.out.println("-".repeat(120));
        for (Throwable t : cases) {
            System.out.printf("%-32s %s%n", t.getClass().getSimpleName(), decide(t));
        }
    }
}

EXCEPTION                        RECOMMENDATION
------------------------------------------------------------------------------------------------------------------------
NumberFormatException            level=FINE    | user=true  | incident=false | Ask for the data again stating the expected format.
IllegalArgumentException         level=SEVERE  | user=false | incident=true  | Treat as a bug until proven otherwise.
IOException                      level=SEVERE  | user=false | incident=true  | Degrade if there is an alternative; if not, abort the operation. Alert operations.
NullPointerException             level=SEVERE  | user=false | incident=true  | BUG: generic message with an incident, full stack trace to the log.
OutOfMemoryError                 level=SEVERE  | user=false | incident=true  | Log (protected) and terminate in an orderly way. Do NOT carry on.
NoSuchElementException           level=FINE    | user=true  | incident=false | Report that it was not found and offer alternatives.

package com.nexussoftware.bibliotech.service;

import java.util.HashMap;
import java.util.Map;
import java.util.function.Supplier;
import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.domain.BiblioTechException;

/**
 * Wraps BiblioTech operations adding logging, measurement and a
 * uniform error policy.
 *
 * It is an example of the "service decorator" pattern that in module 11
 * the frameworks do with aspects and annotations.
 */
public class OperationLog {

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

    /** Accumulated statistics of one operation (mutable on purpose). */
    private static class Stats {
        int runs;
        int successes;
        int failures;
        long totalNanos;

        double averageMs() {
            return (runs == 0) ? 0.0 : (totalNanos / 1_000_000.0) / runs;
        }
    }

    private final Map<String, Stats> stats = new HashMap<>();
    private int counter = 0;

    /**
     * Runs an operation logging the start, the end, the duration and the failures.
     *
     * @param operationName logical name (LEND, RETURN, IMPORT...)
     * @param employeeId    the employee's IDENTIFIER, never their name
     * @param operation     the operation to run
     */
    public <T> T execute(String operationName, String employeeId, Supplier<T> operation) {
        String operationId = nextId();
        long start = System.nanoTime();
        boolean success = false;

        // Lazy form: if FINE is disabled, the string is not built
        LOG.fine(() -> "[" + operationId + "] START " + operationName
                + " (employee " + employeeId + ")");

        try {
            T result = operation.get();
            success = true;
            return result;

        } catch (BiblioTechException e) {
            // EXPECTED domain failure: WARNING with the exception as the
            // third argument, and it is RETHROWN so the caller decides.
            LOG.log(Level.WARNING, "[" + operationId + "] " + operationName
                    + " rejected [" + e.getCode() + "]", e);
            throw e;

        } catch (RuntimeException e) {
            // UNEXPECTED failure: it is a bug. SEVERE with the identifier as the
            // incident, and it is WRAPPED preserving the cause (06-03).
            LOG.log(Level.SEVERE, "[" + operationId + "] Unhandled error in "
                    + operationName, e);
            throw new IllegalStateException(
                    "Internal error in " + operationName + ". Incident: " + operationId, e);

        } finally {
            // The duration is ALWAYS logged, on success and on failure (06-05)
            long duration = System.nanoTime() - start;
            accumulate(operationName, success, duration);

            final boolean succeeded = success;
            final double ms = duration / 1_000_000.0;

            if (succeeded) {
                LOG.info(() -> String.format("[%s] END %s OK (%.2f ms)",
                        operationId, operationName, ms));
            } else {
                LOG.fine(() -> String.format("[%s] END %s FAILED (%.2f ms)",
                        operationId, operationName, ms));
            }
        }
    }

    /** Variant with no result. */
    public void executeWithoutResult(String operationName, String employeeId, Runnable operation) {
        execute(operationName, employeeId, () -> {
            operation.run();
            return null;
        });
    }

    private synchronized void accumulate(String name, boolean success, long nanos) {
        Stats s = stats.computeIfAbsent(name, n -> new Stats());
        s.runs++;
        s.totalNanos += nanos;
        if (success) { s.successes++; } else { s.failures++; }
    }

    private synchronized String nextId() {
        counter++;
        return String.format("OP-%05d", counter);
    }

    public void dumpStats() {
        System.out.println();
        System.out.printf("%-14s %-12s %-9s %-9s %s%n",
                "OPERATION", "RUNS", "SUCCESSES", "FAILURES", "AVERAGE (ms)");
        System.out.println("-".repeat(62));

        stats.forEach((name, s) ->
                System.out.printf("%-14s %-12d %-9d %-9d %.2f%n",
                        name, s.runs, s.successes, s.failures, s.averageMs()));
    }

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

    public static void main(String[] args) {
        com.nexussoftware.bibliotech.presentation.LogConfiguration.initialise();

        Catalog catalog = new Catalog();
        catalog.register(new com.nexussoftware.bibliotech.domain.Book(
                "BK-0001", "Effective Java", "Bloch", 2018, "978-0000000001"));
        catalog.register(new com.nexussoftware.bibliotech.domain.Book(
                "BK-0002", "Design Patterns", "GoF", 1994, "978-0000000002"));

        OperationLog operationLog = new OperationLog();

        System.out.println("\n----- Operations -----");

        // 1 and 2: correct
        operationLog.execute("QUERY", "EMP-001",
                () -> catalog.getByReference("BK-0001").getTitle());
        operationLog.execute("QUERY", "EMP-002",
                () -> catalog.getByReference("BK-0002").getTitle());

        // 3: expected domain failure, rethrown as it is
        try {
            operationLog.execute("QUERY", "EMP-001",
                    () -> catalog.getByReference("BK-9999").getTitle());
        } catch (BiblioTechException e) {
            System.out.println("Rejected: " + e.getMessage());
        }

        // 4: correct registration
        operationLog.executeWithoutResult("REGISTER", "EMP-003", () ->
                catalog.register(new com.nexussoftware.bibliotech.domain.Book(
                        "BK-0003", "Refactoring", "Fowler", 1999, "978-0000000003")));

        // 5: duplicate registration, domain failure
        try {
            operationLog.executeWithoutResult("REGISTER", "EMP-003", () ->
                    catalog.register(new com.nexussoftware.bibliotech.domain.Book(
                            "BK-0001", "Copy", "X", 2020, "978-0000000009")));
        } catch (BiblioTechException e) {
            System.out.println("Rejected: " + e.getMessage());
        }

        // 6: simulated BUG, wrapped with an incident
        try {
            operationLog.execute("REPORT", "EMP-001", () -> {
                String nothing = null;
                return nothing.length();       // NullPointerException
            });
        } catch (IllegalStateException e) {
            System.out.println("Internal error: " + e.getMessage());
            System.out.println("  logged cause: " + e.getCause().getClass().getSimpleName());
        }

        operationLog.dumpStats();
    }
}

----- Operations -----
[INFO   ] OperationLog       [OP-00001] END QUERY OK (0.08 ms)
[INFO   ] OperationLog       [OP-00002] END QUERY OK (0.01 ms)
[WARNING] OperationLog       [OP-00003] QUERY rejected [MATERIALNOTFOUND]
          cause: com.nexussoftware.bibliotech.domain.MaterialNotFoundException: There is no...
Rejected: There is no material with the reference 'BK-9999' (the catalogue has 2 materials)
[INFO   ] Catalog            Material registered: BK-0003 (total 3)
[INFO   ] OperationLog       [OP-00004] END REGISTER OK (0.15 ms)
[WARNING] OperationLog       [OP-00005] REGISTER rejected [DUPLICATEREFERENCE]
Rejected: A material already exists with the reference BK-0001: 'Effective Java'
[SEVERE ] OperationLog       [OP-00006] Unhandled error in REPORT
Internal error: Internal error in REPORT. Incident: OP-00006
  logged cause: NullPointerException

OPERATION      RUNS         SUCCESSES FAILURES  AVERAGE (ms)
--------------------------------------------------------------
QUERY          3            2         1         0.04
REGISTER       2            1         1         0.09
REPORT         1            0         1         0.05

package com.nexussoftware.bibliotech.presentation;

import java.util.NoSuchElementException;
import java.util.Scanner;
import java.util.logging.Level;
import java.util.logging.Logger;

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

/**
 * BiblioTech's main menu, final version of module 6.
 *
 * Error policy:
 *   - A single instance Scanner over System.in, which is NEVER closed.
 *   - Catching is by TYPE, from most specific to most general.
 *   - Domain failures produce user messages and a FINE log entry.
 *   - Bugs produce a generic message with an incident and a SEVERE log entry.
 *   - Throwable is not caught: Errors go up to the main boundary.
 *   - Zero diagnostic System.out.println.
 */
public class BiblioTechMenu {

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

    private static final int LOAN_DAYS = 15;

    /** A SINGLE Scanner, created once and never closed (06-06). */
    private final Scanner scanner = new Scanner(System.in);

    private final LoanManager manager;
    private int operationCounter = 0;
    private boolean exit = false;

    public BiblioTechMenu(LoanManager manager) {
        this.manager = manager;
    }

    public void start() {
        LOG.info("BiblioTech menu started");

        while (!exit) {
            showMenu();
            int option = readOption(0, 3);

            // Each option handles ITS OWN errors: there is no net here
            // catching everything, because such a net would hide bugs.
            switch (option) {
                case 1 -> lend();
                case 2 -> returnItem();
                case 3 -> list();
                case 0 -> exit();
                default -> System.out.println("Unrecognised option: " + option);
            }
        }
        LOG.info("BiblioTech menu finished");
    }

    private void showMenu() {
        System.out.println("""

                ===== BiblioTech - Nexus Software =====
                1. Lend material
                2. Return material
                3. List catalogue
                0. Exit
                =======================================""");
    }

    /** Unbounded retry: there is a person in front who can correct it (06-02). */
    private int readOption(int min, int max) {
        while (true) {
            System.out.print("Option: ");
            String line = scanner.nextLine().trim();
            try {
                int value = Integer.parseInt(line);
                if (value < min || value > max) {
                    System.out.printf("It must be between %d and %d.%n", min, max);
                    continue;
                }
                return value;
            } catch (NumberFormatException e) {
                System.out.println("'" + line + "' is not a number. Type a digit from "
                        + min + " to " + max + ".");
                LOG.fine(() -> "Non-numeric input in the menu: '" + line + "'");
            }
        }
    }

    private void lend() {
        String operationId = nextOperationId();

        System.out.print("Material reference: ");
        String reference = scanner.nextLine().trim();
        System.out.print("Employee identifier: ");
        String employeeId = scanner.nextLine().trim();
        int day = readIntWithLimit("Day of the loan (1-365)", 1, 365);
        if (day == -1) {
            System.out.println("Operation cancelled.");
            return;
        }

        try {
            manager.lend(operationId, reference, employeeId, day);
            // Program OUTPUT (what the user asked to see), not a log
            System.out.println("Lent " + reference + ". Return expected: day "
                    + (day + LOAN_DAYS));

        } catch (MaterialNotFoundException e) {
            System.out.println("Material '" + e.getSearchedReference() + "' does not exist.");
            LOG.fine(() -> "[" + operationId + "] Non-existent reference: "
                    + e.getSearchedReference());

        } catch (MaterialNotAvailableException e) {
            System.out.println("'" + e.getTitle() + "' is on loan.");
            System.out.println("Available in about " + e.waitDays(day) + " days.");
            LOG.fine(() -> "[" + operationId + "] Material unavailable: " + e.getReference());

        } catch (LoanLimitExceededException e) {
            System.out.printf("Limit of %d loans reached. Return %d material(s).%n",
                    e.getLimit(), e.returnsNeeded());
            LOG.fine(() -> "[" + operationId + "] Limit exceeded by " + e.getEmployeeId());

        } catch (BiblioTechException e) {
            System.out.println("The loan could not be completed: " + e.getMessage());
            LOG.log(Level.WARNING, "[" + operationId + "] Unforeseen domain failure ["
                    + e.getCode() + "]", e);

        } catch (RuntimeException e) {
            // BUG. The user sees an incident; the log, all the detail.
            System.out.println("Internal error. Incident: " + operationId);
            LOG.log(Level.SEVERE, "[" + operationId + "] Unhandled error lending "
                    + reference + " to " + employeeId, e);
        }
        // Throwable is NOT caught: an Error must go up to the main boundary.
    }

    private void returnItem() {
        String operationId = nextOperationId();

        System.out.print("Loan reference (LN-NNNN): ");
        String loanReference = scanner.nextLine().trim();
        int day = readIntWithLimit("Day of the return (1-365)", 1, 365);
        if (day == -1) {
            System.out.println("Operation cancelled.");
            return;
        }

        try {
            manager.returnItem(operationId, loanReference, day);
            // INSIDE the try: success is only claimed if there really was any
            System.out.println("Return of " + loanReference + " processed.");

        } catch (LoanAlreadyReturnedException e) {
            System.out.println("That loan was already returned on day "
                    + e.getOriginalReturnDay() + ".");
            LOG.fine(() -> "[" + operationId + "] Duplicate return of "
                    + e.getLoanReference());

        } catch (MaterialNotFoundException e) {
            System.out.println("Loan '" + e.getSearchedReference() + "' does not exist.");
            LOG.fine(() -> "[" + operationId + "] Non-existent loan: "
                    + e.getSearchedReference());

        } catch (BiblioTechException e) {
            System.out.println("The return could not be completed: " + e.getMessage());
            LOG.log(Level.WARNING, "[" + operationId + "] Domain failure on return", e);

        } catch (RuntimeException e) {
            System.out.println("Internal error. Incident: " + operationId);
            LOG.log(Level.SEVERE, "[" + operationId + "] Unhandled error returning "
                    + loanReference, e);
        }
    }

    private void list() {
        System.out.println("(catalogue listing)");
    }

    /**
     * ORDERLY exit: the flag is set and the loop ends on its own.
     * No System.exit here: that would skip the finally blocks and the clean-up (06-05).
     */
    private void exit() {
        exit = true;
        System.out.println("Goodbye.");
    }

    private int readIntWithLimit(String prompt, int min, int max) {
        for (int attempt = 1; attempt <= 3; attempt++) {
            System.out.print(prompt + ": ");
            String line;
            try {
                line = scanner.nextLine().trim();
            } catch (NoSuchElementException e) {
                // Happens if System.in is closed or reaches the end (redirected input)
                LOG.log(Level.WARNING, "Standard input exhausted; cancelling the operation", e);
                return -1;
            }
            try {
                int value = Integer.parseInt(line);
                if (value < min || value > max) {
                    System.out.printf("Out of range [%d..%d]. Attempt %d of 3.%n",
                            min, max, attempt);
                    continue;
                }
                return value;
            } catch (NumberFormatException e) {
                System.out.printf("'%s' is not a number. Attempt %d of 3.%n", line, attempt);
            }
        }
        return -1;
    }

    private String nextOperationId() {
        operationCounter++;
        return String.format("OP-%05d", operationCounter);
    }
}