// NORMAL ACCESS: everything is resolved at COMPILE TIME
Book book = new Book("Effective Java", "978-0000000001");
String title = book.getTitle();

// ACCESS BY REFLECTION: everything is resolved at RUN TIME
Class<?> type = Class.forName("com.nexussoftware.bibliotech.domain.Book");
Object book = type.getDeclaredConstructor(String.class, String.class)
                  .newInstance("Effective Java", "978-0000000001");
Method method = type.getMethod("getTitle");
String title = (String) method.invoke(book);

// 1. CLASS LITERAL: .class on the type's name
Class<Book> type1 = Book.class;

// 2. FROM AN INSTANCE: getClass()
Book book = new Book("Effective Java", "978-0000000001");
Class<? extends Book> type2 = book.getClass();

// 3. FROM ITS FULL NAME: Class.forName
Class<?> type3 = Class.forName("com.nexussoftware.bibliotech.domain.Book");

Material m = new Book("Effective Java", "978-0000000001");
System.out.println(m.getClass().getSimpleName());   // Book, not Material

Class<?> uninitialised = Class.forName(
        "com.nexussoftware.bibliotech.domain.Book",
        false,                                  // do not initialise
        Thread.currentThread().getContextClassLoader());

System.out.println(int.class.getName());          // int
System.out.println(Integer.class.getName());      // java.lang.Integer  (different)
System.out.println(String[].class.getName());     // [Ljava.lang.String;
System.out.println(int[][].class.getName());      // [[I
System.out.println(void.class.getName());         // void

package com.nexussoftware.bibliotech;

import java.lang.reflect.Modifier;
import java.util.Arrays;

public class ClassInspector {

    public static void describe(Class<?> type) {

        System.out.println("=== " + type.getSimpleName() + " ===");

        // --- NAMES ---
        System.out.println("getName():          " + type.getName());
        System.out.println("getSimpleName():    " + type.getSimpleName());
        System.out.println("getCanonicalName(): " + type.getCanonicalName());
        System.out.println("getPackageName():   " + type.getPackageName());

        // --- HIERARCHY ---
        Class<?> parent = type.getSuperclass();
        System.out.println("superclass:         " + (parent == null ? "none" : parent.getSimpleName()));

        System.out.println("interfaces:         " + Arrays.toString(
                Arrays.stream(type.getInterfaces()).map(Class::getSimpleName).toArray()));

        // Full inheritance chain up to Object
        StringBuilder chain = new StringBuilder(type.getSimpleName());
        for (Class<?> c = type.getSuperclass(); c != null; c = c.getSuperclass()) {
            chain.append(" -> ").append(c.getSimpleName());
        }
        System.out.println("chain:              " + chain);

        // --- MODIFIERS ---
        int mods = type.getModifiers();
        System.out.println("modifiers:          " + Modifier.toString(mods));
        System.out.println("  is public:        " + Modifier.isPublic(mods));
        System.out.println("  is abstract:      " + Modifier.isAbstract(mods));
        System.out.println("  is final:         " + Modifier.isFinal(mods));
        System.out.println();
    }

    public static void main(String[] args) {
        describe(Book.class);
        describe(Material.class);
        describe(Severity.class);
    }
}

=== Book ===
getName():          com.nexussoftware.bibliotech.domain.Book
getSimpleName():    Book
getCanonicalName(): com.nexussoftware.bibliotech.domain.Book
getPackageName():   com.nexussoftware.bibliotech.domain
superclass:         Material
interfaces:         []
chain:              Book -> Material -> Object
modifiers:          public
  is public:        true
  is abstract:      false
  is final:         false

=== Material ===
getName():          com.nexussoftware.bibliotech.domain.Material
getSimpleName():    Material
getCanonicalName(): com.nexussoftware.bibliotech.domain.Material
getPackageName():   com.nexussoftware.bibliotech.domain
superclass:         Object
interfaces:         [Identifiable]
chain:              Material -> Object
modifiers:          public abstract
  is public:        true
  is abstract:      true
  is final:         false

public static String classify(Class<?> type) {
    if (type.isPrimitive())   return "primitive";
    if (type.isArray())       return "array of " + type.getComponentType().getSimpleName();
    if (type.isEnum())        return "enum with " + type.getEnumConstants().length + " constants";
    if (type.isRecord())      return "record with " + type.getRecordComponents().length + " components";
    if (type.isAnnotation())  return "annotation";
    if (type.isInterface())   return "interface";
    if (type.isSealed())      return "sealed class";      // Java 17, see 10-06
    if (Modifier.isAbstract(type.getModifiers())) return "abstract class";
    return "concrete class";
}

System.out.println(Book.class          + " -> " + classify(Book.class));
System.out.println(Material.class      + " -> " + classify(Material.class));
System.out.println(Severity.class      + " -> " + classify(Severity.class));
System.out.println(Card.class          + " -> " + classify(Card.class));
System.out.println(Identifiable.class  + " -> " + classify(Identifiable.class));
System.out.println(int[].class         + " -> " + classify(int[].class));
System.out.println(CsvField.class      + " -> " + classify(CsvField.class));

