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

public class LegacyCatalog {

    public static void main(String[] args) {
        List catalog = new ArrayList();   // no generics: holds Object

        catalog.add(new Book("Effective Java", "978-0000000001"));
        catalog.add(new Book("Design Patterns", "978-0000000002"));
        catalog.add("Refactoring");   // WRONG! but the compiler says nothing

        for (int i = 0; i < catalog.size(); i++) {
            Book book = (Book) catalog.get(i);   // cast is mandatory
            System.out.println(book.getTitle());
        }
    }
}

Effective Java
Design Patterns
Exception in thread "main" java.lang.ClassCastException:
    class java.lang.String cannot be cast to class Book
    at LegacyCatalog.main(LegacyCatalog.java:14)

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

public class ModernCatalog {

    public static void main(String[] args) {
        List<Book> catalog = new ArrayList<>();

        catalog.add(new Book("Effective Java", "978-0000000001"));
        catalog.add(new Book("Design Patterns", "978-0000000002"));
        // catalog.add("Refactoring");   // DOES NOT COMPILE

        for (Book book : catalog) {           // no cast
            System.out.println(book.getTitle());
        }
    }
}

error: no suitable method found for add(String)
    catalog.add("Refactoring");
           ^
    method Collection.add(Book) is not applicable
      (argument mismatch; String cannot be converted to Book)

package com.nexussoftware.bibliotech.domain;

/**
 * Container for a single value of type T.
 * T is a TYPE PARAMETER: it does not exist until somebody
 * writes Box<Book> or Box<String>.
 */
public class Box<T> {

    private T content;            // field of the parameterised type

    public Box(T content) {       // parameter of the parameterised type
        this.content = content;
    }

    public T get() {              // return of the parameterised type
        return content;
    }

    public void put(T content) {
        this.content = content;
    }

    public boolean isEmpty() {
        return content == null;
    }

    @Override
    public String toString() {
        return "Box[" + content + "]";
    }
}

Box<Book> bookBox = new Box<>(new Book("Effective Java", "978-0000000001"));
Book b = bookBox.get();             // no cast: the compiler knows it is a Book

Box<String> textBox = new Box<>("Room 3");
String s = textBox.get();

// bookBox.put("not this");         // DOES NOT COMPILE

/**
 * Pair of values of possibly different types.
 * It is, in essence, what Map.Entry<K, V> does.
 */
public class Pair<A, B> {

    private final A first;
    private final B second;

    public Pair(A first, B second) {
        this.first = first;
        this.second = second;
    }

    public A first()  { return first; }
    public B second() { return second; }

    /** Returns the pair with its elements swapped. */
    public Pair<B, A> swap() {
        return new Pair<>(second, first);
    }

    @Override
    public String toString() {
        return "(" + first + ", " + second + ")";
    }
}

Pair<String, Integer> loansPerEmployee = new Pair<>("Marta Ruiz", 4);
Pair<Integer, String> swapped = loansPerEmployee.swap();
System.out.println(loansPerEmployee);   // (Marta Ruiz, 4)
System.out.println(swapped);            // (4, Marta Ruiz)

Map<String, List<Loan>> byEmployee = new HashMap<String, List<Loan>>();

Map<String, List<Loan>> byEmployee = new HashMap<>();

var catalog = new ArrayList<Book>();      // GOOD: the type goes on the right
// var list = new ArrayList<>();          // infers ArrayList<Object>: almost never what you want

Comparator<Book> byTitle = new Comparator<>() {      // Java 9+
    @Override
    public int compare(Book a, Book b) {
        return a.getTitle().compareTo(b.getTitle());
    }
};

package com.nexussoftware.bibliotech.domain;

/**
 * Everything BiblioTech can store in a repository
 * knows how to state its identifier.
 */
public interface Identifiable {
    String getId();
}

package com.nexussoftware.bibliotech.service;

/**
 * Turns objects of type T into a line of text and back again.
 * Replaces the toText/fromText methods repeated in module 7.
 */
public interface Serialiser<T> {

    String serialise(T object);

    T deserialise(String line);
}

// WAY 1: pin the type down. The implementation is NO LONGER generic.
public class BookSerialiser implements Serialiser<Book> {

    @Override
    public String serialise(Book book) {
        return book.getIsbn() + ";" + book.getTitle();
    }

    @Override
    public Book deserialise(String line) {
        String[] parts = line.split(";", 2);
        return new Book(parts[1], parts[0]);
    }
}

// WAY 2: propagate the parameter. The implementation stays generic.
public class LoggingSerialiser<T> implements Serialiser<T> {

    private final Serialiser<T> delegate;

    public LoggingSerialiser(Serialiser<T> delegate) {
        this.delegate = delegate;
    }

