// 1. ANOTACIO MARCADORA: sense elements. Els parentesis s ometen.
@Override
public String toString() { ... }

// 2. VALOR UNIC: si l element es diu 'value', s omet el nom.
@SuppressWarnings("unchecked")
List<Llibre> llibres = (List<Llibre>) cru;

// equival exactament a:
@SuppressWarnings(value = "unchecked")

// 3. DIVERSOS ELEMENTS: parells nom = valor, separats per comes.
@Deprecated(since = "3.2", forRemoval = true)
public void prestarLlibre(String isbn) { ... }

@SuppressWarnings({"unchecked", "rawtypes"})     // diversos valors
@SuppressWarnings("unchecked")                   // un de sol: claus opcionals

@Auditable(nivell = "ALT")
@Override
@SuppressWarnings("unchecked")
public Resultat<Prestec> prestar(String isbn, String empleat) { ... }

public class Material {
    private final String isbn;

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

public class Material {

    // SENSE @Override: sembla que sobreescriu equals... pero NO.
    public boolean equals(Material altre) {         // Material, no Object!
        return this.isbn.equals(altre.isbn);
    }
}

Material a = new Llibre("Java Eficac", "978-0000000001");
Material b = new Llibre("Java Eficac", "978-0000000001");

System.out.println(a.equals(b));        // true: crida el teu equals(Material)

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

Set<Material> conjunt = new HashSet<>();
conjunt.add(a);
conjunt.add(b);
System.out.println(conjunt.size());     // 2! duplicats en un Set

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

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

package com.nexussoftware.bibliotech.servei;

public class GestorPrestecs {

    /**
     * Presta un material identificat pel seu ISBN.
     *
     * @deprecated Des de 3.2 fes servir {@link #prestar(String, String)}, que retorna
     *             un {@code Resultat<Prestec>} en lloc de llançar excepcions
     *             per a casos esperables. S'eliminarà a la versió 4.0.
     */
    @Deprecated(since = "3.2", forRemoval = true)
    public void prestarLlibre(String isbn) throws BiblioTechException {
        prestar(isbn, "desconegut");
    }

    public Resultat<Prestec> prestar(String isbn, String empleat) { ... }
}

gestor.prestarLlibre("978-0000000001");

warning: [removal] prestarLlibre(String) in GestorPrestecs has been deprecated and marked for removal

@SuppressWarnings("unchecked")
T[] copia = (T[]) new Object[capacitat];

// MALAMENT: apaga tot a tota la classe per sempre
@SuppressWarnings("all")
public class ImportadorCataleg { ... }

// BE: ambit minim i justificacio
public List<Llibre> llegirLlibres(Path fitxer) throws IOException {
    // SEGUR: el fitxer nomes l escriu ExportadorCatalegCsv, que
    // sempre serialitza Llibre. Qualsevol altre contingut falla abans,
    // a la validacio de capcalera.
    @SuppressWarnings("unchecked")
    List<Llibre> llibres = (List<Llibre>) llegirEntitats(fitxer);
    return llibres;
}

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

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

// PERILLOS: exposa l array de varargs
@SafeVarargs
static <T> T[] perillos(T... elements) {
    return elements;                      // retorna l array creat pel compilador
}

public static void main(String[] args) {
    String[] textos = perillos("a", "b");   // ClassCastException aqui
}

@SafeVarargs
public static <T> List<T> llistaDe(T... elements) {
    return new ArrayList<>(Arrays.asList(elements));   // nomes LLEGEIX de l array
}

package com.nexussoftware.bibliotech.servei;

/**
 * Calcula la multa d un prestec amb retard.
 * En ser funcional, es pot implementar amb una lambda.
 */
@FunctionalInterface
public interface PoliticaMultes {

    double calcular(int diesDeRetard);

    // Els default NO compten com a abstractes: la interficie continua sent funcional
    default PoliticaMultes ambSostreDe(double maxim) {
        return dies -> Math.min(calcular(dies), maxim);
    }