class ...Book -> concrete class
class ...Material -> abstract class
class ...Severity -> enum with 3 constants
class ...Card -> record with 3 components
interface ...Identifiable -> interface
class [I -> array of int
interface ...CsvField -> annotation

for (Object constant : Severity.class.getEnumConstants()) {
    System.out.println("  - " + constant);
}

for (RecordComponent comp : Card.class.getRecordComponents()) {
    System.out.printf("  %s %s (accessor: %s)%n",
            comp.getType().getSimpleName(), comp.getName(), comp.getAccessor().getName());
}

  String isbn (accessor: isbn)
  String title (accessor: title)
  boolean available (accessor: available)

Material m = new Book("Effective Java", "978-0000000001");

// isInstance: equivalent to  (m instanceof Book)
System.out.println(Book.class.isInstance(m));                    // true

// isAssignableFrom: can a Book be assigned to a Material variable?
System.out.println(Material.class.isAssignableFrom(Book.class)); // true
System.out.println(Book.class.isAssignableFrom(Material.class)); // false

package com.nexussoftware.bibliotech;

import java.lang.reflect.Field;
import java.lang.reflect.Modifier;

public class FieldComparison {

    public static void main(String[] args) {

        System.out.println("--- getFields() on Book ---");
        for (Field f : Book.class.getFields()) {
            System.out.printf("  %-12s %-10s declared in %s%n",
                    f.getName(), Modifier.toString(f.getModifiers()),
                    f.getDeclaringClass().getSimpleName());
        }

        System.out.println("--- getDeclaredFields() on Book ---");
        for (Field f : Book.class.getDeclaredFields()) {
            System.out.printf("  %-12s %-20s %s%n",
                    f.getName(), Modifier.toString(f.getModifiers()),
                    f.getType().getSimpleName());
        }
    }
}

--- getFields() on Book ---
  DEFAULT_CATEGORY public static final declared in Material
--- getDeclaredFields() on Book ---
  isbn         private final        String
  title        private final        String
  author       private final        String
  pages        private final        int
  rating       private final        double
  onLoan       private              boolean

/**
 * All the fields declared in the class and in all its superclasses,
 * from the most derived to the most general.
 */
public static List<Field> allFields(Class<?> type) {
    List<Field> fields = new ArrayList<>();
    for (Class<?> c = type; c != null && c != Object.class; c = c.getSuperclass()) {
        fields.addAll(Arrays.asList(c.getDeclaredFields()));
    }
    return fields;
}

Book book = new Book("Effective Java", "978-0000000001", "Joshua Bloch", 412, 4.8);

Field titleField = Book.class.getDeclaredField("title");
titleField.setAccessible(true);                     // it is private (section 10)

String value = (String) titleField.get(book);       // READ
System.out.println(value);                          // Effective Java

titleField.set(book, "Effective Java 3rd ed.");     // WRITE
System.out.println(book.getTitle());                // Effective Java 3rd ed.

Field pagesField = Book.class.getDeclaredField("pages");
pagesField.setAccessible(true);
int pages = pagesField.getInt(book);           // no boxing

Field constant = Material.class.getDeclaredField("DEFAULT_CATEGORY");
String value = (String) constant.get(null);    // null: there is no instance

package com.nexussoftware.bibliotech;

import java.lang.reflect.*;
import java.util.Arrays;
import java.util.Comparator;

public class MethodInspector {

    public static void main(String[] args) {

        System.out.println("getMethods():         " + Book.class.getMethods().length + " methods");
        System.out.println("getDeclaredMethods(): " + Book.class.getDeclaredMethods().length + " methods");
        System.out.println();

        Method[] methods = Book.class.getDeclaredMethods();
        Arrays.sort(methods, Comparator.comparing(Method::getName));   // stable order

        for (Method m : methods) {

            // Filter out the BRIDGE and SYNTHETIC methods generated by the compiler (10-01)
            if (m.isBridge() || m.isSynthetic()) {
                System.out.println("  [bridge/synthetic] " + m.getName() + " -- ignored");
                continue;
            }

            String parameters = Arrays.stream(m.getParameterTypes())
                    .map(Class::getSimpleName)
                    .reduce((a, b) -> a + ", " + b)
                    .orElse("");

            System.out.printf("  %-10s %s %s(%s)%n",
                    Modifier.toString(m.getModifiers()),
                    m.getReturnType().getSimpleName(),
                    m.getName(),
                    parameters);
        }
    }
}

getMethods():         15 methods
getDeclaredMethods(): 8 methods

  public     boolean equals(Object)
  public     String getAuthor()
  public     String getId()
  public     String getIsbn()
  public     int getPages()
  public     String getTitle()
  public     int hashCode()
  public     String toString()

// lend(String, String)
Method lend = LoanManager.class.getMethod("lend", String.class, String.class);

// A method with no parameters
Method list = LoanManager.class.getMethod("listActive");

// A private method: getDeclaredMethod
Method internal = LoanManager.class.getDeclaredMethod("nextReference");

for (Parameter p : lend.getParameters()) {
    System.out.println(p.getType().getSimpleName() + " " + p.getName());
}

String arg0
String arg1

javac -parameters com/nexussoftware/bibliotech/service/LoanManager.java

String isbn
String employee

// No-argument constructor
Class<?> type = Class.forName("com.nexussoftware.bibliotech.domain.Book");
Object object = type.getDeclaredConstructor().newInstance();

// Constructor with arguments: you give the TYPES when looking it up
// and the VALUES when invoking it
Constructor<?> ctor = type.getDeclaredConstructor(
        String.class, String.class, String.class, int.class, double.class);

Object book = ctor.newInstance("Effective Java", "978-0000000001", "Joshua Bloch", 412, 4.8);

Class<Book> type = Book.class;                         // Class<Book>, not Class<?>
Constructor<Book> ctor = type.getDeclaredConstructor(String.class, String.class);
Book book = ctor.newInstance("Effective Java", "978-0000000001");    // no cast

Object o = type.newInstance();     // @Deprecated(since = "9")

// A singleton "protected" by a private constructor
Constructor<Configuration> ctor = Configuration.class.getDeclaredConstructor();
ctor.setAccessible(true);
Configuration second = ctor.newInstance();    // a second instance!

Method method = Book.class.getMethod("getTitle");

// invoke(instance, arguments...)
String title = (String) method.invoke(book);

// Method with arguments
Method lend = LoanManager.class.getMethod("lend", String.class, String.class);
Object result = lend.invoke(manager, "978-0000000001", "Marta Ruiz");

// Static method: null instance
Method factory = Result.class.getMethod("success", Object.class);
Object success = factory.invoke(null, "value");

// Method returning a primitive: it arrives autoboxed
Method pages = Book.class.getMethod("getPages");
int n = (Integer) pages.invoke(book);

package com.nexussoftware.bibliotech.service;

import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.util.Arrays;
import java.util.Comparator;

public final class StateInspector {

    private StateInspector() { }

    /** Prints the result of every no-argument getter of any object. */
    public static void dump(Object object) {

        Class<?> type = object.getClass();
        System.out.println("State of " + type.getSimpleName() + ":");

        Method[] methods = type.getMethods();
        Arrays.sort(methods, Comparator.comparing(Method::getName));

        for (Method m : methods) {

            boolean isGetter = (m.getName().startsWith("get") || m.getName().startsWith("is"))
                    && m.getParameterCount() == 0
                    && m.getReturnType() != void.class
                    && !m.getName().equals("getClass")          // inherited from Object
                    && !Modifier.isStatic(m.getModifiers())
                    && !m.isSynthetic();

            if (!isGetter) {
                continue;
            }

            try {
                Object value = m.invoke(object);
                System.out.printf("  %-16s = %s%n", propertyName(m.getName()), value);
            } catch (ReflectiveOperationException e) {
                System.out.printf("  %-16s = <error: %s>%n",
                        propertyName(m.getName()), e.getCause());
            }
        }
    }

    /** getTitle -> title, isOnLoan -> onLoan */
    private static String propertyName(String methodName) {
        String withoutPrefix = methodName.startsWith("is")
                ? methodName.substring(2)
                : methodName.substring(3);
        return Character.toLowerCase(withoutPrefix.charAt(0)) + withoutPrefix.substring(1);
    }
}

StateInspector.dump(new Book("Effective Java", "978-0000000001", "Joshua Bloch", 412, 4.8));
StateInspector.dump(new Loan("LN-2026-0041", "978-0000000001", "Marta Ruiz"));

State of Book:
  author           = Joshua Bloch
  id               = 978-0000000001
  isbn             = 978-0000000001
  pages            = 412
  rating           = 4.8
  title            = Effective Java
  onLoan           = false
State of Loan:
  employee         = Marta Ruiz
  id               = LN-2026-0041
  isbn             = 978-0000000001
  loanDay          = 120
  reference        = LN-2026-0041

try {
    Object o = type.getDeclaredConstructor().newInstance();
} catch (ReflectiveOperationException e) {      // catches all five at once
    throw new BiblioTechException("Could not instantiate " + type.getName(), e);
}

public class InvocationTargetDemo {

    public static void main(String[] args) throws Exception {

        LoanManager manager = new LoanManager(catalog, loans);
        Method returnItem = LoanManager.class.getMethod("returnItem", String.class);

        try {
            returnItem.invoke(manager, "REFERENCE-DOES-NOT-EXIST");

        } catch (InvocationTargetException e) {
            // e is NOT the real exception: it is the wrapper
            System.out.println("Wrapper:    " + e.getClass().getSimpleName());

            // getCause() gives the exception the method REALLY threw
            Throwable cause = e.getCause();
            System.out.println("Real cause: " + cause.getClass().getSimpleName()
                                              + ": " + cause.getMessage());

            // The right thing: rethrow the cause, not the wrapper
            if (cause instanceof BiblioTechException bte) {
                throw bte;
            }
            throw new BiblioTechException("Failure returning by reflection", cause);
        }
    }
}

Wrapper:    InvocationTargetException
Real cause: BiblioTechException: There is no loan REFERENCE-DOES-NOT-EXIST

Field field = Book.class.getDeclaredField("title");
field.setAccessible(true);       // switches off the access check
String title = (String) field.get(book);

Exception in thread "main" java.lang.IllegalAccessException:
    class Example cannot access a member of class Book with modifiers "private final"

public class BreakingEncapsulation {

    public static void main(String[] args) throws Exception {

        Book book = new Book("Effective Java", "978-0000000001", "Joshua Bloch", 412, 4.8);
        System.out.println("Before: " + book.getPages() + " pages");

        // The field is private FINAL: not even the class can change it
        Field pages = Book.class.getDeclaredField("pages");
        pages.setAccessible(true);
        pages.setInt(book, -999);

        System.out.println("After:  " + book.getPages() + " pages");
    }
}

Before: 412 pages
After:  -999 pages

public class BlockedReflection {

    public static void main(String[] args) throws Exception {
        Field value = String.class.getDeclaredField("value");
        value.setAccessible(true);      // no longer works
    }
}

Exception in thread "main" java.lang.reflect.InaccessibleObjectException:
    Unable to make field private final byte[] java.lang.String.value accessible:
    module java.base does not "opens java.lang" to unnamed module @0x1b6d3586

java --add-opens java.base/java.lang=ALL-UNNAMED -cp . MyProgram

module com.nexussoftware.bibliotech {
    requires java.logging;
    requires java.net.http;

    exports com.nexussoftware.bibliotech.domain;       // normal use at compile time
    opens com.nexussoftware.bibliotech.domain;         // plus deep reflection
}

// Does it have it?
boolean has = field.isAnnotationPresent(CsvField.class);

// Get it (null if it does not have it)
CsvField annotation = field.getAnnotation(CsvField.class);
if (annotation != null) {
    System.out.println(annotation.name() + " at position " + annotation.order());
}

// All of them (including those inherited with @Inherited)
Annotation[] all = type.getAnnotations();

// Only the directly declared ones
Annotation[] own = type.getDeclaredAnnotations();

// Repeatable: works with 0, 1 or N
Owner[] owners = type.getAnnotationsByType(Owner.class);

Annotation[][] perParameter = method.getParameterAnnotations();
for (int i = 0; i < perParameter.length; i++) {
    System.out.println("Parameter " + i + ": " + Arrays.toString(perParameter[i]));
}

// A more readable alternative since Java 8
for (Parameter p : method.getParameters()) {
    if (p.isAnnotationPresent(NonNull.class)) {
        System.out.println(p.getName() + " does not accept null");
    }
}

package com.nexussoftware.bibliotech.persistence;

import com.nexussoftware.bibliotech.annotations.CsvField;

import java.lang.reflect.Field;
import java.util.*;
import java.util.logging.Logger;

/**
 * Universal CSV exporter based on annotations.
 *
 * It does not know Book, nor Loan, nor Card. It discovers at run time
 * which fields carry @CsvField, sorts them by 'order' and builds
 * the header and the line.
 *
 * It replaces CsvCatalogExporter (07-07) and all the
 * per-class exporters that would have to be written without it.
 */
public class AnnotatedExporter {

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

    private static final char SEPARATOR = ';';
    private static final String MASKED = "***";

    /**
     * Cache of the introspection: getDeclaredFields() is expensive and the
     * result never changes for a given class (section 17).
     */
    private final Map<Class<?>, List<Field>> cache = new HashMap<>();

    /** If true, the fields marked sensitive = true are masked. */
    private final boolean maskSensitive;

    public AnnotatedExporter(boolean maskSensitive) {
        this.maskSensitive = maskSensitive;
    }

    // ------------------------------------------------------------------
    // Public API
    // ------------------------------------------------------------------

    /** CSV header of a class, with no need to have an instance. */
    public String header(Class<?> type) {
        StringJoiner sj = new StringJoiner(String.valueOf(SEPARATOR));
        for (Field field : exportableFields(type)) {
            CsvField meta = field.getAnnotation(CsvField.class);
            // an empty name() means "use the field's name" (10-02, section 10)
            String heading = meta.name().isEmpty() ? field.getName() : meta.name();
            sj.add(escape(heading));
        }
        return sj.toString();
    }

    /** CSV line of any entity. */
    public String line(Object entity) {
        Objects.requireNonNull(entity, "entity");

        StringJoiner sj = new StringJoiner(String.valueOf(SEPARATOR));

        for (Field field : exportableFields(entity.getClass())) {
            CsvField meta = field.getAnnotation(CsvField.class);
            sj.add(escape(valueOf(field, meta, entity)));
        }
        return sj.toString();
    }

    /** Exports a whole collection: header + one line per element. */
    public List<String> export(Class<?> type, Collection<?> entities) {
        List<String> lines = new ArrayList<>(entities.size() + 1);
        lines.add(header(type));
        for (Object entity : entities) {
            lines.add(line(entity));
        }
        return lines;
    }

    // ------------------------------------------------------------------
    // Introspection
    // ------------------------------------------------------------------

    /**
     * Fields annotated with @CsvField, from the class and from ALL its superclasses,
     * sorted by the 'order' element.
     */
    private List<Field> exportableFields(Class<?> type) {

        // computeIfAbsent: the introspection is done ONCE per class (05-05)
        return cache.computeIfAbsent(type, t -> {

            List<Field> found = new ArrayList<>();

            // Walking the hierarchy: getDeclaredFields does NOT see the inherited ones
            for (Class<?> c = t; c != null && c != Object.class; c = c.getSuperclass()) {
                for (Field field : c.getDeclaredFields()) {

                    if (field.isSynthetic()) {
                        continue;            // this$0 of inner classes, etc.
                    }
                    if (!field.isAnnotationPresent(CsvField.class)) {
                        continue;            // no annotation: not exported
                    }

                    field.setAccessible(true);   // they are private: they must be opened
                    found.add(field);
                }
            }

            // Declared order. getDeclaredFields does NOT guarantee any order,
            // so without this the output would be unpredictable between runs.
            found.sort(Comparator.comparingInt(
                    f -> f.getAnnotation(CsvField.class).order()));

            LOG.fine(() -> "Introspection of " + t.getSimpleName()
                    + ": " + found.size() + " exportable fields");

            return List.copyOf(found);
        });
    }

    /** Reads the field and formats it according to the annotation. */
    private String valueOf(Field field, CsvField meta, Object entity) {
        try {
            Object value = field.get(entity);

            if (value == null) {
                return "";
            }
            if (maskSensitive && meta.sensitive()) {
                return MASKED;
            }
            if (!meta.format().isEmpty()) {
                return String.format(meta.format(), value);
            }
            return String.valueOf(value);

        } catch (IllegalAccessException e) {
            // It can only happen if setAccessible failed (modules, section 11)
            throw new IllegalStateException(
                    "Could not read the field " + field.getName()
                    + " of " + entity.getClass().getSimpleName(), e);
        }
    }

    /** CSV escaping per RFC 4180 (07-07): quotes if there is a separator, a quote or a line break. */
    private String escape(String value) {
        boolean needed = value.indexOf(SEPARATOR) >= 0
                || value.indexOf('"') >= 0
                || value.indexOf('\n') >= 0
                || value.indexOf('\r') >= 0;

        if (!needed) {
            return value;
        }
        return '"' + value.replace("\"", "\"\"") + '"';
    }
}

package com.nexussoftware.bibliotech;

import com.nexussoftware.bibliotech.domain.*;
import com.nexussoftware.bibliotech.persistence.AnnotatedExporter;

import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.List;

public class UniversalExport {

    public static void main(String[] args) throws Exception {

        AnnotatedExporter exporter = new AnnotatedExporter(true);     // mask sensitive ones

        // --- Books ---
        List<Book> books = List.of(
                new Book("978-0000000001", "Effective Java",  "Joshua Bloch",  412, 4.85),
                new Book("978-0000000002", "Design Patterns", "GoF",           395, 4.60),
                new Book("978-0000000003", "Refactoring",     "Martin Fowler", 448, 4.72));

        System.out.println("--- catalog.csv ---");
        exporter.export(Book.class, books).forEach(System.out::println);

        // --- Loans: ANOTHER class, SAME exporter ---
        List<Loan> loans = List.of(
                new Loan("LN-2026-0041", "978-0000000001", "Marta Ruiz",   120),
                new Loan("LN-2026-0042", "978-0000000003", "Diego Alonso", 124));

        System.out.println();
        System.out.println("--- loans.csv ---");
        exporter.export(Loan.class, loans).forEach(System.out::println);

        // --- A record: it ALSO works ---
        List<Card> cards = List.of(
                new Card("978-0000000001", "Effective Java", false),
                new Card("978-0000000002", "Design Patterns", true));

        System.out.println();
        System.out.println("--- cards.csv ---");
        exporter.export(Card.class, cards).forEach(System.out::println);

        // And writing it to disk with NIO.2 and explicit UTF-8 (07-06)
        Files.write(Path.of("catalog.csv"),
                    exporter.export(Book.class, books),
                    StandardCharsets.UTF_8);
    }
}

--- catalog.csv ---
ISBN;Title;Author;Pages;Rating
978-0000000001;Effective Java;Joshua Bloch;412;4.85
978-0000000002;Design Patterns;GoF;395;4.60
978-0000000003;Refactoring;Martin Fowler;448;4.72

--- loans.csv ---
Reference;ISBN;Employee;Loan day
LN-2026-0041;978-0000000001;***;120
LN-2026-0042;978-0000000003;***;124

--- cards.csv ---
ISBN;Title;Available
978-0000000001;Effective Java;false
978-0000000002;Design Patterns;true

@CsvField(name = "Publisher", order = 6)
private final String publisher;

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

package com.nexussoftware.bibliotech.service;

public class CatalogService {
    private Repository<Material> catalog;            // generic declaration
    private Map<String, List<Loan>> byEmployee;

    public List<Book> findBooks(Predicate<Material> criterion) { ... }
}

package com.nexussoftware.bibliotech;

import java.lang.reflect.*;
import java.util.Arrays;

public class GenericsInspector {

    public static void main(String[] args) throws Exception {

        // --- FIELDS ---
        for (Field field : CatalogService.class.getDeclaredFields()) {

            System.out.println("field: " + field.getName());
            System.out.println("  getType():        " + field.getType().getSimpleName());
            System.out.println("  getGenericType(): " + field.getGenericType());

            Type generic = field.getGenericType();
            if (generic instanceof ParameterizedType pt) {
                System.out.println("  raw type:         "
                        + ((Class<?>) pt.getRawType()).getSimpleName());
                System.out.println("  arguments:        "
                        + Arrays.toString(pt.getActualTypeArguments()));
            }
            System.out.println();
        }

        // --- METHODS ---
        Method find = CatalogService.class.getMethod("findBooks", java.util.function.Predicate.class);
        System.out.println("method: " + find.getName());
        System.out.println("  getReturnType():         " + find.getReturnType().getSimpleName());
        System.out.println("  getGenericReturnType():  " + find.getGenericReturnType());
        System.out.println("  getGenericParameterTypes(): "
                + Arrays.toString(find.getGenericParameterTypes()));
    }
}

field: catalog
  getType():        Repository
  getGenericType(): com...Repository<com...Material>
  raw type:         Repository
  arguments:        [class com...Material]

field: byEmployee
  getType():        Map
  getGenericType(): java.util.Map<java.lang.String, java.util.List<com...Loan>>
  raw type:         Map
  arguments:        [class java.lang.String, java.util.List<com...Loan>]

method: findBooks
  getReturnType():         List
  getGenericReturnType():  java.util.List<com...Book>
  getGenericParameterTypes(): [java.util.function.Predicate<com...Material>]

// Anonymous class: its superclass's signature DOES keep <List<Book>>
var token = new TypeToken<List<Book>>() { };
System.out.println(token.type());

public abstract class TypeToken<T> {

    public Type type() {
        // getGenericSuperclass() of the anonymous class gives TypeToken<List<Book>>
        ParameterizedType superclass = (ParameterizedType) getClass().getGenericSuperclass();
        return superclass.getActualTypeArguments()[0];
    }
}

java.util.List<com.nexussoftware.bibliotech.domain.Book>

// 1. The interface being implemented
public interface LoanService {
    Result<Loan> lend(String isbn, String employee);
    Result<Loan> returnItem(String reference);
    List<Loan> listActive();
}

// 2. The handler that intercepts
InvocationHandler handler = (proxy, method, args) -> {
    System.out.println("Intercepted: " + method.getName());
    return method.invoke(realObject, args);
};

// 3. The manufacturing of the proxy
LoanService proxy = (LoanService) Proxy.newProxyInstance(
        LoanService.class.getClassLoader(),            // who loads the generated class
        new Class<?>[] { LoanService.class },          // interfaces to implement
        handler);                                      // who serves the calls

package com.nexussoftware.bibliotech.service;

import java.lang.reflect.*;

public final class TimingProxy {

    private TimingProxy() { }

    @SuppressWarnings("unchecked")
    public static <T> T wrap(T object, Class<T> iface) {
        return (T) Proxy.newProxyInstance(
                iface.getClassLoader(),
                new Class<?>[] { iface },
                (proxy, method, args) -> {

                    long start = System.nanoTime();
                    try {
                        return method.invoke(object, args);

                    } catch (InvocationTargetException e) {
                        throw e.getCause();      // rethrow the cause, not the wrapper
                    } finally {
                        long ms = (System.nanoTime() - start) / 1_000_000;
                        System.out.printf("[TIMING] %s() -> %d ms%n", method.getName(), ms);
                    }
                });
    }
}

LoanService real = new LoanManager(catalog, loans);
LoanService measured = TimingProxy.wrap(real, LoanService.class);

measured.lend("978-0000000001", "Marta Ruiz");
measured.listActive();

[TIMING] lend() -> 3 ms
[TIMING] listActive() -> 0 ms

package com.nexussoftware.bibliotech.service;

import com.nexussoftware.bibliotech.annotations.Auditable;
import com.nexussoftware.bibliotech.domain.Severity;

import java.lang.reflect.*;
import java.util.Arrays;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Annotation-driven auditing proxy.
 *
 * It intercepts every call, looks for @Auditable on the method and, if it
 * does not find it, on the class (configuration inheritance, like Spring's
 * @Transactional). It records start, end, duration and failure.
 *
 * LoanManager contains not one line of auditing.
 */
public final class AuditProxy implements InvocationHandler {

    private static final Logger LOG = Logger.getLogger("bibliotech.audit");

    private final Object target;
    private final Class<?> targetClass;

    private AuditProxy(Object target) {
        this.target = target;
        this.targetClass = target.getClass();
    }

    /** Typed factory: returns something usable as the original interface. */
    @SuppressWarnings("unchecked")
    public static <T> T audit(T target, Class<T> iface) {
        if (!iface.isInterface()) {
            throw new IllegalArgumentException(
                    iface.getSimpleName() + " is not an interface; Proxy only accepts interfaces");
        }
        return (T) Proxy.newProxyInstance(
                iface.getClassLoader(),
                new Class<?>[] { iface },
                new AuditProxy(target));
    }

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {

        Auditable policy = resolvePolicy(method);

        if (policy == null) {
            // No annotation: pass the call through without doing anything else
            return callTarget(method, args);
        }

        String operation = policy.value().isEmpty() ? method.getName() : policy.value();
        Level level = toLogLevel(policy.level());

        String argsDescription = policy.logArguments()
                ? describeArguments(args, policy.sensitiveArguments())
                : "(not recorded)";

        LOG.log(level, () -> String.format("START  %s %s", operation, argsDescription));

        long start = System.nanoTime();
        try {
            Object result = callTarget(method, args);

            long ms = (System.nanoTime() - start) / 1_000_000;
            LOG.log(level, () -> String.format("END    %s in %d ms -> %s", operation, ms, result));
            return result;

        } catch (Throwable failure) {
            long ms = (System.nanoTime() - start) / 1_000_000;
            // Failures are ALWAYS recorded as SEVERE, whatever the level
            LOG.log(Level.SEVERE, failure,
                    () -> String.format("ERROR  %s after %d ms: %s", operation, ms, failure));
            throw failure;
        }
    }

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

    /**
     * Looks for the annotation on the REAL CLASS's method (not on the interface,
     * where it might not be) and, failing that, on the class.
     */
    private Auditable resolvePolicy(Method interfaceMethod) {
        try {
            Method realMethod = targetClass.getMethod(
                    interfaceMethod.getName(), interfaceMethod.getParameterTypes());

            Auditable onMethod = realMethod.getAnnotation(Auditable.class);
            if (onMethod != null) {
                return onMethod;
            }
        } catch (NoSuchMethodException e) {
            // Should not happen: the proxy implements the interface the class implements
        }
        return targetClass.getAnnotation(Auditable.class);     // class-level default
    }

    /** Invokes the real method unwrapping the exception. */
    private Object callTarget(Method method, Object[] args) throws Throwable {
        try {
            return method.invoke(target, args);
        } catch (InvocationTargetException e) {
            throw e.getCause();          // RULE: rethrow the cause, not the wrapper
        }
    }

    /** Masks the arguments marked as sensitive (09-06: never log credentials). */
    private String describeArguments(Object[] args, int[] sensitive) {
        if (args == null || args.length == 0) {
            return "()";
        }
        Object[] copy = Arrays.copyOf(args, args.length);
        for (int index : sensitive) {
            if (index >= 0 && index < copy.length) {
                copy[index] = "***";
            }
        }
        return Arrays.toString(copy);
    }

    private Level toLogLevel(Severity severity) {
        return switch (severity) {
            case HIGH   -> Level.WARNING;
            case MEDIUM -> Level.INFO;
            case LOW    -> Level.FINE;
        };
    }
}

package com.nexussoftware.bibliotech;

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

public class TransparentAuditing {

    public static void main(String[] args) {

        LogConfiguration.initialise();      // from module 6

        Repository<Material> catalog = new Repository<>("catalogue");
        Repository<Loan> loans       = new Repository<>("loans");
        catalog.save(new Book("978-0000000001", "Effective Java"));
        catalog.save(new Book("978-0000000002", "Design Patterns"));

        // The REAL object, with no auditing inside
        LoanService real = new LoanManager(catalog, loans);

        // The object the application uses
        LoanService service = AuditProxy.audit(real, LoanService.class);

        service.lend("978-0000000001", "Marta Ruiz");
        service.lend("978-0000000001", "Diego Alonso");    // already on loan: returns failure
        service.listActive();                              // no @Auditable: not recorded
        service.changeEmployeePassword("Nuria Vidal", "real-secret-password");

        try {
            service.returnItem("LN-NONEXISTENT");
        } catch (Exception e) {
            System.out.println("Exception received by the client: "
                    + e.getClass().getSimpleName() + " -- " + e.getMessage());
        }
    }
}

[WARNING] bibliotech.audit: START  lend [978-0000000001, Marta Ruiz]
[WARNING] bibliotech.audit: END    lend in 4 ms -> Success[Loan[LN-2026-0001]]
[WARNING] bibliotech.audit: START  lend [978-0000000001, Diego Alonso]
[WARNING] bibliotech.audit: END    lend in 0 ms -> Failure[The material 'Effective Java' is already on loan]
[INFO]    bibliotech.audit: START  changePassword [Nuria Vidal, ***]
[INFO]    bibliotech.audit: END    changePassword in 1 ms -> Success[null]
[WARNING] bibliotech.audit: START  return [LN-NONEXISTENT]
[SEVERE]  bibliotech.audit: ERROR  return after 0 ms: BiblioTechException: There is no loan LN-NONEXISTENT
    com.nexussoftware.bibliotech.BiblioTechException: There is no loan LN-NONEXISTENT
        at com.nexussoftware.bibliotech.service.LoanManager.returnItem(LoanManager.java:78)
        ...
Exception received by the client: BiblioTechException -- There is no loan LN-NONEXISTENT

// If somebody renames getTitle() to title(), this still compiles
// and fails at run time, perhaps months later, perhaps in production.
Method m = type.getMethod("getTitle");

package com.nexussoftware.bibliotech.service;

import java.lang.invoke.*;

public class MethodHandleExample {

    public static void main(String[] args) throws Throwable {

        MethodHandles.Lookup lookup = MethodHandles.lookup();

        // The method's TYPE is declared explicitly: (return, parameters...)
        MethodType type = MethodType.methodType(String.class);
        MethodHandle getTitle = lookup.findVirtual(Book.class, "getTitle", type);

        Book book = new Book("978-0000000001", "Effective Java");

        // invokeExact requires the types to match EXACTLY
        String title = (String) getTitle.invokeExact(book);
        System.out.println(title);

        // VarHandle for fields, with explicit memory semantics (picks up 08-04)
        VarHandle onLoanField = MethodHandles
                .privateLookupIn(Book.class, lookup)
                .findVarHandle(Book.class, "onLoan", boolean.class);

        System.out.println("onLoan: " + onLoanField.get(book));
        onLoanField.setVolatile(book, true);                 // volatile write
        System.out.println("onLoan: " + onLoanField.get(book));

        // And atomic operations without AtomicBoolean (08-06)
        boolean changed = onLoanField.compareAndSet(book, true, false);
        System.out.println("compareAndSet: " + changed);
    }
}

Effective Java
onLoan: false
onLoan: true
compareAndSet: true

package com.nexussoftware.bibliotech.service;

import com.nexussoftware.bibliotech.annotations.Validate;

import java.lang.reflect.Field;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.regex.Pattern;

/**
 * Validation engine driven by @Validate.
 * It does not know Book, Loan or any concrete entity.
 */
public class AnnotatedValidator {

    /** Introspection cached per class (ConcurrentHashMap: it may be used from several threads). */
    private final Map<Class<?>, List<Field>> fieldsByClass = new ConcurrentHashMap<>();

    /** Compiled patterns: Pattern.compile is expensive and the pattern does not change. */
    private final Map<String, Pattern> patterns = new ConcurrentHashMap<>();

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

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

        List<String> failures = new ArrayList<>();

        for (Field field : validatableFields(entity.getClass())) {
            Validate rule = field.getAnnotation(Validate.class);
            Object value = read(field, entity);
            check(field, rule, value, failures);
        }

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

    /** Prints a class's rules without instantiating it. */
    public void describe(Class<?> type) {
        System.out.println("Rules of " + type.getSimpleName() + ":");
        for (Field field : validatableFields(type)) {
            Validate r = field.getAnnotation(Validate.class);
            System.out.printf("  %-12s required=%-5s len=[%d..%s] pattern=%s%n",
                    field.getName(),
                    r.required(),
                    r.minLength(),
                    r.maxLength() == Integer.MAX_VALUE ? "∞" : r.maxLength(),
                    r.pattern().isEmpty() ? "-" : r.pattern());
        }
    }

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

    /** Annotated fields of the class and of all its superclasses. */
    private List<Field> validatableFields(Class<?> type) {
        return fieldsByClass.computeIfAbsent(type, t -> {
            List<Field> found = new ArrayList<>();
            for (Class<?> c = t; c != null && c != Object.class; c = c.getSuperclass()) {
                for (Field field : c.getDeclaredFields()) {
                    if (field.isSynthetic() || !field.isAnnotationPresent(Validate.class)) {
                        continue;
                    }
                    field.setAccessible(true);
                    found.add(field);
                }
            }
            // Stable order by name: getDeclaredFields does not guarantee one
            found.sort(Comparator.comparing(Field::getName));
            return List.copyOf(found);
        });
    }

    private Object read(Field field, Object entity) {
        try {
            return field.get(entity);
        } catch (IllegalAccessException e) {
            throw new IllegalStateException("Could not read " + field.getName(), e);
        }
    }

    private void check(Field field, Validate rule, Object value, List<String> failures) {

        String name = field.getName();

        // 1. Requiredness
        if (value == null) {
            if (rule.required()) {
                failures.add(message(rule, "'" + name + "' is mandatory and is empty"));
            }
            return;                                  // with no value there is nothing else to check
        }

        // The other rules only apply to text
        if (!(value instanceof String text)) {
            return;
        }

        if (rule.required() && text.isBlank()) {
            failures.add(message(rule, "'" + name + "' is mandatory and is blank"));
            return;
        }

        // 2. Lengths
        if (text.length() < rule.minLength()) {
            failures.add(message(rule, String.format(
                    "'%s' needs at least %d characters and has %d",
                    name, rule.minLength(), text.length())));
        }
        if (text.length() > rule.maxLength()) {
            failures.add(message(rule, String.format(
                    "'%s' allows at most %d characters and has %d",
                    name, rule.maxLength(), text.length())));
        }

        // 3. Pattern
        if (!rule.pattern().isEmpty()) {
            Pattern pattern = patterns.computeIfAbsent(rule.pattern(), Pattern::compile);
            if (!pattern.matcher(text).matches()) {
                failures.add(message(rule, String.format(
                        "'%s' does not match the format %s (value: \"%s\")",
                        name, rule.pattern(), text)));
            }
        }
    }

    /** The annotation's custom message takes priority over the generated one. */
    private String message(Validate rule, String generated) {
        return rule.message().isEmpty() ? generated : rule.message();
    }
}

package com.nexussoftware.bibliotech;

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

import java.util.List;

public class AnnotatedValidatorTest {

    public static void main(String[] args) {

        AnnotatedValidator validator = new AnnotatedValidator();

        validator.describe(Book.class);
        System.out.println();

        List<Book> candidates = List.of(
                new Book("978-0000000001", "Effective Java", "Joshua Bloch"),
                new Book("978-1",          "Refactoring",    "Martin Fowler"),
                new Book("978-0000000003", "",               "A".repeat(150)));

        for (Book book : candidates) {
            Result<Book> r = validator.validate(book);
            System.out.println(r.isSuccess()
                    ? "OK       -> " + r.value().getTitle()
                    : "REJECTED -> " + r.error());
        }
    }
}

Rules of Book:
  author       required=false len=[0..120] pattern=-
  isbn         required=true  len=[0..∞] pattern=978-\d{10}
  title        required=true  len=[1..200] pattern=-

OK       -> Effective Java
REJECTED -> Invalid Book: The ISBN must follow the format 978-XXXXXXXXXX
REJECTED -> Invalid Book: 'author' allows at most 120 characters and has 150; 'title' is mandatory and is blank

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Component {
    String name() default "";
}

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.CONSTRUCTOR, ElementType.FIELD})
public @interface Inject {
}

