// 1. MARKER ANNOTATION: no elements. The parentheses are omitted.
@Override
public String toString() { ... }

// 2. SINGLE VALUE: if the element is called 'value', the name is omitted.
@SuppressWarnings("unchecked")
List<Book> books = (List<Book>) raw;

// equivalent in every way to:
@SuppressWarnings(value = "unchecked")

// 3. SEVERAL ELEMENTS: name = value pairs, separated by commas.
@Deprecated(since = "3.2", forRemoval = true)
public void lendBook(String isbn) { ... }

@SuppressWarnings({"unchecked", "rawtypes"})     // several values
@SuppressWarnings("unchecked")                   // just one: braces optional

@Auditable(level = "HIGH")
@Override
@SuppressWarnings("unchecked")
public Result<Loan> lend(String isbn, String employee) { ... }

public class Material {
    private final String isbn;

    @Override
    public boolean equals(Object other) {
        if (this == other) return true;
        if (!(other instanceof Material)) return false;
        return isbn.equals(((Material) other).isbn);
    }
}

public class Material {

    // NO @Override: it looks like it overrides equals... but it does NOT.
    public boolean equals(Material other) {         // Material, not Object!
        return this.isbn.equals(other.isbn);
    }
}

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

System.out.println(a.equals(b));        // true: it calls your equals(Material)

List<Material> list = new ArrayList<>();
list.add(a);
System.out.println(list.contains(b));   // false! contains() calls equals(Object)

Set<Material> set = new HashSet<>();
set.add(a);
set.add(b);
System.out.println(set.size());         // 2! duplicates in a Set

@Override
public boolean equals(Material other) { ... }

error: method does not override or implement a method from a supertype
    @Override
    ^

package com.nexussoftware.bibliotech.service;

public class LoanManager {

    /**
     * Lends a material identified by its ISBN.
     *
     * @deprecated Since 3.2 use {@link #lend(String, String)}, which returns
     *             a {@code Result<Loan>} instead of throwing exceptions
     *             for expected cases. It will be removed in version 4.0.
     */
    @Deprecated(since = "3.2", forRemoval = true)
    public void lendBook(String isbn) throws BiblioTechException {
        lend(isbn, "unknown");
    }

    public Result<Loan> lend(String isbn, String employee) { ... }
}

manager.lendBook("978-0000000001");

warning: [removal] lendBook(String) in LoanManager has been deprecated and marked for removal

@SuppressWarnings("unchecked")
T[] copy = (T[]) new Object[capacity];

// BAD: switches everything off in the whole class forever
@SuppressWarnings("all")
public class CatalogImporter { ... }

// GOOD: minimum scope and justification
public List<Book> readBooks(Path file) throws IOException {
    // SAFE: the file is only written by CsvCatalogExporter, which
    // always serialises Book. Any other content fails earlier,
    // in the header validation.
    @SuppressWarnings("unchecked")
    List<Book> books = (List<Book>) readEntities(file);
    return books;
}

public static <T> List<T> listOf(T... elements) {
    return new ArrayList<>(Arrays.asList(elements));
}