    // Els static tampoc no compten
    static PoliticaMultes fixa(double perDia) {
        return dies -> dies * perDia;
    }
}

PoliticaMultes estandard = dies -> dies * 0.25;
PoliticaMultes acotada   = estandard.ambSostreDe(10.0);

System.out.printf("30 dies de retard: %.2f €%n", estandard.calcular(30));   // 7,50 €
System.out.printf("100 dies acotat:   %.2f €%n", acotada.calcular(100));    // 10,00 €

@FunctionalInterface
public interface PoliticaMultes {
    double calcular(int dies);
    double calcularAmbDescompte(int dies, double descompte);   // segon abstracte
}

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

package com.nexussoftware.bibliotech.anotacions;

/**
 * Marca un element que encara no esta acabat.
 * Per si sola no fa absolutament res.
 */
public @interface EnConstruccio {
}

@EnConstruccio
public class ImportadorMarc21 {
    // ...
}

package com.nexussoftware.bibliotech.anotacions;

/**
 * Documenta qui es responsable d un component i des de quan.
 */
public @interface Responsable {

    /** Nom del responsable. Obligatori: no te default. */
    String nom();

    /** Equip. Opcional. */
    String equip() default "Plataforma";

    /** Data en format ISO. Opcional. */
    String desDe() default "";

    /** Persones de suport. Opcional, array buit per defecte. */
    String[] suport() default {};
}

@Responsable(nom = "Marta Ruiz", equip = "Cataleg", desDe = "2026-01-15",
             suport = {"Diego Alonso", "Nuria Vidal"})
public class CatalegService { }

@Responsable(nom = "Nuria Vidal")        // els altres prenen el seu default
public class ServeiAvisos { }

@Responsable(equip = "Cataleg")

error: annotation @Responsable is missing a default value for the element 'nom'

public @interface Dolent {
    List<String> etiquetes();     // ERROR: invalid type for annotation member
    LocalDate creat();            // ERROR
    Llibre llibre();              // ERROR
}

@Responsable(nom = "Marta " + "Ruiz")              // concatenacio de literals: constant

@Responsable(nom = obtenirResponsable())           // ERROR: no es una constant

public @interface CampCsv {
    String nom() default "";         // "" significa "fes servir el nom del camp"
    int ordre() default Integer.MAX_VALUE;   // sentinella: "al final"
}

public @interface Auditable {
    String value();     // el nom magic
}

@Auditable("prestar")            // forma abreujada
@Auditable(value = "prestar")    // forma completa: equivalents

public @interface Auditable {
    String value();
    Gravetat nivell() default Gravetat.MITJANA;
}

@Auditable("prestar")                                  // OK: nivell pren el seu default
@Auditable(value = "prestar", nivell = Gravetat.ALTA)  // OK: forma completa obligatoria
// @Auditable("prestar", nivell = Gravetat.ALTA)       // ERROR: no es poden barrejar

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

// en una altra banda
boolean te = metode.isAnnotationPresent(Auditable.class);
System.out.println(te);              // false, i no entens per que

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

@Retention(RetentionPolicy.RUNTIME)
public @interface Auditable { }      // ara si

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface CampCsv {
    String nom() default "";
    int ordre();
}

@CampCsv(ordre = 1)       // ERROR: no aplicable a classes
public class Llibre { }

error: annotation type not applicable to this kind of declaration

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

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

@Auditat(modul = "cataleg")
public abstract class Material { }

public class Llibre extends Material { }   // sense anotacio propia

System.out.println(Llibre.class.isAnnotationPresent(Auditat.class));    // true, gracies a @Inherited
System.out.println(Llibre.class.getAnnotation(Auditat.class).modul());  // cataleg

@Responsable(nom = "Marta Ruiz")
@Responsable(nom = "Diego Alonso")        // ERROR abans de Java 8
public class CatalegService { }

error: Responsable is not a repeatable annotation type

package com.nexussoftware.bibliotech.anotacions;

import java.lang.annotation.*;

/** L anotacio CONTENIDORA: guarda un array de les repetibles. */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Responsables {
    Responsable[] value();     // l element HA de dir-se value i ser un array
}

package com.nexussoftware.bibliotech.anotacions;

import java.lang.annotation.*;

/** L anotacio REPETIBLE: declara qui la conte. */
@Repeatable(Responsables.class)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Responsable {
    String nom();
    String equip() default "Plataforma";
}

@Responsable(nom = "Marta Ruiz",   equip = "Cataleg")
@Responsable(nom = "Diego Alonso", equip = "Prestecs")
public class CatalegService { }

// Amb UNA sola @Responsable
CatalegService.class.getAnnotation(Responsable.class);     // retorna l anotacio
CatalegService.class.getAnnotation(Responsables.class);    // null

// Amb DUES @Responsable
CatalegService.class.getAnnotation(Responsable.class);     // null! son dins del contenidor
CatalegService.class.getAnnotation(Responsables.class);    // retorna el contenidor

Responsable[] tots = CatalegService.class.getAnnotationsByType(Responsable.class);
for (Responsable r : tots) {
    System.out.println(r.nom() + " (" + r.equip() + ")");
}

Marta Ruiz (Cataleg)
Diego Alonso (Prestecs)

import java.lang.annotation.*;

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

// En una declaracio de variable
@NoNul String titol = "Java Eficac";

// Al tipus d un parametre generic
List<@NoNul Llibre> cataleg = new ArrayList<>();

// En una conversio
String s = (@NoNul String) objecte;

// En un new
Llibre llibre = new @NoNul Llibre("Refactoritzacio", "978-0000000003");

// En un throws i en un implements
public class Cataleg implements @NoNul Identificable { }

// En arrays: anota el TIPUS D ELEMENT
@NoNul String[] noms;             // array de String no nuls
String @NoNul [] noms2;           // array no nul de String

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

public class Repositori<@Entitat T extends Identificable> { }

package com.nexussoftware.bibliotech.processador;

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

@SupportedAnnotationTypes("com.nexussoftware.bibliotech.anotacions.CampCsv")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
public class ProcessadorCampCsv extends AbstractProcessor {

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