package com.nexussoftware.bibliotech.service;

import com.nexussoftware.bibliotech.annotations.*;

import java.lang.reflect.*;
import java.util.*;

/**
 * Minimal dependency injection container.
 * It is, in essence, what Spring's ApplicationContext does
 * reduced to the bare essentials.
 */
public class SimpleContainer {

    /** Types registered as available. */
    private final Set<Class<?>> registered = new LinkedHashSet<>();

    /** Instances already created: every component is a singleton. */
    private final Map<Class<?>, Object> instances = new LinkedHashMap<>();

    /** Types currently being created: used to detect cycles. */
    private final Deque<Class<?>> underConstruction = new ArrayDeque<>();

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

    public SimpleContainer register(Class<?>... classes) {
        for (Class<?> clazz : classes) {
            if (!clazz.isAnnotationPresent(Component.class)) {
                throw new IllegalArgumentException(
                        clazz.getSimpleName() + " is not annotated with @Component");
            }
            registered.add(clazz);
        }
        return this;
    }

    /** Registers an already-built instance (for configuration, values, etc.). */
    public <T> SimpleContainer registerInstance(Class<T> type, T instance) {
        instances.put(type, instance);
        registered.add(type);
        return this;
    }

    @SuppressWarnings("unchecked")
    public <T> T get(Class<T> type) {
        // Safe cast: we only store instances of the type they are indexed by
        return (T) resolve(type);
    }

