@Service
public class LoanManager {

    public void lend(String isbn, Long employeeId, int days) {
        // 1. Input validation
        if (isbn == null || !isbn.matches("97[89]-\\d{10}")) {
            throw new IllegalArgumentException("Invalid ISBN");
        }
        // 2. Data access
        Material m = em.createQuery("select m from Material m where m.isbn = :i", Material.class)
                       .setParameter("i", isbn).getSingleResult();
        // 3. Business rules
        long active = em.createQuery("select count(l) from Loan l where …").getSingleResult();
        if (active >= 3) throw new LimitExceededException();
        // 4. Persistence
        Loan loan = new Loan(m, employee, LocalDate.now(), LocalDate.now().plusDays(days));
        em.persist(loan);
        // 5. Notification
        smtp.send(employee.getEmail(), "Loan confirmed", "You have taken " + m.getTitle());
        // 6. Output formatting
        System.out.printf("%-40s %s%n", m.getTitle(), loan.getDueDate());
        // 7. Auditing
        Files.writeString(Path.of("audit.log"), LocalDateTime.now() + " LOAN " + isbn + "\n",
                          StandardOpenOption.APPEND);
    }
}

// DOMAIN: the rule, and only the rule
public class LoanPolicy {
    private final int maxActive;

    public void checkCanBorrow(Employee employee, List<Loan> active) {
        if (active.size() >= maxActive) {
            throw new LoanLimitExceededException(employee.getName(), maxActive);
        }
        if (employee.hasOutstandingFines()) {
            throw new OutstandingFinesException(employee.getName());
        }
    }
}

// APPLICATION: orchestration, and only orchestration
public class LoanManager implements ManageLoans {

    private final MaterialRepository materials;
    private final LoanRepository loans;
    private final EmployeeRepository employees;
    private final LoanPolicy policy;
    private final NoticeSender sender;
    private final Clock clock;

    @Override
    public Loan lend(Isbn isbn, Long employeeId, int days) {
        Material material = materials.findByIsbn(isbn)
                .orElseThrow(() -> new MaterialNotFoundException(isbn));
        Employee employee = employees.findById(employeeId)
                .orElseThrow(() -> new EmployeeNotFoundException(employeeId));

        policy.checkCanBorrow(employee, loans.activeFor(employee));

        Loan loan = Loan.standard(material, employee, LocalDate.now(clock), days);
        loans.save(loan);
        sender.send(Notice.forLoan(loan));
        return loan;
    }
}

public int loanDays(Material material) {
    switch (material.getType()) {
        case BOOK:     return 15;
        case MAGAZINE: return 7;
        case DVD:      return 3;
        default: throw new IllegalStateException("Unknown type: " + material.getType());
    }
}

public abstract class Material {
    // Each subtype answers for itself; the rest of the system does not change.
    public abstract int defaultLoanDays();
    public abstract Money finePerDay();
}

public class Book extends Material {
    @Override public int defaultLoanDays() { return 15; }
    @Override public Money finePerDay() { return Money.euros("0.50"); }
}

public class Magazine extends Material {
    @Override public int defaultLoanDays() { return 7; }
    @Override public Money finePerDay() { return Money.euros("0.25"); }
}

public class Dvd extends Material {
    @Override public int defaultLoanDays() { return 3; }
    @Override public Money finePerDay() { return Money.euros("1.00"); }
}

public class ReferenceMaterial extends Book {

    @Override
    public Loan lendTo(Employee employee, int days) {
        throw new UnsupportedOperationException("Reference materials are not lent out");
    }
}

// This method was correct. Now it blows up in production when Diego Alonso
// adds a reference material to the loan basket.
public void lendAll(List<Material> materials, Employee employee) {
    for (Material m : materials) {
        m.lendTo(employee, m.defaultLoanDays());          // UnsupportedOperationException
    }
}

/** Not every material is lendable. The capability is modelled apart from the type. */
public interface Lendable {
    Loan lendTo(Employee employee, int days);
    int defaultLoanDays();
}

public abstract class Material {                 // all of them: title, ISBN, location
    public abstract String getTitle();
    public abstract Isbn getIsbn();
}

public class Book extends Material implements Lendable { … }
public class ReferenceMaterial extends Material { }      // it simply is NOT Lendable

public void lendAll(List<Lendable> materials, Employee employee) { … }
// It is now IMPOSSIBLE to pass it a ReferenceMaterial.

public interface LibraryManagement {
    Loan lend(Isbn isbn, Long employeeId, int days);
    void returnItem(Long loanId);
    void reserve(Isbn isbn, Long employeeId);
    void sendNotice(Notice notice);
    MonthlyReport generateReport(YearMonth period);
    void importCatalog(Path file);
    void exportCatalog(Path destination);
}

public interface Lendable {
    Loan lendTo(Employee employee, int days);
}

public interface Notifiable {
    String notificationTarget();
}

public interface ManageLoans {                  // the use case's inbound port
    Loan lend(Isbn isbn, Long employeeId, int days);
    void returnItem(Long loanId);
}