        for (Element element : entorn.getElementsAnnotatedWith(CampCsv.class)) {

            // Comprovacio en TEMPS DE COMPILACIO
            if (element.getModifiers().contains(Modifier.STATIC)) {
                processingEnv.getMessager().printMessage(
                        Diagnostic.Kind.ERROR,
                        "@CampCsv no es pot posar en un camp estatic",
                        element);
            }
            // Aqui es podria generar codi amb
            // processingEnv.getFiler().createSourceFile(...)
        }
        return true;   // true = aquestes anotacions ja estan processades
    }
}

@Data
public class Llibre {
    private String isbn;
    private String titol;
}

import java.lang.reflect.Method;

Method metode = GestorPrestecs.class.getMethod("prestar", String.class, String.class);

// Te l anotacio?
if (metode.isAnnotationPresent(Auditable.class)) {

    // Obtenir-la i llegir-ne els elements
    Auditable auditable = metode.getAnnotation(Auditable.class);
    System.out.println("Operacio: " + auditable.value());
    System.out.println("Nivell:   " + auditable.nivell());
}

// Totes les anotacions (incloses les heretades)
for (Annotation a : metode.getAnnotations()) {
    System.out.println(a);
}

// Nomes les declarades directament
for (Annotation a : metode.getDeclaredAnnotations()) { }

// Repetibles
Responsable[] responsables = CatalegService.class.getAnnotationsByType(Responsable.class);

Operacio: prestar
Nivell:   ALTA
@com.nexussoftware.bibliotech.anotacions.Auditable(value="prestar", nivell=ALTA)

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

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

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

@Service
public class GestorPrestecs {

    private final Repositori<Material> cataleg;

    @Autowired
    public GestorPrestecs(Repositori<Material> cataleg) {
        this.cataleg = cataleg;
    }

    @Transactional
    public Resultat<Prestec> prestar(String isbn, String empleat) { ... }
}

class GestorPrestecsTest {

    @BeforeEach
    void prepararCataleg() { ... }

    @Test
    @DisplayName("Prestar un material disponible retorna exit")
    void prestarDisponible() { ... }
}

<bean id="gestorPrestecs" class="com.nexussoftware.bibliotech.servei.GestorPrestecs">
    <constructor-arg ref="repositoriCataleg"/>
</bean>
<bean id="repositoriCataleg" class="com.nexussoftware.bibliotech.servei.Repositori">
    <constructor-arg value="cataleg"/>
</bean>

@Service
public class GestorPrestecs {
    public GestorPrestecs(Repositori<Material> cataleg) { ... }
}

// MALAMENT: has inventat un llenguatge dins d una cadena
@Regla("si dies > 15 && empleat.categoria != 'DIRECCIO' llavors multa = dies * 0.25")
public double calcularMulta(Prestec p) { ... }

// MALAMENT: canviar de servidor obliga a recompilar
@ConnexioBd(url = "jdbc:postgresql://produccio.nexus:5432/bibliotech")
public class MagatzemPrestecs { }

public class ExportadorCatalegCsv {