    public void list() {
        System.out.println("Instantiated components (" + instances.size() + "):");
        instances.forEach((type, obj) ->
                System.out.printf("  %-24s -> %s%n", type.getSimpleName(), obj));
    }

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

    private Object resolve(Class<?> type) {

        // 1. Does it already exist? Singleton.
        Object existing = instances.get(type);
        if (existing != null) {
            return existing;
        }

        // 2. Look for a compatible registered implementation
        Class<?> implementation = findImplementation(type);

        // 3. Detect cycles BEFORE going into recursion
        if (underConstruction.contains(implementation)) {
            List<String> cycle = new ArrayList<>();
            for (Class<?> c : underConstruction) {
                cycle.add(0, c.getSimpleName());
            }
            cycle.add(implementation.getSimpleName());
            throw new IllegalStateException("Circular dependency: " + String.join(" -> ", cycle));
        }

        underConstruction.push(implementation);
        try {
            Object instance = build(implementation);
            injectFields(instance);
            instances.put(type, instance);
            if (type != implementation) {
                instances.put(implementation, instance);
            }
            return instance;
        } finally {
            underConstruction.pop();
        }
    }

    /** If an interface is requested, find the single registered implementation. */
    private Class<?> findImplementation(Class<?> type) {
        if (registered.contains(type) && !type.isInterface()) {
            return type;
        }
        List<Class<?>> candidates = new ArrayList<>();
        for (Class<?> c : registered) {
            if (type.isAssignableFrom(c) && !c.isInterface()
                    && !Modifier.isAbstract(c.getModifiers())) {
                candidates.add(c);
            }
        }
        if (candidates.isEmpty()) {
            throw new IllegalStateException(
                    "There is no registered component satisfying " + type.getSimpleName());
        }
        if (candidates.size() > 1) {
            throw new IllegalStateException("There are " + candidates.size()
                    + " candidates for " + type.getSimpleName() + ": " + candidates);
        }
        return candidates.get(0);
    }