    @Override
    public String serialise(T object) {
        String result = delegate.serialise(object);
        System.out.println("[SER] " + object.getClass().getSimpleName());
        return result;
    }

    @Override
    public T deserialise(String line) {
        return delegate.deserialise(line);
    }
}

public class Utilities {

    /**
     * Swaps two positions of a list of any type.
     *   modifiers  <T>  return  name
     */
    public static <T> void swap(List<T> list, int i, int j) {
        T temp = list.get(i);
        list.set(i, list.get(j));
        list.set(j, temp);
    }

    /** Returns the first element, or null if the list is empty. */
    public static <T> T first(List<T> list) {
        return list.isEmpty() ? null : list.get(0);
    }

    /** Builds a list out of loose elements. */
    @SafeVarargs
    public static <T> List<T> listOf(T... elements) {
        return new ArrayList<>(Arrays.asList(elements));
    }

    /** Counts how many elements of the list satisfy the predicate. */
    public static <T> long count(List<T> list, Predicate<T> criterion) {
        long total = 0;
        for (T element : list) {
            if (criterion.test(element)) {
                total++;
            }
        }
        return total;
    }
}

List<Book> catalog = Utilities.listOf(
        new Book("Effective Java", "978-0000000001"),
        new Book("Refactoring", "978-0000000003"));

Utilities.swap(catalog, 0, 1);                  // T is inferred: Book
Book first = Utilities.first(catalog);           // T is inferred: Book

long onLoan = Utilities.count(catalog, Book::isOnLoan);

List<Material> empty = Utilities.<Material>listOf();   // with no arguments there is nothing to infer

public class Box<T> {
    // ERROR: non-static type variable T cannot be referenced from a static context
    public static T createEmpty() { return null; }
}

public static <U> Box<U> createEmpty() {
    return new Box<>(null);
}

/**
 * Returns the largest element of the list.
 * T MUST know how to compare itself with itself.
 */
public static <T extends Comparable<T>> T max(List<T> list) {
    if (list.isEmpty()) {
        throw new IllegalArgumentException("empty list");
    }
    T largest = list.get(0);
    for (T element : list) {
        if (element.compareTo(largest) > 0) {   // legal ONLY thanks to the bound
            largest = element;
        }
    }
    return largest;
}

/** Concatenates the titles of any collection of materials. */
public static <T extends Material> String titles(List<T> materials) {
    StringBuilder sb = new StringBuilder();
    for (T m : materials) {
        sb.append(m.getTitle()).append("; ");   // getTitle() belongs to Material
    }
    return sb.toString();
}

/**
 * Sorts and prints elements that on top of being comparable
 * know how to serialise themselves.
 */
public static <T extends Comparable<T> & Serializable> void archiveSorted(List<T> items) {
    Collections.sort(items);
    for (T item : items) {
        System.out.println("Archiving: " + item);
    }
}

public static <T extends Material & Comparable<T>> List<T> sortCatalog(List<T> materials) {
    List<T> copy = new ArrayList<>(materials);
    Collections.sort(copy);
    return copy;
}

List<String> texts = new ArrayList<>();
// List<Object> objects = texts;    // DOES NOT COMPILE

List<String> texts = new ArrayList<>();
List<Object> objects = texts;         // suppose this compiled
objects.add(Integer.valueOf(42));     // legal: an Integer IS an Object
String s = texts.get(0);              // BOOM: ClassCastException at run time

public class ArrayCovariance {

    public static void main(String[] args) {
        String[] texts = { "Effective Java", "Refactoring" };
        Object[] objects = texts;           // COMPILES: arrays are covariant

        objects[0] = Integer.valueOf(42);   // compiles... and blows up at run time
        System.out.println(texts[0]);
    }
}

Exception in thread "main" java.lang.ArrayStoreException: java.lang.Integer
    at ArrayCovariance.main(ArrayCovariance.java:8)

public static void printTitles(List<Material> materials) {
    for (Material m : materials) {
        System.out.println(m.getTitle());
    }
}

/** Works for ANY list: it only uses methods that do not depend on T. */
public static void reportSize(List<?> list) {
    System.out.println("The list has " + list.size() + " elements");
    for (Object o : list) {          // the only safe thing is to read as Object
        System.out.println("  - " + o);
    }
}

reportSize(List.of("a", "b"));                                     // List<String>
reportSize(List.of(new Book("Effective Java", "978-0000000001"))); // List<Book>

public static void tryToAdd(List<?> list) {
    // list.add("hello");     // DOES NOT COMPILE
    // list.add(new Object()); // DOES NOT COMPILE
    list.add(null);            // the only one allowed
}

