https://api.nexussoftware.com:8443/v1/libros/buscar?isbn=978-0000000001&formato=json#resumen
 \___/   \____________________/\__/\_________________/\____________________________/\______/
   |               |            |          |                      |                     |
esquema          host        puerto      ruta                 consulta              fragmento

import java.net.URL;

URL url = new URL("https://api.nexussoftware.com:8443/v1/libros/buscar"
        + "?isbn=978-0000000001&formato=json#resumen");

System.out.println("Protocolo : " + url.getProtocol());   // https
System.out.println("Host      : " + url.getHost());       // api.nexussoftware.com
System.out.println("Puerto    : " + url.getPort());       // 8443
System.out.println("Por defecto: " + url.getDefaultPort()); // 443
System.out.println("Ruta      : " + url.getPath());       // /v1/libros/buscar
System.out.println("Consulta  : " + url.getQuery());      // isbn=978-...&formato=json
System.out.println("Fragmento : " + url.getRef());        // resumen
System.out.println("Fichero   : " + url.getFile());       // ruta + ? + consulta

URL a = new URL("http://example.com/pagina");
URL b = new URL("http://93.184.216.34/pagina");

// Esta comparacion HACE UNA CONSULTA DNS y puede tardar segundos.
// Y devuelve true si ambos nombres resuelven a la misma direccion.
boolean iguales = a.equals(b);

import java.net.URI;
import java.net.URL;

// 1. Construir y manipular con URI: validacion estricta, sin DNS.
URI uri = new URI("https", "api.nexussoftware.com", "/v1/libros/buscar",
                  "isbn=978-0000000001", null);
//                 esquema  host          ruta        consulta        fragmento

System.out.println(uri);    // https://api.nexussoftware.com/v1/libros/buscar?isbn=978-0000000001

// 2. Convertir a URL solo para conectar.
URL url = uri.toURL();

URI base = URI.create("https://api.nexussoftware.com/v1/");
URI completa = base.resolve("libros/978-0000000001");
// -> https://api.nexussoftware.com/v1/libros/978-0000000001

URI sucia = URI.create("https://api.nexussoftware.com/v1/../v2/./libros");
System.out.println(sucia.normalize());
// -> https://api.nexussoftware.com/v2/libros

Buscar el titulo "Patrones de Diseño":

  MAL:  /buscar?titulo=Patrones de Diseño
        -> El espacio rompe la peticion HTTP (el servidor cree que la ruta
           termina en "Patrones" y que "de" es la version del protocolo).
        -> La ñ, sin codificar, llega como bytes que el servidor puede
           interpretar en otra codificacion.

  BIEN: /buscar?titulo=Patrones+de+Dise%C3%B1o
        -> El espacio es +, y la ñ son sus dos bytes UTF-8: C3 B1.

  Buscar autor = "Bloch & Gamma"

  MAL:  /buscar?autor=Bloch & Gamma&admin=true
        -> El servidor ve DOS parametros: autor="Bloch " y " Gamma"
        -> Y si el atacante escribe "&admin=true", inyecta un parametro.

  BIEN: /buscar?autor=Bloch+%26+Gamma

import java.net.URLEncoder;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;

String titulo = "Patrones de Diseño";
String codificado = URLEncoder.encode(titulo, StandardCharsets.UTF_8);
System.out.println(codificado);     // Patrones+de+Dise%C3%B1o

String vuelta = URLDecoder.decode(codificado, StandardCharsets.UTF_8);
System.out.println(vuelta);         // Patrones de Diseño

// MAL: en la ruta, el + no significa espacio.
String ruta = "/libros/" + URLEncoder.encode("Java Efectivo", UTF_8);
// -> /libros/Java+Efectivo   (el servidor buscara un libro con un + en el titulo)

// BIEN: dejar que URI codifique la ruta correctamente.
URI uri = new URI("https", "api.nexussoftware.com",
                  "/libros/Java Efectivo", null, null);
// -> https://api.nexussoftware.com/libros/Java%20Efectivo

package com.nexussoftware.bibliotech.red;

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;

/**
 * Constructor de cadenas de consulta con codificacion correcta.
 * LinkedHashMap para que el orden sea predecible (util al depurar y al cachear).
 */
public class ConsultaUrl {

    private final Map<String, String> parametros = new LinkedHashMap<>();

    public ConsultaUrl con(String clave, String valor) {
        if (valor != null) {
            parametros.put(clave, valor);
        }
        return this;    // encadenable
    }

    public ConsultaUrl con(String clave, int valor) {
        parametros.put(clave, String.valueOf(valor));
        return this;
    }

    /** Devuelve "a=1&b=2" con todo codificado, o "" si no hay parametros. */
    public String construir() {
        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> e : parametros.entrySet()) {
            if (sb.length() > 0) {
                sb.append('&');
            }
            // Se codifican TANTO la clave COMO el valor: una clave con
            // caracteres raros rompe la peticion igual que un valor.
            sb.append(URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8));
            sb.append('=');
            sb.append(URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8));
        }
        return sb.toString();
    }
}

String consulta = new ConsultaUrl()
        .con("titulo", "Patrones de Diseño")
        .con("autor", "Bloch & Gamma")
        .con("max", 10)
        .construir();
// titulo=Patrones+de+Dise%C3%B1o&autor=Bloch+%26+Gamma&max=10

GET /v1/libros/978-0000000001 HTTP/1.1\r\n     <- linea de peticion
Host: api.nexussoftware.com\r\n                 <- cabeceras
Accept: application/json\r\n
User-Agent: BiblioTech/1.0\r\n
Connection: close\r\n
\r\n                                            <- LINEA VACIA: fin de cabeceras
                                                <- (aqui iria el cuerpo, si lo hubiera)

printf 'GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n' | nc example.com 80

HTTP/1.1 200 OK\r\n                             <- linea de estado
Content-Type: application/json; charset=utf-8\r\n  <- cabeceras
Content-Length: 87\r\n
Date: Wed, 05 Aug 2026 09:14:22 GMT\r\n
Server: nginx/1.24.0\r\n
\r\n                                            <- linea vacia
{"isbn":"978-0000000001","titulo":"Java Efectivo","autor":"Bloch","paginas":416}

nc -l 8080

curl -v http://localhost:8080/v1/libros/978-0000000001

GET /v1/libros/978-0000000001 HTTP/1.1
Host: localhost:8080
User-Agent: curl/8.5.0
Accept: */*

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 44

{"isbn":"978-0000000001","titulo":"Java Efectivo"}

* Connected to localhost (127.0.0.1) port 8080
> GET /v1/libros/978-0000000001 HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/8.5.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Content-Length: 44
<
{"isbn":"978-0000000001","titulo":"Java Efectivo"}

Content-Type: application/json; charset=utf-8
                                ^^^^^^^^^^^^^

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.URI;
import java.net.URL;
import java.nio.charset.StandardCharsets;

URL url = URI.create("http://localhost:8080/v1/libros/978-0000000001").toURL();

// openStream() = openConnection().getInputStream(), abreviado.
try (BufferedReader lector = new BufferedReader(
        new InputStreamReader(url.openStream(), StandardCharsets.UTF_8))) {
    String linea;
    while ((linea = lector.readLine()) != null) {
        System.out.println(linea);
    }
}

package com.nexussoftware.bibliotech.red;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Map;
import java.util.logging.Logger;

/** Petición HTTP GET con HttpURLConnection, hecha correctamente. */
public class EjemploGet {

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