    /** Instantiates, resolving the constructor's parameters recursively. */
    private Object build(Class<?> clazz) {

        Constructor<?> chosen = chooseConstructor(clazz);
        chosen.setAccessible(true);

        Class<?>[] parameterTypes = chosen.getParameterTypes();
        Object[] arguments = new Object[parameterTypes.length];

        for (int i = 0; i < parameterTypes.length; i++) {
            arguments[i] = resolve(parameterTypes[i]);        // RECURSION
        }

        try {
            return chosen.newInstance(arguments);
        } catch (InvocationTargetException e) {
            throw new IllegalStateException(
                    clazz.getSimpleName() + "'s constructor threw an exception",
                    e.getCause());                            // the CAUSE, not the wrapper
        } catch (ReflectiveOperationException e) {
            throw new IllegalStateException("Could not instantiate " + clazz.getSimpleName(), e);
        }
    }

    private Constructor<?> chooseConstructor(Class<?> clazz) {
        Constructor<?> noArgs = null;

        for (Constructor<?> c : clazz.getDeclaredConstructors()) {
            if (c.isAnnotationPresent(Inject.class)) {
                return c;                                     // the annotated one wins
            }
            if (c.getParameterCount() == 0) {
                noArgs = c;
            }
        }
        if (noArgs != null) {
            return noArgs;
        }
        // Convention: if there is only one, it is used (as Spring does since 4.3)
        Constructor<?>[] all = clazz.getDeclaredConstructors();
        if (all.length == 1) {
            return all[0];
        }
        throw new IllegalStateException(clazz.getSimpleName()
                + " has several constructors and none carries @Inject");
    }

