https://api.nexussoftware.com:8443/v1/llibres/cercar?isbn=978-0000000001&format=json#resum
 \___/   \____________________/\__/\_________________/\____________________________/\_____/
   |               |            |          |                      |                    |
esquema          host         port        cami                consulta             fragment

import java.net.URL;

URL url = new URL("https://api.nexussoftware.com:8443/v1/llibres/cercar"
        + "?isbn=978-0000000001&format=json#resum");

System.out.println("Protocol  : " + url.getProtocol());   // https
System.out.println("Host      : " + url.getHost());       // api.nexussoftware.com
System.out.println("Port      : " + url.getPort());       // 8443
System.out.println("Per defecte: " + url.getDefaultPort()); // 443
System.out.println("Cami      : " + url.getPath());       // /v1/llibres/cercar
System.out.println("Consulta  : " + url.getQuery());      // isbn=978-...&format=json
System.out.println("Fragment  : " + url.getRef());        // resum
System.out.println("Fitxer    : " + url.getFile());       // cami + ? + consulta

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

// Aquesta comparacio FA UNA CONSULTA DNS i pot trigar segons.
// I retorna true si tots dos noms resolen a la mateixa adreca.
boolean iguals = a.equals(b);

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

// 1. Construir i manipular amb URI: validacio estricta, sense DNS.
URI uri = new URI("https", "api.nexussoftware.com", "/v1/llibres/cercar",
                  "isbn=978-0000000001", null);
//                 esquema  host          cami        consulta        fragment

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

// 2. Convertir a URL nomes per connectar.
URL url = uri.toURL();

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

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

Cercar el titol "Java Eficaç":

  MALAMENT:  /cercar?titol=Java Eficaç
        -> L'espai trenca la peticio HTTP (el servidor creu que el cami
           acaba en "Java" i que "Eficaç" es la versio del protocol).
        -> La ç, sense codificar, arriba com a bytes que el servidor pot
           interpretar en una altra codificacio.

  BE: /cercar?titol=Java+Efica%C3%A7
        -> L'espai es +, i la ç son els seus dos bytes UTF-8: C3 A7.

  Cercar autor = "Bloch & Gamma"

  MALAMENT:  /cercar?autor=Bloch & Gamma&admin=true
        -> El servidor veu DOS parametres: autor="Bloch " i " Gamma"
        -> I si l'atacant escriu "&admin=true", injecta un parametre.

  BE: /cercar?autor=Bloch+%26+Gamma

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

String titol = "Java Eficaç";
String codificat = URLEncoder.encode(titol, StandardCharsets.UTF_8);
System.out.println(codificat);      // Java+Efica%C3%A7

String tornada = URLDecoder.decode(codificat, StandardCharsets.UTF_8);
System.out.println(tornada);        // Java Eficaç

// MALAMENT: al cami, el + no significa espai.
String cami = "/llibres/" + URLEncoder.encode("Java Eficac", UTF_8);
// -> /llibres/Java+Eficac   (el servidor cercara un llibre amb un + al titol)

// BE: deixar que URI codifiqui el cami correctament.
URI uri = new URI("https", "api.nexussoftware.com",
                  "/llibres/Java Eficac", null, null);
// -> https://api.nexussoftware.com/llibres/Java%20Eficac

package com.nexussoftware.bibliotech.xarxa;

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

/**
 * Constructor de cadenes de consulta amb codificacio correcta.
 * LinkedHashMap perque l'ordre sigui predictible (util en depurar i en cachejar).
 */
public class ConsultaUrl {

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

    public ConsultaUrl amb(String clau, String valor) {
        if (valor != null) {
            parametres.put(clau, valor);
        }
        return this;    // encadenable
    }

    public ConsultaUrl amb(String clau, int valor) {
        parametres.put(clau, String.valueOf(valor));
        return this;
    }