    public static void main(String[] args) throws IOException {
        URL url = URI.create("http://localhost:8080/v1/libros/978-0000000001").toURL();

        // 1. openConnection() NO conecta: devuelve un objeto de configuracion.
        HttpURLConnection conexion = (HttpURLConnection) url.openConnection();

        try {
            // 2. Configuracion. TODO esto debe ir ANTES de getResponseCode().
            conexion.setRequestMethod("GET");
            conexion.setRequestProperty("Accept", "application/json");
            conexion.setRequestProperty("User-Agent", "BiblioTech/1.0");
            conexion.setRequestProperty("Accept-Charset", "UTF-8");

            // NUNCA sin tiempos limite. Los dos, y son distintos (09-02).
            conexion.setConnectTimeout(5_000);      // establecer la conexion
            conexion.setReadTimeout(10_000);        // esperar datos

            // 3. AQUI se conecta de verdad y se lee la respuesta.
            int codigo = conexion.getResponseCode();
            String mensaje = conexion.getResponseMessage();
            System.out.println("Estado: " + codigo + " " + mensaje);

            // 4. Cabeceras de respuesta.
            System.out.println("Content-Type  : " + conexion.getContentType());
            System.out.println("Content-Length: " + conexion.getContentLengthLong());

            for (Map.Entry<String, List<String>> e : conexion.getHeaderFields().entrySet()) {
                // OJO: la clave null contiene la LINEA DE ESTADO.
                // Es una rareza de la API que sorprende la primera vez.
                String nombre = e.getKey() == null ? "(linea de estado)" : e.getKey();
                System.out.println("  " + nombre + ": " + e.getValue());
            }

            // 5. El cuerpo: getInputStream si fue bien, getErrorStream si no.
            //    ESTA distincion es el error clasico numero dos.
            InputStream cuerpo = (codigo >= 200 && codigo < 400)
                    ? conexion.getInputStream()
                    : conexion.getErrorStream();

            if (cuerpo == null) {
                System.out.println("(sin cuerpo)");
                return;
            }

            Charset charset = charsetDe(conexion.getContentType());
            try (BufferedReader lector = new BufferedReader(
                    new InputStreamReader(cuerpo, charset))) {
                String linea;
                while ((linea = lector.readLine()) != null) {
                    System.out.println(linea);
                }
            }

        } finally {
            // 6. disconnect() libera la conexion (o la devuelve al pool interno).
            conexion.disconnect();
        }
    }

    /**
     * Extrae el charset del Content-Type. Suponer UTF-8 funciona
     * casi siempre y falla justo cuando peor viene.
     */
    static Charset charsetDe(String contentType) {
        if (contentType != null) {
            for (String parte : contentType.split(";")) {
                String p = parte.strip();
                if (p.toLowerCase().startsWith("charset=")) {
                    String nombre = p.substring("charset=".length())
                            .replace("\"", "").strip();
                    try {
                        return Charset.forName(nombre);
                    } catch (Exception e) {
                        LOG.warning("Charset desconocido: " + nombre + "; se usa UTF-8");
                    }
                }
            }
        }
        return StandardCharsets.UTF_8;      // respaldo razonable
    }
}

conexion.setConnectTimeout(5_000);      // establecer la conexion TCP
conexion.setReadTimeout(10_000);        // esperar datos, por operacion

// CODIGO ROTO.
int codigo = conexion.getResponseCode();
InputStream entrada = conexion.getInputStream();   // <-- LANZA con un 404

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"isbn_invalido","mensaje":"El ISBN debe tener 13 digitos","campo":"isbn"}

int codigo = conexion.getResponseCode();

InputStream cuerpo = (codigo >= 200 && codigo < 400)
        ? conexion.getInputStream()
        : conexion.getErrorStream();

/**
 * Lee el cuerpo de la respuesta, venga por el flujo normal o por el de error.
 * Devuelve cadena vacia si no hay cuerpo.
 */
static String leerCuerpo(HttpURLConnection conexion, int codigo) throws IOException {
    InputStream entrada = (codigo >= 200 && codigo < 400)
            ? conexion.getInputStream()
            : conexion.getErrorStream();

    if (entrada == null) {
        return "";
    }

    Charset charset = charsetDe(conexion.getContentType());
    // readAllBytes es comodo pero SIN LIMITE: una respuesta gigante
    // agota la memoria. Se acota, como en 09-03.
    try (InputStream flujo = entrada) {
        byte[] bytes = flujo.readNBytes(MAXIMO_CUERPO);
        if (bytes.length == MAXIMO_CUERPO) {
            LOG.warning("Respuesta truncada a " + MAXIMO_CUERPO + " bytes");
        }
        return new String(bytes, charset);
    }
}

package com.nexussoftware.bibliotech.red;

import java.io.IOException;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
import java.nio.charset.StandardCharsets;

/** POST con cuerpo JSON usando HttpURLConnection. */
public class EjemploPost {

    public static void main(String[] args) throws IOException {
        URL url = URI.create("http://localhost:8080/v1/prestamos").toURL();
        HttpURLConnection conexion = (HttpURLConnection) url.openConnection();

        try {
            conexion.setRequestMethod("POST");

            // setDoOutput(true) es lo que habilita getOutputStream().
            // OJO: ademas cambia el metodo por defecto a POST, asi que
            // si haces setDoOutput(true) tras un setRequestMethod("GET"),
            // la peticion sale como POST. Trampa clasica de esta API.
            conexion.setDoOutput(true);

            conexion.setRequestProperty("Content-Type", "application/json; charset=utf-8");
            conexion.setRequestProperty("Accept", "application/json");
            conexion.setRequestProperty("User-Agent", "BiblioTech/1.0");
            conexion.setConnectTimeout(5_000);
            conexion.setReadTimeout(10_000);

            // El cuerpo, construido a mano. Escapar las comillas y las
            // barras es imprescindible; hacerlo BIEN requiere una libreria
            // de JSON, y eso es 11-07.
            String json = "{\"isbn\":\"978-0000000001\",\"empleado\":\"Marta Ruiz\"}";
            byte[] cuerpo = json.getBytes(StandardCharsets.UTF_8);

            // Content-Length en BYTES, no en caracteres: con acentos
            // no coinciden, y un valor equivocado corrompe la peticion.
            conexion.setFixedLengthStreamingMode(cuerpo.length);

            try (OutputStream salida = conexion.getOutputStream()) {
                salida.write(cuerpo);
                salida.flush();     // el flush de siempre
            }

            int codigo = conexion.getResponseCode();
            System.out.println("Estado: " + codigo);
            System.out.println("Cuerpo: " + leerCuerpo(conexion, codigo));

        } finally {
            conexion.disconnect();
        }
    }
}

conexion.setRequestProperty("Content-Type",
        "application/x-www-form-urlencoded; charset=utf-8");

// Aqui SI es correcto usar URLEncoder: es exactamente su formato.
String cuerpo = new ConsultaUrl()
        .con("isbn", "978-0000000001")
        .con("empleado", "Marta Ruiz")
        .construir();
// isbn=978-0000000001&empleado=Marta+Ruiz

// Global, para toda la JVM. Evítalo: afecta a código que no es tuyo.
HttpURLConnection.setFollowRedirects(false);

// Por instancia. Este es el que debes usar.
conexion.setInstanceFollowRedirects(false);

/** Sigue redirecciones a mano, con limite y control de esquema. */
static HttpURLConnection seguirRedirecciones(URL url, int maximoSaltos)
        throws IOException {
    URL actual = url;
    for (int salto = 0; salto <= maximoSaltos; salto++) {
        HttpURLConnection conexion = (HttpURLConnection) actual.openConnection();
        conexion.setInstanceFollowRedirects(false);     // las gestionamos nosotros
        conexion.setConnectTimeout(5_000);
        conexion.setReadTimeout(10_000);

        int codigo = conexion.getResponseCode();
        if (codigo < 300 || codigo >= 400) {
            return conexion;        // no es redireccion: hemos llegado
        }

        String destino = conexion.getHeaderField("Location");
        conexion.disconnect();

        if (destino == null) {
            throw new IOException("Redireccion " + codigo + " sin cabecera Location");
        }
        // resolve() maneja las Location relativas ("/nueva/ruta"),
        // que son perfectamente legales y sorprenden si no se esperan.
        actual = actual.toURI().resolve(destino).toURL();
        LOG.info("Redireccion " + codigo + " -> " + actual);
    }
    throw new IOException("Demasiadas redirecciones (mas de " + maximoSaltos + ")");
}