    /** Field injection, AFTER building. */
    private void injectFields(Object instance) {
        for (Class<?> c = instance.getClass(); c != null && c != Object.class; c = c.getSuperclass()) {
            for (Field field : c.getDeclaredFields()) {
                if (!field.isAnnotationPresent(Inject.class)) {
                    continue;
                }
                field.setAccessible(true);
                try {
                    field.set(instance, resolve(field.getType()));
                } catch (IllegalAccessException e) {
                    throw new IllegalStateException(
                            "Could not inject the field " + field.getName(), e);
                }
            }
        }
    }
}

@Component
public class FineCalculator {
    public double calculate(int daysLate) { return daysLate * 0.25; }
    @Override public String toString() { return "[email protected] EUR/day"; }
}

@Component
public class MaterialRepository extends Repository<Material> {
    public MaterialRepository() { super("catalogue"); }
}

@Component
public class LoanRepository extends Repository<Loan> {
    public LoanRepository() { super("loans"); }
}

@Component
public class LoanManager implements LoanService {

    private final MaterialRepository catalog;
    private final LoanRepository loans;

    @Inject                                    // the container will use THIS constructor
    public LoanManager(MaterialRepository catalog, LoanRepository loans) {
        this.catalog = catalog;
        this.loans = loans;
    }