public static void printTitles(List<? extends Material> materials) {
    for (Material m : materials) {       // reading as Material: SAFE
        System.out.println(m.getTitle());
    }
    // materials.add(new Book(...));      // DOES NOT COMPILE
}

List<Book> books = new ArrayList<>();
List<Magazine> magazines = new ArrayList<>();
List<Material> mixed = new ArrayList<>();

printTitles(books);        // OK
printTitles(magazines);    // OK
printTitles(mixed);        // OK

public static void addSampleBooks(List<? super Book> target) {
    target.add(new Book("Effective Java", "978-0000000001"));   // SAFE
    target.add(new Book("Refactoring", "978-0000000003"));

    // Book b = target.get(0);      // DOES NOT COMPILE
    Object o = target.get(0);       // the only safe thing is Object
}

List<Book> booksOnly = new ArrayList<>();
List<Material> materials = new ArrayList<>();
List<Object> anything = new ArrayList<>();

addSampleBooks(booksOnly);    // OK
addSampleBooks(materials);    // OK
addSampleBooks(anything);     // OK

/**
 * Copies elements from source to target.
 *   source PRODUCES elements -> ? extends T
 *   target CONSUMES elements -> ? super T
 */
public static <T> void copy(List<? extends T> source, List<? super T> target) {
    for (T element : source) {
        target.add(element);
    }
}

List<Book> books = List.of(
        new Book("Effective Java", "978-0000000001"),
        new Book("Design Patterns", "978-0000000002"));

List<Material> store = new ArrayList<>();
List<Object> log      = new ArrayList<>();

Utilities.<Material>copy(books, store);   // Book produces, Material consumes
Utilities.<Book>copy(books, log);         // Book produces, Object consumes

// WRONG: the target declared as a producer
public static <T> void copyWrong(List<? extends T> source, List<? extends T> target) {
    for (T element : source) {
        target.add(element);     // DOES NOT COMPILE
    }
}