public interface QueryCatalog {
    List<Material> search(SearchCriteria criteria);
    Optional<Material> byIsbn(Isbn isbn);
}

public class LoanManager {
    // The high-level policy depends on a low-level detail.
    private final JpaLoanRepository repository = new JpaLoanRepository();
    private final HttpMetadataGateway metadata = new HttpMetadataGateway();
}

public class LoanManager {
    private final LoanRepository repository;          // an abstraction defined in the domain
    private final MetadataGateway metadata;

    public LoanManager(LoanRepository repository, MetadataGateway metadata) {
        this.repository = repository;
        this.metadata = metadata;
    }
}

// VIOLATION: four levels deep. You know the whole internal structure.
String city = loan.getEmployee().getDepartment().getOffice().getAddress().getCity();

// CORRECT: each object exposes what it is asked, and hides how it knows.
String city = loan.employeeCity();

// in Loan
public String employeeCity() { return employee.city(); }
// in Employee
public String city() { return department.city(); }

public class BiblioTechConfiguration {

    private static final BiblioTechConfiguration INSTANCE = new BiblioTechConfiguration();

    private BiblioTechConfiguration() { }          // nobody else can construct it

    public static BiblioTechConfiguration getInstance() { return INSTANCE; }
}

public enum BiblioTechConfiguration {
    INSTANCE;

    private final int defaultDays = 15;
    public int defaultDays() { return defaultDays; }
}

public final class MaterialFactory {

    private MaterialFactory() { }

    public static Material from(ImportRecord record) {
        return switch (record.type()) {
            case BOOK     -> new Book(record.title(), new Isbn(record.isbn()),
                                      record.author(), record.pages());
            case MAGAZINE -> new Magazine(record.title(), new Isbn(record.isbn()),
                                          record.issue(), record.frequency());
            case DVD      -> new Dvd(record.title(), new Isbn(record.isbn()),
                                     record.durationMinutes());
        };
    }
}

public class Loan {

    private Loan(...) { }       // private constructor: creation goes through the factories

    /** A standard loan, using the material's default number of days. */
    public static Loan standard(Material material, Employee employee, LocalDate today) {
        return new Loan(material, employee, today,
                        today.plusDays(material.defaultLoanDays()),
                        LoanStatus.ACTIVE);
    }

    /** A loan extended by management: up to 90 days. */
    public static Loan special(Material material, Employee employee, LocalDate today, int days) {
        if (days > 90) throw new IllegalArgumentException("90 days maximum");
        return new Loan(material, employee, today, today.plusDays(days), LoanStatus.ACTIVE);
    }
}

public interface ExportFactory {
    ReportGenerator generator();
    TableFormatter tableFormatter();
    String extension();

    static ExportFactory forFormat(Format format) {
        return switch (format) {
            case PDF  -> new PdfFactory();
            case CSV  -> new CsvFactory();
            case JSON -> new JsonFactory();
        };
    }
}

// What does the 15 mean? And the true? And the second null?
Loan l = new Loan(material, employee, LocalDate.now(), 15, true, null, false, null, "Marta Ruiz");

public class Loan {

    private final Material material;
    private final Employee employee;
    private final LocalDate loanDate;
    private final LocalDate dueDate;
    private final boolean renewable;
    private final String notes;
    private final Employee authorisedBy;
    private final LoanStatus status;

    private Loan(Builder b) {
        this.material = b.material;
        this.employee = b.employee;
        this.loanDate = b.loanDate;
        this.dueDate = b.dueDate;
        this.renewable = b.renewable;
        this.notes = b.notes;
        this.authorisedBy = b.authorisedBy;
        this.status = LoanStatus.ACTIVE;
    }

    public static Builder of(Material material, Employee employee) {
        return new Builder(material, employee);      // mandatory ones in the builder's factory
    }

    public static class Builder {
        // Mandatory: final, required in the builder's constructor
        private final Material material;
        private final Employee employee;
        // Optional: with a sensible default
        private LocalDate loanDate = LocalDate.now();
        private LocalDate dueDate;
        private boolean renewable = true;
        private String notes = "";
        private Employee authorisedBy;

        private Builder(Material material, Employee employee) {
            this.material = Objects.requireNonNull(material, "material");
            this.employee = Objects.requireNonNull(employee, "employee");
        }

        public Builder from(LocalDate date)         { this.loanDate = date; return this; }
        public Builder forDays(int days)            { this.dueDate = loanDate.plusDays(days); return this; }
        public Builder until(LocalDate date)        { this.dueDate = date; return this; }
        public Builder notRenewable()               { this.renewable = false; return this; }
        public Builder withNotes(String n)          { this.notes = n; return this; }
        public Builder authorisedBy(Employee e)     { this.authorisedBy = e; return this; }