// Si pones esto A MANO, TIENES que descomprimir tu.
conexion.setRequestProperty("Accept-Encoding", "gzip");

int codigo = conexion.getResponseCode();
InputStream entrada = conexion.getInputStream();

if ("gzip".equalsIgnoreCase(conexion.getContentEncoding())) {
    entrada = new GZIPInputStream(entrada);     // decorador del modulo 7
}

URL url = URI.create("https://api.nexussoftware.com/v1/libros").toURL();
HttpsURLConnection conexion = (HttpsURLConnection) url.openConnection();

// ... igual que siempre ...

// Metodos adicionales, si necesitas inspeccionar el certificado:
System.out.println("Cifrado    : " + conexion.getCipherSuite());
System.out.println("Certificado: " + conexion.getServerCertificates()[0]);

GET /v1/libros/{isbn}
  200 -> {"isbn":"...","titulo":"...","autor":"...","paginas":416,
          "portada":"https://metadatos.nexussoftware.local/portadas/978-0000000001.jpg"}
  404 -> {"error":"no_encontrado","mensaje":"ISBN desconocido"}
  429 -> cabecera Retry-After con los segundos de espera

GET /portadas/{isbn}.jpg
  200 -> imagen JPEG binaria

package com.nexussoftware.bibliotech.red;

import com.nexussoftware.bibliotech.excepcion.BiblioTechException;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.SocketTimeoutException;
import java.net.URI;
import java.net.URL;
import java.net.UnknownHostException;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Cliente del servicio externo de metadatos de Nexus Software,
 * con HttpURLConnection.
 *
 * Muestra el uso correcto de la API antigua: tiempos limite, comprobacion
 * explicita del codigo de estado, getErrorStream para los errores, lectura
 * acotada y traduccion a excepciones de dominio.
 */
public class ClienteMetadatos {

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

    private static final int LIMITE_CONEXION_MS = 5_000;
    private static final int LIMITE_LECTURA_MS = 10_000;
    /** Ninguna ficha de metadatos legitima pasa de esto. Defensa de memoria. */
    private static final int MAXIMO_CUERPO = 256 * 1024;
    /** Ninguna portada legitima pasa de esto. */
    private static final long MAXIMO_PORTADA = 5L * 1024 * 1024;
    private static final String AGENTE = "BiblioTech/1.0 (+https://nexussoftware.com)";

    private final String base;

    public ClienteMetadatos(String base) {
        // Se normaliza para poder concatenar rutas sin duplicar barras.
        this.base = base.endsWith("/") ? base.substring(0, base.length() - 1) : base;
    }

    /** Metadatos de un libro tal como los devuelve el servicio. */
    public record Metadatos(String isbn, String titulo, String autor,
                            int paginas, String urlPortada) {
    }

    // =================================================================
    // Consulta de metadatos
    // =================================================================

    /** Consulta un ISBN. Devuelve null si el servicio no lo conoce (404). */
    public Metadatos consultar(String isbn) throws BiblioTechException {
        validarIsbn(isbn);

        HttpURLConnection conexion = null;
        try {
            // El ISBN va en la RUTA, asi que se codifica con el constructor
            // multiargumento de URI, no con URLEncoder (que pondria + por espacio).
            URI uri = new URI("http", null, hostDe(base), puertoDe(base),
                    rutaDe(base) + "/v1/libros/" + isbn, null, null);
            URL url = uri.toURL();

            conexion = (HttpURLConnection) url.openConnection();
            conexion.setRequestMethod("GET");
            conexion.setRequestProperty("Accept", "application/json");
            conexion.setRequestProperty("User-Agent", AGENTE);
            conexion.setConnectTimeout(LIMITE_CONEXION_MS);
            conexion.setReadTimeout(LIMITE_LECTURA_MS);
            conexion.setInstanceFollowRedirects(true);

            // AQUI se conecta de verdad.
            int codigo = conexion.getResponseCode();
            LOG.fine(() -> "GET " + url + " -> " + codigo);

            // 404 no es un error del programa: es "no lo tengo".
            if (codigo == HttpURLConnection.HTTP_NOT_FOUND) {
                consumirYCerrar(conexion, codigo);
                return null;
            }

            // 429: el servicio nos pide que bajemos el ritmo.
            if (codigo == 429) {
                String espera = conexion.getHeaderField("Retry-After");
                consumirYCerrar(conexion, codigo);
                throw new BiblioTechException(
                        "El servicio de metadatos ha limitado las peticiones."
                        + (espera == null ? "" : " Reintentar en " + espera + " s."));
            }

            if (codigo != HttpURLConnection.HTTP_OK) {
                // El cuerpo del error casi siempre explica que ha pasado:
                // leerlo es la diferencia entre depurar en dos minutos
                // o en dos horas.
                String detalle = leerCuerpo(conexion, codigo);
                LOG.warning("Respuesta " + codigo + " del servicio: " + recortar(detalle));
                throw new BiblioTechException(
                        "El servicio de metadatos respondio " + codigo);
            }

            String cuerpo = leerCuerpo(conexion, codigo);
            return analizar(cuerpo, isbn);

        } catch (SocketTimeoutException e) {
            // TRANSITORIO: merece reintento con espera creciente.
            LOG.warning("Tiempo agotado consultando metadatos de " + isbn);
            throw new BiblioTechException(
                    "El servicio de metadatos no responde a tiempo.", e);

        } catch (UnknownHostException e) {
            // PERMANENTE: configuracion mal puesta.
            LOG.severe("Host de metadatos no resoluble: " + base);
            throw new BiblioTechException(
                    "No se encuentra el servicio de metadatos.", e);

        } catch (IOException | java.net.URISyntaxException e) {
            LOG.log(Level.WARNING, "Fallo consultando metadatos de " + isbn, e);
            throw new BiblioTechException(
                    "Error consultando el servicio de metadatos.", e);

        } finally {
            if (conexion != null) {
                conexion.disconnect();
            }
        }
    }

    // =================================================================
    // Descarga de la portada (binario a disco)
    // =================================================================