warning: [unchecked] Possible heap pollution from parameterized vararg type T
    public static <T> List<T> listOf(T... elements) {
                                          ^

// DANGEROUS: it exposes the varargs array
@SafeVarargs
static <T> T[] dangerous(T... elements) {
    return elements;                      // returns the array created by the compiler
}

public static void main(String[] args) {
    String[] texts = dangerous("a", "b");    // ClassCastException here
}

@SafeVarargs
public static <T> List<T> listOf(T... elements) {
    return new ArrayList<>(Arrays.asList(elements));   // it only READS from the array
}

package com.nexussoftware.bibliotech.service;

/**
 * Calculates the fine of an overdue loan.
 * Being functional, it can be implemented with a lambda.
 */
@FunctionalInterface
public interface FinePolicy {

    double calculate(int daysLate);

    // default methods do NOT count as abstract: the interface is still functional
    default FinePolicy cappedAt(double maximum) {
        return days -> Math.min(calculate(days), maximum);
    }

    // static methods do not count either
    static FinePolicy fixed(double perDay) {
        return days -> days * perDay;
    }
}

FinePolicy standard = days -> days * 0.25;
FinePolicy capped   = standard.cappedAt(10.0);

System.out.printf("30 days late:    %.2f EUR%n", standard.calculate(30));   // 7.50 EUR
System.out.printf("100 days capped: %.2f EUR%n", capped.calculate(100));    // 10.00 EUR

@FunctionalInterface
public interface FinePolicy {
    double calculate(int days);
    double calculateWithDiscount(int days, double discount);   // second abstract
}

error: Unexpected @FunctionalInterface annotation
    FinePolicy is not a functional interface
      multiple non-overriding abstract methods found in interface FinePolicy

package com.nexussoftware.bibliotech.annotations;

/**
 * Marks an element that is not finished yet.
 * On its own it does absolutely nothing.
 */
public @interface UnderConstruction {
}

@UnderConstruction
public class Marc21Importer {
    // ...
}

package com.nexussoftware.bibliotech.annotations;

/**
 * Documents who owns a component and since when.
 */
public @interface Owner {

    /** Name of the owner. Mandatory: it has no default. */
    String name();

    /** Team. Optional. */
    String team() default "Platform";

    /** Date in ISO format. Optional. */
    String since() default "";

    /** Backup people. Optional, empty array by default. */
    String[] backup() default {};
}

@Owner(name = "Marta Ruiz", team = "Catalogue", since = "2026-01-15",
       backup = {"Diego Alonso", "Nuria Vidal"})
public class CatalogService { }

@Owner(name = "Nuria Vidal")             // the rest take their default
public class NoticeService { }

@Owner(team = "Catalogue")

error: annotation @Owner is missing a default value for the element 'name'

public @interface Bad {
    List<String> tags();          // ERROR: invalid type for annotation member
    LocalDate created();          // ERROR
    Book book();                  // ERROR
}

@Owner(name = "Marta " + "Ruiz")                  // concatenation of literals: constant

@Owner(name = resolveOwner())                     // ERROR: not a constant

public @interface CsvField {
    String name() default "";        // "" means "use the field's name"
    int order() default Integer.MAX_VALUE;    // sentinel: "at the end"
}

public @interface Auditable {
    String value();     // the magic name
}

@Auditable("lend")               // shorthand form
@Auditable(value = "lend")       // full form: equivalent

public @interface Auditable {
    String value();
    Severity level() default Severity.MEDIUM;
}

@Auditable("lend")                                    // OK: level takes its default
@Auditable(value = "lend", level = Severity.HIGH)     // OK: full form mandatory
// @Auditable("lend", level = Severity.HIGH)          // ERROR: they cannot be mixed

public @interface Auditable { }      // no @Retention -> CLASS

// elsewhere
boolean has = method.isAnnotationPresent(Auditable.class);
System.out.println(has);             // false, and you do not understand why

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@Retention(RetentionPolicy.RUNTIME)
public @interface Auditable { }      // now it works

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface CsvField {
    String name() default "";
    int order();
}

@CsvField(order = 1)      // ERROR: not applicable to classes
public class Book { }

error: annotation type not applicable to this kind of declaration

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

@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Audited {
    String module();
}

@Audited(module = "catalogue")
public abstract class Material { }

public class Book extends Material { }     // no annotation of its own

System.out.println(Book.class.isAnnotationPresent(Audited.class));    // true, thanks to @Inherited
System.out.println(Book.class.getAnnotation(Audited.class).module()); // catalogue

@Owner(name = "Marta Ruiz")
@Owner(name = "Diego Alonso")             // ERROR before Java 8
public class CatalogService { }

error: Owner is not a repeatable annotation type

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

/** The CONTAINER annotation: it holds an array of the repeatable ones. */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Owners {
    Owner[] value();           // the element MUST be called value and be an array
}

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

/** The REPEATABLE annotation: it declares who contains it. */
@Repeatable(Owners.class)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Owner {
    String name();
    String team() default "Platform";
}

@Owner(name = "Marta Ruiz",   team = "Catalogue")
@Owner(name = "Diego Alonso", team = "Loans")
public class CatalogService { }

// With ONE single @Owner
CatalogService.class.getAnnotation(Owner.class);     // returns the annotation
CatalogService.class.getAnnotation(Owners.class);    // null

// With TWO @Owner
CatalogService.class.getAnnotation(Owner.class);     // null! they are inside the container
CatalogService.class.getAnnotation(Owners.class);    // returns the container

Owner[] all = CatalogService.class.getAnnotationsByType(Owner.class);
for (Owner o : all) {
    System.out.println(o.name() + " (" + o.team() + ")");
}

Marta Ruiz (Catalogue)
Diego Alonso (Loans)

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE_USE)
public @interface NonNull { }