        public Loan build() {
            // The consistency validation happens ONCE, here:
            // that way the constructed object is always valid.
            if (dueDate == null) {
                dueDate = loanDate.plusDays(material.defaultLoanDays());
            }
            if (dueDate.isBefore(loanDate)) {
                throw new IllegalStateException("The due date cannot precede the loan date");
            }
            if (!material.isLendable() && authorisedBy == null) {
                throw new IllegalStateException("A restricted material requires authorisation");
            }
            return new Loan(this);
        }
    }
}

Loan l = Loan.of(effectiveJava, martaRuiz)
        .from(LocalDate.of(2026, 3, 1))
        .forDays(30)
        .notRenewable()
        .withNotes("For the internal Java course")
        .authorisedBy(nuriaVidal)
        .build();

public record SearchCriteria(String title, String author, MaterialType type,
                             Integer yearFrom, Integer yearTo, Boolean onlyAvailable) {

    public static Builder builder() { return new Builder(); }

    public static class Builder {
        private String title; private String author; private MaterialType type;
        private Integer yearFrom; private Integer yearTo;
        private Boolean onlyAvailable = Boolean.FALSE;

        public Builder title(String t) { this.title = t; return this; }
        public Builder author(String a) { this.author = a; return this; }
        public Builder type(MaterialType t) { this.type = t; return this; }
        public Builder between(int from, int to) { this.yearFrom = from; this.yearTo = to; return this; }
        public Builder onlyAvailable() { this.onlyAvailable = true; return this; }

        public SearchCriteria build() {
            return new SearchCriteria(title, author, type, yearFrom, yearTo, onlyAvailable);
        }
    }
}

public record SearchCriteria(String title, String author, MaterialType type, …) {

    public SearchCriteria withType(MaterialType newType) {
        return new SearchCriteria(title, author, newType, yearFrom, yearTo, onlyAvailable);
    }
}

package com.nexussoftware.bibliotech.domain.catalog.port;

public interface MetadataGateway {
    /** Empty if there is no metadata or if the service is unavailable. */
    Optional<MaterialMetadata> findByIsbn(Isbn isbn);
}

package com.nexussoftware.bibliotech.infrastructure.metadata;

@Component
class HttpMetadataGateway implements MetadataGateway {

    private static final Logger log = LoggerFactory.getLogger(HttpMetadataGateway.class);

    private final MetadataClient client;      // the "adaptee": the class with the incompatible interface

    HttpMetadataGateway(MetadataClient client) { this.client = client; }

    @Override
    public Optional<MaterialMetadata> findByIsbn(Isbn isbn) {
        try {
            ApiResponseDto dto = client.queryByIsbn(isbn.value());          // external format

            // 1. Translates the external model into the domain's
            // 2. Translates the exceptions (error boundary, 06-07)
            // 3. Shields the domain from the existence of HTTP, JSON and this particular API
            return Optional.of(new MaterialMetadata(
                    dto.title(),
                    dto.authors() == null ? List.of() : dto.authors(),
                    dto.publishedDate() == null ? null : Year.parse(dto.publishedDate().substring(0, 4)),
                    dto.pageCount()));

        } catch (ResourceNotFoundException e) {
            return Optional.empty();                     // "no data" is not an error
        } catch (IOException | InterruptedException e) {
            if (e instanceof InterruptedException) Thread.currentThread().interrupt();
            log.warn("Metadata unavailable for {}: {}", isbn, e.getMessage());
            return Optional.empty();                     // graceful degradation
        }
    }
}

// Each wrapper ADDS a capability to the previous one, and all of them are InputStream.
InputStream base       = Files.newInputStream(Path.of("catalog.csv"));   // raw bytes
InputStream buffered   = new BufferedInputStream(base);                  // + buffering
InputStream unzipped   = new GZIPInputStream(buffered);                  // + decompression
Reader      reader     = new InputStreamReader(unzipped, UTF_8);         // + character encoding
BufferedReader lines   = new BufferedReader(reader);                     // + readLine()

/**
 * Decorator: it IS a MaterialRepository and it HAS a MaterialRepository.
 * That double relationship is the pattern's signature.
 */
public class CachingCatalog implements MaterialRepository {

    private static final Logger log = LoggerFactory.getLogger(CachingCatalog.class);

    private final MaterialRepository delegate;
    private final Map<Isbn, Material> cache = new ConcurrentHashMap<>();   // module 8

    public CachingCatalog(MaterialRepository delegate) {
        this.delegate = delegate;
    }

    @Override
    public Optional<Material> findByIsbn(Isbn isbn) {
        Material cached = cache.get(isbn);
        if (cached != null) {
            log.debug("Cache hit for {}", isbn);
            return Optional.of(cached);
        }
        Optional<Material> result = delegate.findByIsbn(isbn);
        result.ifPresent(m -> cache.put(isbn, m));
        return result;
    }

    @Override
    public List<Material> search(SearchCriteria criteria) {
        return delegate.search(criteria);      // searches are not cached: they vary too much
    }

    @Override
    public Material save(Material material) {
        cache.remove(material.getIsbn());      // invalidation: the hardest part of a cache
        return delegate.save(material);
    }
}