    public String aLinia(Llibre llibre) {
        return String.join(";",
                llibre.getIsbn(),
                llibre.getTitol(),
                llibre.getAutor(),
                String.valueOf(llibre.getPagines()));
    }

    public String capcalera() {
        return "ISBN;Titol;Autor;Pagines";
    }
}

package com.nexussoftware.bibliotech.anotacions;

import java.lang.annotation.*;

/**
 * Marca un camp com a exportable a CSV.
 *
 * La llegeix l ExportadorAnotat de 10-03, que recorre per reflexio
 * els camps de qualsevol entitat, es queda amb els anotats,
 * els ordena per 'ordre' i construeix capcalera i linia.
 *
 * RUNTIME es OBLIGATORI: sense ell, la reflexio no la veura.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface CampCsv {

    /**
     * Capcalera de la columna.
     * Buit = fer servir el nom del camp (no s hi pot posar null: apartat 10).
     */
    String nom() default "";

    /** Posicio de la columna. Els camps s ordenen per aquest valor. */
    int ordre();

    /** Format opcional per a String.format. Buit = String.valueOf. */
    String format() default "";

    /** Si es true, el valor s emmascara en exportar (dades personals). */
    boolean sensible() default false;
}

package com.nexussoftware.bibliotech.domini;

import com.nexussoftware.bibliotech.anotacions.CampCsv;

public class Llibre extends Material {

    @CampCsv(nom = "ISBN", ordre = 1)
    private final String isbn;

    @CampCsv(nom = "Titol", ordre = 2)
    private final String titol;

    @CampCsv(nom = "Autor", ordre = 3)
    private final String autor;

    @CampCsv(nom = "Pagines", ordre = 4)
    private final int pagines;

    @CampCsv(nom = "Valoracio", ordre = 5, format = "%.2f")
    private final double valoracio;

    // SENSE anotacio: es estat intern, no s exporta
    private boolean prestat;

    // SENSE anotacio: memoria cau interna
    private transient String resumCalculat;

    public Llibre(String isbn, String titol, String autor, int pagines, double valoracio) {
        super(isbn, titol);
        this.isbn = isbn;
        this.titol = titol;
        this.autor = autor;
        this.pagines = pagines;
        this.valoracio = valoracio;
    }

    // getters...
}

package com.nexussoftware.bibliotech.domini;

import com.nexussoftware.bibliotech.anotacions.CampCsv;

public record Fitxa(
        @CampCsv(nom = "ISBN", ordre = 1) String isbn,
        @CampCsv(nom = "Titol", ordre = 2) String titol,
        @CampCsv(nom = "Disponible", ordre = 3) boolean disponible) {
}

public class Prestec implements Identificable {

    @CampCsv(nom = "Referencia", ordre = 1)
    private final String referencia;

    @CampCsv(nom = "ISBN", ordre = 2)
    private final String isbn;

    @CampCsv(nom = "Empleat", ordre = 3, sensible = true)
    private final String empleat;

    @CampCsv(nom = "Dia prestec", ordre = 4)
    private final int diaPrestec;       // continuara sent int fins a 10-05

    private final List<Incidencia> incidencies = new ArrayList<>();   // no s exporta
}

public Resultat<Prestec> prestar(String isbn, String empleat) {
    registre.registrar("prestar", empleat, isbn);       // repetit en 14 metodes
    // ... logica real
}

package com.nexussoftware.bibliotech.anotacions;

import com.nexussoftware.bibliotech.domini.Gravetat;
import java.lang.annotation.*;

/**
 * Marca una operacio que ha de quedar registrada a l auditoria.
 *
 * Per si sola NO registra res: es una etiqueta. El proxy dinamic
 * de 10-03 la llegeix i intercepta les crides als metodes marcats.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface Auditable {

    /**
     * Nom de l operacio al registre.
     * Es diu 'value' per permetre la forma abreujada @Auditable("prestar").
     * Buit = fer servir el nom del metode.
     */
    String value() default "";

    /** Importancia de l operacio. */
    Gravetat nivell() default Gravetat.MITJANA;

    /** Si es true, tambe es registren els arguments de la crida. */
    boolean registrarArguments() default false;

    /** Index dels arguments que NO han d apareixer al registre. */
    int[] argumentsSensibles() default {};
}

package com.nexussoftware.bibliotech.servei;

import com.nexussoftware.bibliotech.anotacions.Auditable;
import com.nexussoftware.bibliotech.domini.*;