    /**
     * Descarga la portada a un fichero. Combina HTTP con NIO.2 del modulo 7.
     * Escritura ATOMICA: primero a un temporal, luego se mueve. Asi una
     * descarga interrumpida no deja un JPEG a medias en el catalogo.
     */
    public Path descargarPortada(String urlPortada, Path destino)
            throws BiblioTechException {

        HttpURLConnection conexion = null;
        Path temporal = null;

        try {
            URL url = URI.create(urlPortada).toURL();

            // Solo http y https: sin esto, una URL "file:///etc/passwd"
            // recibida del servicio nos haria leer ficheros locales.
            String esquema = url.getProtocol();
            if (!esquema.equals("http") && !esquema.equals("https")) {
                throw new BiblioTechException("Esquema no permitido: " + esquema);
            }

            conexion = (HttpURLConnection) url.openConnection();
            conexion.setRequestMethod("GET");
            conexion.setRequestProperty("Accept", "image/jpeg, image/png, image/*");
            conexion.setRequestProperty("User-Agent", AGENTE);
            conexion.setConnectTimeout(LIMITE_CONEXION_MS);
            conexion.setReadTimeout(30_000);        // una imagen tarda mas

            int codigo = conexion.getResponseCode();
            if (codigo != HttpURLConnection.HTTP_OK) {
                consumirYCerrar(conexion, codigo);
                throw new BiblioTechException(
                        "No se pudo descargar la portada: HTTP " + codigo);
            }

            // Content-Length es ORIENTATIVO: puede faltar (-1) o mentir.
            // Se comprueba antes Y durante la descarga.
            long anunciado = conexion.getContentLengthLong();
            if (anunciado > MAXIMO_PORTADA) {
                consumirYCerrar(conexion, codigo);
                throw new BiblioTechException(
                        "Portada demasiado grande: " + anunciado + " bytes");
            }

            String tipo = conexion.getContentType();
            if (tipo != null && !tipo.startsWith("image/")) {
                consumirYCerrar(conexion, codigo);
                throw new BiblioTechException("El recurso no es una imagen: " + tipo);
            }

            Files.createDirectories(destino.getParent());
            temporal = Files.createTempFile(destino.getParent(), "portada-", ".tmp");

            long descargados = 0;
            try (InputStream entrada = conexion.getInputStream();
                 OutputStream salida = Files.newOutputStream(temporal)) {

                byte[] bufer = new byte[8192];
                int leidos;
                while ((leidos = entrada.read(bufer)) != -1) {
                    descargados += leidos;
                    // El limite se comprueba TAMBIEN durante la descarga:
                    // el Content-Length puede mentir o no venir.
                    if (descargados > MAXIMO_PORTADA) {
                        throw new BiblioTechException(
                                "La portada supera el limite durante la descarga");
                    }
                    // write(bufer, 0, leidos): nunca bufer.length (modulo 7).
                    salida.write(bufer, 0, leidos);
                }
            }

            // Movimiento atomico: el fichero final aparece completo o no aparece.
            Files.move(temporal, destino,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            temporal = null;    // ya no hay que limpiarlo

            long total = descargados;
            LOG.info(() -> "Portada descargada: " + destino + " (" + total + " bytes)");
            return destino;

        } catch (SocketTimeoutException e) {
            throw new BiblioTechException("Tiempo agotado descargando la portada.", e);

        } catch (IOException e) {
            LOG.log(Level.WARNING, "Fallo descargando " + urlPortada, e);
            throw new BiblioTechException("No se pudo descargar la portada.", e);

        } finally {
            if (conexion != null) {
                conexion.disconnect();
            }
            // Limpieza del temporal si algo fallo a mitad.
            if (temporal != null) {
                try {
                    Files.deleteIfExists(temporal);
                } catch (IOException e) {
                    LOG.fine("No se pudo borrar el temporal: " + temporal);
                }
            }
        }
    }

    // =================================================================
    // Utilidades
    // =================================================================

    private String leerCuerpo(HttpURLConnection conexion, int codigo) throws IOException {
        // La distincion que todo el mundo olvida: con 4xx/5xx hay que
        // usar getErrorStream, porque getInputStream LANZA.
        InputStream entrada = (codigo >= 200 && codigo < 400)
                ? conexion.getInputStream()
                : conexion.getErrorStream();

        if (entrada == null) {
            return "";
        }
        Charset charset = charsetDe(conexion.getContentType());
        try (InputStream flujo = entrada) {
            // readNBytes acotado, no readAllBytes: una respuesta enorme
            // no puede agotar nuestra memoria.
            byte[] bytes = flujo.readNBytes(MAXIMO_CUERPO);
            if (bytes.length == MAXIMO_CUERPO) {
                LOG.warning("Respuesta truncada a " + MAXIMO_CUERPO + " bytes");
            }
            return new String(bytes, charset);
        }
    }

    /**
     * Consume y cierra el cuerpo aunque no nos interese.
     * Sin esto, la conexion no vuelve al pool interno y se pierde
     * la reutilizacion, que en HTTP vale un viaje de red completo.
     */
    private void consumirYCerrar(HttpURLConnection conexion, int codigo) {
        try {
            InputStream entrada = (codigo >= 200 && codigo < 400)
                    ? conexion.getInputStream()
                    : conexion.getErrorStream();
            if (entrada != null) {
                try (InputStream flujo = entrada) {
                    flujo.readNBytes(MAXIMO_CUERPO);
                }
            }
        } catch (IOException e) {
            LOG.fine("Fallo consumiendo el cuerpo: " + e.getMessage());
        }
    }

    static Charset charsetDe(String contentType) {
        if (contentType != null) {
            for (String parte : contentType.split(";")) {
                String p = parte.strip();
                if (p.toLowerCase().startsWith("charset=")) {
                    String nombre = p.substring(8).replace("\"", "").strip();
                    try {
                        return Charset.forName(nombre);
                    } catch (Exception e) {
                        LOG.warning("Charset desconocido: " + nombre);
                    }
                }
            }
        }
        return StandardCharsets.UTF_8;
    }

    /**
     * Extraccion de campos de JSON POR BUSQUEDA DE SUBCADENA.
     *
     * ESTO ES UN APAÑO DIDACTICO, y hay que decirlo claramente.
     * Funciona con la respuesta concreta y sencilla de este servicio, y se
     * rompe con: valores que contengan la subcadena buscada, escapes (\"),
     * anidamiento, arrays, espacios distintos, campos en otro orden o
     * valores null. Analizar JSON de verdad requiere una libreria, y
     * eso se hace con JACKSON EN 11-07. No lleves esto a produccion.
     */
    private Metadatos analizar(String json, String isbnPedido)
            throws BiblioTechException {
        try {
            String titulo = campoTexto(json, "titulo");
            String autor = campoTexto(json, "autor");
            String portada = campoTexto(json, "portada");
            int paginas = campoEntero(json, "paginas");

            if (titulo == null) {
                throw new BiblioTechException(
                        "Respuesta del servicio sin el campo 'titulo'");
            }
            return new Metadatos(isbnPedido, titulo,
                    autor == null ? "(desconocido)" : autor,
                    paginas, portada);

        } catch (RuntimeException e) {
            throw new BiblioTechException(
                    "No se pudo interpretar la respuesta del servicio", e);
        }
    }

    /** Busca "campo":"valor" y devuelve el valor. Apaño, ver el comentario. */
    private String campoTexto(String json, String campo) {
        String marca = "\"" + campo + "\"";
        int i = json.indexOf(marca);
        if (i < 0) {
            return null;
        }
        int dosPuntos = json.indexOf(':', i + marca.length());
        if (dosPuntos < 0) {
            return null;
        }
        int abre = json.indexOf('"', dosPuntos);
        if (abre < 0) {
            return null;
        }
        int cierra = json.indexOf('"', abre + 1);
        if (cierra < 0) {
            return null;
        }
        return json.substring(abre + 1, cierra);
    }

    /** Busca "campo":123 y devuelve el numero, o 0 si no lo encuentra. */
    private int campoEntero(String json, String campo) {
        String marca = "\"" + campo + "\"";
        int i = json.indexOf(marca);
        if (i < 0) {
            return 0;
        }
        int dosPuntos = json.indexOf(':', i + marca.length());
        if (dosPuntos < 0) {
            return 0;
        }
        int j = dosPuntos + 1;
        while (j < json.length() && !Character.isDigit(json.charAt(j))) {
            if (json.charAt(j) == ',' || json.charAt(j) == '}') {
                return 0;
            }
            j++;
        }
        int inicio = j;
        while (j < json.length() && Character.isDigit(json.charAt(j))) {
            j++;
        }
        return inicio == j ? 0 : Integer.parseInt(json.substring(inicio, j));
    }

    private void validarIsbn(String isbn) throws BiblioTechException {
        if (isbn == null || isbn.isBlank() || isbn.length() > 20) {
            throw new BiblioTechException("ISBN no valido");
        }
        // Lista blanca: solo digitos y guiones. Impide inyectar rutas
        // ("../admin") o parametros ("?x=1") en la URL.
        for (int i = 0; i < isbn.length(); i++) {
            char c = isbn.charAt(i);
            if (!Character.isDigit(c) && c != '-') {
                throw new BiblioTechException("ISBN con caracteres no permitidos");
            }
        }
    }

    private String recortar(String texto) {
        return texto.length() > 200 ? texto.substring(0, 200) + "..." : texto;
    }

    // Descomposicion sencilla de la URL base para el constructor de URI.
    private String hostDe(String base) throws java.net.URISyntaxException {
        return new URI(base).getHost();
    }

    private int puertoDe(String base) throws java.net.URISyntaxException {
        return new URI(base).getPort();
    }

    private String rutaDe(String base) throws java.net.URISyntaxException {
        String p = new URI(base).getPath();
        return p == null ? "" : p;
    }
}

printf 'HTTP/1.1 200 OK\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: 160\r\nConnection: close\r\n\r\n{"isbn":"978-0000000001","titulo":"Java Efectivo","autor":"Joshua Bloch","paginas":416,"portada":"http://localhost:8080/portadas/978-0000000001.jpg"}' | nc -l 8080

package com.nexussoftware.bibliotech.presentacion;

import com.nexussoftware.bibliotech.excepcion.BiblioTechException;
import com.nexussoftware.bibliotech.red.ClienteMetadatos;
import com.nexussoftware.bibliotech.red.ClienteMetadatos.Metadatos;

import java.nio.file.Path;

public class PruebaMetadatos {

