// 1. ANOTACION MARCADORA: sin elementos. Los parentesis se omiten.
@Override
public String toString() { ... }

// 2. VALOR UNICO: si el elemento se llama 'value', se omite el nombre.
@SuppressWarnings("unchecked")
List<Libro> libros = (List<Libro>) crudo;

// equivale exactamente a:
@SuppressWarnings(value = "unchecked")

// 3. VARIOS ELEMENTOS: pares nombre = valor, separados por comas.
@Deprecated(since = "3.2", forRemoval = true)
public void prestarLibro(String isbn) { ... }

@SuppressWarnings({"unchecked", "rawtypes"})     // varios valores
@SuppressWarnings("unchecked")                   // uno solo: llaves opcionales

@Auditable(nivel = "ALTO")
@Override
@SuppressWarnings("unchecked")
public Resultado<Prestamo> prestar(String isbn, String empleado) { ... }

public class Material {
    private final String isbn;

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

public class Material {

    // SIN @Override: parece que sobrescribe equals... pero NO.
    public boolean equals(Material otro) {          // ¡Material, no Object!
        return this.isbn.equals(otro.isbn);
    }
}

Material a = new Libro("Java Efectivo", "978-0000000001");
Material b = new Libro("Java Efectivo", "978-0000000001");

System.out.println(a.equals(b));        // true: llama a tu equals(Material)

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

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

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

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

package com.nexussoftware.bibliotech.servicio;

public class GestorPrestamos {

    /**
     * Presta un material identificado por su ISBN.
     *
     * @deprecated Desde 3.2 usa {@link #prestar(String, String)}, que devuelve
     *             un {@code Resultado<Prestamo>} en lugar de lanzar excepciones
     *             para casos esperables. Se eliminará en la versión 4.0.
     */
    @Deprecated(since = "3.2", forRemoval = true)
    public void prestarLibro(String isbn) throws BiblioTechException {
        prestar(isbn, "desconocido");
    }

    public Resultado<Prestamo> prestar(String isbn, String empleado) { ... }
}

gestor.prestarLibro("978-0000000001");

warning: [removal] prestarLibro(String) in GestorPrestamos has been deprecated and marked for removal

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

// MAL: apaga todo en toda la clase para siempre
@SuppressWarnings("all")
public class ImportadorCatalogo { ... }

// BIEN: ambito minimo y justificacion
public List<Libro> leerLibros(Path fichero) throws IOException {
    // SEGURO: el fichero solo lo escribe ExportadorCatalogoCsv, que
    // siempre serializa Libro. Cualquier otro contenido falla antes,
    // en la validacion de cabecera.
    @SuppressWarnings("unchecked")
    List<Libro> libros = (List<Libro>) leerEntidades(fichero);
    return libros;
}

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

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

// PELIGROSO: expone el array de varargs
@SafeVarargs
static <T> T[] peligroso(T... elementos) {
    return elementos;                     // devuelve el array creado por el compilador
}

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

@SafeVarargs
public static <T> List<T> listaDe(T... elementos) {
    return new ArrayList<>(Arrays.asList(elementos));   // solo LEE del array
}

package com.nexussoftware.bibliotech.servicio;

/**
 * Calcula la multa de un prestamo con retraso.
 * Al ser funcional, se puede implementar con una lambda.
 */
@FunctionalInterface
public interface PoliticaMultas {

    double calcular(int diasDeRetraso);

    // Los default NO cuentan como abstractos: la interfaz sigue siendo funcional
    default PoliticaMultas conTopeDe(double maximo) {
        return dias -> Math.min(calcular(dias), maximo);
    }

    // Los static tampoco cuentan
    static PoliticaMultas fija(double porDia) {
        return dias -> dias * porDia;
    }
}

PoliticaMultas estandar = dias -> dias * 0.25;
PoliticaMultas acotada  = estandar.conTopeDe(10.0);

System.out.printf("30 días de retraso: %.2f €%n", estandar.calcular(30));   // 7,50 €
System.out.printf("100 días acotado:   %.2f €%n", acotada.calcular(100));   // 10,00 €

@FunctionalInterface
public interface PoliticaMultas {
    double calcular(int dias);
    double calcularConDescuento(int dias, double descuento);   // segundo abstracto
}

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

package com.nexussoftware.bibliotech.anotaciones;

/**
 * Marca un elemento que aun no esta terminado.
 * Por si sola no hace absolutamente nada.
 */
public @interface EnConstruccion {
}

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

package com.nexussoftware.bibliotech.anotaciones;

/**
 * Documenta quien es responsable de un componente y desde cuando.
 */
public @interface Responsable {