// In a variable declaration
@NonNull String title = "Effective Java";

// In the type of a generic parameter
List<@NonNull Book> catalog = new ArrayList<>();

// In a cast
String s = (@NonNull String) object;

// In a new
Book book = new @NonNull Book("Refactoring", "978-0000000003");

// In a throws and in an implements
public class Catalog implements @NonNull Identifiable { }

// In arrays: it annotates the ELEMENT TYPE
@NonNull String[] names;          // array of non-null String
String @NonNull [] names2;        // non-null array of String

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE_PARAMETER)
public @interface DomainEntity { }

public class Repository<@DomainEntity T extends Identifiable> { }

package com.nexussoftware.bibliotech.processor;

import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.*;
import java.util.Set;

@SupportedAnnotationTypes("com.nexussoftware.bibliotech.annotations.CsvField")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
public class CsvFieldProcessor extends AbstractProcessor {

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment environment) {

        for (Element element : environment.getElementsAnnotatedWith(CsvField.class)) {

            // Check at COMPILE TIME
            if (element.getModifiers().contains(Modifier.STATIC)) {
                processingEnv.getMessager().printMessage(
                        Diagnostic.Kind.ERROR,
                        "@CsvField cannot be put on a static field",
                        element);
            }
            // Here code could be generated with
            // processingEnv.getFiler().createSourceFile(...)
        }
        return true;   // true = these annotations are already processed
    }
}

@Data
public class Book {
    private String isbn;
    private String title;
}

import java.lang.reflect.Method;

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

// Does it have the annotation?
if (method.isAnnotationPresent(Auditable.class)) {

    // Get it and read its elements
    Auditable auditable = method.getAnnotation(Auditable.class);
    System.out.println("Operation: " + auditable.value());
    System.out.println("Level:     " + auditable.level());
}

// All the annotations (including inherited ones)
for (Annotation a : method.getAnnotations()) {
    System.out.println(a);
}

// Only the directly declared ones
for (Annotation a : method.getDeclaredAnnotations()) { }

// Repeatable ones
Owner[] owners = CatalogService.class.getAnnotationsByType(Owner.class);

Operation: lend
Level:     HIGH
@com.nexussoftware.bibliotech.annotations.Auditable(value="lend", level=HIGH)

@Entity
@Table(name = "materials")
public class Book {

    @Id
    @Column(name = "isbn", length = 17)
    private String isbn;

    @Column(name = "title", nullable = false)
    private String title;
}

@Service
public class LoanManager {

    private final Repository<Material> catalog;

    @Autowired
    public LoanManager(Repository<Material> catalog) {
        this.catalog = catalog;
    }

    @Transactional
    public Result<Loan> lend(String isbn, String employee) { ... }
}

class LoanManagerTest {

    @BeforeEach
    void prepareCatalog() { ... }