    public static void main(String[] args) {
        ClienteMetadatos cliente = new ClienteMetadatos("http://localhost:8080");

        try {
            Metadatos m = cliente.consultar("978-0000000001");
            if (m == null) {
                System.out.println("El servicio no conoce ese ISBN");
                return;
            }
            System.out.println("Titulo  : " + m.titulo());
            System.out.println("Autor   : " + m.autor());
            System.out.println("Paginas : " + m.paginas());
            System.out.println("Portada : " + m.urlPortada());

            if (m.urlPortada() != null) {
                Path destino = Path.of("portadas", m.isbn() + ".jpg");
                cliente.descargarPortada(m.urlPortada(), destino);
                System.out.println("Guardada en " + destino.toAbsolutePath());
            }

        } catch (BiblioTechException e) {
            System.err.println("ERROR: " + e.getMessage());
            if (e.getCause() != null) {
                System.err.println("Causa: " + e.getCause());
            }
        }
    }
}

Titulo  : Java Efectivo
Autor   : Joshua Bloch
Paginas : 416
Portada : http://localhost:8080/portadas/978-0000000001.jpg

package com.nexussoftware.bibliotech.red;

import java.io.IOException;
import java.io.InputStream;
import java.net.ConnectException;
import java.net.HttpURLConnection;
import java.net.SocketTimeoutException;
import java.net.URI;
import java.net.URL;
import java.net.UnknownHostException;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;

/**
 * Inspector HTTP: informe completo de una URL, al estilo de curl -v.
 * Herramienta de diagnostico del equipo de sistemas de Nexus Software.
 */
public class InspectorHttp {

    private static final int MAXIMO_SALTOS = 5;
    private static final int LIMITE_CONEXION_MS = 5_000;
    private static final int LIMITE_LECTURA_MS = 10_000;
    private static final int MAXIMO_CUERPO = 1024 * 1024;

    /** Un salto de la cadena de redirecciones. */
    private record Salto(String url, int codigo, String mensaje, String destino) {
    }

    public void inspeccionar(String urlTexto) {
        System.out.println("=".repeat(78));
        System.out.println("INSPECCION DE: " + urlTexto);
        System.out.println("=".repeat(78));

        URL url;
        try {
            // URI valida la sintaxis estrictamente; URL no.
            url = URI.create(urlTexto).toURL();
        } catch (Exception e) {
            System.out.println("URL invalida: " + e.getMessage());
            return;
        }

        mostrarPartes(url);

        List<Salto> cadena = new ArrayList<>();
        URL actual = url;
        HttpURLConnection conexion = null;

        try {
            // --- Seguir la cadena de redirecciones a mano ---
            for (int salto = 0; salto <= MAXIMO_SALTOS; salto++) {
                conexion = abrir(actual, "HEAD");

                long t0 = System.nanoTime();
                int codigo = conexion.getResponseCode();
                long msConexion = (System.nanoTime() - t0) / 1_000_000;

                // Muchos servidores no admiten HEAD y devuelven 405.
                // Se reintenta con GET, que siempre esta soportado.
                if (codigo == HttpURLConnection.HTTP_BAD_METHOD) {
                    System.out.println("\n(HEAD devolvio 405; se reintenta con GET)");
                    conexion.disconnect();
                    conexion = abrir(actual, "GET");
                    t0 = System.nanoTime();
                    codigo = conexion.getResponseCode();
                    msConexion = (System.nanoTime() - t0) / 1_000_000;
                }

                String destino = conexion.getHeaderField("Location");
                cadena.add(new Salto(actual.toString(), codigo,
                        conexion.getResponseMessage(), destino));

                if (codigo < 300 || codigo >= 400 || destino == null) {
                    mostrarRespuesta(conexion, codigo, msConexion);
                    break;
                }

                // Location puede ser relativa: resolve() lo maneja.
                actual = actual.toURI().resolve(destino).toURL();
                conexion.disconnect();
                conexion = null;
            }

            mostrarCadena(cadena);

        } catch (UnknownHostException e) {
            System.out.println("\nNO RESUELVE el host: " + e.getMessage());
        } catch (ConnectException e) {
            System.out.println("\nCONEXION RECHAZADA: no hay servidor en ese puerto");
        } catch (SocketTimeoutException e) {
            System.out.println("\nTIEMPO AGOTADO: el servidor no responde");
        } catch (Exception e) {
            System.out.println("\nFALLO: " + e);
        } finally {
            if (conexion != null) {
                conexion.disconnect();
            }
        }
    }

    private HttpURLConnection abrir(URL url, String metodo) throws IOException {
        HttpURLConnection c = (HttpURLConnection) url.openConnection();
        c.setRequestMethod(metodo);
        c.setRequestProperty("User-Agent", "BiblioTech-Inspector/1.0");
        c.setRequestProperty("Accept", "*/*");
        c.setConnectTimeout(LIMITE_CONEXION_MS);
        c.setReadTimeout(LIMITE_LECTURA_MS);
        // Las gestionamos nosotros, para poder mostrarlas.
        c.setInstanceFollowRedirects(false);
        return c;
    }

    private void mostrarPartes(URL url) {
        // getPort() devuelve -1 si no viene explicito: hay que combinarlo
        // con getDefaultPort() para saber el puerto efectivo.
        int puerto = url.getPort() != -1 ? url.getPort() : url.getDefaultPort();

        System.out.println("\n--- PARTES DE LA URL ---");
        System.out.printf("  %-16s %s%n", "Esquema", url.getProtocol());
        System.out.printf("  %-16s %s%n", "Host", url.getHost());
        System.out.printf("  %-16s %d%s%n", "Puerto", puerto,
                url.getPort() == -1 ? "  (por defecto del esquema)" : "  (explicito)");
        System.out.printf("  %-16s %s%n", "Ruta",
                url.getPath().isEmpty() ? "/" : url.getPath());
        System.out.printf("  %-16s %s%n", "Consulta",
                url.getQuery() == null ? "(ninguna)" : url.getQuery());
        System.out.printf("  %-16s %s%n", "Fragmento",
                url.getRef() == null ? "(ninguno)"
                        : url.getRef() + "  <- NO se envia al servidor");
    }