    /** Nombre del responsable. Obligatorio: no tiene default. */
    String nombre();

    /** Equipo. Opcional. */
    String equipo() default "Plataforma";

    /** Fecha en formato ISO. Opcional. */
    String desde() default "";

    /** Personas de respaldo. Opcional, array vacio por defecto. */
    String[] respaldo() default {};
}

@Responsable(nombre = "Marta Ruiz", equipo = "Catálogo", desde = "2026-01-15",
             respaldo = {"Diego Alonso", "Nuria Vidal"})
public class CatalogoService { }

@Responsable(nombre = "Nuria Vidal")     // los demas toman su default
public class ServicioAvisos { }

@Responsable(equipo = "Catálogo")

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

public @interface Malo {
    List<String> etiquetas();     // ERROR: invalid type for annotation member
    LocalDate creado();           // ERROR
    Libro libro();                // ERROR
}

@Responsable(nombre = "Marta " + "Ruiz")           // concatenacion de literales: constante

@Responsable(nombre = obtenerResponsable())        // ERROR: no es una constante

public @interface CampoCsv {
    String nombre() default "";      // "" significa "usa el nombre del campo"
    int orden() default Integer.MAX_VALUE;   // centinela: "al final"
}

public @interface Auditable {
    String value();     // el nombre magico
}

@Auditable("prestar")            // forma abreviada
@Auditable(value = "prestar")    // forma completa: equivalentes

public @interface Auditable {
    String value();
    Gravedad nivel() default Gravedad.MEDIA;
}

@Auditable("prestar")                                 // OK: nivel toma su default
@Auditable(value = "prestar", nivel = Gravedad.ALTA)  // OK: forma completa obligatoria
// @Auditable("prestar", nivel = Gravedad.ALTA)       // ERROR: no se puede mezclar

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

// en otra parte
boolean tiene = metodo.isAnnotationPresent(Auditable.class);
System.out.println(tiene);           // false, y no entiendes por que

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

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

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface CampoCsv {
    String nombre() default "";
    int orden();
}

@CampoCsv(orden = 1)      // ERROR: no aplicable a clases
public class Libro { }

error: annotation type not applicable to this kind of declaration

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

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

@Auditado(modulo = "catálogo")
public abstract class Material { }

public class Libro extends Material { }    // sin anotacion propia

System.out.println(Libro.class.isAnnotationPresent(Auditado.class));   // true, gracias a @Inherited
System.out.println(Libro.class.getAnnotation(Auditado.class).modulo()); // catálogo

@Responsable(nombre = "Marta Ruiz")
@Responsable(nombre = "Diego Alonso")     // ERROR antes de Java 8
public class CatalogoService { }

error: Responsable is not a repeatable annotation type

package com.nexussoftware.bibliotech.anotaciones;

import java.lang.annotation.*;

/** La anotacion CONTENEDORA: guarda un array de las repetibles. */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Responsables {
    Responsable[] value();     // el elemento DEBE llamarse value y ser un array
}

package com.nexussoftware.bibliotech.anotaciones;

import java.lang.annotation.*;

/** La anotacion REPETIBLE: declara quien la contiene. */
@Repeatable(Responsables.class)
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Responsable {
    String nombre();
    String equipo() default "Plataforma";
}

@Responsable(nombre = "Marta Ruiz",   equipo = "Catálogo")
@Responsable(nombre = "Diego Alonso", equipo = "Préstamos")
public class CatalogoService { }

// Con UNA sola @Responsable
CatalogoService.class.getAnnotation(Responsable.class);    // devuelve la anotacion
CatalogoService.class.getAnnotation(Responsables.class);   // null

// Con DOS @Responsable
CatalogoService.class.getAnnotation(Responsable.class);    // ¡null! estan dentro del contenedor
CatalogoService.class.getAnnotation(Responsables.class);   // devuelve el contenedor

Responsable[] todos = CatalogoService.class.getAnnotationsByType(Responsable.class);
for (Responsable r : todos) {
    System.out.println(r.nombre() + " (" + r.equipo() + ")");
}

Marta Ruiz (Catálogo)
Diego Alonso (Préstamos)

import java.lang.annotation.*;

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

// En una declaracion de variable
@NoNulo String titulo = "Java Efectivo";

// En el tipo de un parametro generico
List<@NoNulo Libro> catalogo = new ArrayList<>();

// En un cast
String s = (@NoNulo String) objeto;

// En un new
Libro libro = new @NoNulo Libro("Refactorización", "978-0000000003");

// En un throws y en un implements
public class Catalogo implements @NoNulo Identificable { }

// En arrays: anota el TIPO DE ELEMENTO
@NoNulo String[] nombres;         // array de String no nulos
String @NoNulo [] nombres2;       // array no nulo de String

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

public class Repositorio<@Entidad T extends Identificable> { }

package com.nexussoftware.bibliotech.procesador;

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

@SupportedAnnotationTypes("com.nexussoftware.bibliotech.anotaciones.CampoCsv")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
public class ProcesadorCampoCsv extends AbstractProcessor {

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