    @Test
    @DisplayName("Lending an available material returns success")
    void lendAvailable() { ... }
}

<bean id="loanManager" class="com.nexussoftware.bibliotech.service.LoanManager">
    <constructor-arg ref="catalogRepository"/>
</bean>
<bean id="catalogRepository" class="com.nexussoftware.bibliotech.service.Repository">
    <constructor-arg value="catalogue"/>
</bean>

@Service
public class LoanManager {
    public LoanManager(Repository<Material> catalog) { ... }
}

// BAD: you have invented a language inside a string
@Rule("if daysLate > 15 && employee.category != 'MANAGEMENT' then fine = daysLate * 0.25")
public double calculateFine(Loan l) { ... }

// BAD: changing server forces a recompile
@DbConnection(url = "jdbc:postgresql://production.nexus:5432/bibliotech")
public class LoanStore { }

public class CsvCatalogExporter {

    public String toLine(Book book) {
        return String.join(";",
                book.getIsbn(),
                book.getTitle(),
                book.getAuthor(),
                String.valueOf(book.getPages()));
    }

    public String header() {
        return "ISBN;Title;Author;Pages";
    }
}

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

/**
 * Marks a field as exportable to CSV.
 *
 * It is read by 10-03's AnnotatedExporter, which walks by reflection
 * the fields of any entity, keeps the annotated ones,
 * sorts them by 'order' and builds the header and the line.
 *
 * RUNTIME is MANDATORY: without it, reflection will not see it.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface CsvField {

    /**
     * Column header.
     * Empty = use the field's name (null cannot be used: section 10).
     */
    String name() default "";

    /** Column position. The fields are sorted by this value. */
    int order();

    /** Optional format for String.format. Empty = String.valueOf. */
    String format() default "";

    /** If true, the value is masked when exporting (personal data). */
    boolean sensitive() default false;
}

package com.nexussoftware.bibliotech.domain;

import com.nexussoftware.bibliotech.annotations.CsvField;

public class Book extends Material {

    @CsvField(name = "ISBN", order = 1)
    private final String isbn;

    @CsvField(name = "Title", order = 2)
    private final String title;

    @CsvField(name = "Author", order = 3)
    private final String author;

    @CsvField(name = "Pages", order = 4)
    private final int pages;

    @CsvField(name = "Rating", order = 5, format = "%.2f")
    private final double rating;

    // NO annotation: it is internal state, it is not exported
    private boolean onLoan;

    // NO annotation: internal cache
    private transient String computedSummary;

    public Book(String isbn, String title, String author, int pages, double rating) {
        super(isbn, title);
        this.isbn = isbn;
        this.title = title;
        this.author = author;
        this.pages = pages;
        this.rating = rating;
    }

    // getters...
}

package com.nexussoftware.bibliotech.domain;

import com.nexussoftware.bibliotech.annotations.CsvField;

public record Card(
        @CsvField(name = "ISBN", order = 1) String isbn,
        @CsvField(name = "Title", order = 2) String title,
        @CsvField(name = "Available", order = 3) boolean available) {
}

public class Loan implements Identifiable {

    @CsvField(name = "Reference", order = 1)
    private final String reference;

    @CsvField(name = "ISBN", order = 2)
    private final String isbn;

    @CsvField(name = "Employee", order = 3, sensitive = true)
    private final String employee;

    @CsvField(name = "Loan day", order = 4)
    private final int loanDay;          // it will stay an int until 10-05

    private final List<Incident> incidents = new ArrayList<>();        // not exported
}

public Result<Loan> lend(String isbn, String employee) {
    log.record("lend", employee, isbn);                // repeated in 14 methods
    // ... the real logic
}

package com.nexussoftware.bibliotech.annotations;

import com.nexussoftware.bibliotech.domain.Severity;
import java.lang.annotation.*;