    private void mostrarRespuesta(HttpURLConnection c, int codigo, long ms)
            throws IOException {
        System.out.println("\n--- RESPUESTA ---");
        System.out.printf("  %-16s %d %s   (%s)%n", "Estado", codigo,
                c.getResponseMessage(), familia(codigo));
        System.out.printf("  %-16s %d ms%n", "Tiempo", ms);

        System.out.println("\n--- CABECERAS ---");
        // TreeMap para orden alfabetico. La clave null lleva la linea de estado.
        Map<String, List<String>> cabeceras = new TreeMap<>((a, b) -> {
            if (a == null) return -1;
            if (b == null) return 1;
            return a.compareToIgnoreCase(b);
        });
        cabeceras.putAll(c.getHeaderFields());

        for (Map.Entry<String, List<String>> e : cabeceras.entrySet()) {
            String nombre = e.getKey() == null ? "(linea de estado)" : e.getKey();
            for (String valor : e.getValue()) {
                System.out.printf("  %-24s %s%n", nombre + ":", valor);
            }
        }

        System.out.println("\n--- CONTENIDO ---");
        System.out.printf("  %-16s %s%n", "Tipo",
                c.getContentType() == null ? "(no indicado)" : c.getContentType());
        System.out.printf("  %-16s %s%n", "Charset",
                ClienteMetadatos.charsetDe(c.getContentType()));
        long longitud = c.getContentLengthLong();
        System.out.printf("  %-16s %s%n", "Longitud",
                longitud < 0 ? "(no indicada: chunked o cierre)" : longitud + " bytes");
        System.out.printf("  %-16s %s%n", "Compresion",
                c.getContentEncoding() == null ? "(ninguna)" : c.getContentEncoding());

        // Con HEAD no hay cuerpo, pero con el GET de respaldo si.
        if ("GET".equals(c.getRequestMethod())) {
            InputStream entrada = (codigo >= 200 && codigo < 400)
                    ? c.getInputStream() : c.getErrorStream();
            if (entrada != null) {
                try (InputStream flujo = entrada) {
                    byte[] bytes = flujo.readNBytes(MAXIMO_CUERPO);
                    System.out.printf("  %-16s %d bytes leidos%n",
                            "Cuerpo real", bytes.length);
                    String texto = new String(bytes,
                            ClienteMetadatos.charsetDe(c.getContentType()));
                    System.out.println("\n--- PRIMERAS LINEAS DEL CUERPO ---");
                    String[] lineas = texto.split("\n", 6);
                    for (int i = 0; i < Math.min(5, lineas.length); i++) {
                        // Recortamos: nunca volcar sin limite datos de la red.
                        String l = lineas[i];
                        System.out.println("  " + (l.length() > 100
                                ? l.substring(0, 100) + "..." : l));
                    }
                }
            }
        }
    }

    private void mostrarCadena(List<Salto> cadena) {
        if (cadena.size() <= 1) {
            return;
        }
        System.out.println("\n--- CADENA DE REDIRECCIONES (" + cadena.size() + ") ---");
        for (int i = 0; i < cadena.size(); i++) {
            Salto s = cadena.get(i);
            System.out.printf("  %d. %d %s%n     %s%n", i + 1, s.codigo(),
                    s.mensaje(), s.url());
            if (s.destino() != null) {
                System.out.println("     -> Location: " + s.destino());
            }
        }
    }

    private String familia(int codigo) {
        return switch (codigo / 100) {
            case 1 -> "informativo";
            case 2 -> "EXITO";
            case 3 -> "redireccion";
            case 4 -> "ERROR DEL CLIENTE";
            case 5 -> "ERROR DEL SERVIDOR";
            default -> "desconocido";
        };
    }

    public static void main(String[] args) {
        InspectorHttp inspector = new InspectorHttp();
        inspector.inspeccionar(args.length > 0 ? args[0]
                : "http://localhost:8080/v1/libros/978-0000000001?formato=json#resumen");
    }
}

==============================================================================
INSPECCION DE: http://localhost:8080/v1/libros/978-0000000001?formato=json#resumen
==============================================================================

--- PARTES DE LA URL ---
  Esquema          http
  Host             localhost
  Puerto           8080  (explicito)
  Ruta             /v1/libros/978-0000000001
  Consulta         formato=json
  Fragmento        resumen  <- NO se envia al servidor

--- RESPUESTA ---
  Estado           200 OK   (EXITO)
  Tiempo           4 ms

--- CABECERAS ---
  (linea de estado):       HTTP/1.1 200 OK
  Content-Length:          49
  Content-Type:            application/json; charset=utf-8

--- CONTENIDO ---
  Tipo             application/json; charset=utf-8
  Charset          UTF-8
  Longitud         49 bytes
  Compresion       (ninguna)

--- CADENA DE REDIRECCIONES (2) ---
  1. 302 Found
     http://localhost:8080/v1/libros/978-0000000001?formato=json
     -> Location: /v2/libros/978-0000000001
  2. 200 OK
     http://localhost:8080/v2/libros/978-0000000001

package com.nexussoftware.bibliotech.red;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.ConnectException;
import java.net.HttpURLConnection;
import java.net.SocketTimeoutException;
import java.net.URI;
import java.net.URL;
import java.net.UnknownHostException;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ThreadLocalRandom;
import java.util.logging.Logger;

/**
 * Cliente HTTP con politica de reintentos correcta.
 *
 * La regla que lo gobierna todo: se reintenta lo TRANSITORIO
 * (tiempos agotados, 429, 5xx de infraestructura) y nunca lo
 * PERMANENTE (4xx, host inexistente).
 */
public class ClienteHttpResistente {

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

    private static final int MAXIMO_INTENTOS = 4;
    private static final int ESPERA_INICIAL_MS = 200;
    private static final int MAXIMO_RETRY_AFTER_S = 30;
    private static final int MAXIMO_CUERPO = 1024 * 1024;
    private static final int LIMITE_CONEXION_MS = 5_000;
    private static final int LIMITE_LECTURA_MS = 10_000;

    public record Respuesta(int codigo, String cuerpo,
                            Map<String, List<String>> cabeceras, int intentos) {

        public boolean exito() {
            return codigo >= 200 && codigo < 300;
        }
    }

    // =================================================================
    // GET: idempotente, se reintenta
    // =================================================================

    public Respuesta get(String url) throws IOException {
        return ejecutar(url, "GET", null, null, true);
    }

    // =================================================================
    // POST: NO idempotente, NO se reintenta por defecto
    // =================================================================

    /**
     * POST sin reintentos.
     *
     * POR QUE ES DISTINTO: si un POST agota el tiempo de espera, NO SABEMOS
     * si el servidor lo proceso. Puede que la peticion llegara, se ejecutara
     * y solo se perdiera la respuesta. Reintentar duplicaria la operacion:
     * dos prestamos, dos cargos, dos pedidos.
     *
     * La solucion profesional es la CLAVE DE IDEMPOTENCIA: el cliente genera
     * un identificador unico por operacion, lo envia en una cabecera
     * (Idempotency-Key) y el servidor rechaza la segunda peticion con la
     * misma clave. Con eso, reintentar SI es seguro. Sin eso, no lo es.
     */
    public Respuesta post(String url, String cuerpo, String contentType)
            throws IOException {
        return ejecutar(url, "POST", cuerpo, contentType, false);
    }

    /** POST con reintentos: solo si el servicio garantiza idempotencia. */
    public Respuesta postIdempotente(String url, String cuerpo, String contentType)
            throws IOException {
        return ejecutar(url, "POST", cuerpo, contentType, true);
    }

    // =================================================================
    // Nucleo
    // =================================================================