/**
 * @Auditable a nivell de TYPE: valor per defecte per a tota la classe.
 * Els metodes poden afinar-lo amb la seva propia anotacio.
 */
@Auditable(nivell = Gravetat.BAIXA)
public class GestorPrestecs implements ServeiPrestecs {

    private final Repositori<Material> cataleg;
    private final Repositori<Prestec> prestecs;

    public GestorPrestecs(Repositori<Material> cataleg, Repositori<Prestec> prestecs) {
        this.cataleg = cataleg;
        this.prestecs = prestecs;
    }

    @Override
    @Auditable(value = "prestar", nivell = Gravetat.ALTA, registrarArguments = true)
    public Resultat<Prestec> prestar(String isbn, String empleat) {
        Material material = cataleg.cercarPerId(isbn).orElse(null);
        if (material == null) {
            return Resultat.fallada("No existeix cap material amb ISBN " + isbn);
        }
        if (material.estaPrestat()) {
            return Resultat.fallada("El material '" + material.getTitol() + "' ja esta prestat");
        }
        material.marcarPrestat(empleat);
        Prestec prestec = new Prestec(seguentReferencia(), isbn, empleat);
        prestecs.desar(prestec);
        return Resultat.exit(prestec);
        // Ni una sola linia d auditoria: la logica esta NETA
    }

    @Override
    @Auditable(value = "retornar", nivell = Gravetat.ALTA, registrarArguments = true)
    public Resultat<Prestec> retornar(String referencia) { ... }

    @Override
    @Auditable(value = "canviarClau", registrarArguments = true, argumentsSensibles = {1})
    public Resultat<Void> canviarClauEmpleat(String empleat, String clauNova) { ... }

    // SENSE @Auditable: consulta de nomes lectura, no s audita
    @Override
    public List<Prestec> llistarActius() { ... }
}

public class CatalegLlegat {

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

    public boolean equals(CatalegLlegat altre) {
        return materials.equals(altre.materials);
    }

    public String toString() {
        return "CatalegLlegat amb " + materials.size() + " materials";
    }

    public void afegirTots(List... llistes) {
        for (List llista : llistes) {
            for (Object o : llista) {
                Material m = (Material) o;
                materials.put(m.getId(), m);
            }
        }
    }

    public void agregarLlibre(String isbn, String titol) {
        materials.put(isbn, new Llibre(isbn, titol));
    }

    public interface FiltreMaterial {
        boolean accepta(Material m);
    }
}

package com.nexussoftware.bibliotech.anotacions;

import java.lang.annotation.*;

/**
 * Restriccions declaratives sobre el valor d un camp.
 * El validador que les consumeix s escriu a 10-03.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)          // OBLIGATORI per llegir-la per reflexio
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Validar {

    boolean obligatori() default true;

    int longitudMinima() default 0;

    int longitudMaxima() default Integer.MAX_VALUE;

    /** Expressio regular. Buit = sense patro (no s hi pot posar null). */
    String patro() default "";

    /** Missatge personalitzat. Buit = el motor en genera un. */
    String missatge() default "";
}

package com.nexussoftware.bibliotech.anotacions;

import java.lang.annotation.*;

/** CONTENIDORA de @Exemple. El seu value es un array del tipus repetible. */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Exemples {
    Exemple[] value();
}

package com.nexussoftware.bibliotech.anotacions;

import java.lang.annotation.*;

/** Documenta un valor valid d exemple. Repetible. */
@Documented
@Repeatable(Exemples.class)                  // declara qui la conte
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Exemple {
    String value();                          // 'value' permet @Exemple("978-0000000001")
}

package com.nexussoftware.bibliotech.domini;

import com.nexussoftware.bibliotech.anotacions.*;

public class Llibre extends Material {

    @Validar(obligatori = true, patro = "978-\\d{10}",
             missatge = "L ISBN ha de seguir el format 978-XXXXXXXXXX")
    @Exemple("978-0000000001")
    @Exemple("978-0000000002")
    private final String isbn;

    @Validar(obligatori = true, longitudMinima = 1, longitudMaxima = 200)
    @Exemple("Java Eficac")
    private final String titol;

    @Validar(obligatori = false, longitudMaxima = 120)
    private final String autor;

    // Sense anotar: no es valida
    private boolean prestat;

    public Llibre(String isbn, String titol, String autor) {
        super(isbn, titol);
        this.isbn = isbn;
        this.titol = titol;
        this.autor = autor;
    }
}