        for (Element elemento : entorno.getElementsAnnotatedWith(CampoCsv.class)) {

            // Comprobacion en TIEMPO DE COMPILACION
            if (elemento.getModifiers().contains(Modifier.STATIC)) {
                processingEnv.getMessager().printMessage(
                        Diagnostic.Kind.ERROR,
                        "@CampoCsv no se puede poner en un campo estático",
                        elemento);
            }
            // Aqui se podria generar codigo con
            // processingEnv.getFiler().createSourceFile(...)
        }
        return true;   // true = estas anotaciones ya estan procesadas
    }
}

@Data
public class Libro {
    private String isbn;
    private String titulo;
}

import java.lang.reflect.Method;

Method metodo = GestorPrestamos.class.getMethod("prestar", String.class, String.class);

// ¿Tiene la anotacion?
if (metodo.isAnnotationPresent(Auditable.class)) {

    // Obtenerla y leer sus elementos
    Auditable auditable = metodo.getAnnotation(Auditable.class);
    System.out.println("Operación: " + auditable.value());
    System.out.println("Nivel:     " + auditable.nivel());
}

// Todas las anotaciones (incluidas heredadas)
for (Annotation a : metodo.getAnnotations()) {
    System.out.println(a);
}

// Solo las declaradas directamente
for (Annotation a : metodo.getDeclaredAnnotations()) { }

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

Operación: prestar
Nivel:     ALTA
@com.nexussoftware.bibliotech.anotaciones.Auditable(value="prestar", nivel=ALTA)

@Entity
@Table(name = "materiales")
public class Libro {

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

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

@Service
public class GestorPrestamos {

    private final Repositorio<Material> catalogo;

    @Autowired
    public GestorPrestamos(Repositorio<Material> catalogo) {
        this.catalogo = catalogo;
    }

    @Transactional
    public Resultado<Prestamo> prestar(String isbn, String empleado) { ... }
}

class GestorPrestamosTest {

    @BeforeEach
    void prepararCatalogo() { ... }

    @Test
    @DisplayName("Prestar un material disponible devuelve éxito")
    void prestarDisponible() { ... }
}

<bean id="gestorPrestamos" class="com.nexussoftware.bibliotech.servicio.GestorPrestamos">
    <constructor-arg ref="repositorioCatalogo"/>
</bean>
<bean id="repositorioCatalogo" class="com.nexussoftware.bibliotech.servicio.Repositorio">
    <constructor-arg value="catálogo"/>
</bean>

@Service
public class GestorPrestamos {
    public GestorPrestamos(Repositorio<Material> catalogo) { ... }
}

// MAL: has inventado un lenguaje dentro de una cadena
@Regla("si dias > 15 && empleado.categoria != 'DIRECCION' entonces multa = dias * 0.25")
public double calcularMulta(Prestamo p) { ... }

// MAL: cambiar de servidor obliga a recompilar
@ConexionBd(url = "jdbc:postgresql://produccion.nexus:5432/bibliotech")
public class AlmacenPrestamos { }

public class ExportadorCatalogoCsv {

    public String aLinea(Libro libro) {
        return String.join(";",
                libro.getIsbn(),
                libro.getTitulo(),
                libro.getAutor(),
                String.valueOf(libro.getPaginas()));
    }