@Bean
MaterialRepository materialRepository(JpaMaterialRepository jpa, MeterRegistry registry) {
    return new MeteredCatalog(               // 3rd: measures
             new CachingCatalog(             // 2nd: caches
               new RetryingCatalog(jpa, 3)));        // 1st: retries
}

// Dynamic proxy from module 10-03: logs the time taken by each call
@SuppressWarnings("unchecked")
public static <T> T withTiming(T target, Class<T> iface) {
    return (T) Proxy.newProxyInstance(
        iface.getClassLoader(),
        new Class<?>[]{iface},
        (proxy, method, args) -> {
            long start = System.nanoTime();
            try {
                return method.invoke(target, args);
            } finally {
                long ms = (System.nanoTime() - start) / 1_000_000;
                LoggerFactory.getLogger(iface).debug("{} took {} ms", method.getName(), ms);
            }
        });
}

@Service
public class LoanManager {
    @Transactional
    public Loan lend(Isbn isbn, Long employeeId, int days) { … }
}

public interface CatalogItem {
    String title();
    int availableCopies();
}

public class Book implements CatalogItem { … }                    // leaf

public class ThematicCollection implements CatalogItem {          // composite
    private final String title;
    private final List<CatalogItem> items;

    @Override
    public int availableCopies() {
        // Available if ALL of its items are: the minimum rules
        return items.stream().mapToInt(CatalogItem::availableCopies).min().orElse(0);
    }
}

public Money calculateFine(Loan l, LocalDate today) {
    int daysLate = (int) ChronoUnit.DAYS.between(l.getDueDate(), today);
    if (daysLate <= 0) return Money.ZERO;

    if (l.getEmployee().tenureInMonths() < 6) {
        return Money.euros("0.25").times(daysLate);
    } else if (l.getMaterial().isCritical()) {
        return Money.euros("2.00").times(daysLate);
    } else if (l.getEmployee().isManagement()) {
        return Money.ZERO;
    } else {
        return Money.euros("0.50").times(daysLate);
    }
}

@FunctionalInterface
public interface RateRule {
    Money calculate(int daysLate, Loan loan);

    default boolean appliesTo(Loan loan) { return true; }
}

public class StandardRate implements RateRule {
    @Override public Money calculate(int days, Loan l) {
        return l.getMaterial().finePerDay().times(days).cappedAt(Money.euros("20.00"));
    }
}

public class NewEmployeeReducedRate implements RateRule {
    @Override public boolean appliesTo(Loan l) { return l.getEmployee().tenureInMonths() < 6; }
    @Override public Money calculate(int days, Loan l) { return Money.euros("0.25").times(days); }
}

public class ManagementExemptRate implements RateRule {
    @Override public boolean appliesTo(Loan l) { return l.getEmployee().isManagement(); }
    @Override public Money calculate(int days, Loan l) { return Money.ZERO; }
}

public class FineCalculator {
    private final List<RateRule> rules;          // ordered: the first that applies wins
    private final RateRule defaultRule = new StandardRate();

    public FineCalculator(List<RateRule> rules) { this.rules = List.copyOf(rules); }

    public Money calculate(Loan l, LocalDate today) {
        int daysLate = (int) ChronoUnit.DAYS.between(l.getDueDate(), today);
        if (daysLate <= 0) return Money.ZERO;

        return rules.stream()
                .filter(r -> r.appliesTo(l))
                .findFirst()
                .orElse(defaultRule)
                .calculate(daysLate, l);
    }
}

@Component @Order(10) class ManagementExemptRate implements RateRule { … }
@Component @Order(20) class NewEmployeeReducedRate implements RateRule { … }

@Service
class FineCalculator {
    private final List<RateRule> rules;
    FineCalculator(List<RateRule> rules) { this.rules = rules; }             // Spring injects all
}

public abstract class CatalogImporter {

    private static final Logger log = LoggerFactory.getLogger(CatalogImporter.class);

    private final MaterialRepository repository;

    protected CatalogImporter(MaterialRepository repository) {
        this.repository = repository;
    }

    /**
     * TEMPLATE METHOD: it defines the algorithm and is final so that nobody
     * can alter the sequence. Only the steps are replaceable.
     */
    public final ImportResult importFrom(Path source) {
        log.info("Starting import from {}", source);
        long start = System.nanoTime();

        int successful = 0;
        List<ImportError> errors = new ArrayList<>();

        try (Source s = open(source)) {                         // ABSTRACT STEP
            for (ImportRecord record : readRecords(s)) {              // ABSTRACT STEP
                try {
                    if (!isValid(record)) {                    // HOOK with a default implementation
                        errors.add(ImportError.invalid(record));
                        continue;
                    }
                    repository.save(MaterialFactory.from(record));
                    successful++;
                } catch (Exception e) {
                    errors.add(ImportError.of(record, e));
                }
            }
        } catch (IOException e) {
            throw new ImportFailedException(source, e);
        }

        long ms = (System.nanoTime() - start) / 1_000_000;
        onFinish(successful, errors);                          // optional HOOK
        log.info("Import finished: {} successful, {} errors, {} ms",
                 successful, errors.size(), ms);
        return new ImportResult(successful, errors, Duration.ofMillis(ms));
    }