/**
 * Marks an operation that must be recorded in the audit.
 *
 * On its own it records NOTHING: it is a label. The dynamic proxy
 * of 10-03 reads it and intercepts the calls to the marked methods.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface Auditable {

    /**
     * Name of the operation in the log.
     * It is called 'value' to allow the shorthand form @Auditable("lend").
     * Empty = use the method's name.
     */
    String value() default "";

    /** Importance of the operation. */
    Severity level() default Severity.MEDIUM;

    /** If true, the call's arguments are recorded too. */
    boolean logArguments() default false;

    /** Indices of the arguments that must NOT appear in the log. */
    int[] sensitiveArguments() default {};
}

package com.nexussoftware.bibliotech.service;

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

/**
 * @Auditable at TYPE level: default value for the whole class.
 * Methods can refine it with their own annotation.
 */
@Auditable(level = Severity.LOW)
public class LoanManager implements LoanService {

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

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

    @Override
    @Auditable(value = "lend", level = Severity.HIGH, logArguments = true)
    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);
        // Not a single line of auditing: the logic is CLEAN
    }

    @Override
    @Auditable(value = "return", level = Severity.HIGH, logArguments = true)
    public Result<Loan> returnItem(String reference) { ... }

    @Override
    @Auditable(value = "changePassword", logArguments = true, sensitiveArguments = {1})
    public Result<Void> changeEmployeePassword(String employee, String newPassword) { ... }

    // NO @Auditable: read-only query, it is not audited
    @Override
    public List<Loan> listActive() { ... }
}

public class LegacyCatalog {

    private final Map<String, Material> materials = new HashMap<>();

    public boolean equals(LegacyCatalog other) {
        return materials.equals(other.materials);
    }

    public String toString() {
        return "LegacyCatalog with " + materials.size() + " materials";
    }

    public void addAll(List... lists) {
        for (List list : lists) {
            for (Object o : list) {
                Material m = (Material) o;
                materials.put(m.getId(), m);
            }
        }
    }

    public void addBook(String isbn, String title) {
        materials.put(isbn, new Book(isbn, title));
    }

    public interface MaterialFilter {
        boolean accepts(Material m);
    }
}

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

/**
 * Declarative constraints on a field's value.
 * The validator that consumes them is written in 10-03.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)          // MANDATORY in order to read it by reflection
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Validate {

    boolean required() default true;

    int minLength() default 0;

    int maxLength() default Integer.MAX_VALUE;

    /** Regular expression. Empty = no pattern (null cannot be used). */
    String pattern() default "";

    /** Custom message. Empty = the engine generates one. */
    String message() default "";
}

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

/** CONTAINER of @Example. Its value is an array of the repeatable type. */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Examples {
    Example[] value();
}

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

/** Documents a valid example value. Repeatable. */
@Documented
@Repeatable(Examples.class)                  // declares who contains it
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Example {
    String value();                          // 'value' allows @Example("978-0000000001")
}

package com.nexussoftware.bibliotech.domain;

import com.nexussoftware.bibliotech.annotations.*;

public class Book extends Material {

    @Validate(required = true, pattern = "978-\\d{10}",
              message = "The ISBN must follow the format 978-XXXXXXXXXX")
    @Example("978-0000000001")
    @Example("978-0000000002")
    private final String isbn;

    @Validate(required = true, minLength = 1, maxLength = 200)
    @Example("Effective Java")
    private final String title;

    @Validate(required = false, maxLength = 120)
    private final String author;

    // Not annotated: not validated
    private boolean onLoan;

    public Book(String isbn, String title, String author) {
        super(isbn, title);
        this.isbn = isbn;
        this.title = title;
        this.author = author;
    }
}

package com.nexussoftware.bibliotech;

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

import java.lang.reflect.Field;

public class RuleInspector {