    public String cabecera() {
        return "ISBN;Título;Autor;Páginas";
    }
}

package com.nexussoftware.bibliotech.anotaciones;

import java.lang.annotation.*;

/**
 * Marca un campo como exportable a CSV.
 *
 * La lee el ExportadorAnotado de 10-03, que recorre por reflexion
 * los campos de cualquier entidad, se queda con los anotados,
 * los ordena por 'orden' y construye cabecera y linea.
 *
 * RUNTIME es OBLIGATORIO: sin el, la reflexion no la vera.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface CampoCsv {

    /**
     * Encabezado de la columna.
     * Vacio = usar el nombre del campo (no se puede poner null: apartado 10).
     */
    String nombre() default "";

    /** Posicion de la columna. Los campos se ordenan por este valor. */
    int orden();

    /** Formato opcional para String.format. Vacio = String.valueOf. */
    String formato() default "";

    /** Si es true, el valor se enmascara al exportar (datos personales). */
    boolean sensible() default false;
}

package com.nexussoftware.bibliotech.dominio;

import com.nexussoftware.bibliotech.anotaciones.CampoCsv;

public class Libro extends Material {

    @CampoCsv(nombre = "ISBN", orden = 1)
    private final String isbn;

    @CampoCsv(nombre = "Título", orden = 2)
    private final String titulo;

    @CampoCsv(nombre = "Autor", orden = 3)
    private final String autor;

    @CampoCsv(nombre = "Páginas", orden = 4)
    private final int paginas;

    @CampoCsv(nombre = "Valoración", orden = 5, formato = "%.2f")
    private final double valoracion;

    // SIN anotacion: es estado interno, no se exporta
    private boolean prestado;

    // SIN anotacion: cache interna
    private transient String resumenCalculado;

    public Libro(String isbn, String titulo, String autor, int paginas, double valoracion) {
        super(isbn, titulo);
        this.isbn = isbn;
        this.titulo = titulo;
        this.autor = autor;
        this.paginas = paginas;
        this.valoracion = valoracion;
    }

    // getters...
}

package com.nexussoftware.bibliotech.dominio;

import com.nexussoftware.bibliotech.anotaciones.CampoCsv;

public record Ficha(
        @CampoCsv(nombre = "ISBN", orden = 1) String isbn,
        @CampoCsv(nombre = "Título", orden = 2) String titulo,
        @CampoCsv(nombre = "Disponible", orden = 3) boolean disponible) {
}

public class Prestamo implements Identificable {

    @CampoCsv(nombre = "Referencia", orden = 1)
    private final String referencia;

    @CampoCsv(nombre = "ISBN", orden = 2)
    private final String isbn;

    @CampoCsv(nombre = "Empleado", orden = 3, sensible = true)
    private final String empleado;

    @CampoCsv(nombre = "Día préstamo", orden = 4)
    private final int diaPrestamo;      // seguira siendo int hasta 10-05

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

public Resultado<Prestamo> prestar(String isbn, String empleado) {
    registro.registrar("prestar", empleado, isbn);      // repetido en 14 metodos
    // ... logica real
}

package com.nexussoftware.bibliotech.anotaciones;

import com.nexussoftware.bibliotech.dominio.Gravedad;
import java.lang.annotation.*;

/**
 * Marca una operacion que debe quedar registrada en la auditoria.
 *
 * Por si sola NO registra nada: es una etiqueta. El proxy dinamico
 * de 10-03 la lee e intercepta las llamadas a los metodos marcados.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface Auditable {

    /**
     * Nombre de la operacion en el registro.
     * Se llama 'value' para permitir la forma abreviada @Auditable("prestar").
     * Vacio = usar el nombre del metodo.
     */
    String value() default "";

    /** Importancia de la operacion. */
    Gravedad nivel() default Gravedad.MEDIA;

    /** Si es true, tambien se registran los argumentos de la llamada. */
    boolean registrarArgumentos() default false;

    /** Indices de los argumentos que NO deben aparecer en el registro. */
    int[] argumentosSensibles() default {};
}

package com.nexussoftware.bibliotech.servicio;

import com.nexussoftware.bibliotech.anotaciones.Auditable;
import com.nexussoftware.bibliotech.dominio.*;

/**
 * @Auditable a nivel de TYPE: valor por defecto para toda la clase.
 * Los metodos pueden afinarlo con su propia anotacion.
 */
@Auditable(nivel = Gravedad.BAJA)
public class GestorPrestamos implements ServicioPrestamos {

    private final Repositorio<Material> catalogo;
    private final Repositorio<Prestamo> prestamos;