    // --- Steps every subclass MUST provide ---
    protected abstract Source open(Path path) throws IOException;
    protected abstract List<ImportRecord> readRecords(Source source) throws IOException;

    // --- Hooks: default behaviour, replaceable ---
    protected boolean isValid(ImportRecord r) {
        return r.isbn() != null && r.title() != null && !r.title().isBlank();
    }

    protected void onFinish(int successful, List<ImportError> errors) { }
}

public class CsvImporter extends CatalogImporter {

    private final char separator;

    @Override
    protected Source open(Path path) throws IOException {
        return new ReaderSource(Files.newBufferedReader(path, StandardCharsets.UTF_8));
    }

    @Override
    protected List<ImportRecord> readRecords(Source source) throws IOException {
        try (CSVReader csv = new CSVReaderBuilder(source.reader())
                .withSkipLines(1)
                .withCSVParser(new CSVParserBuilder().withSeparator(separator).build())
                .build()) {
            return csv.readAll().stream().map(this::toRecord).toList();
        }
    }
}

public interface ReturnListener {
    void onReturn(ReturnEvent event);
}

public class LoanManager {
    private final List<ReturnListener> listeners = new CopyOnWriteArrayList<>();  // module 8

    public void register(ReturnListener listener) { listeners.add(listener); }

    public void returnItem(Long id) {
        Loan l = …;
        l.registerReturn(LocalDate.now(clock));
        loans.save(l);

        ReturnEvent event = new ReturnEvent(l.getId(), l.getIsbn(), …);
        for (ReturnListener listener : listeners) {
            try {
                listener.onReturn(event);
            } catch (Exception e) {
                // A listener that fails must NOT stop the others from running
                log.error("Listener {} failed", listener.getClass().getSimpleName(), e);
            }
        }
    }
}

// The event: an immutable record
public record MaterialReturned(Long loanId, Isbn isbn, Long employeeId,
                               LocalDate date, Money fine) { }

// The publisher: it knows no listener
@Service
public class LoanManager {

    private final ApplicationEventPublisher events;

    @Transactional
    public void returnItem(Long id) {
        Loan l = loans.findById(id).orElseThrow(…);
        Money fine = l.registerReturn(LocalDate.now(clock));
        loans.save(l);

        events.publishEvent(new MaterialReturned(l.getId(), l.getIsbn(),
                                                 l.getEmployeeId(), LocalDate.now(clock), fine));
    }
}

// The listeners: independent, adding one does not touch the publisher
@Component
class ReservationActivator {
    @EventListener
    void onReturn(MaterialReturned event) {
        reservationProcessor.activateNextReservation(event.isbn());
    }
}

@Component
class StatisticsUpdater {
    // Only if the transaction COMMITS: we do not want to count returns that were rolled back
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void onReturn(MaterialReturned event) {
        statistics.recordReturn(event);
    }
}

@Component
class FineNotifier {
    @Async                                     // on another thread: does not block the response
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    void onReturn(MaterialReturned event) {
        if (event.fine().isPositive()) {
            sender.send(Notice.forFine(event));
        }
    }
}

public enum LoanStatus {

    ACTIVE {
        @Override public boolean allowsRenewal() { return true; }
        @Override public boolean allowsReturn()  { return true; }
        @Override public LoanStatus onRenew()    { return RENEWED; }
    },
    RENEWED {
        @Override public boolean allowsRenewal() { return false; }      // only one renewal
        @Override public boolean allowsReturn()  { return true; }
    },
    OVERDUE {
        @Override public boolean allowsRenewal() { return false; }
        @Override public boolean allowsReturn()  { return true; }
        @Override public boolean generatesFine() { return true; }
    },
    RETURNED {
        @Override public boolean isFinal() { return true; }
    },
    LOST {
        @Override public boolean isFinal() { return true; }
        @Override public boolean generatesFine() { return true; }
    };

    public boolean allowsRenewal() { return false; }
    public boolean allowsReturn()  { return false; }
    public boolean generatesFine() { return false; }
    public boolean isFinal()       { return false; }

    public LoanStatus onRenew() {
        throw new InvalidTransitionException(this, "renew");
    }
}

public void renew(int days) {
    if (!status.allowsRenewal()) {
        throw new InvalidTransitionException(status, "renew");
    }
    this.dueDate = dueDate.plusDays(days);
    this.status = status.onRenew();
}

public interface Command {
    void execute();
    void undo();
    String description();
}

public class LendCommand implements Command {

    private final ManageLoans manager;
    private final Isbn isbn;
    private final Long employeeId;
    private Long createdLoanId;         // the state needed in order to undo

    @Override
    public void execute() {
        this.createdLoanId = manager.lend(isbn, employeeId, 15).getId();
    }

    @Override
    public void undo() {
        if (createdLoanId == null) throw new IllegalStateException("Not executed");
        manager.cancel(createdLoanId);
    }