error: no suitable method found for add(T)
    target.add(element);
          ^
    method Collection.add(CAP#1) is not applicable
      (argument mismatch; T cannot be converted to CAP#1)

// WRONG: the source declared as a consumer
public static <T> void copyWrong2(List<? super T> source, List<? super T> target) {
    for (T element : source) {   // DOES NOT COMPILE
        target.add(element);
    }
}

error: incompatible types: CAP#1 cannot be converted to T

// Collections: the source produces, the destination consumes
public static <T> void copy(List<? super T> dest, List<? extends T> src)

// The comparator CONSUMES elements in order to compare them
public static <T> void sort(List<T> list, Comparator<? super T> c)

// Stream.map: the function CONSUMES T and PRODUCES R
<R> Stream<R> map(Function<? super T, ? extends R> mapper)

// Optional.ifPresent: the consumer CONSUMES T
public void ifPresent(Consumer<? super T> action)

Comparator<Material> byTitle = Comparator.comparing(Material::getTitle);

List<Book> books = new ArrayList<>(...);
books.sort(byTitle);       // works thanks to the ? super T

public class Box<T> {
    private T content;
    public T get() { return content; }
    public void put(T c) { this.content = c; }
}

public class Box {
    private Object content;
    public Object get() { return content; }
    public void put(Object c) { this.content = c; }
}

Box<Book> box = new Box<>(book);
Book b = box.get();

Box box = new Box(book);
Book b = (Book) box.get();      // the cast is put in by the compiler

public static <T extends Material> String titles(List<T> list)
// erases to
public static String titles(List list)     // and inside, T is treated as Material

javac Box.java
javap -p Box.class

public class Box<T> {
  private T content;
  public Box(T);
  public T get();
  public void put(T);
}

public class Repository<T> {
    public T createEmpty() {
        // return new T();   // ERROR: type parameter T cannot be instantiated directly
        return null;
    }
}

public class Repository<T> {

    private final Supplier<T> factory;

    public Repository(Supplier<T> factory) {
        this.factory = factory;
    }

    public T createEmpty() {
        return factory.get();      // the factory DOES know how to build a T
    }
}

// usage
Repository<Book> repo = new Repository<>(Book::new);

if (object instanceof List<String>) { }   // ERROR: illegal generic type for instanceof
if (object instanceof List<?>) { }        // OK: only the raw type is checkable

public class Reports {
    // ERROR: name clash: both erase to  process(List)
    public void process(List<Book> books) { }
    public void process(List<Magazine> magazines) { }
}

error: name clash: process(List<Magazine>) and process(List<Book>) have the same erasure

public class Repository<T> {
    // private T[] items = new T[10];   // ERROR: generic array creation
}

// SOLUTION 1 (recommended): use a List
private final List<T> items = new ArrayList<>();

// SOLUTION 2: array of Object with a cast and a suppressed warning (what ArrayList does inside)
@SuppressWarnings("unchecked")
private T[] items = (T[]) new Object[10];

List<Book> books = new ArrayList<>();
List<String> texts = new ArrayList<>();

System.out.println(books.getClass());                       // class java.util.ArrayList
System.out.println(books.getClass() == texts.getClass());   // true

public class BookComparator implements Comparator<Book> {
    @Override
    public int compare(Book a, Book b) {
        return a.getTitle().compareTo(b.getTitle());
    }
}

// generated by the compiler, marked as synthetic and bridge
public int compare(Object a, Object b) {
    return compare((Book) a, (Book) b);   // delegates, with the cast
}

List raw = new ArrayList();         // raw type
raw.add("anything");
raw.add(42);

Note: Example.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

public static void poison(List raw) {        // raw type
    raw.add("I am not a Book");
}

public static void main(String[] args) {
    List<Book> catalog = new ArrayList<>();
    poison(catalog);                         // compiles, only a warning

    for (Book b : catalog) {                 // ClassCastException here
        System.out.println(b.getTitle());
    }
}

javac -Xlint:unchecked -Xlint:rawtypes *.java

@SuppressWarnings("unchecked")   // over the whole class: it silences future bugs
public class Repository<T> { ... }

public <T> T[] copyInto(T[] target) {
    if (target.length < size) {
        // SAFE: Arrays.copyOf with the target array's real type
        // returns an array of the same type as 'target', which is T[].
        @SuppressWarnings("unchecked")
        T[] fresh = (T[]) Arrays.copyOf(items, size, target.getClass());
        return fresh;
    }
    System.arraycopy(items, 0, target, 0, size);
    return target;
}

package com.nexussoftware.bibliotech.service;

import java.lang.reflect.InvocationTargetException;

/**
 * Generic factory that CAN create instances of T,
 * because it receives the Class<T> as a type token.
 */
public class EntityFactory<T> {

    private final Class<T> type;

    public EntityFactory(Class<T> type) {
        this.type = type;
    }

    /** Creates an instance using the no-argument constructor. */
    public T create() {
        try {
            return type.getDeclaredConstructor().newInstance();
        } catch (NoSuchMethodException | InstantiationException
                 | IllegalAccessException | InvocationTargetException e) {
            throw new IllegalStateException(
                    "Could not instantiate " + type.getSimpleName(), e);
        }
    }

    /**
     * Converts safely: a cast checked at RUN TIME.
     * If the object is not of the expected type it throws ClassCastException
     * right here, not three layers further down.
     */
    public T convert(Object candidate) {
        return type.cast(candidate);
    }

    public String typeName() {
        return type.getSimpleName();
    }
}

EntityFactory<Book> factory = new EntityFactory<>(Book.class);
Book fresh = factory.create();
System.out.println(factory.typeName());     // Book

public class TypedContext {

    private final Map<Class<?>, Object> values = new HashMap<>();

    public <T> void put(Class<T> type, T value) {
        values.put(Objects.requireNonNull(type), value);
    }

    public <T> T get(Class<T> type) {
        return type.cast(values.get(type));   // safe cast
    }
}

TypedContext ctx = new TypedContext();
ctx.put(Employee.class, new Employee("Marta Ruiz"));
ctx.put(String.class, "session-4711");

Employee who = ctx.get(Employee.class);     // no cast, no warning

public <E extends Exception> void execute(Runnable task, Class<E> type) {
    try {
        task.run();
    } catch (E e) {        // ERROR: cannot use the type variable E in a catch clause
        // ...
    }
}

public <E extends Exception> void execute(Runnable task, Class<E> type) throws E {
    try {
        task.run();
    } catch (Exception e) {
        if (type.isInstance(e)) {
            throw type.cast(e);     // rethrown already typed
        }
        throw new BiblioTechException("Unexpected failure in the task", e);
    }
}

// ERROR: a generic class may not extend java.lang.Throwable
public class TypedError<T> extends BiblioTechException { }

/** Runs the task propagating its typed exception. */
public static <T, E extends Exception> T attempt(FailingSupplier<T, E> task) throws E {
    return task.get();
}

@FunctionalInterface
public interface FailingSupplier<T, E extends Exception> {
    T get() throws E;
}

package com.nexussoftware.bibliotech.service;

import com.nexussoftware.bibliotech.domain.Identifiable;

import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Predicate;

/**
 * Generic, thread-safe repository for any entity
 * that knows how to give its identifier.
 *
 * The bound <T extends Identifiable> allows calling getId()
 * inside the class with no cast at all.
 */
public class Repository<T extends Identifiable> {

    private final Map<String, T> byId = new ConcurrentHashMap<>();
    private final String name;

    public Repository(String name) {
        this.name = Objects.requireNonNull(name, "name");
    }

    /** Stores or replaces. Returns the previous value, if there was one. */
    public Optional<T> save(T entity) {
        Objects.requireNonNull(entity, "entity");
        return Optional.ofNullable(byId.put(entity.getId(), entity));
    }

    /** Stores only if it was absent. true if it was inserted. */
    public boolean saveIfAbsent(T entity) {
        return byId.putIfAbsent(entity.getId(), entity) == null;
    }

    public Optional<T> findById(String id) {
        return Optional.ofNullable(byId.get(id));
    }

    public Optional<T> remove(String id) {
        return Optional.ofNullable(byId.remove(id));
    }

    public boolean contains(String id) {
        return byId.containsKey(id);
    }

    public int size() {
        return byId.size();
    }

    /** Unmodifiable view: nobody can alter the repository through the back door. */
    public List<T> listAll() {
        return List.copyOf(byId.values());
    }

    /**
     * Filters with a predicate.
     * Predicate<? super T> by PECS: the predicate CONSUMES elements,
     * so a Predicate<Identifiable> will do as well.
     */
    public List<T> find(Predicate<? super T> criterion) {
        List<T> result = new ArrayList<>();
        for (T entity : byId.values()) {
            if (criterion.test(entity)) {
                result.add(entity);
            }
        }
        return result;
    }

    /**
     * Sorts a copy.
     * Comparator<? super T> by PECS: a Comparator<Identifiable> works
     * for sorting any subtype.
     */
    public List<T> listSorted(Comparator<? super T> order) {
        List<T> copy = new ArrayList<>(byId.values());
        copy.sort(order);
        return copy;
    }

    /**
     * Dumps all the entities into the target.
     * ? super T by PECS: the target CONSUMES.
     */
    public void dumpInto(Collection<? super T> target) {
        target.addAll(byId.values());
    }

    @Override
    public String toString() {
        return "Repository[" + name + ", " + byId.size() + " entities]";
    }
}

public abstract class Material implements Identifiable {

    private final String isbn;
    private final String title;
    // ... the rest from module 3

    @Override
    public String getId() {
        return isbn;
    }
}

public class Loan implements Identifiable {

    private final String reference;    // e.g. "LN-2026-0041"

    @Override
    public String getId() {
        return reference;
    }
}

package com.nexussoftware.bibliotech;

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

import java.util.Comparator;
import java.util.List;

public class BiblioTechApp {

    public static void main(String[] args) {

        Repository<Material> catalog = new Repository<>("catalogue");
        Repository<Loan> loans = new Repository<>("loans");

        catalog.save(new Book("Effective Java", "978-0000000001"));
        catalog.save(new Book("Design Patterns", "978-0000000002"));
        catalog.save(new Book("Refactoring", "978-0000000003"));

        loans.save(new Loan("LN-2026-0041", "978-0000000001", "Marta Ruiz"));
        loans.save(new Loan("LN-2026-0042", "978-0000000003", "Diego Alonso"));

        // Not a single cast in everything that follows.
        catalog.findById("978-0000000001")
               .ifPresent(m -> System.out.println("Found: " + m.getTitle()));

        List<Material> sorted =
                catalog.listSorted(Comparator.comparing(Material::getTitle));
        sorted.forEach(m -> System.out.println("  " + m.getTitle()));

        List<Loan> martasLoans = loans.find(l -> l.getEmployee().equals("Marta Ruiz"));
        System.out.println("Marta's loans: " + martasLoans.size());

        System.out.println(catalog);
        System.out.println(loans);
    }
}

Found: Effective Java
  Design Patterns
  Effective Java
  Refactoring
Marta's loans: 1
Repository[catalogue, 3 entities]
Repository[loans, 2 entities]

package com.nexussoftware.bibliotech.service;

import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.function.Function;

/**
 * Result of an operation that can fail in an expected way.
 * It either holds a value of type T, or it holds an error message.
 * Never both, never neither.
 *
 * Private constructor + static factories: it is impossible to build
 * an incoherent Result.
 */
public final class Result<T> {

    private final T value;
    private final String error;

    private Result(T value, String error) {
        this.value = value;
        this.error = error;
    }

    /**
     * Static generic method: it declares its own <U>, because a
     * static method CANNOT use the class's T (section 7).
     */
    public static <U> Result<U> success(U value) {
        return new Result<>(Objects.requireNonNull(value, "value"), null);
    }

    public static <U> Result<U> failure(String error) {
        return new Result<>(null, Objects.requireNonNull(error, "error"));
    }

    public boolean isSuccess() { return error == null; }
    public boolean isFailure() { return error != null; }

    public T value() {
        if (isFailure()) {
            throw new NoSuchElementException("The result is a failure: " + error);
        }
        return value;
    }

    public String error() {
        if (isSuccess()) {
            throw new NoSuchElementException("The result is a success");
        }
        return error;
    }

    public T orDefault(T alternative) {
        return isSuccess() ? value : alternative;
    }

    /**
     * Transforms the value on success; propagates the error otherwise.
     * Function<? super T, ? extends R> by PECS:
     *   the function CONSUMES T -> ? super T
     *   the function PRODUCES R -> ? extends R
     */
    public <R> Result<R> map(Function<? super T, ? extends R> transformation) {
        if (isFailure()) {
            return Result.failure(error);       // the error travels untouched
        }
        return Result.success(transformation.apply(value));
    }

    /** Chains operations that can themselves fail, without nesting Result<Result<R>>. */
    public <R> Result<R> flatMap(Function<? super T, Result<R>> next) {
        return isFailure() ? Result.failure(error) : next.apply(value);
    }

    @Override
    public String toString() {
        return isSuccess() ? "Success[" + value + "]" : "Failure[" + error + "]";
    }
}

package com.nexussoftware.bibliotech.service;

import com.nexussoftware.bibliotech.domain.*;

public class LoanManager {

    private final Repository<Material> catalog;
    private final Repository<Loan> loans;

    public LoanManager(Repository<Material> catalog, Repository<Loan> loans) {
        this.catalog = catalog;
        this.loans = loans;
    }

    /** The return type SAYS this can fail, and with what value it succeeds. */
    public Result<Loan> lend(String isbn, String employee) {

        Material material = catalog.findById(isbn).orElse(null);
        if (material == null) {
            return Result.failure("There is no material with ISBN " + isbn);
        }
        if (material.isOnLoan()) {
            return Result.failure("The material '" + material.getTitle() + "' is already on loan");
        }

        material.markOnLoan(employee);
        Loan loan = new Loan(nextReference(), isbn, employee);
        loans.save(loan);
        return Result.success(loan);
    }

    private String nextReference() {
        return String.format("LN-2026-%04d", loans.size() + 1);
    }
}

Result<Loan> result = manager.lend("978-0000000001", "Nuria Vidal");

if (result.isSuccess()) {
    System.out.println("Loan registered: " + result.value().getId());
} else {
    System.out.println("Could not lend: " + result.error());
}

// Chaining with no intermediate checks
String receipt = manager.lend("978-0000000002", "Diego Alonso")
        .map(Loan::getId)
        .map(id -> "Receipt no. " + id)
        .orDefault("No receipt: the loan could not be registered");

System.out.println(receipt);

Loan registered: LN-2026-0043
Receipt no. LN-2026-0044

package com.nexussoftware.bibliotech.service;

import java.util.*;
import java.util.function.Function;

/**
 * Generic LRU cache with a maximum capacity.
 *
 * K and V are independent: you can have a Cache<String, Card>
 * or a Cache<Integer, List<Loan>> with the same class.
 */
public class Cache<K, V> {

    private final int capacity;
    private final LinkedHashMap<K, V> map;

    private long hits = 0;
    private long misses = 0;

    public Cache(int capacity) {
        if (capacity <= 0) {
            throw new IllegalArgumentException("The capacity must be positive: " + capacity);
        }
        this.capacity = capacity;

        // Third argument true = ACCESS order (not insertion order): that is the LRU.
        // 0.75f is the usual load factor (picks up 05-05).
        this.map = new LinkedHashMap<>(capacity, 0.75f, true) {
            @Override
            protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
                // When it returns true, LinkedHashMap removes the oldest entry.
                return size() > Cache.this.capacity;
            }
        };
    }

    /** Returns Optional instead of null: absence is explicit (see 10-04). */
    public Optional<V> get(K key) {
        V value = map.get(key);           // get() reorders because it is access order
        if (value != null) {
            hits++;
        } else {
            misses++;
        }
        return Optional.ofNullable(value);
    }

    public void put(K key, V value) {
        Objects.requireNonNull(key, "key");
        Objects.requireNonNull(value, "value");
        map.put(key, value);
    }

    /**
     * PECS applied: the function CONSUMES the key (? super K)
     * and PRODUCES the value (? extends V).
     * That way it accepts a Function<Object, Card> for a Cache<String, Card>.
     */
    public V getOrCompute(K key, Function<? super K, ? extends V> computation) {
        V existing = map.get(key);
        if (existing != null) {
            hits++;
            return existing;
        }
        misses++;
        V computed = computation.apply(key);
        map.put(key, computed);
        return computed;
    }

    public int size() {
        return map.size();
    }

    /** From the least recently used to the most recent. */
    public List<K> keysByAge() {
        return new ArrayList<>(map.keySet());
    }

    public double hitRate() {
        long total = hits + misses;
        return total == 0 ? 0.0 : (double) hits / total;
    }

    @Override
    public String toString() {
        return String.format("Cache[%d/%d entries, %d hits, %d misses, %.0f%% hit rate]",
                map.size(), capacity, hits, misses, hitRate() * 100);
    }
}

public class CacheTest {

    public static void main(String[] args) {

        Cache<String, Card> cards = new Cache<>(3);

        // The computation simulates an expensive lookup (reading the CSV, or a network call)
        Function<String, Card> expensiveLookup = isbn -> {
            System.out.println("  [COMPUTING card for " + isbn + "]");
            return new Card(isbn, "Title of " + isbn);
        };

        System.out.println("1) " + cards.getOrCompute("978-0000000001", expensiveLookup));
        System.out.println("2) " + cards.getOrCompute("978-0000000002", expensiveLookup));
        System.out.println("3) " + cards.getOrCompute("978-0000000001", expensiveLookup)); // hit
        System.out.println("4) " + cards.getOrCompute("978-0000000003", expensiveLookup));

        System.out.println("Keys before overflow: " + cards.keysByAge());

        // This fourth key evicts the least recently used one,
        // which is ...0002 (...0001 was refreshed in step 3).
        System.out.println("5) " + cards.getOrCompute("978-0000000004", expensiveLookup));

        System.out.println("Keys after:           " + cards.keysByAge());
        System.out.println(cards);
    }
}

  [COMPUTING card for 978-0000000001]
1) Card[978-0000000001, Title of 978-0000000001]
  [COMPUTING card for 978-0000000002]