    public static void main(String[] args) {

        System.out.printf("%-10s %-6s %-5s %-6s %-20s%n",
                "FIELD", "REQ", "MIN", "MAX", "PATTERN");
        System.out.println("-".repeat(56));

        for (Field field : Book.class.getDeclaredFields()) {

            // Without the annotation, this field is not validated
            if (!field.isAnnotationPresent(Validate.class)) {
                continue;
            }

            Validate rule = field.getAnnotation(Validate.class);

            System.out.printf("%-10s %-6s %-5d %-6s %-20s%n",
                    field.getName(),
                    rule.required() ? "yes" : "no",
                    rule.minLength(),
                    rule.maxLength() == Integer.MAX_VALUE ? "-" : rule.maxLength(),
                    rule.pattern().isEmpty() ? "-" : rule.pattern());

            if (!rule.message().isEmpty()) {
                System.out.println("           message: " + rule.message());
            }

            // REPEATABLE: getAnnotationsByType works with 0, 1 or N occurrences.
            // getAnnotation(Example.class) would return null when there are two.
            Example[] examples = field.getAnnotationsByType(Example.class);
            if (examples.length > 0) {
                StringBuilder sb = new StringBuilder("           examples: ");
                for (Example e : examples) {
                    sb.append(e.value()).append("  ");
                }
                System.out.println(sb);
            }
        }

        // Demonstration of the repeatable trap
        System.out.println();
        try {
            Field isbn = Book.class.getDeclaredField("isbn");
            System.out.println("isbn: getAnnotation(Example)      -> " + isbn.getAnnotation(Example.class));
            System.out.println("isbn: getAnnotation(Examples)     -> present="
                    + isbn.isAnnotationPresent(Examples.class));
            System.out.println("isbn: getAnnotationsByType(Example) -> "
                    + isbn.getAnnotationsByType(Example.class).length + " elements");

            Field title = Book.class.getDeclaredField("title");
            System.out.println("title: getAnnotation(Example)     -> " + title.getAnnotation(Example.class));
        } catch (NoSuchFieldException e) {
            throw new IllegalStateException(e);
        }
    }
}

FIELD      REQ    MIN   MAX    PATTERN
--------------------------------------------------------
isbn       yes    0     -      978-\d{10}
           message: The ISBN must follow the format 978-XXXXXXXXXX
           examples: 978-0000000001  978-0000000002
title      yes    1     200    -
           examples: Effective Java
author     no     0     120    -

isbn: getAnnotation(Example)      -> null
isbn: getAnnotation(Examples)     -> present=true
isbn: getAnnotationsByType(Example) -> 2 elements
title: getAnnotation(Example)     -> @...Example(value="Effective Java")

package com.nexussoftware.bibliotech.service;

import com.nexussoftware.bibliotech.domain.*;
import java.util.*;

public class LegacyCatalog {

    private final Map<String, Material> materials = new HashMap<>();

    /**
     * FIXED: the original signature was equals(LegacyCatalog), which OVERLOADS
     * instead of overriding. With @Override the compiler would have stopped it.
     * HashMap, HashSet and contains() call equals(Object).
     */
    @Override
    public boolean equals(Object other) {
        if (this == other) return true;
        if (!(other instanceof LegacyCatalog)) return false;
        return materials.equals(((LegacyCatalog) other).materials);
    }

    /**
     * Overriding equals FORCES you to override hashCode (03-09).
     * The @Override on equals reminded us that it was missing.
     */
    @Override
    public int hashCode() {
        return Objects.hash(materials);
    }

    @Override
    public String toString() {
        return "LegacyCatalog with " + materials.size() + " materials";
    }

    /**
     * FIXED: it was List... (a raw type) with a cast to Material inside.
     * Now it is generic and typed. @SafeVarargs because the method
     * ONLY READS from the varargs array: it neither stores nor returns it.
     * It must be final (or static/private) in order to be annotated.
     */
    @SafeVarargs
    public final void addAll(List<? extends Material>... lists) {
        for (List<? extends Material> list : lists) {   // ? extends: we only read (PECS, 10-01)
            for (Material m : list) {
                materials.put(m.getId(), m);
            }
        }
    }