    @Override
    public String description() { return "Lend " + isbn + " to employee " + employeeId; }
}

public class OperationHistory {
    private final Deque<Command> stack = new ArrayDeque<>();     // 05-07/05-08

    public void execute(Command c) {
        c.execute();
        stack.push(c);
    }

    public void undoLast() {
        if (stack.isEmpty()) throw new NothingToUndoException();
        stack.pop().undo();
    }
}

public interface ImportValidator {
    Optional<ImportError> validate(ImportRecord r);
}

@Service
class ValidationChain {
    private final List<ImportValidator> validators;         // Spring injects all, ordered

    public Optional<ImportError> validate(ImportRecord r) {
        return validators.stream()
                .map(v -> v.validate(r))
                .flatMap(Optional::stream)
                .findFirst();               // the first error cuts the chain short
    }
}

public class PagedCatalog implements Iterable<Material> {

    private final MaterialRepository repository;
    private final int pageSize;

    @Override
    public Iterator<Material> iterator() {
        return new Iterator<>() {
            private int page = 0;
            private Iterator<Material> current = Collections.emptyIterator();

            @Override public boolean hasNext() {
                if (current.hasNext()) return true;
                List<Material> next = repository.page(page++, pageSize);
                current = next.iterator();
                return current.hasNext();
            }

            @Override public Material next() {
                if (!hasNext()) throw new NoSuchElementException();
                return current.next();
            }
        };
    }
}

// The client walks 50,000 materials without loading them all into memory
for (Material m : new PagedCatalog(repository, 500)) { … }

@Transactional
public void renew(Long id, int days) {
    Loan l = loans.findById(id).orElseThrow(…);
    l.renew(days);
    // There is NO need for loans.save(l):
    // the persistence context (the unit of work) tracks the entity
    // and issues the UPDATE on flush, before the commit.
}

public final class GlobalConfig {
    public static int loanDays = 15;        // anybody can change it, from any thread
}

// WRONG: a loan manager IS NOT a list of loans.
public class LoanManager extends ArrayList<Loan> { … }

// ANAEMIC: Loan is a bag of data
public class Loan {
    private LocalDate dueDate;
    private LoanStatus status;
    // 15 getters and 15 setters, zero behaviour
}

@Service
public class LoanManager {
    public void returnItem(Loan l, LocalDate today) {
        // The business rule lives OUTSIDE the object it protects
        if (l.getStatus() == LoanStatus.RETURNED) throw new …;
        l.setReturnDate(today);
        l.setStatus(LoanStatus.RETURNED);
    }
}

// RICH: the object protects its own rules
public class Loan {
    public Money registerReturn(LocalDate date) {
        if (status.isFinal()) throw new LoanAlreadyClosedException(id);
        if (date.isBefore(loanDate)) throw new InvalidDateException(date);
        this.returnDate = date;
        this.status = LoanStatus.RETURNED;
        return fineUpTo(date);
    }
    // no public setters: it is IMPOSSIBLE to leave the object half-done
}

@Service
public class ExportService {

    @Autowired private EntityManager em;
    @Autowired private JavaMailSender mail;

    public void export(String format, String destination, String emailTo) throws Exception {
        List<Material> materials = em.createQuery("select m from Material m", Material.class)
                                     .getResultList();
        String content;

        if (format.equals("csv")) {
            StringBuilder sb = new StringBuilder("isbn;title;type\n");
            for (Material m : materials) {
                sb.append(m.getIsbn()).append(';')
                  .append(m.getTitle()).append(';');
                if (m instanceof Book)          sb.append("BOOK");
                else if (m instanceof Magazine) sb.append("MAGAZINE");
                else if (m instanceof Dvd)      sb.append("DVD");
                sb.append('\n');
            }
            content = sb.toString();
        } else if (format.equals("json")) {
            content = new ObjectMapper().writeValueAsString(materials);
        } else {
            throw new IllegalArgumentException("Unsupported format: " + format);
        }

        Files.writeString(Path.of(destination), content);

        if (emailTo != null) {
            SimpleMailMessage m = new SimpleMailMessage();
            m.setTo(emailTo);
            m.setSubject("BiblioTech catalogue");
            m.setText("Attached is the catalogue in format " + format);
            mail.send(m);
        }
        System.out.println("Exported " + materials.size() + " materials");
    }
}

public abstract class Material {
    public abstract MaterialType type();     // goodbye to instanceof
}
public class Book extends Material {
    @Override public MaterialType type() { return MaterialType.BOOK; }
}

public interface CatalogFormatter {
    String format(List<Material> materials);
    Format format();
    String extension();
}

@Component
class CsvFormatter implements CatalogFormatter {
    @Override public Format format()     { return Format.CSV; }
    @Override public String extension()  { return "csv"; }

    @Override
    public String format(List<Material> materials) {
        return materials.stream()
                .map(m -> String.join(";", m.getIsbn().value(), m.getTitle(), m.type().name()))
                .collect(Collectors.joining("\n", "isbn;title;type\n", "\n"));
    }
}