2) Card[978-0000000002, Title of 978-0000000002]
3) Card[978-0000000001, Title of 978-0000000001]
  [COMPUTING card for 978-0000000003]
4) Card[978-0000000003, Title of 978-0000000003]
Keys before overflow: [978-0000000002, 978-0000000001, 978-0000000003]
  [COMPUTING card for 978-0000000004]
5) Card[978-0000000004, Title of 978-0000000004]
Keys after:           [978-0000000001, 978-0000000003, 978-0000000004]
Cache[3/3 entries, 1 hits, 4 misses, 20% hit rate]

package com.nexussoftware.bibliotech.service;

import java.util.*;
import java.util.function.Predicate;

public final class Aggregator {

    private Aggregator() { }   // utility class: not instantiated

    /**
     * PRODUCES numbers that we read -> ? extends Number.
     * That way it accepts List<Integer>, List<Double>, List<Long>...
     * With Collection<Number> it would NOT accept a List<Integer> (invariance).
     */
    public static double sum(Collection<? extends Number> numbers) {
        double total = 0;
        for (Number n : numbers) {
            total += n.doubleValue();
        }
        return total;
    }

    /**
     * source   PRODUCES -> ? extends T
     * target   CONSUMES -> ? super T
     * criterion CONSUMES -> Predicate<? super T>
     */
    public static <T> int copyMatching(Collection<? extends T> source,
                                       Collection<? super T> target,
                                       Predicate<? super T> criterion) {
        int copied = 0;
        for (T element : source) {
            if (criterion.test(element)) {
                target.add(element);
                copied++;
            }
        }
        return copied;
    }