    public GestorPrestamos(Repositorio<Material> catalogo, Repositorio<Prestamo> prestamos) {
        this.catalogo = catalogo;
        this.prestamos = prestamos;
    }

    @Override
    @Auditable(value = "prestar", nivel = Gravedad.ALTA, registrarArgumentos = true)
    public Resultado<Prestamo> prestar(String isbn, String empleado) {
        Material material = catalogo.buscarPorId(isbn).orElse(null);
        if (material == null) {
            return Resultado.fallo("No existe ningún material con ISBN " + isbn);
        }
        if (material.estaPrestado()) {
            return Resultado.fallo("El material '" + material.getTitulo() + "' ya está prestado");
        }
        material.marcarPrestado(empleado);
        Prestamo prestamo = new Prestamo(siguienteReferencia(), isbn, empleado);
        prestamos.guardar(prestamo);
        return Resultado.exito(prestamo);
        // Ni una sola linea de auditoria: la logica esta LIMPIA
    }

    @Override
    @Auditable(value = "devolver", nivel = Gravedad.ALTA, registrarArgumentos = true)
    public Resultado<Prestamo> devolver(String referencia) { ... }

    @Override
    @Auditable(value = "cambiarClave", registrarArgumentos = true, argumentosSensibles = {1})
    public Resultado<Void> cambiarClaveEmpleado(String empleado, String claveNueva) { ... }

    // SIN @Auditable: consulta de solo lectura, no se audita
    @Override
    public List<Prestamo> listarActivos() { ... }
}

public class CatalogoLegado {

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

    public boolean equals(CatalogoLegado otro) {
        return materiales.equals(otro.materiales);
    }

    public String toString() {
        return "CatalogoLegado con " + materiales.size() + " materiales";
    }

    public void anadirTodos(List... listas) {
        for (List lista : listas) {
            for (Object o : lista) {
                Material m = (Material) o;
                materiales.put(m.getId(), m);
            }
        }
    }

    public void agregarLibro(String isbn, String titulo) {
        materiales.put(isbn, new Libro(isbn, titulo));
    }

    public interface FiltroMaterial {
        boolean acepta(Material m);
    }
}

package com.nexussoftware.bibliotech.anotaciones;

import java.lang.annotation.*;

/**
 * Restricciones declarativas sobre el valor de un campo.
 * El validador que las consume se escribe en 10-03.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)          // OBLIGATORIO para leerla por reflexion
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Validar {

    boolean obligatorio() default true;

    int longitudMinima() default 0;

    int longitudMaxima() default Integer.MAX_VALUE;

    /** Expresion regular. Vacio = sin patron (no se puede poner null). */
    String patron() default "";

    /** Mensaje personalizado. Vacio = el motor genera uno. */
    String mensaje() default "";
}

package com.nexussoftware.bibliotech.anotaciones;

import java.lang.annotation.*;

/** CONTENEDORA de @Ejemplo. Su value es un array del tipo repetible. */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Ejemplos {
    Ejemplo[] value();
}

package com.nexussoftware.bibliotech.anotaciones;

import java.lang.annotation.*;

/** Documenta un valor valido de ejemplo. Repetible. */
@Documented
@Repeatable(Ejemplos.class)                  // declara quien la contiene
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.RECORD_COMPONENT})
public @interface Ejemplo {
    String value();                          // 'value' permite @Ejemplo("978-0000000001")
}

package com.nexussoftware.bibliotech.dominio;

import com.nexussoftware.bibliotech.anotaciones.*;

public class Libro extends Material {

    @Validar(obligatorio = true, patron = "978-\\d{10}",
             mensaje = "El ISBN debe seguir el formato 978-XXXXXXXXXX")
    @Ejemplo("978-0000000001")
    @Ejemplo("978-0000000002")
    private final String isbn;

    @Validar(obligatorio = true, longitudMinima = 1, longitudMaxima = 200)
    @Ejemplo("Java Efectivo")
    private final String titulo;

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

    // Sin anotar: no se valida
    private boolean prestado;

    public Libro(String isbn, String titulo, String autor) {
        super(isbn, titulo);
        this.isbn = isbn;
        this.titulo = titulo;
        this.autor = autor;
    }
}

package com.nexussoftware.bibliotech;

import com.nexussoftware.bibliotech.anotaciones.*;
import com.nexussoftware.bibliotech.dominio.Libro;

import java.lang.reflect.Field;