@Component
class JsonFormatter implements CatalogFormatter {
    private final ObjectMapper mapper;               // injected: only one, reused

    JsonFormatter(ObjectMapper mapper) { this.mapper = mapper; }

    @Override public Format format()    { return Format.JSON; }
    @Override public String extension() { return "json"; }

    @Override
    public String format(List<Material> materials) {
        try {
            // DTOs, not entities (12-01)
            List<MaterialDto> dtos = materials.stream().map(MaterialDto::from).toList();
            return mapper.writeValueAsString(dtos);
        } catch (JsonProcessingException e) {
            throw new ExportFailedException("Could not serialise the catalogue", e);
        }
    }
}

public interface ExportStore {
    URI store(String name, String content);
}

public interface NoticeSender {
    void send(Notice notice);
}

@Service
public class ExportService {

    private static final Logger log = LoggerFactory.getLogger(ExportService.class);

    private final MaterialRepository materials;
    private final Map<Format, CatalogFormatter> formatters;
    private final ExportStore store;
    private final NoticeSender sender;

    /** Spring injects ALL the formatters; we index them by format. */
    public ExportService(MaterialRepository materials,
                         List<CatalogFormatter> formatters,
                         ExportStore store,
                         NoticeSender sender) {
        this.materials = materials;
        this.formatters = formatters.stream()
                .collect(Collectors.toUnmodifiableMap(CatalogFormatter::format, f -> f));
        this.store = store;
        this.sender = sender;
    }

    public ExportResult export(Format format, String name, String emailTo) {
        CatalogFormatter formatter = formatters.get(format);
        if (formatter == null) {
            throw new UnsupportedFormatException(format, formatters.keySet());
        }

        List<Material> catalog = materials.findAll();
        String content = formatter.format(catalog);
        URI location = store.store(name + "." + formatter.extension(), content);

        if (emailTo != null) {
            sender.send(Notice.exportReady(emailTo, format, location));
        }

        log.info("Exported {} materials in {} format to {}", catalog.size(), format, location);
        return new ExportResult(catalog.size(), location, format);
    }
}

/**
 * Decorator that rate-limits requests to the metadata gateway.
 *
 * It implements a sliding window: it keeps the timestamps of the
 * last N requests; if the oldest one is still inside the window,
 * it waits until it falls out.
 *
 * It IS a MetadataGateway and it HAS a MetadataGateway: a decorator.
 */
public class RateLimitedGateway implements MetadataGateway {

    private static final Logger log = LoggerFactory.getLogger(RateLimitedGateway.class);

    private final MetadataGateway delegate;
    private final int maxRequests;
    private final Duration window;
    private final Clock clock;                     // 10-05: injectable, so it can be tested

    /** Timestamps of the most recent requests. Always accessed under the lock. */
    private final Deque<Instant> timestamps = new ArrayDeque<>();
    private final ReentrantLock lock = new ReentrantLock(true);   // fair: FIFO order

    public RateLimitedGateway(MetadataGateway delegate, int maxRequests,
                              Duration window, Clock clock) {
        this.delegate = Objects.requireNonNull(delegate);
        if (maxRequests < 1) throw new IllegalArgumentException("maxRequests >= 1");
        this.maxRequests = maxRequests;
        this.window = Objects.requireNonNull(window);
        this.clock = Objects.requireNonNull(clock);
    }

    @Override
    public Optional<MaterialMetadata> findByIsbn(Isbn isbn) {
        acquirePermit();                        // may block
        return delegate.findByIsbn(isbn);       // the real call, now outside the lock
    }

    private void acquirePermit() {
        lock.lock();
        try {
            while (true) {
                Instant now = Instant.now(clock);
                purgeOld(now);

                if (timestamps.size() < maxRequests) {
                    timestamps.addLast(now);
                    return;
                }

                // The window is full: we must wait for the oldest one to expire
                Instant oldest = timestamps.peekFirst();
                Duration wait = Duration.between(now, oldest.plus(window));
                if (wait.isNegative() || wait.isZero()) continue;

                log.debug("Rate limit reached; waiting {} ms", wait.toMillis());
                lock.unlock();                       // release it while we sleep
                try {
                    Thread.sleep(wait.toMillis());
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();     // module 8's rule: restore the flag
                    throw new QueryInterruptedException("Rate-limit wait interrupted", e);
                } finally {
                    lock.lock();                     // reacquire before going round again
                }
            }
        } finally {
            lock.unlock();
        }
    }

    private void purgeOld(Instant now) {
        Instant limit = now.minus(window);
        while (!timestamps.isEmpty() && timestamps.peekFirst().isBefore(limit)) {
            timestamps.pollFirst();
        }
    }
}

@Bean
MetadataGateway metadataGateway(HttpMetadataGateway http, Clock clock, MeterRegistry registry) {
    return new MeteredGateway(                           // 3rd: measures total time (waiting included)
             new RateLimitedGateway(                     // 2nd: never exceeds 10 per minute
               new CachingGateway(http, Duration.ofHours(24)),    // 1st: the cache avoids requests
               10, Duration.ofMinutes(1), clock));
}