    @Inject                                    // field injection
    private FineCalculator calculator;

    @Override public String toString() {
        return "LoanManager[catalogue=" + catalog + ", fines=" + calculator + "]";
    }
}

public class ContainerBootstrap {

    public static void main(String[] args) {

        SimpleContainer container = new SimpleContainer()
                .register(LoanManager.class,
                          MaterialRepository.class,
                          LoanRepository.class,
                          FineCalculator.class);

        // NOT A SINGLE new: the container resolves the whole graph
        LoanService service = container.get(LoanService.class);

        System.out.println("Obtained: " + service);
        System.out.println();
        container.list();

        // Singleton: two requests give the SAME object
        System.out.println();
        System.out.println("Singleton? "
                + (container.get(FineCalculator.class)
                   == container.get(FineCalculator.class)));
    }
}

Obtained: LoanManager[catalogue=Repository[catalogue, 0 entities], [email protected] EUR/day]

Instantiated components (5):
  MaterialRepository       -> Repository[catalogue, 0 entities]
  LoanRepository           -> Repository[loans, 0 entities]
  FineCalculator           -> [email protected] EUR/day
  LoanManager              -> LoanManager[...]
  LoanService              -> LoanManager[...]

Singleton? true

Exception in thread "main" java.lang.IllegalStateException:
    Circular dependency: ServiceA -> ServiceB -> ServiceA