public class InspectorDeReglas {

    public static void main(String[] args) {

        System.out.printf("%-10s %-6s %-5s %-6s %-20s%n",
                "CAMPO", "OBLIG", "MIN", "MAX", "PATRÓN");
        System.out.println("-".repeat(56));

        for (Field campo : Libro.class.getDeclaredFields()) {

            // Sin la anotacion, este campo no se valida
            if (!campo.isAnnotationPresent(Validar.class)) {
                continue;
            }

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

            System.out.printf("%-10s %-6s %-5d %-6s %-20s%n",
                    campo.getName(),
                    regla.obligatorio() ? "sí" : "no",
                    regla.longitudMinima(),
                    regla.longitudMaxima() == Integer.MAX_VALUE ? "-" : regla.longitudMaxima(),
                    regla.patron().isEmpty() ? "-" : regla.patron());

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

            // REPETIBLES: getAnnotationsByType funciona con 0, 1 o N apariciones.
            // getAnnotation(Ejemplo.class) devolveria null cuando hay dos.
            Ejemplo[] ejemplos = campo.getAnnotationsByType(Ejemplo.class);
            if (ejemplos.length > 0) {
                StringBuilder sb = new StringBuilder("           ejemplos: ");
                for (Ejemplo e : ejemplos) {
                    sb.append(e.value()).append("  ");
                }
                System.out.println(sb);
            }
        }

        // Demostracion de la trampa de las repetibles
        System.out.println();
        try {
            Field isbn = Libro.class.getDeclaredField("isbn");
            System.out.println("isbn: getAnnotation(Ejemplo)      -> " + isbn.getAnnotation(Ejemplo.class));
            System.out.println("isbn: getAnnotation(Ejemplos)     -> presente="
                    + isbn.isAnnotationPresent(Ejemplos.class));
            System.out.println("isbn: getAnnotationsByType(Ejemplo) -> "
                    + isbn.getAnnotationsByType(Ejemplo.class).length + " elementos");

            Field titulo = Libro.class.getDeclaredField("titulo");
            System.out.println("título: getAnnotation(Ejemplo)    -> " + titulo.getAnnotation(Ejemplo.class));
        } catch (NoSuchFieldException e) {
            throw new IllegalStateException(e);
        }
    }
}

CAMPO      OBLIG  MIN   MAX    PATRÓN
--------------------------------------------------------
isbn       sí     0     -      978-\d{10}
           mensaje: El ISBN debe seguir el formato 978-XXXXXXXXXX
           ejemplos: 978-0000000001  978-0000000002
titulo     sí     1     200    -
           ejemplos: Java Efectivo
autor      no     0     120    -

isbn: getAnnotation(Ejemplo)      -> null
isbn: getAnnotation(Ejemplos)     -> presente=true
isbn: getAnnotationsByType(Ejemplo) -> 2 elementos
título: getAnnotation(Ejemplo)    -> @...Ejemplo(value="Java Efectivo")

package com.nexussoftware.bibliotech.servicio;

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

public class CatalogoLegado {

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

    /**
     * CORREGIDO: la firma original era equals(CatalogoLegado), que SOBRECARGA
     * en lugar de sobrescribir. Con @Override el compilador lo habria cortado.
     * HashMap, HashSet y contains() llaman a equals(Object).
     */
    @Override
    public boolean equals(Object otro) {
        if (this == otro) return true;
        if (!(otro instanceof CatalogoLegado)) return false;
        return materiales.equals(((CatalogoLegado) otro).materiales);
    }

    /**
     * Sobrescribir equals OBLIGA a sobrescribir hashCode (03-09).
     * El @Override sobre equals nos ha recordado que faltaba.
     */
    @Override
    public int hashCode() {
        return Objects.hash(materiales);
    }

    @Override
    public String toString() {
        return "CatalogoLegado con " + materiales.size() + " materiales";
    }

    /**
     * CORREGIDO: era List... (tipo crudo) con cast a Material dentro.
     * Ahora es generico y tipado. @SafeVarargs porque el metodo
     * SOLO LEE del array de varargs: no lo guarda ni lo devuelve.
     * Requiere ser final (o static/private) para poder anotarlo.
     */
    @SafeVarargs
    public final void anadirTodos(List<? extends Material>... listas) {
        for (List<? extends Material> lista : listas) {   // ? extends: solo leemos (PECS, 10-01)
            for (Material m : lista) {
                materiales.put(m.getId(), m);
            }
        }
    }