@Test
void waitsWhenTheLimitIsExceeded() {
    var delegate = new FakeGateway();
    var clock = Clock.fixed(Instant.parse("2026-03-20T10:00:00Z"), ZoneOffset.UTC);
    var gateway = new RateLimitedGateway(delegate, 2, Duration.ofSeconds(1), clock);

    long start = System.nanoTime();
    gateway.findByIsbn(Isbn.of("978-0000000001"));
    gateway.findByIsbn(Isbn.of("978-0000000002"));
    gateway.findByIsbn(Isbn.of("978-0000000003"));   // the third must wait ~1 s
    long ms = (System.nanoTime() - start) / 1_000_000;

    assertThat(ms).isGreaterThanOrEqualTo(900);
    assertThat(delegate.calls()).isEqualTo(3);
}

public enum ReservationStatus {

    /** Queued, waiting for a copy to become free. */
    PENDING {
        @Override public boolean canBeCancelled()      { return true; }
        @Override public boolean holdsQueuePlace()     { return true; }
        @Override public ReservationStatus onCopyAvailable() { return AVAILABLE; }
    },

    /** A copy is being held; the employee has 48 hours. */
    AVAILABLE {
        @Override public boolean canBeCancelled()  { return true; }
        @Override public boolean canBeCollected()  { return true; }
        @Override public boolean canExpire()       { return true; }
        @Override public boolean holdsQueuePlace() { return true; }
        @Override public boolean hasDeadline()     { return true; }
        @Override public ReservationStatus onCollect() { return COLLECTED; }
        @Override public ReservationStatus onExpire()  { return EXPIRED; }
    },

    COLLECTED { @Override public boolean isFinal() { return true; } },
    EXPIRED   { @Override public boolean isFinal() { return true; } },
    CANCELLED { @Override public boolean isFinal() { return true; } };

    // --- Queries: by default, nothing is allowed ---
    public boolean canBeCancelled()  { return false; }
    public boolean canBeCollected()  { return false; }
    public boolean canExpire()       { return false; }
    public boolean holdsQueuePlace() { return false; }
    public boolean hasDeadline()     { return false; }
    public boolean isFinal()         { return false; }

    // --- Transitions: by default, invalid ---
    public ReservationStatus onCopyAvailable() { throw new InvalidTransitionException(this, "copy available"); }
    public ReservationStatus onCollect()       { throw new InvalidTransitionException(this, "collect"); }
    public ReservationStatus onExpire()        { throw new InvalidTransitionException(this, "expire"); }

    /** Cancelling is the only transition shared by several states. */
    public ReservationStatus onCancel() {
        if (!canBeCancelled()) throw new InvalidTransitionException(this, "cancel");
        return CANCELLED;
    }
}

@Entity
public class Reservation {

    private static final int HOURS_TO_COLLECT = 48;

    @Id @GeneratedValue private Long id;
    @ManyToOne(fetch = FetchType.LAZY) private Material material;
    @ManyToOne(fetch = FetchType.LAZY) private Employee employee;
    @Enumerated(EnumType.STRING) private ReservationStatus status;
    private Instant requestDate;
    private Instant collectionDeadline;       // only meaningful in AVAILABLE
    @Version private long version;            // optimistic locking (11-03)

    protected Reservation() { }               // required by JPA

    public static Reservation create(Material material, Employee employee, Clock clock) {
        Reservation r = new Reservation();
        r.material = material;
        r.employee = employee;
        r.status = ReservationStatus.PENDING;
        r.requestDate = Instant.now(clock);
        return r;
    }

    public void assignCopy(Clock clock) {
        this.status = status.onCopyAvailable();       // validates and transitions in one line
        this.collectionDeadline = Instant.now(clock).plus(HOURS_TO_COLLECT, ChronoUnit.HOURS);
    }

    public void collect() {
        this.status = status.onCollect();
        this.collectionDeadline = null;
    }

    public void cancel() {
        this.status = status.onCancel();
        this.collectionDeadline = null;
    }

    /** Returns true if it did expire. Idempotent: if it does not apply, it does nothing. */
    public boolean expireIfDue(Clock clock) {
        if (!status.canExpire()) return false;
        if (Instant.now(clock).isBefore(collectionDeadline)) return false;
        this.status = status.onExpire();
        this.collectionDeadline = null;
        return true;
    }

    public boolean holdsQueuePlace() { return status.holdsQueuePlace(); }
}

@Scheduled(cron = "0 */15 * * * *")     // every 15 minutes
@Transactional
public void expireOverdueReservations() {
    int expired = 0;
    for (Reservation r : repository.withStatus(ReservationStatus.AVAILABLE)) {
        if (r.expireIfDue(clock)) {
            expired++;
            events.publishEvent(new ReservationExpired(r.getId()));   // Observer
        }
    }
    log.info("Reservations expired: {}", expired);
}