    /** Replacement for addBook. */
    public void add(Material material) {
        Objects.requireNonNull(material, "material");
        materials.put(material.getId(), material);
    }

    /**
     * @deprecated Since 3.1 use {@link #add(Material)}, which accepts
     *             any material and not only books. It will be removed in 4.0.
     */
    @Deprecated(since = "3.1", forRemoval = true)
    public void addBook(String isbn, String title) {
        add(new Book(isbn, title));
    }

    /**
     * @FunctionalInterface protects the contract: if somebody adds
     * a second abstract method, the compilation fails here
     * instead of breaking everybody who uses it with lambdas.
     */
    @FunctionalInterface
    public interface MaterialFilter {
        boolean accepts(Material m);

        // default methods do NOT count as abstract
        default MaterialFilter and(MaterialFilter other) {
            return m -> this.accepts(m) && other.accepts(m);
        }
    }
}

public class LegacyCatalogTest {

    @SuppressWarnings("removal")   // we deliberately use the deprecated method, and we justify it
    public static void main(String[] args) {

        LegacyCatalog a = new LegacyCatalog();
        LegacyCatalog b = new LegacyCatalog();

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

        a.addAll(books);         // no warnings: safe generic varargs
        b.addAll(books);

        // With the correct equals, this NOW works
        System.out.println("a.equals(b): " + a.equals(b));

        Set<LegacyCatalog> set = new HashSet<>();
        set.add(a);
        set.add(b);
        System.out.println("Set size: " + set.size() + " (it would have been 2 before)");

        // The deprecated method still works, with a compile warning
        a.addBook("978-0000000003", "Refactoring");

        // The functional interface is used with a lambda
        LegacyCatalog.MaterialFilter available = m -> !m.isOnLoan();
        LegacyCatalog.MaterialFilter titled    = m -> m.getTitle() != null;
        LegacyCatalog.MaterialFilter both = available.and(titled);
        System.out.println("Composite filter created: " + (both != null));
    }
}

a.equals(b): true
Set size: 1 (it would have been 2 before)
Composite filter created: true

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

/**
 * META-ANNOTATION: it can only be put on other annotations.
 * It marks an aspect that cuts across the application instead of
 * belonging to a specific layer.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)     // ONLY on annotations
public @interface CrossCutting {

    /** Order of application when several aspects are stacked. */
    int order() default 0;

    String description() default "";
}

package com.nexussoftware.bibliotech.annotations;

import java.lang.annotation.*;

/**
 * Declares the retry policy of a network operation.
 * Replaces the policy hard-coded by hand in ResilientHttpClient (09-06).
 */
@Documented
@CrossCutting(order = 20, description = "Retries with increasing wait")
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Retryable {

    /** Total number of attempts, including the first one. */
    int attempts() default 3;

    /** Wait before the second attempt, in milliseconds. */
    long initialWaitMs() default 200;

    /** Multiplier of the wait on each retry. */
    double growthFactor() default 2.0;

    /**
     * Exceptions that trigger the retry.
     * Class<? extends Exception>[] is an ALLOWED type in annotations
     * (Class and arrays of Class are), and it is bounded too (10-01).
     */
    Class<? extends Exception>[] exceptions() default { Exception.class };

    /** If true, it only retries when the operation is idempotent (09-06). */
    boolean idempotentOnly() default true;
}

package com.nexussoftware.bibliotech.network;

import com.nexussoftware.bibliotech.annotations.Retryable;

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

public class MetadataClient {

    /** Read-only query: it can be retried with confidence. */
    @Retryable(attempts = 5, initialWaitMs = 100, growthFactor = 2.0,
               exceptions = { SocketTimeoutException.class, ConnectException.class })
    public String lookupByIsbn(String isbn) throws IOException { ... }