    /**
     * elements PRODUCES -> ? extends T
     * order    CONSUMES -> Comparator<? super T>
     * The return has NO wildcard: a clean Optional<T>.
     */
    public static <T> Optional<T> maxBy(Collection<? extends T> elements,
                                        Comparator<? super T> order) {
        Iterator<? extends T> it = elements.iterator();
        if (!it.hasNext()) {
            return Optional.empty();
        }
        T largest = it.next();
        while (it.hasNext()) {
            T candidate = it.next();
            if (order.compare(candidate, largest) > 0) {
                largest = candidate;
            }
        }
        return Optional.of(largest);
    }
}

public class AggregatorTest {

    public static void main(String[] args) {

        // 1) sum accepts any collection of subtypes of Number
        List<Integer> pages = List.of(412, 395, 448);
        List<Double>  fines = List.of(1.50, 0.75, 3.20);

        System.out.printf("Total pages: %.0f%n", Aggregator.sum(pages));
        System.out.printf("Total fines: %.2f EUR%n", Aggregator.sum(fines));

        // 2) source List<Book>, target List<Material>: two DIFFERENT types
        List<Book> books = new ArrayList<>(List.of(
                new Book("Effective Java",  "978-0000000001", 412, true),
                new Book("Design Patterns", "978-0000000002", 395, false),
                new Book("Refactoring",     "978-0000000003", 448, true)));

        List<Material> onLoan = new ArrayList<>();

        int copied = Aggregator.copyMatching(books, onLoan, Book::isOnLoan);
        System.out.println("Copied into the materials list: " + copied);
        onLoan.forEach(m -> System.out.println("  " + m.getTitle()));

        // 3) Comparator<Material> sorting a List<Book>: thanks to the ? super T
        Comparator<Material> byTitle = Comparator.comparing(Material::getTitle);

        Aggregator.maxBy(books, byTitle)
                  .ifPresent(b -> System.out.println("Last alphabetically: " + b.getTitle()));

        // And the maximum returns Book, not Material: the type is preserved
        Optional<Book> last = Aggregator.maxBy(books, byTitle);
        System.out.println("The static type is Book: " + last.map(Book::getIsbn).orElse("-"));
    }
}