    /** Sustituto de agregarLibro. */
    public void anadir(Material material) {
        Objects.requireNonNull(material, "material");
        materiales.put(material.getId(), material);
    }

    /**
     * @deprecated Desde 3.1 usa {@link #anadir(Material)}, que acepta
     *             cualquier material y no solo libros. Se eliminará en 4.0.
     */
    @Deprecated(since = "3.1", forRemoval = true)
    public void agregarLibro(String isbn, String titulo) {
        anadir(new Libro(isbn, titulo));
    }

    /**
     * @FunctionalInterface protege el contrato: si alguien anade
     * un segundo metodo abstracto, la compilacion falla aqui
     * en vez de romper a todos los que la usan con lambdas.
     */
    @FunctionalInterface
    public interface FiltroMaterial {
        boolean acepta(Material m);

        // Los default NO cuentan como abstractos
        default FiltroMaterial y(FiltroMaterial otro) {
            return m -> this.acepta(m) && otro.acepta(m);
        }
    }
}

public class PruebaCatalogoLegado {

    @SuppressWarnings("removal")   // usamos a proposito el metodo obsoleto, y lo justificamos
    public static void main(String[] args) {

        CatalogoLegado a = new CatalogoLegado();
        CatalogoLegado b = new CatalogoLegado();

        List<Libro> libros = List.of(
                new Libro("978-0000000001", "Java Efectivo"),
                new Libro("978-0000000002", "Patrones de Diseño"));

        a.anadirTodos(libros);   // sin avisos: varargs genericos seguros
        b.anadirTodos(libros);

        // Con el equals correcto, esto AHORA funciona
        System.out.println("a.equals(b): " + a.equals(b));

        Set<CatalogoLegado> conjunto = new HashSet<>();
        conjunto.add(a);
        conjunto.add(b);
        System.out.println("Tamaño del Set: " + conjunto.size() + " (antes habría sido 2)");

        // El metodo obsoleto sigue funcionando, con aviso en compilacion
        a.agregarLibro("978-0000000003", "Refactorización");

        // La interfaz funcional se usa con lambda
        CatalogoLegado.FiltroMaterial disponibles = m -> !m.estaPrestado();
        CatalogoLegado.FiltroMaterial conTitulo   = m -> m.getTitulo() != null;
        CatalogoLegado.FiltroMaterial ambos = disponibles.y(conTitulo);
        System.out.println("Filtro compuesto creado: " + (ambos != null));
    }
}

a.equals(b): true
Tamaño del Set: 1 (antes habría sido 2)
Filtro compuesto creado: true

package com.nexussoftware.bibliotech.anotaciones;

import java.lang.annotation.*;

/**
 * META-ANOTACION: solo se puede poner sobre otras anotaciones.
 * Marca un aspecto que atraviesa la aplicacion en lugar de
 * pertenecer a una capa concreta.
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)     // SOLO sobre anotaciones
public @interface Transversal {

    /** Orden de aplicacion cuando varios aspectos se apilan. */
    int orden() default 0;

    String descripcion() default "";
}

package com.nexussoftware.bibliotech.anotaciones;

import java.lang.annotation.*;

/**
 * Declara la politica de reintentos de una operacion de red.
 * Sustituye a la politica codificada a mano en ClienteHttpResistente (09-06).
 */
@Documented
@Transversal(orden = 20, descripcion = "Reintentos con espera creciente")
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Reintentable {

    /** Numero total de intentos, incluido el primero. */
    int intentos() default 3;

    /** Espera antes del segundo intento, en milisegundos. */
    long esperaInicialMs() default 200;

    /** Multiplicador de la espera en cada reintento. */
    double factorDeCrecimiento() default 2.0;

    /**
     * Excepciones que activan el reintento.
     * Class<? extends Exception>[] es un tipo PERMITIDO en anotaciones
     * (Class y arrays de Class lo son), y ademas esta acotado (10-01).
     */
    Class<? extends Exception>[] excepciones() default { Exception.class };

    /** Si es true, solo se reintenta si la operacion es idempotente (09-06). */
    boolean soloIdempotentes() default true;
}

package com.nexussoftware.bibliotech.red;

import com.nexussoftware.bibliotech.anotaciones.Reintentable;

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

public class ClienteMetadatos {