package com.nexussoftware.bibliotech.network;

import com.nexussoftware.bibliotech.annotations.Retryable;

import java.lang.reflect.*;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ThreadLocalRandom;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Proxy that applies @Retryable's policy.
 * It replaces the retry logic hard-coded by hand
 * inside ResilientHttpClient (09-06).
 */
public final class RetryProxy implements InvocationHandler {

    private static final Logger LOG = Logger.getLogger("bibliotech.retries");

    private final Object target;

    private RetryProxy(Object target) {
        this.target = target;
    }

    @SuppressWarnings("unchecked")
    public static <T> T withRetries(T target, Class<T> iface) {
        return (T) Proxy.newProxyInstance(
                iface.getClassLoader(),
                new Class<?>[] { iface },
                new RetryProxy(target));
    }

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {

        Retryable policy = resolvePolicy(method);

        if (policy == null || policy.attempts() <= 1) {
            return callTarget(method, args);       // no policy: just once
        }

        List<Throwable> previousFailures = new ArrayList<>();
        long wait = policy.initialWaitMs();

        for (int attempt = 1; attempt <= policy.attempts(); attempt++) {
            try {
                Object result = callTarget(method, args);

                if (attempt > 1) {
                    int n = attempt;
                    LOG.info(() -> String.format("%s() succeeded on attempt %d",
                            method.getName(), n));
                }
                return result;

            } catch (Throwable failure) {

                if (!isRetryable(failure, policy)) {
                    LOG.fine(() -> "Not retrying " + failure.getClass().getSimpleName()
                            + ": it is not in the policy");
                    throw failure;                  // permanent error: do not insist
                }

                previousFailures.add(failure);

                if (attempt == policy.attempts()) {
                    // Last attempt: attach the previous ones as suppressed (06-06)
                    for (int i = 0; i < previousFailures.size() - 1; i++) {
                        failure.addSuppressed(previousFailures.get(i));
                    }
                    LOG.log(Level.SEVERE, () -> String.format(
                            "%s() ran out of its %d attempts", method.getName(), policy.attempts()));
                    throw failure;
                }

                // Randomisation (jitter): stops N clients retrying at once (09-06)
                long withJitter = wait + ThreadLocalRandom.current().nextLong(wait / 2 + 1);

                int n = attempt;
                LOG.warning(() -> String.format("%s() failed on attempt %d (%s); waiting %d ms",
                        method.getName(), n, failure.getClass().getSimpleName(), withJitter));

                sleep(withJitter);

                wait = (long) (wait * policy.growthFactor());
            }
        }
        throw new IllegalStateException("unreachable");
    }

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

    private Retryable resolvePolicy(Method interfaceMethod) {
        try {
            Method real = target.getClass().getMethod(
                    interfaceMethod.getName(), interfaceMethod.getParameterTypes());
            return real.getAnnotation(Retryable.class);
        } catch (NoSuchMethodException e) {
            return null;
        }
    }

    private boolean isRetryable(Throwable failure, Retryable policy) {
        for (Class<? extends Exception> type : policy.exceptions()) {
            if (type.isInstance(failure)) {     // isInstance: the reflective instanceof
                return true;
            }
        }
        return false;
    }

    private Object callTarget(Method method, Object[] args) throws Throwable {
        try {
            return method.invoke(target, args);
        } catch (InvocationTargetException e) {
            throw e.getCause();
        }
    }

    /** Respects interruption: restores the flag and aborts (08-02). */
    private void sleep(long ms) throws InterruptedException {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw e;
        }
    }
}

package com.nexussoftware.bibliotech;

import com.nexussoftware.bibliotech.annotations.Retryable;
import com.nexussoftware.bibliotech.network.RetryProxy;

import java.io.IOException;
import java.net.SocketTimeoutException;

public class RetryProxyTest {

    interface MetadataService {
        String lookupByIsbn(String isbn) throws IOException;
        String alwaysFails(String isbn) throws IOException;
    }

    /** Test double: it fails the first two times and then works. */
    static class FlakyClient implements MetadataService {

        private int calls = 0;

        @Override
        @Retryable(attempts = 4, initialWaitMs = 100, growthFactor = 2.0,
                   exceptions = { SocketTimeoutException.class })
        public String lookupByIsbn(String isbn) throws IOException {
            calls++;
            if (calls < 3) {
                throw new SocketTimeoutException("timed out (call " + calls + ")");
            }
            return "{\"isbn\":\"" + isbn + "\",\"title\":\"Effective Java\"}";
        }

        @Override
        @Retryable(attempts = 3, initialWaitMs = 50, growthFactor = 3.0,
                   exceptions = { IOException.class })
        public String alwaysFails(String isbn) throws IOException {
            throw new IOException("the metadata service is not responding");
        }
    }

    public static void main(String[] args) throws Exception {

        LogConfiguration.initialise();

        MetadataService service =
                RetryProxy.withRetries(new FlakyClient(), MetadataService.class);

        System.out.println("--- case 1: recovers on the third attempt ---");
        System.out.println("Result: " + service.lookupByIsbn("978-0000000001"));

        System.out.println();
        System.out.println("--- case 2: runs out of attempts ---");
        try {
            service.alwaysFails("978-0000000002");
        } catch (IOException e) {
            System.out.println("Final exception: " + e.getMessage());
            System.out.println("Suppressed failures: " + e.getSuppressed().length);
            for (Throwable s : e.getSuppressed()) {
                System.out.println("  suppressed: " + s.getMessage());
            }
        }
    }
}

--- case 1: recovers on the third attempt ---
[WARNING] lookupByIsbn() failed on attempt 1 (SocketTimeoutException); waiting 137 ms
[WARNING] lookupByIsbn() failed on attempt 2 (SocketTimeoutException); waiting 265 ms
[INFO]    lookupByIsbn() succeeded on attempt 3
Result: {"isbn":"978-0000000001","title":"Effective Java"}

--- case 2: runs out of attempts ---
[WARNING] alwaysFails() failed on attempt 1 (IOException); waiting 71 ms
[WARNING] alwaysFails() failed on attempt 2 (IOException); waiting 194 ms
[SEVERE]  alwaysFails() ran out of its 3 attempts
Final exception: the metadata service is not responding
Suppressed failures: 2
  suppressed: the metadata service is not responding
  suppressed: the metadata service is not responding