Total pages: 1255
Total fines: 5.45 EUR
Copied into the materials list: 2
  Effective Java
  Refactoring
Last alphabetically: Refactoring
The static type is Book: 978-0000000003

package com.nexussoftware.bibliotech.service;

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

/**
 * Generic, chainable validator.
 * It accumulates rules and returns a Result<T> with ALL the failures,
 * not just the first one: whoever fills in a form is grateful to see them together.
 */
public final class ChainableValidator<T> {

    /** Rule-message pair. A generic record (04-07 + section 3 of this lesson). */
    private record Rule<T>(Predicate<? super T> condition, String message) { }

    private final String typeName;
    private final List<Rule<T>> rules = new ArrayList<>();

    private ChainableValidator(String typeName) {
        this.typeName = typeName;
    }

    /**
     * Type token (section 19): the Class<T> provides the readable name
     * and also pins T down without your having to write it.
     */
    public static <T> ChainableValidator<T> of(Class<T> type) {
        return new ChainableValidator<>(type.getSimpleName());
    }

    /**
     * Returns this so it can be chained.
     * Predicate<? super T> by PECS: the rule CONSUMES the object,
     * so a Predicate<Object> or a Predicate<Material> will also do.
     */
    public ChainableValidator<T> withRule(Predicate<? super T> condition, String message) {
        rules.add(new Rule<>(Objects.requireNonNull(condition, "condition"),
                             Objects.requireNonNull(message, "message")));
        return this;
    }