    /** Retorna "a=1&b=2" amb tot codificat, o "" si no hi ha parametres. */
    public String construir() {
        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> e : parametres.entrySet()) {
            if (sb.length() > 0) {
                sb.append('&');
            }
            // Es codifiquen TANT la clau COM el valor: una clau amb
            // caracters estranys trenca la peticio 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()
        .amb("titol", "Java Eficaç")
        .amb("autor", "Bloch & Gamma")
        .amb("max", 10)
        .construir();
// titol=Java+Efica%C3%A7&autor=Bloch+%26+Gamma&max=10

GET /v1/llibres/978-0000000001 HTTP/1.1\r\n    <- linia de peticio
Host: api.nexussoftware.com\r\n                 <- capcaleres
Accept: application/json\r\n
User-Agent: BiblioTech/1.0\r\n
Connection: close\r\n
\r\n                                            <- LINIA BUIDA: fi de capcaleres
                                                <- (aqui aniria el cos, si n'hi hagues)

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                             <- linia d'estat
Content-Type: application/json; charset=utf-8\r\n  <- capcaleres
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                                            <- linia buida
{"isbn":"978-0000000001","titol":"Java Eficac","autor":"Bloch","pagines":416}

nc -l 8080

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

GET /v1/llibres/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","titol":"Java Eficac"}

* Connected to localhost (127.0.0.1) port 8080
> GET /v1/llibres/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","titol":"Java Eficac"}

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/llibres/978-0000000001").toURL();

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

package com.nexussoftware.bibliotech.xarxa;

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;

/** Peticio HTTP GET amb HttpURLConnection, feta correctament. */
public class ExempleGet {

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

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

        // 1. openConnection() NO connecta: retorna un objecte de configuracio.
        HttpURLConnection connexio = (HttpURLConnection) url.openConnection();

        try {
            // 2. Configuracio. TOT aixo ha d'anar ABANS de getResponseCode().
            connexio.setRequestMethod("GET");
            connexio.setRequestProperty("Accept", "application/json");
            connexio.setRequestProperty("User-Agent", "BiblioTech/1.0");
            connexio.setRequestProperty("Accept-Charset", "UTF-8");

            // MAI sense temps limit. Tots dos, i son diferents (09-02).
            connexio.setConnectTimeout(5_000);      // establir la connexio
            connexio.setReadTimeout(10_000);        // esperar dades

            // 3. AQUI es connecta de veritat i es llegeix la resposta.
            int codi = connexio.getResponseCode();
            String missatge = connexio.getResponseMessage();
            System.out.println("Estat: " + codi + " " + missatge);

            // 4. Capcaleres de resposta.
            System.out.println("Content-Type  : " + connexio.getContentType());
            System.out.println("Content-Length: " + connexio.getContentLengthLong());

            for (Map.Entry<String, List<String>> e : connexio.getHeaderFields().entrySet()) {
                // COMPTE: la clau null conte la LINIA D'ESTAT.
                // Es una raresa de l'API que sorpren la primera vegada.
                String nom = e.getKey() == null ? "(linia d'estat)" : e.getKey();
                System.out.println("  " + nom + ": " + e.getValue());
            }

            // 5. El cos: getInputStream si ha anat be, getErrorStream si no.
            //    AQUESTA distincio es l'error classic numero dos.
            InputStream cos = (codi >= 200 && codi < 400)
                    ? connexio.getInputStream()
                    : connexio.getErrorStream();

            if (cos == null) {
                System.out.println("(sense cos)");
                return;
            }

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

        } finally {
            // 6. disconnect() allibera la connexio (o la torna al pool intern).
            connexio.disconnect();
        }
    }

    /**
     * Extreu el charset del Content-Type. Suposar UTF-8 funciona
     * gairebe sempre i falla justament quan pitjor va.
     */
    static Charset charsetDe(String contentType) {
        if (contentType != null) {
            for (String part : contentType.split(";")) {
                String p = part.strip();
                if (p.toLowerCase().startsWith("charset=")) {
                    String nom = p.substring("charset=".length())
                            .replace("\"", "").strip();
                    try {
                        return Charset.forName(nom);
                    } catch (Exception e) {
                        LOG.warning("Charset desconegut: " + nom + "; es fa servir UTF-8");
                    }
                }
            }
        }
        return StandardCharsets.UTF_8;      // reserva raonable
    }
}

connexio.setConnectTimeout(5_000);      // establir la connexio TCP
connexio.setReadTimeout(10_000);        // esperar dades, per operacio

// CODI TRENCAT.
int codi = connexio.getResponseCode();
InputStream entrada = connexio.getInputStream();   // <-- LLANCA amb un 404

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

{"error":"isbn_invalid","missatge":"L'ISBN ha de tenir 13 digits","camp":"isbn"}

int codi = connexio.getResponseCode();

InputStream cos = (codi >= 200 && codi < 400)
        ? connexio.getInputStream()
        : connexio.getErrorStream();

/**
 * Llegeix el cos de la resposta, vingui pel flux normal o pel d'error.
 * Retorna cadena buida si no hi ha cos.
 */
static String llegirCos(HttpURLConnection connexio, int codi) throws IOException {
    InputStream entrada = (codi >= 200 && codi < 400)
            ? connexio.getInputStream()
            : connexio.getErrorStream();

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

    Charset charset = charsetDe(connexio.getContentType());
    // readAllBytes es comode pero SENSE LIMIT: una resposta gegant
    // esgota la memoria. S'acota, com a 09-03.
    try (InputStream flux = entrada) {
        byte[] bytes = flux.readNBytes(MAXIM_COS);
        if (bytes.length == MAXIM_COS) {
            LOG.warning("Resposta truncada a " + MAXIM_COS + " bytes");
        }
        return new String(bytes, charset);
    }
}

package com.nexussoftware.bibliotech.xarxa;

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 amb cos JSON fent servir HttpURLConnection. */
public class ExemplePost {

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

        try {
            connexio.setRequestMethod("POST");

            // setDoOutput(true) es el que habilita getOutputStream().
            // COMPTE: a mes canvia el metode per defecte a POST, aixi que
            // si fas setDoOutput(true) despres d'un setRequestMethod("GET"),
            // la peticio surt com a POST. Parany classic d'aquesta API.
            connexio.setDoOutput(true);

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

            // El cos, construit a ma. Escapar les cometes i les
            // barres es imprescindible; fer-ho BE requereix una llibreria
            // de JSON, i aixo es 11-07.
            String json = "{\"isbn\":\"978-0000000001\",\"empleat\":\"Marta Ruiz\"}";
            byte[] cos = json.getBytes(StandardCharsets.UTF_8);

            // Content-Length en BYTES, no en caracters: amb accents
            // no coincideixen, i un valor equivocat corromp la peticio.
            connexio.setFixedLengthStreamingMode(cos.length);

            try (OutputStream sortida = connexio.getOutputStream()) {
                sortida.write(cos);
                sortida.flush();    // el buidatge de sempre
            }

            int codi = connexio.getResponseCode();
            System.out.println("Estat: " + codi);
            System.out.println("Cos: " + llegirCos(connexio, codi));

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

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

// Aqui SI que es correcte fer servir URLEncoder: es exactament el seu format.
String cos = new ConsultaUrl()
        .amb("isbn", "978-0000000001")
        .amb("empleat", "Marta Ruiz")
        .construir();
// isbn=978-0000000001&empleat=Marta+Ruiz

// Global, per a tota la JVM. Evita-ho: afecta codi que no es teu.
HttpURLConnection.setFollowRedirects(false);

// Per instancia. Aquest es el que has de fer servir.
connexio.setInstanceFollowRedirects(false);

/** Segueix redireccions a ma, amb limit i control d'esquema. */
static HttpURLConnection seguirRedireccions(URL url, int maximSalts)
        throws IOException {
    URL actual = url;
    for (int salt = 0; salt <= maximSalts; salt++) {
        HttpURLConnection connexio = (HttpURLConnection) actual.openConnection();
        connexio.setInstanceFollowRedirects(false);     // les gestionem nosaltres
        connexio.setConnectTimeout(5_000);
        connexio.setReadTimeout(10_000);

        int codi = connexio.getResponseCode();
        if (codi < 300 || codi >= 400) {
            return connexio;        // no es redireccio: hi hem arribat
        }

        String desti = connexio.getHeaderField("Location");
        connexio.disconnect();

        if (desti == null) {
            throw new IOException("Redireccio " + codi + " sense capcalera Location");
        }
        // resolve() gestiona les Location relatives ("/nou/cami"),
        // que son perfectament legals i sorprenen si no s'esperen.
        actual = actual.toURI().resolve(desti).toURL();
        LOG.info("Redireccio " + codi + " -> " + actual);
    }
    throw new IOException("Massa redireccions (mes de " + maximSalts + ")");
}

// Si poses aixo A MA, HAS de descomprimir tu.
connexio.setRequestProperty("Accept-Encoding", "gzip");

int codi = connexio.getResponseCode();
InputStream entrada = connexio.getInputStream();

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

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

// ... igual que sempre ...

// Metodes addicionals, si necessites inspeccionar el certificat:
System.out.println("Xifratge   : " + connexio.getCipherSuite());
System.out.println("Certificat : " + connexio.getServerCertificates()[0]);

GET /v1/llibres/{isbn}
  200 -> {"isbn":"...","titol":"...","autor":"...","pagines":416,
          "portada":"https://metadades.nexussoftware.local/portades/978-0000000001.jpg"}
  404 -> {"error":"no_trobat","missatge":"ISBN desconegut"}
  429 -> capcalera Retry-After amb els segons d'espera

GET /portades/{isbn}.jpg
  200 -> imatge JPEG binaria

package com.nexussoftware.bibliotech.xarxa;

import com.nexussoftware.bibliotech.excepcio.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;

/**
 * Client del servei extern de metadades de Nexus Software,
 * amb HttpURLConnection.
 *
 * Mostra l'us correcte de l'API antiga: temps limit, comprovacio
 * explicita del codi d'estat, getErrorStream per als errors, lectura
 * acotada i traduccio a excepcions de domini.
 */
public class ClientMetadades {

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

    private static final int LIMIT_CONNEXIO_MS = 5_000;
    private static final int LIMIT_LECTURA_MS = 10_000;
    /** Cap fitxa de metadades legitima no passa d'aixo. Defensa de memoria. */
    private static final int MAXIM_COS = 256 * 1024;
    /** Cap portada legitima no passa d'aixo. */
    private static final long MAXIMA_PORTADA = 5L * 1024 * 1024;
    private static final String AGENT = "BiblioTech/1.0 (+https://nexussoftware.com)";

    private final String base;

    public ClientMetadades(String base) {
        // Es normalitza per poder concatenar camins sense duplicar barres.
        this.base = base.endsWith("/") ? base.substring(0, base.length() - 1) : base;
    }

    /** Metadades d'un llibre tal com les retorna el servei. */
    public record Metadades(String isbn, String titol, String autor,
                            int pagines, String urlPortada) {
    }

    // =================================================================
    // Consulta de metadades
    // =================================================================

    /** Consulta un ISBN. Retorna null si el servei no el coneix (404). */
    public Metadades consultar(String isbn) throws BiblioTechException {
        validarIsbn(isbn);

        HttpURLConnection connexio = null;
        try {
            // L'ISBN va al CAMI, aixi que es codifica amb el constructor
            // multiargument d'URI, no amb URLEncoder (que posaria + per espai).
            URI uri = new URI("http", null, hostDe(base), portDe(base),
                    camiDe(base) + "/v1/llibres/" + isbn, null, null);
            URL url = uri.toURL();

            connexio = (HttpURLConnection) url.openConnection();
            connexio.setRequestMethod("GET");
            connexio.setRequestProperty("Accept", "application/json");
            connexio.setRequestProperty("User-Agent", AGENT);
            connexio.setConnectTimeout(LIMIT_CONNEXIO_MS);
            connexio.setReadTimeout(LIMIT_LECTURA_MS);
            connexio.setInstanceFollowRedirects(true);

            // AQUI es connecta de veritat.
            int codi = connexio.getResponseCode();
            LOG.fine(() -> "GET " + url + " -> " + codi);

            // 404 no es un error del programa: es "no el tinc".
            if (codi == HttpURLConnection.HTTP_NOT_FOUND) {
                consumirITancar(connexio, codi);
                return null;
            }

            // 429: el servei ens demana que baixem el ritme.
            if (codi == 429) {
                String espera = connexio.getHeaderField("Retry-After");
                consumirITancar(connexio, codi);
                throw new BiblioTechException(
                        "El servei de metadades ha limitat les peticions."
                        + (espera == null ? "" : " Reintentar d'aqui a " + espera + " s."));
            }

            if (codi != HttpURLConnection.HTTP_OK) {
                // El cos de l'error gairebe sempre explica que ha passat:
                // llegir-lo es la diferencia entre depurar en dos minuts
                // o en dues hores.
                String detall = llegirCos(connexio, codi);
                LOG.warning("Resposta " + codi + " del servei: " + retallar(detall));
                throw new BiblioTechException(
                        "El servei de metadades ha respost " + codi);
            }

            String cos = llegirCos(connexio, codi);
            return analitzar(cos, isbn);

        } catch (SocketTimeoutException e) {
            // TRANSITORI: mereix reintent amb espera creixent.
            LOG.warning("Temps esgotat consultant metadades de " + isbn);
            throw new BiblioTechException(
                    "El servei de metadades no respon a temps.", e);

        } catch (UnknownHostException e) {
            // PERMANENT: configuracio mal posada.
            LOG.severe("Host de metadades no resoluble: " + base);
            throw new BiblioTechException(
                    "No es troba el servei de metadades.", e);

        } catch (IOException | java.net.URISyntaxException e) {
            LOG.log(Level.WARNING, "Fallada consultant metadades de " + isbn, e);
            throw new BiblioTechException(
                    "Error consultant el servei de metadades.", e);

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

    // =================================================================
    // Descarrega de la portada (binari a disc)
    // =================================================================

    /**
     * Descarrega la portada a un fitxer. Combina HTTP amb NIO.2 del modul 7.
     * Escriptura ATOMICA: primer a un temporal, despres es mou. Aixi una
     * descarrega interrompuda no deixa un JPEG a mitges al cataleg.
     */
    public Path descarregarPortada(String urlPortada, Path desti)
            throws BiblioTechException {

        HttpURLConnection connexio = null;
        Path temporal = null;

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

            // Nomes http i https: sense aixo, una URL "file:///etc/passwd"
            // rebuda del servei ens faria llegir fitxers locals.
            String esquema = url.getProtocol();
            if (!esquema.equals("http") && !esquema.equals("https")) {
                throw new BiblioTechException("Esquema no permes: " + esquema);
            }

            connexio = (HttpURLConnection) url.openConnection();
            connexio.setRequestMethod("GET");
            connexio.setRequestProperty("Accept", "image/jpeg, image/png, image/*");
            connexio.setRequestProperty("User-Agent", AGENT);
            connexio.setConnectTimeout(LIMIT_CONNEXIO_MS);
            connexio.setReadTimeout(30_000);        // una imatge triga mes

            int codi = connexio.getResponseCode();
            if (codi != HttpURLConnection.HTTP_OK) {
                consumirITancar(connexio, codi);
                throw new BiblioTechException(
                        "No s'ha pogut descarregar la portada: HTTP " + codi);
            }

            // Content-Length es ORIENTATIU: pot faltar (-1) o mentir.
            // Es comprova abans I durant la descarrega.
            long anunciat = connexio.getContentLengthLong();
            if (anunciat > MAXIMA_PORTADA) {
                consumirITancar(connexio, codi);
                throw new BiblioTechException(
                        "Portada massa gran: " + anunciat + " bytes");
            }

            String tipus = connexio.getContentType();
            if (tipus != null && !tipus.startsWith("image/")) {
                consumirITancar(connexio, codi);
                throw new BiblioTechException("El recurs no es una imatge: " + tipus);
            }

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

            long descarregats = 0;
            try (InputStream entrada = connexio.getInputStream();
                 OutputStream sortida = Files.newOutputStream(temporal)) {

                byte[] bufer = new byte[8192];
                int llegits;
                while ((llegits = entrada.read(bufer)) != -1) {
                    descarregats += llegits;
                    // El limit es comprova TAMBE durant la descarrega:
                    // el Content-Length pot mentir o no venir.
                    if (descarregats > MAXIMA_PORTADA) {
                        throw new BiblioTechException(
                                "La portada supera el limit durant la descarrega");
                    }
                    // write(bufer, 0, llegits): mai bufer.length (modul 7).
                    sortida.write(bufer, 0, llegits);
                }
            }

            // Moviment atomic: el fitxer final apareix complet o no apareix.
            Files.move(temporal, desti,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            temporal = null;    // ja no cal netejar-lo

            long total = descarregats;
            LOG.info(() -> "Portada descarregada: " + desti + " (" + total + " bytes)");
            return desti;

        } catch (SocketTimeoutException e) {
            throw new BiblioTechException("Temps esgotat descarregant la portada.", e);

        } catch (IOException e) {
            LOG.log(Level.WARNING, "Fallada descarregant " + urlPortada, e);
            throw new BiblioTechException("No s'ha pogut descarregar la portada.", e);

        } finally {
            if (connexio != null) {
                connexio.disconnect();
            }
            // Neteja del temporal si alguna cosa ha fallat a mitges.
            if (temporal != null) {
                try {
                    Files.deleteIfExists(temporal);
                } catch (IOException e) {
                    LOG.fine("No s'ha pogut esborrar el temporal: " + temporal);
                }
            }
        }
    }

    // =================================================================
    // Utilitats
    // =================================================================

    private String llegirCos(HttpURLConnection connexio, int codi) throws IOException {
        // La distincio que tothom oblida: amb 4xx/5xx cal
        // fer servir getErrorStream, perque getInputStream LLANCA.
        InputStream entrada = (codi >= 200 && codi < 400)
                ? connexio.getInputStream()
                : connexio.getErrorStream();

        if (entrada == null) {
            return "";
        }
        Charset charset = charsetDe(connexio.getContentType());
        try (InputStream flux = entrada) {
            // readNBytes acotat, no readAllBytes: una resposta enorme
            // no pot esgotar la nostra memoria.
            byte[] bytes = flux.readNBytes(MAXIM_COS);
            if (bytes.length == MAXIM_COS) {
                LOG.warning("Resposta truncada a " + MAXIM_COS + " bytes");
            }
            return new String(bytes, charset);
        }
    }

    /**
     * Consumeix i tanca el cos encara que no ens interessi.
     * Sense aixo, la connexio no torna al pool intern i es perd
     * la reutilitzacio, que en HTTP val un viatge de xarxa complet.
     */
    private void consumirITancar(HttpURLConnection connexio, int codi) {
        try {
            InputStream entrada = (codi >= 200 && codi < 400)
                    ? connexio.getInputStream()
                    : connexio.getErrorStream();
            if (entrada != null) {
                try (InputStream flux = entrada) {
                    flux.readNBytes(MAXIM_COS);
                }
            }
        } catch (IOException e) {
            LOG.fine("Fallada consumint el cos: " + e.getMessage());
        }
    }

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

    /**
     * Extraccio de camps de JSON PER CERCA DE SUBCADENA.
     *
     * AIXO ES UN APEDACAMENT DIDACTIC, i cal dir-ho clarament.
     * Funciona amb la resposta concreta i senzilla d'aquest servei, i es
     * trenca amb: valors que continguin la subcadena cercada, escapades (\"),
     * imbricacio, arrays, espais diferents, camps en un altre ordre o
     * valors null. Analitzar JSON de veritat requereix una llibreria, i
     * aixo es fa amb JACKSON A 11-07. No portis aixo a produccio.
     */
    private Metadades analitzar(String json, String isbnDemanat)
            throws BiblioTechException {
        try {
            String titol = campText(json, "titol");
            String autor = campText(json, "autor");
            String portada = campText(json, "portada");
            int pagines = campEnter(json, "pagines");

            if (titol == null) {
                throw new BiblioTechException(
                        "Resposta del servei sense el camp 'titol'");
            }
            return new Metadades(isbnDemanat, titol,
                    autor == null ? "(desconegut)" : autor,
                    pagines, portada);

        } catch (RuntimeException e) {
            throw new BiblioTechException(
                    "No s'ha pogut interpretar la resposta del servei", e);
        }
    }

    /** Cerca "camp":"valor" i retorna el valor. Apedacament, veure el comentari. */
    private String campText(String json, String camp) {
        String marca = "\"" + camp + "\"";
        int i = json.indexOf(marca);
        if (i < 0) {
            return null;
        }
        int dosPunts = json.indexOf(':', i + marca.length());
        if (dosPunts < 0) {
            return null;
        }
        int obre = json.indexOf('"', dosPunts);
        if (obre < 0) {
            return null;
        }
        int tanca = json.indexOf('"', obre + 1);
        if (tanca < 0) {
            return null;
        }
        return json.substring(obre + 1, tanca);
    }

    /** Cerca "camp":123 i retorna el numero, o 0 si no el troba. */
    private int campEnter(String json, String camp) {
        String marca = "\"" + camp + "\"";
        int i = json.indexOf(marca);
        if (i < 0) {
            return 0;
        }
        int dosPunts = json.indexOf(':', i + marca.length());
        if (dosPunts < 0) {
            return 0;
        }
        int j = dosPunts + 1;
        while (j < json.length() && !Character.isDigit(json.charAt(j))) {
            if (json.charAt(j) == ',' || json.charAt(j) == '}') {
                return 0;
            }
            j++;
        }
        int inici = j;
        while (j < json.length() && Character.isDigit(json.charAt(j))) {
            j++;
        }
        return inici == j ? 0 : Integer.parseInt(json.substring(inici, j));
    }

    private void validarIsbn(String isbn) throws BiblioTechException {
        if (isbn == null || isbn.isBlank() || isbn.length() > 20) {
            throw new BiblioTechException("ISBN no valid");
        }
        // Llista blanca: nomes digits i guions. Impedeix injectar camins
        // ("../admin") o parametres ("?x=1") a la URL.
        for (int i = 0; i < isbn.length(); i++) {
            char c = isbn.charAt(i);
            if (!Character.isDigit(c) && c != '-') {
                throw new BiblioTechException("ISBN amb caracters no permesos");
            }
        }
    }

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

    // Descomposicio senzilla de la URL base per al constructor d'URI.
    private String hostDe(String base) throws java.net.URISyntaxException {
        return new URI(base).getHost();
    }

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

    private String camiDe(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: 146\r\nConnection: close\r\n\r\n{"isbn":"978-0000000001","titol":"Java Eficac","autor":"Joshua Bloch","pagines":416,"portada":"http://localhost:8080/portades/978-0000000001.jpg"}' | nc -l 8080

package com.nexussoftware.bibliotech.presentacio;

import com.nexussoftware.bibliotech.excepcio.BiblioTechException;
import com.nexussoftware.bibliotech.xarxa.ClientMetadades;
import com.nexussoftware.bibliotech.xarxa.ClientMetadades.Metadades;

import java.nio.file.Path;

public class ProvaMetadades {

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

        try {
            Metadades m = client.consultar("978-0000000001");
            if (m == null) {
                System.out.println("El servei no coneix aquest ISBN");
                return;
            }
            System.out.println("Titol   : " + m.titol());
            System.out.println("Autor   : " + m.autor());
            System.out.println("Pagines : " + m.pagines());
            System.out.println("Portada : " + m.urlPortada());

            if (m.urlPortada() != null) {
                Path desti = Path.of("portades", m.isbn() + ".jpg");
                client.descarregarPortada(m.urlPortada(), desti);
                System.out.println("Desada a " + desti.toAbsolutePath());
            }

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

Titol   : Java Eficac
Autor   : Joshua Bloch
Pagines : 416
Portada : http://localhost:8080/portades/978-0000000001.jpg

package com.nexussoftware.bibliotech.xarxa;

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 complet d'una URL, a l'estil de curl -v.
 * Eina de diagnostic de l'equip de sistemes de Nexus Software.
 */
public class InspectorHttp {

    private static final int MAXIM_SALTS = 5;
    private static final int LIMIT_CONNEXIO_MS = 5_000;
    private static final int LIMIT_LECTURA_MS = 10_000;
    private static final int MAXIM_COS = 1024 * 1024;

    /** Un salt de la cadena de redireccions. */
    private record Salt(String url, int codi, String missatge, String desti) {
    }

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

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

        mostrarParts(url);

        List<Salt> cadena = new ArrayList<>();
        URL actual = url;
        HttpURLConnection connexio = null;

        try {
            // --- Seguir la cadena de redireccions a ma ---
            for (int salt = 0; salt <= MAXIM_SALTS; salt++) {
                connexio = obrir(actual, "HEAD");

                long t0 = System.nanoTime();
                int codi = connexio.getResponseCode();
                long msConnexio = (System.nanoTime() - t0) / 1_000_000;

                // Molts servidors no admeten HEAD i retornen 405.
                // Es reintenta amb GET, que sempre esta suportat.
                if (codi == HttpURLConnection.HTTP_BAD_METHOD) {
                    System.out.println("\n(HEAD ha retornat 405; es reintenta amb GET)");
                    connexio.disconnect();
                    connexio = obrir(actual, "GET");
                    t0 = System.nanoTime();
                    codi = connexio.getResponseCode();
                    msConnexio = (System.nanoTime() - t0) / 1_000_000;
                }

                String desti = connexio.getHeaderField("Location");
                cadena.add(new Salt(actual.toString(), codi,
                        connexio.getResponseMessage(), desti));

                if (codi < 300 || codi >= 400 || desti == null) {
                    mostrarResposta(connexio, codi, msConnexio);
                    break;
                }

                // Location pot ser relativa: resolve() ho gestiona.
                actual = actual.toURI().resolve(desti).toURL();
                connexio.disconnect();
                connexio = null;
            }

            mostrarCadena(cadena);

        } catch (UnknownHostException e) {
            System.out.println("\nNO RESOL el host: " + e.getMessage());
        } catch (ConnectException e) {
            System.out.println("\nCONNEXIO REBUTJADA: no hi ha servidor en aquest port");
        } catch (SocketTimeoutException e) {
            System.out.println("\nTEMPS ESGOTAT: el servidor no respon");
        } catch (Exception e) {
            System.out.println("\nFALLADA: " + e);
        } finally {
            if (connexio != null) {
                connexio.disconnect();
            }
        }
    }

    private HttpURLConnection obrir(URL url, String metode) throws IOException {
        HttpURLConnection c = (HttpURLConnection) url.openConnection();
        c.setRequestMethod(metode);
        c.setRequestProperty("User-Agent", "BiblioTech-Inspector/1.0");
        c.setRequestProperty("Accept", "*/*");
        c.setConnectTimeout(LIMIT_CONNEXIO_MS);
        c.setReadTimeout(LIMIT_LECTURA_MS);
        // Les gestionem nosaltres, per poder mostrar-les.
        c.setInstanceFollowRedirects(false);
        return c;
    }

    private void mostrarParts(URL url) {
        // getPort() retorna -1 si no ve explicit: cal combinar-lo
        // amb getDefaultPort() per saber el port efectiu.
        int port = url.getPort() != -1 ? url.getPort() : url.getDefaultPort();

        System.out.println("\n--- PARTS 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", "Port", port,
                url.getPort() == -1 ? "  (per defecte de l'esquema)" : "  (explicit)");
        System.out.printf("  %-16s %s%n", "Cami",
                url.getPath().isEmpty() ? "/" : url.getPath());
        System.out.printf("  %-16s %s%n", "Consulta",
                url.getQuery() == null ? "(cap)" : url.getQuery());
        System.out.printf("  %-16s %s%n", "Fragment",
                url.getRef() == null ? "(cap)"
                        : url.getRef() + "  <- NO s'envia al servidor");
    }

    private void mostrarResposta(HttpURLConnection c, int codi, long ms)
            throws IOException {
        System.out.println("\n--- RESPOSTA ---");
        System.out.printf("  %-16s %d %s   (%s)%n", "Estat", codi,
                c.getResponseMessage(), familia(codi));
        System.out.printf("  %-16s %d ms%n", "Temps", ms);

        System.out.println("\n--- CAPCALERES ---");
        // TreeMap per ordre alfabetic. La clau null porta la linia d'estat.
        Map<String, List<String>> capcaleres = new TreeMap<>((a, b) -> {
            if (a == null) return -1;
            if (b == null) return 1;
            return a.compareToIgnoreCase(b);
        });
        capcaleres.putAll(c.getHeaderFields());

        for (Map.Entry<String, List<String>> e : capcaleres.entrySet()) {
            String nom = e.getKey() == null ? "(linia d'estat)" : e.getKey();
            for (String valor : e.getValue()) {
                System.out.printf("  %-24s %s%n", nom + ":", valor);
            }
        }

        System.out.println("\n--- CONTINGUT ---");
        System.out.printf("  %-16s %s%n", "Tipus",
                c.getContentType() == null ? "(no indicat)" : c.getContentType());
        System.out.printf("  %-16s %s%n", "Charset",
                ClientMetadades.charsetDe(c.getContentType()));
        long longitud = c.getContentLengthLong();
        System.out.printf("  %-16s %s%n", "Longitud",
                longitud < 0 ? "(no indicada: chunked o tancament)" : longitud + " bytes");
        System.out.printf("  %-16s %s%n", "Compressio",
                c.getContentEncoding() == null ? "(cap)" : c.getContentEncoding());

        // Amb HEAD no hi ha cos, pero amb el GET de reserva si.
        if ("GET".equals(c.getRequestMethod())) {
            InputStream entrada = (codi >= 200 && codi < 400)
                    ? c.getInputStream() : c.getErrorStream();
            if (entrada != null) {
                try (InputStream flux = entrada) {
                    byte[] bytes = flux.readNBytes(MAXIM_COS);
                    System.out.printf("  %-16s %d bytes llegits%n",
                            "Cos real", bytes.length);
                    String text = new String(bytes,
                            ClientMetadades.charsetDe(c.getContentType()));
                    System.out.println("\n--- PRIMERES LINIES DEL COS ---");
                    String[] linies = text.split("\n", 6);
                    for (int i = 0; i < Math.min(5, linies.length); i++) {
                        // Retallem: mai bolcar sense limit dades de la xarxa.
                        String l = linies[i];
                        System.out.println("  " + (l.length() > 100
                                ? l.substring(0, 100) + "..." : l));
                    }
                }
            }
        }
    }

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

    private String familia(int codi) {
        return switch (codi / 100) {
            case 1 -> "informatiu";
            case 2 -> "EXIT";
            case 3 -> "redireccio";
            case 4 -> "ERROR DEL CLIENT";
            case 5 -> "ERROR DEL SERVIDOR";
            default -> "desconegut";
        };
    }

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

==============================================================================
INSPECCIO DE: http://localhost:8080/v1/llibres/978-0000000001?format=json#resum
==============================================================================

--- PARTS DE LA URL ---
  Esquema          http
  Host             localhost
  Port             8080  (explicit)
  Cami             /v1/llibres/978-0000000001
  Consulta         format=json
  Fragment         resum  <- NO s'envia al servidor

--- RESPOSTA ---
  Estat            200 OK   (EXIT)
  Temps            4 ms

--- CAPCALERES ---
  (linia d'estat):         HTTP/1.1 200 OK
  Content-Length:          49
  Content-Type:            application/json; charset=utf-8

--- CONTINGUT ---
  Tipus            application/json; charset=utf-8
  Charset          UTF-8
  Longitud         49 bytes
  Compressio       (cap)

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

package com.nexussoftware.bibliotech.xarxa;

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;

/**
 * Client HTTP amb politica de reintents correcta.
 *
 * La regla que ho governa tot: es reintenta el TRANSITORI
 * (temps esgotats, 429, 5xx d'infraestructura) i mai el
 * PERMANENT (4xx, host inexistent).
 */
public class ClientHttpResistent {

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

    private static final int MAXIM_INTENTS = 4;
    private static final int ESPERA_INICIAL_MS = 200;
    private static final int MAXIM_RETRY_AFTER_S = 30;
    private static final int MAXIM_COS = 1024 * 1024;
    private static final int LIMIT_CONNEXIO_MS = 5_000;
    private static final int LIMIT_LECTURA_MS = 10_000;

    public record Resposta(int codi, String cos,
                           Map<String, List<String>> capcaleres, int intents) {

        public boolean exit() {
            return codi >= 200 && codi < 300;
        }
    }

    // =================================================================
    // GET: idempotent, es reintenta
    // =================================================================

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

    // =================================================================
    // POST: NO idempotent, NO es reintenta per defecte
    // =================================================================

    /**
     * POST sense reintents.
     *
     * PER QUE ES DIFERENT: si un POST esgota el temps d'espera, NO SABEM
     * si el servidor l'ha processat. Pot ser que la peticio arribes, s'executes
     * i nomes es perdes la resposta. Reintentar duplicaria l'operacio:
     * dos prestecs, dos carrecs, dues comandes.
     *
     * La solucio professional es la CLAU D'IDEMPOTENCIA: el client genera
     * un identificador unic per operacio, l'envia en una capcalera
     * (Idempotency-Key) i el servidor rebutja la segona peticio amb la
     * mateixa clau. Amb aixo, reintentar SI que es segur. Sense aixo, no.
     */
    public Resposta post(String url, String cos, String contentType)
            throws IOException {
        return executar(url, "POST", cos, contentType, false);
    }

    /** POST amb reintents: nomes si el servei garanteix idempotencia. */
    public Resposta postIdempotent(String url, String cos, String contentType)
            throws IOException {
        return executar(url, "POST", cos, contentType, true);
    }

    // =================================================================
    // Nucli
    // =================================================================

    private Resposta executar(String urlText, String metode, String cos,
                              String contentType, boolean reintentar)
            throws IOException {

        URL url = URI.create(urlText).toURL();
        int espera = ESPERA_INICIAL_MS;
        IOException ultimaFallada = null;
        int maxim = reintentar ? MAXIM_INTENTS : 1;

        for (int intent = 1; intent <= maxim; intent++) {
            HttpURLConnection connexio = null;
            try {
                connexio = (HttpURLConnection) url.openConnection();
                connexio.setRequestMethod(metode);
                connexio.setRequestProperty("User-Agent", "BiblioTech/1.0");
                connexio.setRequestProperty("Accept", "application/json, */*");
                connexio.setConnectTimeout(LIMIT_CONNEXIO_MS);
                connexio.setReadTimeout(LIMIT_LECTURA_MS);

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

                int codi = connexio.getResponseCode();
                Map<String, List<String>> capcaleres = connexio.getHeaderFields();

                final int n = intent;
                LOG.fine(() -> metode + " " + url + " -> " + codi
                        + " (intent " + n + ")");

                // Codi transitori: mereix reintent si queda marge.
                if (esTransitori(codi) && intent < maxim) {
                    long esperaMs = esperaPerCodi(connexio, codi, espera);
                    consumir(connexio, codi);
                    LOG.warning(metode + " " + url + " -> " + codi
                            + "; reintent " + (intent + 1) + " d'aqui a " + esperaMs + " ms");
                    dormir(esperaMs);
                    espera *= 2;
                    continue;
                }

                String text = llegirCos(connexio, codi);
                return new Resposta(codi, text, capcaleres, intent);

            } catch (UnknownHostException e) {
                // PERMANENT: reintentar no fara que el nom existeixi.
                LOG.severe("Host no resoluble: " + url.getHost());
                throw e;

            } catch (SocketTimeoutException | ConnectException e) {
                // TRANSITORIS: es poden resoldre sols.
                ultimaFallada = e;
                if (intent >= maxim) {
                    break;
                }
                long esperaMs = ambJitter(espera);
                LOG.warning(e.getClass().getSimpleName() + " a " + url
                        + "; reintent " + (intent + 1) + " d'aqui a " + esperaMs + " ms");
                dormir(esperaMs);
                espera *= 2;

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

        throw ultimaFallada != null ? ultimaFallada
                : new IOException("Sense resposta despres de " + maxim + " intents");
    }

    // =================================================================
    // Politica de reintents
    // =================================================================

    private boolean esTransitori(int codi) {
        // 429: ens demanen baixar el ritme. 502/503/504: fallades d'infraestructura.
        // El 500 NO s'hi inclou: sol ser una fallada determinista que es repetira.
        // Els 4xx tampoc: la peticio esta malament i reintentar-la donara el mateix.
        return codi == 429 || codi == 502 || codi == 503 || codi == 504;
    }

    /** Si el servidor diu quant esperar, se li fa cas. */
    private long esperaPerCodi(HttpURLConnection connexio, int codi, int calculada) {
        String retryAfter = connexio.getHeaderField("Retry-After");
        if (retryAfter != null) {
            try {
                // Retry-After admet dos formats: segons, o una data HTTP.
                // Aqui nomes tractem el de segons; el de data requereix
                // analitzar dates, i aixo es fa be a 10-05.
                long segons = Long.parseLong(retryAfter.strip());
                long limitat = Math.min(segons, MAXIM_RETRY_AFTER_S);
                LOG.info("El servidor demana esperar " + segons
                        + " s (apliquem " + limitat + " s)");
                return limitat * 1000;
            } catch (NumberFormatException e) {
                LOG.fine("Retry-After en format de data; s'ignora: " + retryAfter);
            }
        }
        return ambJitter(calculada);
    }

    /**
     * Afegeix una component aleatoria de fins al 20 %.
     *
     * QUIN PROBLEMA EVITA: el "ramat atronador". Si cent clients fallen a la
     * vegada perque el servidor ha caigut, i tots reintenten exactament als
     * 200 ms, les cent peticions tornen a arribar juntes i el tomben una altra
     * vegada, en un cicle que es repeteix indefinidament. Escampar els
     * reintents trenca la sincronitzacio i reparteix la carrega en el temps.
     */
    private long ambJitter(long base) {
        long variacio = (long) (base * 0.2);
        return base + ThreadLocalRandom.current().nextLong(-variacio, variacio + 1);
    }

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

    // =================================================================
    // Utilitats
    // =================================================================

    private String llegirCos(HttpURLConnection connexio, int codi) throws IOException {
        InputStream entrada = (codi >= 200 && codi < 400)
                ? connexio.getInputStream() : connexio.getErrorStream();
        if (entrada == null) {
            return "";
        }
        try (InputStream flux = entrada) {
            byte[] bytes = flux.readNBytes(MAXIM_COS);
            return new String(bytes, ClientMetadades.charsetDe(connexio.getContentType()));
        }
    }

    /** Consumeix el cos perque la connexio torni al pool intern. */
    private void consumir(HttpURLConnection connexio, int codi) {
        try {
            InputStream entrada = (codi >= 200 && codi < 400)
                    ? connexio.getInputStream() : connexio.getErrorStream();
            if (entrada != null) {
                try (InputStream flux = entrada) {
                    flux.readNBytes(MAXIM_COS);
                }
            }
        } catch (IOException e) {
            LOG.fine("Fallada consumint el cos: " + e.getMessage());
        }
    }
}

WARNING: GET http://localhost:8080/v1/llibres -> 503; reintent 2 d'aqui a 2000 ms
INFO: El servidor demana esperar 2 s (apliquem 2 s)
WARNING: GET http://localhost:8080/v1/llibres -> 503; reintent 3 d'aqui a 431 ms
Resposta[codi=200, intents=3]

package com.nexussoftware.bibliotech.xarxa;

import com.nexussoftware.bibliotech.domini.Material;
import com.nexussoftware.bibliotech.excepcio.BiblioTechException;
import com.nexussoftware.bibliotech.servei.CatalegConcurrent;
import com.nexussoftware.bibliotech.xarxa.ClientMetadades.Metadades;

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;

/**
 * Sincronitza les portades del cataleg de BiblioTech amb el servei
 * extern de metadades. Sequencial i respectuos amb el servei.
 */
public class SincronitzadorPortades {

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

    private static final long MAXIMA_PORTADA = 5L * 1024 * 1024;
    private static final int PETICIONS_PER_SEGON = 2;
    private static final int LIMIT_CONNEXIO_MS = 5_000;
    private static final int LIMIT_LECTURA_MS = 30_000;
    private static final String AGENT = "BiblioTech/1.0";

    private final CatalegConcurrent cataleg;
    private final ClientMetadades metadades;
    private final Path directori;

    /** Instant de l'ultim acces a la xarxa, per al limitador de ritme. */
    private long ultimaPeticio = 0;

    private int descarregades = 0;
    private int alDia = 0;
    private int saltades = 0;
    private int fallides = 0;
    private long bytesTotals = 0;

    public SincronitzadorPortades(CatalegConcurrent cataleg,
                                  ClientMetadades metadades, Path directori) {
        this.cataleg = cataleg;
        this.metadades = metadades;
        this.directori = directori;
    }

    public void sincronitzar() throws IOException {
        Files.createDirectories(directori);
        long inici = System.currentTimeMillis();

        List<Material> materials = cataleg.tots();
        System.out.println("Sincronitzant portades de " + materials.size()
                + " materials...\n");

        // SEQUENCIAL a proposit. Fer-ho en PARALLEL -que reduiria el
        // temps total dracticament, perque gairebe tot es espera de xarxa-
        // requereix l'HttpClient asincron amb sendAsync i allOf, i aixo
        // es exactament el que es fa a 09-06.
        for (Material material : materials) {
            processar(material);
        }

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

    private void processar(Material material) {
        String isbn = material.getIsbn();
        Path desti = directori.resolve(isbn + ".jpg");

        try {
            limitarRitme();
            Metadades m = metadades.consultar(isbn);

            if (m == null || m.urlPortada() == null || m.urlPortada().isBlank()) {
                System.out.printf("  %-18s SALTADA (sense portada al servei)%n", isbn);
                saltades++;
                return;
            }

            limitarRitme();
            long bytes = descarregarSiHaCanviat(m.urlPortada(), desti, isbn);

            if (bytes < 0) {
                alDia++;            // 304: ja la teniem actualitzada
            } else if (bytes == 0) {
                saltades++;         // rebutjada per tipus o mida
            } else {
                descarregades++;
                bytesTotals += bytes;
            }

        } catch (BiblioTechException | IOException e) {
            fallides++;
            System.out.printf("  %-18s FALLADA: %s%n", isbn, e.getMessage());
            LOG.log(Level.FINE, "Fallada sincronitzant " + isbn, e);
        }
    }

    /**
     * Descarrega la portada si ha canviat.
     * @return bytes descarregats; -1 si el servidor ha retornat 304; 0 si s'ha rebutjat.
     */
    private long descarregarSiHaCanviat(String urlText, Path desti, String isbn)
            throws IOException, BiblioTechException {

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

        // --- Fase 1: HEAD per comprovar tipus i mida ---
        HttpURLConnection connexioHead = (HttpURLConnection) url.openConnection();
        try {
            connexioHead.setRequestMethod("HEAD");
            connexioHead.setRequestProperty("User-Agent", AGENT);
            connexioHead.setConnectTimeout(LIMIT_CONNEXIO_MS);
            connexioHead.setReadTimeout(LIMIT_LECTURA_MS);

            int codi = connexioHead.getResponseCode();
            if (codi == HttpURLConnection.HTTP_OK) {
                String tipus = connexioHead.getContentType();
                long longitud = connexioHead.getContentLengthLong();

                if (tipus != null && !tipus.startsWith("image/")) {
                    System.out.printf("  %-18s SALTADA (no es imatge: %s)%n", isbn, tipus);
                    return 0;
                }
                if (longitud > MAXIMA_PORTADA) {
                    System.out.printf("  %-18s SALTADA (%d bytes, supera el limit)%n",
                            isbn, longitud);
                    return 0;
                }
            }
            // Un HEAD que falla no impedeix intentar el GET: molts
            // servidors no l'implementen be.
        } finally {
            connexioHead.disconnect();
        }

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

            // DESCARREGA CONDICIONAL: si ja tenim el fitxer, demanem al
            // servidor que nomes ens l'enviï si ha canviat des d'aleshores.
            // Un 304 estalvia la transferencia sencera.
            if (Files.exists(desti)) {
                long modificat = Files.getLastModifiedTime(desti).toMillis();
                connexio.setRequestProperty("If-Modified-Since",
                        dataHttp(new Date(modificat)));
            }

            int codi = connexio.getResponseCode();

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

            // Descarrega a TEMPORAL: una interrupcio no deixa un JPEG a mitges
            // que sembla valid fins que algu intenta obrir-lo.
            temporal = Files.createTempFile(directori, "portada-", ".tmp");
            long descarregats = 0;

            try (InputStream entrada = connexio.getInputStream();
                 OutputStream sortida = Files.newOutputStream(temporal)) {
                byte[] bufer = new byte[8192];
                int llegits;
                while ((llegits = entrada.read(bufer)) != -1) {
                    descarregats += llegits;
                    // El limit es comprova TAMBE aqui: el Content-Length
                    // del HEAD pot faltar o mentir.
                    if (descarregats > MAXIMA_PORTADA) {
                        throw new IOException("La portada supera el limit descarregant");
                    }
                    sortida.write(bufer, 0, llegits);   // mai bufer.length
                }
            }

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

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

        } finally {
            connexio.disconnect();
            if (temporal != null) {
                try {
                    Files.deleteIfExists(temporal);
                } catch (IOException e) {
                    LOG.fine("No s'ha pogut esborrar el temporal " + temporal);
                }
            }
        }
    }

    /**
     * Format de data HTTP (RFC 7231): "Wed, 05 Aug 2026 09:14:22 GMT".
     *
     * Es fa servir SimpleDateFormat perque java.time es 10-05. Dos detalls
     * imprescindibles i que gairebe tothom oblida:
     *   - Locale.US: sense ell, els noms de dia i mes surten en l'idioma
     *     del sistema ("dc", "ago") i el servidor no els enten.
     *   - Zona GMT: el format ho exigeix explicitament.
     * A 10-05 aixo es fa amb DateTimeFormatter.RFC_1123_DATE_TIME,
     * que es immutable i segur per a diversos fils; SimpleDateFormat NO ho es.
     */
    private String dataHttp(Date data) {
        SimpleDateFormat format = new SimpleDateFormat(
                "EEE, dd MMM yyyy HH:mm:ss zzz", Locale.US);
        format.setTimeZone(TimeZone.getTimeZone("GMT"));
        return format.format(data);
    }

    /**
     * Limitador de ritme: no mes de PETICIONS_PER_SEGON al servei.
     * Ser un bon ciutada evita que et bloquegin la IP, i evita
     * provocar els 429 que despres caldria gestionar.
     */
    private void limitarRitme() {
        long interval = 1000 / PETICIONS_PER_SEGON;
        long desDe = System.currentTimeMillis() - ultimaPeticio;
        if (desDe < interval) {
            try {
                Thread.sleep(interval - desDe);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();     // 08-02
            }
        }
        ultimaPeticio = System.currentTimeMillis();
    }

    private void informe(long ms) {
        System.out.println();
        System.out.println("=== SINCRONITZACIO DE PORTADES ===");
        System.out.printf("%-22s %d%n", "Descarregades", descarregades);
        System.out.printf("%-22s %d%n", "Ja al dia (304)", alDia);
        System.out.printf("%-22s %d%n", "Saltades", saltades);
        System.out.printf("%-22s %d%n", "Fallides", fallides);
        System.out.printf("%-22s %.1f KB%n", "Bytes descarregats", bytesTotals / 1024.0);
        System.out.printf("%-22s %.1f s%n", "Temps total", ms / 1000.0);
        System.out.printf("%-22s %s%n", "Directori", directori.toAbsolutePath());
    }
}

Sincronitzant portades de 5 materials...

  978-0000000001     DESCARREGADA (48213 bytes)
  978-0000000002     AL DIA (304, no ha canviat)
  978-0000000003     DESCARREGADA (39104 bytes)
  978-0000000004     SALTADA (sense portada al servei)
  978-0000000005     FALLADA: HTTP 404 descarregant la portada

=== SINCRONITZACIO DE PORTADES ===
Descarregades          2
Ja al dia (304)        1
Saltades               1
Fallides               1
Bytes descarregats     85.3 KB
Temps total            5.4 s