    /** Heavy download: fewer attempts and longer waits. */
    @Retryable(attempts = 2, initialWaitMs = 1000, growthFactor = 3.0,
               exceptions = { IOException.class })
    public byte[] downloadCover(String isbn) throws IOException { ... }

    /** Non-idempotent POST: NEVER retried blindly (09-06). */
    @Retryable(attempts = 1, idempotentOnly = true)
    public void publishRating(String isbn, int stars) throws IOException { ... }

    /** No annotation: no retry policy. */
    public boolean isAvailable() { ... }
}

package com.nexussoftware.bibliotech;

import com.nexussoftware.bibliotech.annotations.*;
import com.nexussoftware.bibliotech.network.MetadataClient;

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

public class PolicyDescriptor {

    public static void main(String[] args) {
        describePolicy(MetadataClient.class);

        System.out.println();
        describeMetaAnnotations(Retryable.class);
        describeMetaAnnotations(Auditable.class);
    }

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

        System.out.println("Retry policies in " + type.getSimpleName());
        System.out.printf("%-22s %-8s %-9s %-7s %-11s %s%n",
                "METHOD", "ATTEMPTS", "WAIT_1ST", "FACTOR", "MAX_WAIT", "EXCEPTIONS");
        System.out.println("-".repeat(96));

        // getDeclaredMethods guarantees no order: we fix it so the output is stable
        Method[] methods = type.getDeclaredMethods();
        Arrays.sort(methods, Comparator.comparing(Method::getName));

        for (Method method : methods) {

            Retryable policy = method.getAnnotation(Retryable.class);
            if (policy == null) {
                continue;                       // no declared policy
            }

            // Accumulated wait: w, w*f, w*f^2, ... for (attempts - 1) retries
            double totalWait = 0;
            double wait = policy.initialWaitMs();
            for (int i = 1; i < policy.attempts(); i++) {
                totalWait += wait;
                wait *= policy.growthFactor();
            }

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

            System.out.printf("%-22s %-8d %-9d %-7.1f %-11.0f %s%n",
                    method.getName(),
                    policy.attempts(),
                    policy.initialWaitMs(),
                    policy.growthFactor(),
                    totalWait,
                    exceptions);

            if (policy.idempotentOnly() && policy.attempts() > 1) {
                System.out.println("    warning: it requires idempotency; check that the method is");
            }
        }
    }

    /** Reads the META-annotations of an annotation: it is reflection on reflection. */
    public static void describeMetaAnnotations(Class<? extends java.lang.annotation.Annotation> annotation) {

        System.out.println("Meta-annotations of @" + annotation.getSimpleName() + ":");

        CrossCutting c = annotation.getAnnotation(CrossCutting.class);
        if (c != null) {
            System.out.printf("  @CrossCutting(order=%d) %s%n", c.order(), c.description());
        } else {
            System.out.println("  it is not a cross-cutting aspect");
        }

        Retention r = annotation.getAnnotation(Retention.class);
        Target    t = annotation.getAnnotation(Target.class);
        System.out.println("  retention: " + (r == null ? "CLASS (by default)" : r.value()));
        System.out.println("  targets:   " + (t == null ? "any" : Arrays.toString(t.value())));
    }
}

Retry policies in MetadataClient
METHOD                 ATTEMPTS WAIT_1ST  FACTOR  MAX_WAIT    EXCEPTIONS
------------------------------------------------------------------------------------------------
downloadCover          2        1000      3.0     1000        IOException
    warning: it requires idempotency; check that the method is
lookupByIsbn           5        100       2.0     1500        SocketTimeoutException, ConnectException
publishRating          1        200       2.0     0           Exception

Meta-annotations of @Retryable:
  @CrossCutting(order=20) Retries with increasing wait
  retention: RUNTIME
  targets:   [METHOD]
Meta-annotations of @Auditable:
  @CrossCutting(order=10) Auditing of operations
  retention: RUNTIME
  targets:   [METHOD, TYPE]