package com.nexussoftware.bibliotech;

import com.nexussoftware.bibliotech.anotacions.*;
import com.nexussoftware.bibliotech.domini.Llibre;

import java.lang.reflect.Field;

public class InspectorDeRegles {

    public static void main(String[] args) {

        System.out.printf("%-10s %-6s %-5s %-6s %-20s%n",
                "CAMP", "OBLIG", "MIN", "MAX", "PATRO");
        System.out.println("-".repeat(56));

        for (Field camp : Llibre.class.getDeclaredFields()) {

            // Sense l anotacio, aquest camp no es valida
            if (!camp.isAnnotationPresent(Validar.class)) {
                continue;
            }

            Validar regla = camp.getAnnotation(Validar.class);

            System.out.printf("%-10s %-6s %-5d %-6s %-20s%n",
                    camp.getName(),
                    regla.obligatori() ? "si" : "no",
                    regla.longitudMinima(),
                    regla.longitudMaxima() == Integer.MAX_VALUE ? "-" : regla.longitudMaxima(),
                    regla.patro().isEmpty() ? "-" : regla.patro());

            if (!regla.missatge().isEmpty()) {
                System.out.println("           missatge: " + regla.missatge());
            }

            // REPETIBLES: getAnnotationsByType funciona amb 0, 1 o N aparicions.
            // getAnnotation(Exemple.class) retornaria null quan n hi ha dues.
            Exemple[] exemples = camp.getAnnotationsByType(Exemple.class);
            if (exemples.length > 0) {
                StringBuilder sb = new StringBuilder("           exemples: ");
                for (Exemple e : exemples) {
                    sb.append(e.value()).append("  ");
                }
                System.out.println(sb);
            }
        }

        // Demostracio del parany de les repetibles
        System.out.println();
        try {
            Field isbn = Llibre.class.getDeclaredField("isbn");
            System.out.println("isbn: getAnnotation(Exemple)      -> " + isbn.getAnnotation(Exemple.class));
            System.out.println("isbn: getAnnotation(Exemples)     -> present="
                    + isbn.isAnnotationPresent(Exemples.class));
            System.out.println("isbn: getAnnotationsByType(Exemple) -> "
                    + isbn.getAnnotationsByType(Exemple.class).length + " elements");

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

CAMP       OBLIG  MIN   MAX    PATRO
--------------------------------------------------------
isbn       si     0     -      978-\d{10}
           missatge: L ISBN ha de seguir el format 978-XXXXXXXXXX
           exemples: 978-0000000001  978-0000000002
titol      si     1     200    -
           exemples: Java Eficac
autor      no     0     120    -

isbn: getAnnotation(Exemple)      -> null
isbn: getAnnotation(Exemples)     -> present=true
isbn: getAnnotationsByType(Exemple) -> 2 elements
titol: getAnnotation(Exemple)     -> @...Exemple(value="Java Eficac")

package com.nexussoftware.bibliotech.servei;

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

public class CatalegLlegat {

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

    /**
     * CORREGIT: la signatura original era equals(CatalegLlegat), que SOBRECARREGA
     * en lloc de sobreescriure. Amb @Override el compilador ho hauria tallat.
     * HashMap, HashSet i contains() criden equals(Object).
     */
    @Override
    public boolean equals(Object altre) {
        if (this == altre) return true;
        if (!(altre instanceof CatalegLlegat)) return false;
        return materials.equals(((CatalegLlegat) altre).materials);
    }

    /**
     * Sobreescriure equals OBLIGA a sobreescriure hashCode (03-09).
     * L @Override sobre equals ens ha recordat que faltava.
     */
    @Override
    public int hashCode() {
        return Objects.hash(materials);
    }

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

    /**
     * CORREGIT: era List... (tipus cru) amb conversio a Material a dins.
     * Ara es generic i tipat. @SafeVarargs perque el metode
     * NOMES LLEGEIX de l array de varargs: no el guarda ni el retorna.
     * Requereix ser final (o static/private) per poder anotar-lo.
     */
    @SafeVarargs
    public final void afegirTots(List<? extends Material>... llistes) {
        for (List<? extends Material> llista : llistes) {   // ? extends: nomes llegim (PECS, 10-01)
            for (Material m : llista) {
                materials.put(m.getId(), m);
            }
        }
    }

    /** Substitut d agregarLlibre. */
    public void afegir(Material material) {
        Objects.requireNonNull(material, "material");
        materials.put(material.getId(), material);
    }

    /**
     * @deprecated Des de 3.1 fes servir {@link #afegir(Material)}, que accepta
     *             qualsevol material i no només llibres. S'eliminarà a la 4.0.
     */
    @Deprecated(since = "3.1", forRemoval = true)
    public void agregarLlibre(String isbn, String titol) {
        afegir(new Llibre(isbn, titol));
    }

    /**
     * @FunctionalInterface protegeix el contracte: si algu afegeix
     * un segon metode abstracte, la compilacio falla aqui
     * en lloc de trencar tots els qui la fan servir amb lambdes.
     */
    @FunctionalInterface
    public interface FiltreMaterial {
        boolean accepta(Material m);

        // Els default NO compten com a abstractes
        default FiltreMaterial i(FiltreMaterial altre) {
            return m -> this.accepta(m) && altre.accepta(m);
        }
    }
}

public class ProvaCatalegLlegat {

    @SuppressWarnings("removal")   // fem servir a proposit el metode obsolet, i ho justifiquem
    public static void main(String[] args) {

        CatalegLlegat a = new CatalegLlegat();
        CatalegLlegat b = new CatalegLlegat();

        List<Llibre> llibres = List.of(
                new Llibre("978-0000000001", "Java Eficac"),
                new Llibre("978-0000000002", "Patrons de Disseny"));

        a.afegirTots(llibres);   // sense avisos: varargs generics segurs
        b.afegirTots(llibres);

        // Amb l equals correcte, aixo ARA funciona
        System.out.println("a.equals(b): " + a.equals(b));

        Set<CatalegLlegat> conjunt = new HashSet<>();
        conjunt.add(a);
        conjunt.add(b);
        System.out.println("Mida del Set: " + conjunt.size() + " (abans hauria estat 2)");

        // El metode obsolet continua funcionant, amb avis en compilacio
        a.agregarLlibre("978-0000000003", "Refactoritzacio");

        // La interficie funcional es fa servir amb lambda
        CatalegLlegat.FiltreMaterial disponibles = m -> !m.estaPrestat();
        CatalegLlegat.FiltreMaterial ambTitol    = m -> m.getTitol() != null;
        CatalegLlegat.FiltreMaterial ambdos = disponibles.i(ambTitol);
        System.out.println("Filtre compost creat: " + (ambdos != null));
    }
}

a.equals(b): true
Mida del Set: 1 (abans hauria estat 2)
Filtre compost creat: true

package com.nexussoftware.bibliotech.anotacions;

import java.lang.annotation.*;

/**
 * METAANOTACIO: nomes es pot posar sobre altres anotacions.
 * Marca un aspecte que travessa l aplicacio en lloc de
 * pertanyer a una capa concreta.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)     // NOMES sobre anotacions
public @interface Transversal {

    /** Ordre d aplicacio quan diversos aspectes s apilen. */
    int ordre() default 0;

    String descripcio() default "";
}

package com.nexussoftware.bibliotech.anotacions;

import java.lang.annotation.*;

/**
 * Declara la politica de reintents d una operacio de xarxa.
 * Substitueix la politica codificada a ma a ClientHttpResistent (09-06).
 */
@Documented
@Transversal(ordre = 20, descripcio = "Reintents amb espera creixent")
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Reintentable {

    /** Nombre total d intents, inclos el primer. */
    int intents() default 3;

    /** Espera abans del segon intent, en millisegons. */
    long esperaInicialMs() default 200;

    /** Multiplicador de l espera a cada reintent. */
    double factorDeCreixement() default 2.0;

    /**
     * Excepcions que activen el reintent.
     * Class<? extends Exception>[] es un tipus PERMES en anotacions
     * (Class i arrays de Class ho son), i a mes esta acotat (10-01).
     */
    Class<? extends Exception>[] excepcions() default { Exception.class };

    /** Si es true, nomes es reintenta si l operacio es idempotent (09-06). */
    boolean nomesIdempotents() default true;
}

package com.nexussoftware.bibliotech.xarxa;

import com.nexussoftware.bibliotech.anotacions.Reintentable;

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

public class ClientMetadades {

    /** Consulta de nomes lectura: es pot reintentar amb confianca. */
    @Reintentable(intents = 5, esperaInicialMs = 100, factorDeCreixement = 2.0,
                  excepcions = { SocketTimeoutException.class, ConnectException.class })
    public String consultarPerIsbn(String isbn) throws IOException { ... }

    /** Descarrega pesada: menys intents i esperes mes llargues. */
    @Reintentable(intents = 2, esperaInicialMs = 1000, factorDeCreixement = 3.0,
                  excepcions = { IOException.class })
    public byte[] descarregarPortada(String isbn) throws IOException { ... }

    /** POST no idempotent: MAI no es reintenta a cegues (09-06). */
    @Reintentable(intents = 1, nomesIdempotents = true)
    public void publicarValoracio(String isbn, int estrelles) throws IOException { ... }

    /** Sense anotacio: sense politica de reintents. */
    public boolean estaDisponible() { ... }
}

package com.nexussoftware.bibliotech;

import com.nexussoftware.bibliotech.anotacions.*;
import com.nexussoftware.bibliotech.xarxa.ClientMetadades;

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

public class DescriptorDePolitiques {

    public static void main(String[] args) {
        descriurePolitica(ClientMetadades.class);

        System.out.println();
        descriureMetaAnotacions(Reintentable.class);
        descriureMetaAnotacions(Auditable.class);
    }

    public static void descriurePolitica(Class<?> tipus) {

        System.out.println("Politiques de reintent a " + tipus.getSimpleName());
        System.out.printf("%-22s %-8s %-9s %-7s %-11s %s%n",
                "METODE", "INTENTS", "ESPERA_1a", "FACTOR", "ESPERA_MAX", "EXCEPCIONS");
        System.out.println("-".repeat(96));

        // getDeclaredMethods no garanteix ordre: el fixem perque la sortida sigui estable
        Method[] metodes = tipus.getDeclaredMethods();
        Arrays.sort(metodes, Comparator.comparing(Method::getName));

        for (Method metode : metodes) {

            Reintentable politica = metode.getAnnotation(Reintentable.class);
            if (politica == null) {
                continue;                       // sense politica declarada
            }

            // Espera acumulada: e, e*f, e*f^2, ... per a (intents - 1) reintents
            double esperaTotal = 0;
            double espera = politica.esperaInicialMs();
            for (int i = 1; i < politica.intents(); i++) {
                esperaTotal += espera;
                espera *= politica.factorDeCreixement();
            }

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

            System.out.printf("%-22s %-8d %-9d %-7.1f %-11.0f %s%n",
                    metode.getName(),
                    politica.intents(),
                    politica.esperaInicialMs(),
                    politica.factorDeCreixement(),
                    esperaTotal,
                    excepcions);

            if (politica.nomesIdempotents() && politica.intents() > 1) {
                System.out.println("    avis: exigeix idempotencia; verifica que el metode ho sigui");
            }
        }
    }

    /** Llegeix les META-anotacions d una anotacio: es reflexio sobre reflexio. */
    public static void descriureMetaAnotacions(Class<? extends java.lang.annotation.Annotation> anotacio) {

        System.out.println("Metaanotacions de @" + anotacio.getSimpleName() + ":");

        Transversal t = anotacio.getAnnotation(Transversal.class);
        if (t != null) {
            System.out.printf("  @Transversal(ordre=%d) %s%n", t.ordre(), t.descripcio());
        } else {
            System.out.println("  no es un aspecte transversal");
        }

        Retention r = anotacio.getAnnotation(Retention.class);
        Target    d = anotacio.getAnnotation(Target.class);
        System.out.println("  retencio: " + (r == null ? "CLASS (per defecte)" : r.value()));
        System.out.println("  destins:  " + (d == null ? "qualsevol" : Arrays.toString(d.value())));
    }
}

Politiques de reintent a ClientMetadades
METODE                 INTENTS  ESPERA_1a FACTOR  ESPERA_MAX  EXCEPCIONS
------------------------------------------------------------------------------------------------
consultarPerIsbn       5        100       2,0     1500        SocketTimeoutException, ConnectException
descarregarPortada     2        1000      3,0     1000        IOException
    avis: exigeix idempotencia; verifica que el metode ho sigui
publicarValoracio      1        200       2,0     0           Exception

Metaanotacions de @Reintentable:
  @Transversal(ordre=20) Reintents amb espera creixent
  retencio: RUNTIME
  destins:  [METHOD]
Metaanotacions de @Auditable:
  @Transversal(ordre=10) Auditoria d operacions
  retencio: RUNTIME
  destins:  [METHOD, TYPE]