    public Result<T> validate(T object) {
        if (object == null) {
            return Result.failure("The " + typeName + " is null");
        }

        List<String> failures = new ArrayList<>();
        for (Rule<T> rule : rules) {
            if (!rule.condition().test(object)) {
                failures.add(rule.message());
            }
        }

        if (failures.isEmpty()) {
            return Result.success(object);
        }
        return Result.failure("Invalid " + typeName + ": " + String.join("; ", failures));
    }

    public int ruleCount() {
        return rules.size();
    }
}

public class ValidatorTest {

    public static void main(String[] args) {

        ChainableValidator<Book> validator = ChainableValidator.of(Book.class)
                .withRule(b -> b.getIsbn() != null,                 "the ISBN is mandatory")
                .withRule(b -> b.getIsbn() != null
                            && b.getIsbn().length() == 17,          "the ISBN must be 17 characters long")
                .withRule(b -> b.getTitle() != null
                            && !b.getTitle().isBlank(),             "the title cannot be empty")
                .withRule(b -> b.getTitle() == null
                            || b.getTitle().length() < 200,         "the title exceeds 200 characters");

        System.out.println("Rules configured: " + validator.ruleCount());

        List<Book> candidates = List.of(
                new Book("Effective Java",  "978-0000000001"),
                new Book("Design Patterns", "978-1"),
                new Book("",                "978-0000000003"));

        for (Book candidate : candidates) {
            Result<Book> result = validator.validate(candidate);

            // Chaining with map: it only runs if there was a success
            String line = result
                    .map(Book::getTitle)
                    .map(t -> "ACCEPTED: " + t)
                    .orDefault("REJECTED: " + (result.isFailure() ? result.error() : ""));

            System.out.println(line);
        }

        // The validator is reusable with any Predicate<Material>
        Predicate<Material> hasTitle = m -> m.getTitle() != null;
        ChainableValidator<Book> other = ChainableValidator.of(Book.class)
                .withRule(hasTitle, "needs a title");   // Predicate<Material> in a Book validator
        System.out.println(other.validate(new Book("Refactoring", "978-0000000003")));
    }
}

Rules configured: 4
ACCEPTED: Effective Java
REJECTED: Invalid Book: the ISBN must be 17 characters long
REJECTED: Invalid Book: the title cannot be empty
Success[Book[Refactoring, 978-0000000003]]