    /** Consulta de solo lectura: se puede reintentar con confianza. */
    @Reintentable(intentos = 5, esperaInicialMs = 100, factorDeCrecimiento = 2.0,
                  excepciones = { SocketTimeoutException.class, ConnectException.class })
    public String consultarPorIsbn(String isbn) throws IOException { ... }

    /** Descarga pesada: menos intentos y esperas mas largas. */
    @Reintentable(intentos = 2, esperaInicialMs = 1000, factorDeCrecimiento = 3.0,
                  excepciones = { IOException.class })
    public byte[] descargarPortada(String isbn) throws IOException { ... }

    /** POST no idempotente: NUNCA se reintenta a ciegas (09-06). */
    @Reintentable(intentos = 1, soloIdempotentes = true)
    public void publicarValoracion(String isbn, int estrellas) throws IOException { ... }

    /** Sin anotacion: sin politica de reintentos. */
    public boolean estaDisponible() { ... }
}

package com.nexussoftware.bibliotech;

import com.nexussoftware.bibliotech.anotaciones.*;
import com.nexussoftware.bibliotech.red.ClienteMetadatos;

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

public class DescriptorDePoliticas {

    public static void main(String[] args) {
        describirPolitica(ClienteMetadatos.class);

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

    public static void describirPolitica(Class<?> tipo) {

        System.out.println("Políticas de reintento en " + tipo.getSimpleName());
        System.out.printf("%-22s %-8s %-9s %-7s %-11s %s%n",
                "MÉTODO", "INTENTOS", "ESPERA_1ª", "FACTOR", "ESPERA_MÁX", "EXCEPCIONES");
        System.out.println("-".repeat(96));

        // getDeclaredMethods no garantiza orden: lo fijamos para que la salida sea estable
        Method[] metodos = tipo.getDeclaredMethods();
        Arrays.sort(metodos, Comparator.comparing(Method::getName));

        for (Method metodo : metodos) {

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

            // Espera acumulada: e, e*f, e*f^2, ... para (intentos - 1) reintentos
            double esperaTotal = 0;
            double espera = politica.esperaInicialMs();
            for (int i = 1; i < politica.intentos(); i++) {
                esperaTotal += espera;
                espera *= politica.factorDeCrecimiento();
            }

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

            System.out.printf("%-22s %-8d %-9d %-7.1f %-11.0f %s%n",
                    metodo.getName(),
                    politica.intentos(),
                    politica.esperaInicialMs(),
                    politica.factorDeCrecimiento(),
                    esperaTotal,
                    excepciones);

            if (politica.soloIdempotentes() && politica.intentos() > 1) {
                System.out.println("    aviso: exige idempotencia; verifica que el método lo sea");
            }
        }
    }

    /** Lee las META-anotaciones de una anotacion: es reflexion sobre reflexion. */
    public static void describirMetaAnotaciones(Class<? extends java.lang.annotation.Annotation> anotacion) {

        System.out.println("Meta-anotaciones de @" + anotacion.getSimpleName() + ":");

        Transversal t = anotacion.getAnnotation(Transversal.class);
        if (t != null) {
            System.out.printf("  @Transversal(orden=%d) %s%n", t.orden(), t.descripcion());
        } else {
            System.out.println("  no es un aspecto transversal");
        }

        Retention r = anotacion.getAnnotation(Retention.class);
        Target    d = anotacion.getAnnotation(Target.class);
        System.out.println("  retención: " + (r == null ? "CLASS (por defecto)" : r.value()));
        System.out.println("  destinos:  " + (d == null ? "cualquiera" : Arrays.toString(d.value())));
    }
}

Políticas de reintento en ClienteMetadatos
MÉTODO                 INTENTOS ESPERA_1ª FACTOR  ESPERA_MÁX  EXCEPCIONES
------------------------------------------------------------------------------------------------
consultarPorIsbn       5        100       2,0     1500        SocketTimeoutException, ConnectException
descargarPortada       2        1000      3,0     1000        IOException
    aviso: exige idempotencia; verifica que el método lo sea
publicarValoracion     1        200       2,0     0           Exception

Meta-anotaciones de @Reintentable:
  @Transversal(orden=20) Reintentos con espera creciente
  retención: RUNTIME
  destinos:  [METHOD]
Meta-anotaciones de @Auditable:
  @Transversal(orden=10) Auditoría de operaciones
  retención: RUNTIME
  destinos:  [METHOD, TYPE]