    private Respuesta ejecutar(String urlTexto, String metodo, String cuerpo,
                               String contentType, boolean reintentar)
            throws IOException {

        URL url = URI.create(urlTexto).toURL();
        int espera = ESPERA_INICIAL_MS;
        IOException ultimoFallo = null;
        int maximo = reintentar ? MAXIMO_INTENTOS : 1;

        for (int intento = 1; intento <= maximo; intento++) {
            HttpURLConnection conexion = null;
            try {
                conexion = (HttpURLConnection) url.openConnection();
                conexion.setRequestMethod(metodo);
                conexion.setRequestProperty("User-Agent", "BiblioTech/1.0");
                conexion.setRequestProperty("Accept", "application/json, */*");
                conexion.setConnectTimeout(LIMITE_CONEXION_MS);
                conexion.setReadTimeout(LIMITE_LECTURA_MS);

                if (cuerpo != null) {
                    conexion.setDoOutput(true);
                    conexion.setRequestProperty("Content-Type",
                            contentType == null ? "application/json; charset=utf-8"
                                    : contentType);
                    byte[] bytes = cuerpo.getBytes(StandardCharsets.UTF_8);
                    // Longitud en BYTES, no en caracteres.
                    conexion.setFixedLengthStreamingMode(bytes.length);
                    try (OutputStream salida = conexion.getOutputStream()) {
                        salida.write(bytes);
                        salida.flush();
                    }
                }

                int codigo = conexion.getResponseCode();
                Map<String, List<String>> cabeceras = conexion.getHeaderFields();

                final int n = intento;
                LOG.fine(() -> metodo + " " + url + " -> " + codigo
                        + " (intento " + n + ")");

                // Codigo transitorio: merece reintento si queda margen.
                if (esTransitorio(codigo) && intento < maximo) {
                    long esperaMs = esperaTrasCodigo(conexion, codigo, espera);
                    consumir(conexion, codigo);
                    LOG.warning(metodo + " " + url + " -> " + codigo
                            + "; reintento " + (intento + 1) + " en " + esperaMs + " ms");
                    dormir(esperaMs);
                    espera *= 2;
                    continue;
                }

                String texto = leerCuerpo(conexion, codigo);
                return new Respuesta(codigo, texto, cabeceras, intento);

            } catch (UnknownHostException e) {
                // PERMANENTE: reintentar no va a hacer que el nombre exista.
                LOG.severe("Host no resoluble: " + url.getHost());
                throw e;

            } catch (SocketTimeoutException | ConnectException e) {
                // TRANSITORIOS: pueden resolverse solos.
                ultimoFallo = e;
                if (intento >= maximo) {
                    break;
                }
                long esperaMs = conJitter(espera);
                LOG.warning(e.getClass().getSimpleName() + " en " + url
                        + "; reintento " + (intento + 1) + " en " + esperaMs + " ms");
                dormir(esperaMs);
                espera *= 2;

            } finally {
                if (conexion != null) {
                    conexion.disconnect();
                }
            }
        }

        throw ultimoFallo != null ? ultimoFallo
                : new IOException("Sin respuesta tras " + maximo + " intentos");
    }

    // =================================================================
    // Politica de reintentos
    // =================================================================

    private boolean esTransitorio(int codigo) {
        // 429: nos piden bajar el ritmo. 502/503/504: fallos de infraestructura.
        // El 500 NO se incluye: suele ser un fallo determinista que se repetira.
        // Los 4xx tampoco: la peticion esta mal y reintentarla dara lo mismo.
        return codigo == 429 || codigo == 502 || codigo == 503 || codigo == 504;
    }

    /** Si el servidor dice cuanto esperar, se le hace caso. */
    private long esperaTrasCodigo(HttpURLConnection conexion, int codigo, int calculada) {
        String retryAfter = conexion.getHeaderField("Retry-After");
        if (retryAfter != null) {
            try {
                // Retry-After admite dos formatos: segundos, o una fecha HTTP.
                // Aqui solo tratamos el de segundos; el de fecha requiere
                // analizar fechas, y eso se hace bien en 10-05.
                long segundos = Long.parseLong(retryAfter.strip());
                long topeado = Math.min(segundos, MAXIMO_RETRY_AFTER_S);
                LOG.info("El servidor pide esperar " + segundos
                        + " s (aplicamos " + topeado + " s)");
                return topeado * 1000;
            } catch (NumberFormatException e) {
                LOG.fine("Retry-After en formato de fecha; se ignora: " + retryAfter);
            }
        }
        return conJitter(calculada);
    }

    /**
     * Anade una componente aleatoria de hasta el 20 %.
     *
     * QUE PROBLEMA EVITA: el "rebano atronador". Si cien clientes fallan a la
     * vez porque el servidor se cayo, y todos reintentan exactamente a los
     * 200 ms, las cien peticiones vuelven a llegar juntas y lo tumban otra
     * vez, en un ciclo que se repite indefinidamente. Desperdigar los
     * reintentos rompe la sincronizacion y reparte la carga en el tiempo.
     */
    private long conJitter(long base) {
        long variacion = (long) (base * 0.2);
        return base + ThreadLocalRandom.current().nextLong(-variacion, variacion + 1);
    }

    private void dormir(long ms) throws IOException {
        try {
            Thread.sleep(Math.max(0, ms));
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();     // 08-02: restaurar la bandera
            throw new IOException("Reintento interrumpido", e);
        }
    }

    // =================================================================
    // Utilidades
    // =================================================================

    private String leerCuerpo(HttpURLConnection conexion, int codigo) throws IOException {
        InputStream entrada = (codigo >= 200 && codigo < 400)
                ? conexion.getInputStream() : conexion.getErrorStream();
        if (entrada == null) {
            return "";
        }
        try (InputStream flujo = entrada) {
            byte[] bytes = flujo.readNBytes(MAXIMO_CUERPO);
            return new String(bytes, ClienteMetadatos.charsetDe(conexion.getContentType()));
        }
    }

    /** Consume el cuerpo para que la conexion vuelva al pool interno. */
    private void consumir(HttpURLConnection conexion, int codigo) {
        try {
            InputStream entrada = (codigo >= 200 && codigo < 400)
                    ? conexion.getInputStream() : conexion.getErrorStream();
            if (entrada != null) {
                try (InputStream flujo = entrada) {
                    flujo.readNBytes(MAXIMO_CUERPO);
                }
            }
        } catch (IOException e) {
            LOG.fine("Fallo consumiendo el cuerpo: " + e.getMessage());
        }
    }
}

WARNING: GET http://localhost:8080/v1/libros -> 503; reintento 2 en 2000 ms
INFO: El servidor pide esperar 2 s (aplicamos 2 s)
WARNING: GET http://localhost:8080/v1/libros -> 503; reintento 3 en 431 ms
Respuesta[codigo=200, intentos=3]

package com.nexussoftware.bibliotech.red;

import com.nexussoftware.bibliotech.dominio.Material;
import com.nexussoftware.bibliotech.excepcion.BiblioTechException;
import com.nexussoftware.bibliotech.servicio.CatalogoConcurrente;
import com.nexussoftware.bibliotech.red.ClienteMetadatos.Metadatos;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.List;
import java.util.Locale;
import java.util.TimeZone;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Sincroniza las portadas del catalogo de BiblioTech con el servicio
 * externo de metadatos. Secuencial y respetuoso con el servicio.
 */
public class SincronizadorPortadas {

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

    private static final long MAXIMO_PORTADA = 5L * 1024 * 1024;
    private static final int PETICIONES_POR_SEGUNDO = 2;
    private static final int LIMITE_CONEXION_MS = 5_000;
    private static final int LIMITE_LECTURA_MS = 30_000;
    private static final String AGENTE = "BiblioTech/1.0";

    private final CatalogoConcurrente catalogo;
    private final ClienteMetadatos metadatos;
    private final Path directorio;

    /** Instante del ultimo acceso a la red, para el limitador de ritmo. */
    private long ultimaPeticion = 0;

    private int descargadas = 0;
    private int alDia = 0;
    private int saltadas = 0;
    private int fallidas = 0;
    private long bytesTotales = 0;

    public SincronizadorPortadas(CatalogoConcurrente catalogo,
                                 ClienteMetadatos metadatos, Path directorio) {
        this.catalogo = catalogo;
        this.metadatos = metadatos;
        this.directorio = directorio;
    }

    public void sincronizar() throws IOException {
        Files.createDirectories(directorio);
        long inicio = System.currentTimeMillis();

        List<Material> materiales = catalogo.todos();
        System.out.println("Sincronizando portadas de " + materiales.size()
                + " materiales...\n");

        // SECUENCIAL a proposito. Hacerlo en PARALELO -que reduciria el
        // tiempo total drasticamente, porque casi todo es espera de red-
        // requiere el HttpClient asincrono con sendAsync y allOf, y eso
        // es exactamente lo que se hace en 09-06.
        for (Material material : materiales) {
            procesar(material);
        }

        informe(System.currentTimeMillis() - inicio);
    }

    private void procesar(Material material) {
        String isbn = material.getIsbn();
        Path destino = directorio.resolve(isbn + ".jpg");

        try {
            limitarRitmo();
            Metadatos m = metadatos.consultar(isbn);

            if (m == null || m.urlPortada() == null || m.urlPortada().isBlank()) {
                System.out.printf("  %-18s SALTADA (sin portada en el servicio)%n", isbn);
                saltadas++;
                return;
            }

            limitarRitmo();
            long bytes = descargarSiHaCambiado(m.urlPortada(), destino, isbn);

            if (bytes < 0) {
                alDia++;            // 304: ya la teniamos actualizada
            } else if (bytes == 0) {
                saltadas++;         // rechazada por tipo o tamano
            } else {
                descargadas++;
                bytesTotales += bytes;
            }

        } catch (BiblioTechException | IOException e) {
            fallidas++;
            System.out.printf("  %-18s FALLO: %s%n", isbn, e.getMessage());
            LOG.log(Level.FINE, "Fallo sincronizando " + isbn, e);
        }
    }

    /**
     * Descarga la portada si ha cambiado.
     * @return bytes descargados; -1 si el servidor devolvio 304; 0 si se rechazo.
     */
    private long descargarSiHaCambiado(String urlTexto, Path destino, String isbn)
            throws IOException, BiblioTechException {

        URL url = URI.create(urlTexto).toURL();
        if (!url.getProtocol().startsWith("http")) {
            throw new BiblioTechException("Esquema no permitido: " + url.getProtocol());
        }

        // --- Fase 1: HEAD para comprobar tipo y tamano ---
        HttpURLConnection cabeza = (HttpURLConnection) url.openConnection();
        try {
            cabeza.setRequestMethod("HEAD");
            cabeza.setRequestProperty("User-Agent", AGENTE);
            cabeza.setConnectTimeout(LIMITE_CONEXION_MS);
            cabeza.setReadTimeout(LIMITE_LECTURA_MS);

            int codigo = cabeza.getResponseCode();
            if (codigo == HttpURLConnection.HTTP_OK) {
                String tipo = cabeza.getContentType();
                long longitud = cabeza.getContentLengthLong();

                if (tipo != null && !tipo.startsWith("image/")) {
                    System.out.printf("  %-18s SALTADA (no es imagen: %s)%n", isbn, tipo);
                    return 0;
                }
                if (longitud > MAXIMO_PORTADA) {
                    System.out.printf("  %-18s SALTADA (%d bytes, supera el limite)%n",
                            isbn, longitud);
                    return 0;
                }
            }
            // Un HEAD que falla no impide intentar el GET: muchos
            // servidores no lo implementan bien.
        } finally {
            cabeza.disconnect();
        }

        // --- Fase 2: GET condicional ---
        HttpURLConnection conexion = (HttpURLConnection) url.openConnection();
        Path temporal = null;
        try {
            conexion.setRequestMethod("GET");
            conexion.setRequestProperty("User-Agent", AGENTE);
            conexion.setRequestProperty("Accept", "image/jpeg, image/png, image/*");
            conexion.setConnectTimeout(LIMITE_CONEXION_MS);
            conexion.setReadTimeout(LIMITE_LECTURA_MS);

            // DESCARGA CONDICIONAL: si ya tenemos el fichero, pedimos al
            // servidor que solo nos lo mande si ha cambiado desde entonces.
            // Un 304 ahorra la transferencia entera.
            if (Files.exists(destino)) {
                long modificado = Files.getLastModifiedTime(destino).toMillis();
                conexion.setRequestProperty("If-Modified-Since",
                        fechaHttp(new Date(modificado)));
            }

            int codigo = conexion.getResponseCode();

            if (codigo == HttpURLConnection.HTTP_NOT_MODIFIED) {   // 304
                System.out.printf("  %-18s AL DIA (304, no ha cambiado)%n", isbn);
                return -1;
            }
            if (codigo != HttpURLConnection.HTTP_OK) {
                throw new IOException("HTTP " + codigo + " descargando la portada");
            }

            // Descarga a TEMPORAL: una interrupcion no deja un JPEG a medias
            // que parece valido hasta que alguien intenta abrirlo.
            temporal = Files.createTempFile(directorio, "portada-", ".tmp");
            long descargados = 0;

            try (InputStream entrada = conexion.getInputStream();
                 OutputStream salida = Files.newOutputStream(temporal)) {
                byte[] bufer = new byte[8192];
                int leidos;
                while ((leidos = entrada.read(bufer)) != -1) {
                    descargados += leidos;
                    // El limite se comprueba TAMBIEN aqui: el Content-Length
                    // del HEAD puede faltar o mentir.
                    if (descargados > MAXIMO_PORTADA) {
                        throw new IOException("La portada supera el limite descargando");
                    }
                    salida.write(bufer, 0, leidos);     // nunca bufer.length
                }
            }

            Files.move(temporal, destino,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            temporal = null;

            System.out.printf("  %-18s DESCARGADA (%d bytes)%n", isbn, descargados);
            return descargados;

        } finally {
            conexion.disconnect();
            if (temporal != null) {
                try {
                    Files.deleteIfExists(temporal);
                } catch (IOException e) {
                    LOG.fine("No se pudo borrar el temporal " + temporal);
                }
            }
        }
    }

    /**
     * Formato de fecha HTTP (RFC 7231): "Wed, 05 Aug 2026 09:14:22 GMT".
     *
     * Se usa SimpleDateFormat porque java.time es 10-05. Dos detalles
     * imprescindibles y que casi todo el mundo olvida:
     *   - Locale.US: sin el, los nombres de dia y mes salen en el idioma
     *     del sistema ("mié", "ago") y el servidor no los entiende.
     *   - Zona GMT: el formato lo exige explicitamente.
     * En 10-05 esto se hace con DateTimeFormatter.RFC_1123_DATE_TIME,
     * que es inmutable y seguro para varios hilos; SimpleDateFormat NO lo es.
     */
    private String fechaHttp(Date fecha) {
        SimpleDateFormat formato = new SimpleDateFormat(
                "EEE, dd MMM yyyy HH:mm:ss zzz", Locale.US);
        formato.setTimeZone(TimeZone.getTimeZone("GMT"));
        return formato.format(fecha);
    }

    /**
     * Limitador de ritmo: no mas de PETICIONES_POR_SEGUNDO al servicio.
     * Ser un buen ciudadano evita que te bloqueen la IP, y evita
     * provocar los 429 que luego habria que gestionar.
     */
    private void limitarRitmo() {
        long intervalo = 1000 / PETICIONES_POR_SEGUNDO;
        long desde = System.currentTimeMillis() - ultimaPeticion;
        if (desde < intervalo) {
            try {
                Thread.sleep(intervalo - desde);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();      // 08-02
            }
        }
        ultimaPeticion = System.currentTimeMillis();
    }

    private void informe(long ms) {
        System.out.println();
        System.out.println("=== SINCRONIZACION DE PORTADAS ===");
        System.out.printf("%-22s %d%n", "Descargadas", descargadas);
        System.out.printf("%-22s %d%n", "Ya al dia (304)", alDia);
        System.out.printf("%-22s %d%n", "Saltadas", saltadas);
        System.out.printf("%-22s %d%n", "Fallidas", fallidas);
        System.out.printf("%-22s %.1f KB%n", "Bytes descargados", bytesTotales / 1024.0);
        System.out.printf("%-22s %.1f s%n", "Tiempo total", ms / 1000.0);
        System.out.printf("%-22s %s%n", "Directorio", directorio.toAbsolutePath());
    }
}

Sincronizando portadas de 5 materiales...

  978-0000000001     DESCARGADA (48213 bytes)
  978-0000000002     AL DIA (304, no ha cambiado)
  978-0000000003     DESCARGADA (39104 bytes)
  978-0000000004     SALTADA (sin portada en el servicio)
  978-0000000005     FALLO: HTTP 404 descargando la portada

=== SINCRONIZACION DE PORTADAS ===
Descargadas            2
Ya al dia (304)        1
Saltadas               1
Fallidas               1
Bytes descargados      85.3 KB
Tiempo total           5.4 s