HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5))
        .followRedirects(HttpClient.Redirect.NORMAL)
        .build();

HttpRequest peticio = HttpRequest.newBuilder()
        .uri(URI.create("http://localhost:8080/v1/llibres/978-0000000001"))
        .header("Accept", "application/json")
        .timeout(Duration.ofSeconds(10))
        .GET()
        .build();

HttpResponse<String> resposta = client.send(peticio,
        HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));

System.out.println(resposta.statusCode());
System.out.println(resposta.body());

import java.net.Authenticator;
import java.net.InetSocketAddress;
import java.net.PasswordAuthentication;
import java.net.ProxySelector;
import java.net.http.HttpClient;
import java.time.Duration;
import java.util.concurrent.Executors;

HttpClient client = HttpClient.newBuilder()

        // Versio del protocol. HTTP_2 es el valor per defecte i negocia:
        // si el servidor no el suporta, cau a HTTP/1.1 sense que facis res.
        .version(HttpClient.Version.HTTP_2)

        // Temps limit per ESTABLIR la connexio. Es del client
        // perque afecta totes les seves peticions.
        .connectTimeout(Duration.ofSeconds(5))

        // Politica de redireccions.
        .followRedirects(HttpClient.Redirect.NORMAL)

        // Executor per a les operacions asincrones. Si no s'indica,
        // en fa servir un d'intern. Passar el teu dona control i noms de fil.
        .executor(Executors.newFixedThreadPool(8))

        // Proxy, si la xarxa ho exigeix.
        .proxy(ProxySelector.of(new InetSocketAddress("proxy.nexussoftware.com", 3128)))

        // Autenticacio basica, per a serveis que la facin servir.
        .authenticator(new Authenticator() {
            @Override
            protected PasswordAuthentication getPasswordAuthentication() {
                return new PasswordAuthentication("bibliotech",
                        "clau".toCharArray());
            }
        })

        .build();

HttpClient client = HttpClient.newHttpClient();

.header("Authorization", "Bearer " + token)

.executor(Executors.newFixedThreadPool(8, r -> {
    Thread f = new Thread(r, "bibliotech-http-" + comptador.getAndIncrement());
    f.setDaemon(true);
    return f;
}))

// MALAMENT. Un client nou per peticio.
for (String isbn : isbns) {
    HttpClient client = HttpClient.newHttpClient();       // <-- aqui hi ha el problema
    HttpResponse<String> r = client.send(peticioDe(isbn), ofString());
}

// BE. Un, creat en arrencar, reutilitzat sempre.
private static final HttpClient CLIENT = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5))
        .build();

for (String isbn : isbns) {
    HttpResponse<String> r = CLIENT.send(peticioDe(isbn), ofString());
}

import java.net.URI;
import java.net.http.HttpRequest;
import java.time.Duration;

HttpRequest peticio = HttpRequest.newBuilder()

        // URI obligatoria. Fixa't que es URI, no URL: l'API moderna
        // fa servir la classe correcta, sense l'equals() que fa DNS (09-05).
        .uri(URI.create("https://api.nexussoftware.com/v1/llibres/978-0000000001"))

        // Capcaleres. header() afegeix; setHeader() reemplaca si ja existeix.
        .header("Accept", "application/json")
        .header("User-Agent", "BiblioTech/1.0")
        .header("Authorization", "Bearer " + token)

        // Diverses de cop: parells nom, valor.
        .headers("Accept-Language", "ca-ES", "X-Origen", "bibliotech")

        // TEMPS LIMIT TOTAL de la peticio. Aixo NO existia a
        // HttpURLConnection, que nomes tenia limit per operacio.
        .timeout(Duration.ofSeconds(10))

        // Versio especifica per a aquesta peticio, si cal.
        .version(HttpClient.Version.HTTP_1_1)

        // El metode. Un d'aquests, al final.
        .GET()

        .build();

.GET()                                          // sense cos
.DELETE()                                       // sense cos
.POST(HttpRequest.BodyPublishers.ofString(json))
.PUT(HttpRequest.BodyPublishers.ofString(json))
.method("PATCH", HttpRequest.BodyPublishers.ofString(json))   // qualsevol altre

// Plantilla amb el que es comu. Es construeix una vegada.
HttpRequest.Builder plantilla = HttpRequest.newBuilder()
        .header("Accept", "application/json")
        .header("User-Agent", "BiblioTech/1.0")
        .timeout(Duration.ofSeconds(10));

// I per cada ISBN, nomes canvia la URI.
// copy() clona el builder: sense ell, modificariem la plantilla.
HttpRequest p1 = plantilla.copy()
        .uri(URI.create(base + "/978-0000000001")).GET().build();
HttpRequest p2 = plantilla.copy()
        .uri(URI.create(base + "/978-0000000002")).GET().build();

import java.net.http.HttpRequest.BodyPublishers;

// JSON
HttpRequest p = HttpRequest.newBuilder()
        .uri(URI.create(base + "/v1/prestecs"))
        .header("Content-Type", "application/json; charset=utf-8")
        .POST(BodyPublishers.ofString(json, StandardCharsets.UTF_8))
        .build();

// Pujar un fitxer SENSE carregar-lo en memoria: es llegeix a mesura que s'envia.
// Amb HttpURLConnection calia fer el streaming a ma.
HttpRequest pujada = HttpRequest.newBuilder()
        .uri(URI.create(base + "/v1/cataleg/importar"))
        .header("Content-Type", "text/csv; charset=utf-8")
        .POST(BodyPublishers.ofFile(Path.of("cataleg.csv")))
        .build();

// Formulari: aqui URLEncoder SI que es el correcte (09-05).
String formulari = "isbn=" + URLEncoder.encode(isbn, UTF_8)
        + "&empleat=" + URLEncoder.encode(empleat, UTF_8);
HttpRequest form = HttpRequest.newBuilder()
        .uri(URI.create(base + "/v1/prestecs"))
        .header("Content-Type", "application/x-www-form-urlencoded; charset=utf-8")
        .POST(BodyPublishers.ofString(formulari))
        .build();

import java.net.http.HttpResponse.BodyHandlers;

// Text. El charset explicit, com sempre.
HttpResponse<String> text = client.send(peticio,
        BodyHandlers.ofString(StandardCharsets.UTF_8));

// Directament a un fitxer. Adeu al bucle de copia de 09-05.
HttpResponse<Path> fitxer = client.send(peticio,
        BodyHandlers.ofFile(Path.of("portades", isbn + ".jpg")));
System.out.println("Desat a " + fitxer.body());

// Com a flux, per processar sense carregar-lo sencer.
HttpResponse<InputStream> flux = client.send(peticio,
        BodyHandlers.ofInputStream());
try (InputStream entrada = flux.body()) {
    // ... l'InputStream del modul 7, un altre cop ...
}

// Nomes interessa el codi d'estat (com un HEAD).
HttpResponse<Void> nomesEstat = client.send(peticio, BodyHandlers.discarding());

HttpResponse<String> r = client.send(peticio, BodyHandlers.ofString(UTF_8));

int codi = r.statusCode();                // 200
String cos = r.body();                    // el cos, del tipus T
HttpHeaders capcaleres = r.headers();     // les capcaleres
URI uri = r.uri();                        // la URI FINAL (despres de redireccions)
HttpClient.Version versio = r.version();  // HTTP_2 o HTTP_1_1
HttpRequest original = r.request();       // la peticio que la va produir

// Les capcaleres, amb una API decent:
Optional<String> tipus = r.headers().firstValue("Content-Type");
List<String> totes = r.headers().allValues("Set-Cookie");
OptionalLong longitud = r.headers().firstValueAsLong("Content-Length");

HttpResponse<String> resposta = client.send(peticio,
        BodyHandlers.ofString(StandardCharsets.UTF_8));

try {
    HttpResponse<String> r = client.send(peticio, BodyHandlers.ofString(UTF_8));

    // OBLIGATORI: comprovar el codi. Un 500 NO llanca excepcio.
    if (r.statusCode() != 200) {
        throw new BiblioTechException("El servei ha respost " + r.statusCode()
                + ": " + retallar(r.body()));
    }
    processar(r.body());

} catch (HttpTimeoutException e) {
    // Transitori: mereix reintent amb espera creixent.
    throw new BiblioTechException("El servei no respon a temps", e);

} catch (IOException e) {
    throw new BiblioTechException("Error de xarxa consultant el servei", e);

} catch (InterruptedException e) {
    Thread.currentThread().interrupt();     // 08-02: restaurar SEMPRE el marcador
    throw new BiblioTechException("Consulta interrompuda", e);
}

CompletableFuture<HttpResponse<String>> futur = client.sendAsync(peticio,
        BodyHandlers.ofString(StandardCharsets.UTF_8));

client.sendAsync(peticio, BodyHandlers.ofString(UTF_8))
        .thenApply(HttpResponse::body)              // extreure el cos
        .thenApply(this::analitzarMetadades)        // convertir-lo en objecte
        .thenAccept(m -> System.out.println(m.titol()))
        .exceptionally(e -> {
            LOG.warning("Fallada: " + e.getMessage());
            return null;
        });
// El fil actual continua treballant. No ha esperat res.

// MALAMENT: escriptura a disc en un fil intern de l'HttpClient.
client.sendAsync(peticio, BodyHandlers.ofString(UTF_8))
        .thenApply(r -> { escriureADisc(r.body()); return r; });

// BE: la feina cara va al nostre executor.
client.sendAsync(peticio, BodyHandlers.ofString(UTF_8))
        .thenApplyAsync(r -> { escriureADisc(r.body()); return r; }, executorEs);

CompletableFuture<Metadades> futur =
        client.sendAsync(peticioDe(isbn), BodyHandlers.ofString(UTF_8))
                .thenApply(r -> {
                    // El codi es comprova AQUI, dins de la cadena.
                    if (r.statusCode() == 404) {
                        return null;
                    }
                    if (r.statusCode() != 200) {
                        // Llancar dins de la cadena la fa fallar,
                        // i la fallada arriba a l'exceptionally.
                        throw new CompletionException(
                                new BiblioTechException("HTTP " + r.statusCode()));
                    }
                    return r.body();
                })
                .thenApply(this::analitzarMetadades);

// Primer les metadades, i amb la URL que porten, la portada.
CompletableFuture<Path> futur =
        client.sendAsync(peticioMetadades(isbn), BodyHandlers.ofString(UTF_8))
                .thenApply(r -> analitzarMetadades(r.body()))
                .thenCompose(m -> {
                    // Retorna un CompletableFuture -> thenCompose, no thenApply.
                    // Amb thenApply obtindriem un
                    // CompletableFuture<CompletableFuture<HttpResponse<Path>>>.
                    HttpRequest p = HttpRequest.newBuilder()
                            .uri(URI.create(m.urlPortada()))
                            .timeout(Duration.ofSeconds(30))
                            .GET().build();
                    return client.sendAsync(p,
                            BodyHandlers.ofFile(Path.of("portades", isbn + ".jpg")));
                })
                .thenApply(HttpResponse::body);

// Dos serveis diferents, consultats EN PARALLEL.
CompletableFuture<String> metadades =
        client.sendAsync(peticioMetadades(isbn), BodyHandlers.ofString(UTF_8))
                .thenApply(HttpResponse::body);

CompletableFuture<String> valoracions =
        client.sendAsync(peticioValoracions(isbn), BodyHandlers.ofString(UTF_8))
                .thenApply(HttpResponse::body);

// El temps total es el del MES LENT, no la suma.
CompletableFuture<String> fitxa = metadades.thenCombine(valoracions,
        (m, v) -> compondreFitxa(m, v));

client.sendAsync(peticio, BodyHandlers.ofString(UTF_8))
        .thenApply(this::processar)
        .orTimeout(15, TimeUnit.SECONDS)        // termini de TOTA la cadena
        .exceptionally(e -> {
            if (e.getCause() instanceof TimeoutException) {
                LOG.warning("La cadena completa ha superat els 15 s");
            }
            return respostaPerDefecte();
        });

package com.nexussoftware.bibliotech.xarxa;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CompletableFuture;

/** Consulta de diversos ISBN en parallel amb allOf. */
public class ConsultaParallela {

    private final HttpClient client;
    private final String base;

    public ConsultaParallela(HttpClient client, String base) {
        this.client = client;
        this.base = base;
    }

    public List<String> consultarTots(List<String> isbns) {
        List<CompletableFuture<String>> futurs = new ArrayList<>();

        // 1. Llancar TOTES les peticions. sendAsync retorna a l'instant,
        //    aixi que aquest bucle acaba en microsegons i les N peticions
        //    queden en vol simultaniament.
        for (String isbn : isbns) {
            HttpRequest peticio = HttpRequest.newBuilder()
                    .uri(URI.create(base + "/v1/llibres/" + isbn))
                    .header("Accept", "application/json")
                    .timeout(Duration.ofSeconds(10))
                    .GET()
                    .build();

            CompletableFuture<String> futur =
                    client.sendAsync(peticio, BodyHandlers.ofString(StandardCharsets.UTF_8))
                            .thenApply(r -> r.statusCode() == 200
                                    ? r.body()
                                    : "ERROR " + r.statusCode() + " a " + isbn)
                            // BLINDAR CADA FUTUR ABANS D'AGREGAR-LO.
                            // Sense aixo, una sola fallada fa fallar l'allOf
                            // complet i perdem les N-1 respostes bones.
                            // Es el parany classic de 08-07.
                            .exceptionally(e -> "FALLADA a " + isbn + ": "
                                    + e.getCause().getMessage());

            futurs.add(futur);
        }

        // 2. allOf es completa quan TOTS acaben.
        CompletableFuture<Void> tots = CompletableFuture.allOf(
                futurs.toArray(new CompletableFuture[0]));

        // 3. Recollir. join() aqui es segur perque allOf ja ha garantit
        //    que tots estan complets: no bloqueja res.
        return tots.thenApply(v -> {
            List<String> resultats = new ArrayList<>(futurs.size());
            for (CompletableFuture<String> f : futurs) {
                resultats.add(f.join());
            }
            return resultats;
        }).join();      // l'unic bloqueig real, i es intencionat
    }
}

// CODI TRENCAT. Molt comu.
HttpResponse<String> r = client.send(peticio, BodyHandlers.ofString(UTF_8));
Metadades m = analitzar(r.body());       // <-- si ha estat un 500, body() es
                                         //     la pagina d'error del servidor

client.sendAsync(peticio, BodyHandlers.ofString(UTF_8))
        .thenApply(r -> {
            if (r.statusCode() == 404) {
                return null;        // "no existeix" es un resultat, no un error
            }
            if (r.statusCode() / 100 == 5) {
                // Llancar dins d'una etapa fa fallar el futur,
                // i la fallada es propaga fins al primer gestor.
                throw new CompletionException(
                        new BiblioTechException("Fallada del servidor: " + r.statusCode()));
            }
            if (r.statusCode() != 200) {
                throw new CompletionException(
                        new BiblioTechException("Resposta inesperada: " + r.statusCode()));
            }
            return r.body();
        })
        .exceptionally(e -> {
            // COMPTE: la causa arriba EMBOLCALLADA en CompletionException (08-07).
            Throwable causa = e.getCause() != null ? e.getCause() : e;
            LOG.warning("Consulta fallida: " + causa.getMessage());
            return null;
        });

HTTP/1.1, sis peticions en parallel:
  connexio 1: [salutacio][TLS][peticio A............]
  connexio 2: [salutacio][TLS][peticio B............]
  ... sis connexions, sis establiments ...

HTTP/2, sis peticions en parallel:
  connexio 1: [salutacio][TLS][A|B|C|A|D|B|E|C|F|...]
  ... UNA connexio, UN establiment, fluxos entrellacats ...

// Comprovar quina versio s'ha negociat realment.
HttpResponse<String> r = client.send(peticio, BodyHandlers.ofString(UTF_8));
System.out.println("Versio negociada: " + r.version());    // HTTP_2 o HTTP_1_1

package com.nexussoftware.bibliotech.xarxa;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.WebSocket;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import java.util.logging.Logger;

/**
 * Exemple minim de WebSocket: BiblioTech rebria avisos del servidor
 * en temps real ("el llibre que esperaves esta disponible") sense sondejar.
 */
public class AvisosWebSocket {

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

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        // El Listener rep els esdeveniments. Fixa't en request(1) al final
        // de cada metode: WebSocket fa servir CONTRAPRESSIO, i cal demanar
        // explicitament el missatge seguent.
        WebSocket.Listener oient = new WebSocket.Listener() {

            @Override
            public void onOpen(WebSocket ws) {
                LOG.info("Connexio WebSocket oberta");
                ws.request(1);      // demanem el primer missatge
            }

            @Override
            public CompletionStage<?> onText(WebSocket ws, CharSequence dades,
                                             boolean ultim) {
                System.out.println("AVIS: " + dades);
                ws.request(1);      // i el seguent
                return null;
            }

            @Override
            public CompletionStage<?> onClose(WebSocket ws, int codi, String motiu) {
                LOG.info("WebSocket tancat: " + codi + " " + motiu);
                return null;
            }

            @Override
            public void onError(WebSocket ws, Throwable error) {
                LOG.warning("Error a WebSocket: " + error.getMessage());
            }
        };

        // buildAsync retorna un CompletableFuture<WebSocket>: coherencia
        // total amb la resta de l'API.
        WebSocket ws = client.newWebSocketBuilder()
                .buildAsync(URI.create("ws://localhost:8080/avisos"), oient)
                .join();

        ws.sendText("SUBSCRIURE 978-0000000001", true);

        Thread.sleep(30_000);       // escoltem 30 segons

        ws.sendClose(WebSocket.NORMAL_CLOSURE, "fi").join();
    }
}

// A MA. Funciona per a casos simples, i CAL ESCAPAR.
String json = "{"
        + "\"isbn\":\"" + escapar(isbn) + "\","
        + "\"empleat\":\"" + escapar(empleat) + "\","
        + "\"dies\":" + dies
        + "}";

/**
 * Escapada minima de JSON. Els caracters que TRENQUEN el document
 * si no s'escapen son: la cometa doble, la barra invertida
 * i els caracters de control.
 */
static String escapar(String text) {
    StringBuilder sb = new StringBuilder(text.length() + 16);
    for (int i = 0; i < text.length(); i++) {
        char c = text.charAt(i);
        switch (c) {
            case '"'  -> sb.append("\\\"");
            case '\\' -> sb.append("\\\\");
            case '\n' -> sb.append("\\n");
            case '\r' -> sb.append("\\r");
            case '\t' -> sb.append("\\t");
            default -> {
                if (c < 0x20) {
                    sb.append(String.format("\\u%04x", (int) c));
                } else {
                    sb.append(c);
                }
            }
        }
    }
    return sb.toString();
}

/**
 * Extreu "camp":"valor" d'un JSON PER CERCA DE SUBCADENA.
 *
 * AIXO ES UN APEDACAMENT DIDACTIC I CAL DIR-HO CLAR.
 *
 * Funciona amb respostes planes i senzilles com les d'aquest servei,
 * i ES TRENCA amb:
 *   - valors que continguin la subcadena cercada
 *   - cometes escapades dins d'un valor ("Java \"Eficac\"")
 *   - objectes imbricats o arrays
 *   - un camp del mateix nom en un objecte intern
 *   - valors null, numerics o booleans on s'espera text
 *   - espais diferents al voltant dels dos punts
 *
 * FER-HO BE REQUEREIX UNA LLIBRERIA DE JSON, I AIXO ES 11-07 (JACKSON),
 * on una linia -mapper.readValue(json, Metadades.class)- substitueix
 * tot aixo i a sobre converteix directament al record. No portis
 * aquest codi a produccio.
 */
static 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;
    }
    // Cerquem la cometa de tancament saltant les escapades.
    int j = obre + 1;
    StringBuilder valor = new StringBuilder();
    while (j < json.length()) {
        char c = json.charAt(j);
        if (c == '\\' && j + 1 < json.length()) {
            valor.append(json.charAt(j + 1));
            j += 2;
            continue;
        }
        if (c == '"') {
            return valor.toString();
        }
        valor.append(c);
        j++;
    }
    return null;
}

HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5))      // establir
        .build();

HttpRequest peticio = HttpRequest.newBuilder()
        .timeout(Duration.ofSeconds(10))            // total de la peticio
        .build();

// El client genera un identificador UNIC per operacio logica
// -no per intent- i l'envia. El servidor emmagatzema les claus ja
// vistes i retorna el resultat anterior en lloc de repetir
// l'operacio. Amb aixo, reintentar SI que es segur.
String clau = UUID.randomUUID().toString();

HttpRequest peticio = HttpRequest.newBuilder()
        .uri(URI.create(base + "/v1/prestecs"))
        .header("Idempotency-Key", clau)        // la MATEIXA a tots els reintents
        .header("Content-Type", "application/json")
        .POST(BodyPublishers.ofString(json))
        .build();

// MALAMENT: el token acaba al fitxer de log, i d'alli a la copia de
// seguretat, al sistema d'agregacio de logs i a qualsevol
// captura de pantalla de suport.
LOG.info("Peticio: " + peticio.headers());

// BE: nomes el que es pot registrar.
LOG.info(() -> "GET " + peticio.uri().getPath()
        + " -> " + resposta.statusCode()
        + " (" + ms + " ms)");

.header("User-Agent", "BiblioTech/1.0 (+https://nexussoftware.com/bibliotech)")

HttpClient client = HttpClient.newBuilder()
        .sslContext(contextAmbMagatzemPropi())       // NO un TrustManager que accepti tot
        .build();

package com.nexussoftware.bibliotech.xarxa;

import com.nexussoftware.bibliotech.domini.Material;
import com.nexussoftware.bibliotech.servei.CatalegConcurrent;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.LongAdder;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Enriqueix el cataleg de BiblioTech amb dades del servei extern
 * de metadades, consultant TOTS els ISBN en parallel i descarregant
 * les portades sense bloquejar ni un sol fil.
 *
 * Resol el problema que va deixar obert SincronitzadorPortades (09-05),
 * que era sequencial i passava tot el temps esperant la xarxa.
 *
 * Aplica: HttpClient reutilitzat, sendAsync + thenCompose + allOf de 08-07,
 * Semaphore de 08-05 per acotar el parallelisme, i LongAdder de 08-06
 * per a les metriques.
 */
public class EnriquidorCataleg implements AutoCloseable {

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

    private static final String AGENT = "BiblioTech/1.0 (+https://nexussoftware.com)";
    private static final int MAXIM_SIMULTANIES = 8;
    private static final long MAXIMA_PORTADA = 5L * 1024 * 1024;

    private final String base;
    private final Path directoriPortades;
    private final HttpClient client;
    private final ExecutorService executor;

    /**
     * Acota el parallelisme. Sense ell, mil ISBN generarien mil peticions
     * simultanies i el servei ens tornaria 429 o ens bloquejaria la IP.
     * Es el Semaphore de 08-05, aplicat a la xarxa.
     */
    private final Semaphore permisos = new Semaphore(MAXIM_SIMULTANIES);

    // Metriques sense contencio (08-06).
    private final LongAdder enriquits = new LongAdder();
    private final LongAdder noTrobats = new LongAdder();
    private final LongAdder portadesDescarregades = new LongAdder();
    private final LongAdder fallits = new LongAdder();
    private final LongAdder bytesPortades = new LongAdder();

    public EnriquidorCataleg(String base, Path directoriPortades) {
        this.base = base.endsWith("/") ? base.substring(0, base.length() - 1) : base;
        this.directoriPortades = directoriPortades;

        // Executor propi amb fils ANOMENATS (08-02): en un bolcat de
        // fils i en cada linia de log sabras qui fa que.
        AtomicInteger n = new AtomicInteger(1);
        this.executor = Executors.newFixedThreadPool(MAXIM_SIMULTANIES, r -> {
            Thread f = new Thread(r, "bibliotech-http-" + n.getAndIncrement());
            f.setDaemon(true);
            return f;
        });

        // UN client, creat una vegada i reutilitzat: pool de connexions,
        // sessions TLS reutilitzades i multiplexacio HTTP/2.
        this.client = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_2)
                .connectTimeout(Duration.ofSeconds(5))
                .followRedirects(HttpClient.Redirect.NORMAL)
                .executor(executor)
                .build();
    }

    /** Fitxa enriquida d'un material. */
    public record FitxaEnriquida(String isbn, String titol, String autor,
                                 int pagines, Path portada, String estat) {
    }

    // =================================================================
    // Punt d'entrada
    // =================================================================

    public List<FitxaEnriquida> enriquir(CatalegConcurrent cataleg) {
        List<Material> materials = cataleg.tots();
        List<String> isbns = new ArrayList<>(materials.size());
        for (Material m : materials) {
            isbns.add(m.getIsbn());
        }
        return enriquirIsbns(isbns);
    }

    public List<FitxaEnriquida> enriquirIsbns(List<String> isbns) {
        long inici = System.currentTimeMillis();
        System.out.println("Enriquint " + isbns.size()
                + " materials (fins a " + MAXIM_SIMULTANIES + " alhora)...\n");

        try {
            Files.createDirectories(directoriPortades);
        } catch (Exception e) {
            LOG.log(Level.WARNING, "No s'ha pogut crear el directori de portades", e);
        }

        // --- 1. Llancar TOTES les cadenes ---
        // sendAsync retorna a l'instant, aixi que aquest bucle acaba en
        // microsegons amb N cadenes en marxa.
        List<CompletableFuture<FitxaEnriquida>> futurs =
                new ArrayList<>(isbns.size());
        for (String isbn : isbns) {
            futurs.add(cadenaDe(isbn));
        }

        // --- 2. Esperar-les totes ---
        CompletableFuture<Void> totes = CompletableFuture.allOf(
                futurs.toArray(new CompletableFuture[0]));

        // --- 3. Recollir ---
        List<FitxaEnriquida> fitxes = totes.thenApply(v -> {
            List<FitxaEnriquida> llista = new ArrayList<>(futurs.size());
            for (CompletableFuture<FitxaEnriquida> f : futurs) {
                // join() segur: allOf ja ha garantit que tots estan complets.
                llista.add(f.join());
            }
            return llista;
        }).join();      // l'unic bloqueig real, intencionat

        informe(System.currentTimeMillis() - inici, isbns.size());
        return fitxes;
    }

    // =================================================================
    // La cadena asincrona d'UN material
    // =================================================================

    private CompletableFuture<FitxaEnriquida> cadenaDe(String isbn) {
        if (!isbnValid(isbn)) {
            fallits.increment();
            return CompletableFuture.completedFuture(
                    new FitxaEnriquida(isbn, null, null, 0, null, "ISBN INVALID"));
        }

        HttpRequest peticio = HttpRequest.newBuilder()
                .uri(URI.create(base + "/v1/llibres/" + isbn))
                .header("Accept", "application/json")
                .header("User-Agent", AGENT)
                .timeout(Duration.ofSeconds(10))    // limit TOTAL, no per operacio
                .GET()
                .build();

        // adquirirPermis bloqueja si ja n'hi ha 8 en vol. Es fa ABANS
        // del sendAsync perque el semafor limiti peticions reals.
        adquirirPermis();

        return client.sendAsync(peticio, BodyHandlers.ofString(StandardCharsets.UTF_8))

                // --- Etapa 1: comprovar el codi i quedar-nos amb el cos ---
                .thenApply(resposta -> {
                    alliberarPermis();

                    int codi = resposta.statusCode();
                    LOG.fine(() -> "GET /v1/llibres/" + isbn + " -> " + codi);

                    if (codi == 404) {
                        return null;        // "no el tinc" es un resultat
                    }
                    if (codi != 200) {
                        // Llancar aqui fa fallar el futur; la fallada arriba
                        // a l'exceptionally del final.
                        throw new CompletionException(
                                new java.io.IOException("HTTP " + codi
                                        + " consultant " + isbn));
                    }
                    return resposta.body();
                })

                // --- Etapa 2: analitzar el JSON ---
                .thenApply(cos -> {
                    if (cos == null) {
                        noTrobats.increment();
                        return new FitxaEnriquida(isbn, null, null, 0, null,
                                "NO TROBAT");
                    }
                    String titol = campText(cos, "titol");
                    String autor = campText(cos, "autor");
                    String portada = campText(cos, "portada");
                    int pagines = campEnter(cos, "pagines");

                    if (titol == null) {
                        throw new CompletionException(
                                new java.io.IOException("Resposta sense titol"));
                    }
                    enriquits.increment();
                    return new FitxaEnriquida(isbn, titol,
                            autor == null ? "(desconegut)" : autor,
                            pagines,
                            portada == null ? null : Path.of(portada),  // marcador
                            "OK");
                })

                // --- Etapa 3: descarregar la portada, si n'hi ha ---
                // thenCompose perque retorna UN ALTRE CompletableFuture:
                // amb thenApply tindriem un futur d'un futur (08-07).
                .thenCompose(fitxa -> {
                    if (fitxa.portada() == null) {
                        return CompletableFuture.completedFuture(fitxa);
                    }
                    // El camp 'portada' porta la URL de forma provisional.
                    String url = fitxa.portada().toString();
                    return descarregarPortada(url, isbn)
                            .thenApply(cami -> new FitxaEnriquida(
                                    fitxa.isbn(), fitxa.titol(), fitxa.autor(),
                                    fitxa.pagines(), cami,
                                    cami == null ? "OK (sense portada)" : "OK"));
                })

                // --- Termini de la cadena COMPLETA ---
                .orTimeout(30, TimeUnit.SECONDS)

                // --- Blindatge: OBLIGATORI abans d'agregar a l'allOf ---
                // Sense aixo, una sola fallada fa fallar l'allOf sencer i
                // perdem totes les fitxes bones. Parany classic de 08-07.
                .exceptionally(e -> {
                    alliberarPermis();      // per si ha fallat abans d'alliberar-lo
                    fallits.increment();
                    // La causa arriba EMBOLCALLADA en CompletionException.
                    Throwable causa = e.getCause() != null ? e.getCause() : e;
                    LOG.warning("Fallada enriquint " + isbn + ": "
                            + causa.getMessage());
                    return new FitxaEnriquida(isbn, null, null, 0, null,
                            "FALLADA: " + causa.getClass().getSimpleName());
                });
    }

    /** Descarrega la portada a disc. Retorna null si no s'ha pogut. */
    private CompletableFuture<Path> descarregarPortada(String url, String isbn) {
        if (!url.startsWith("http://") && !url.startsWith("https://")) {
            // Sense aquesta comprovacio, una URL "file:///etc/passwd" rebuda
            // del servei ens faria llegir fitxers locals.
            LOG.warning("Esquema no permes a la portada de " + isbn);
            return CompletableFuture.completedFuture(null);
        }

        Path desti = directoriPortades.resolve(isbn + ".jpg");

        HttpRequest peticio = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Accept", "image/jpeg, image/png, image/*")
                .header("User-Agent", AGENT)
                .timeout(Duration.ofSeconds(30))
                .GET()
                .build();

        adquirirPermis();

        // BodyHandlers.ofFile escriu directament a disc, sense carregar
        // la imatge en memoria i sense el bucle de copia de 09-05.
        return client.sendAsync(peticio, BodyHandlers.ofFile(desti))
                .thenApply(resposta -> {
                    alliberarPermis();
                    if (resposta.statusCode() != 200) {
                        LOG.fine("Portada de " + isbn + ": HTTP "
                                + resposta.statusCode());
                        return null;
                    }
                    Path cami = resposta.body();
                    try {
                        long mida = Files.size(cami);
                        if (mida > MAXIMA_PORTADA) {
                            Files.deleteIfExists(cami);
                            LOG.warning("Portada de " + isbn + " massa gran");
                            return null;
                        }
                        bytesPortades.add(mida);
                    } catch (Exception e) {
                        LOG.fine("No s'ha pogut comprovar la mida: " + e.getMessage());
                    }
                    portadesDescarregades.increment();
                    return cami;
                })
                .exceptionally(e -> {
                    alliberarPermis();
                    LOG.fine("Fallada descarregant la portada de " + isbn);
                    return null;    // sense portada no es una fallada de l'enriquiment
                });
    }

    // =================================================================
    // Semafor
    // =================================================================

    private void adquirirPermis() {
        try {
            permisos.acquire();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();       // 08-02
            throw new CompletionException(e);
        }
    }

    private void alliberarPermis() {
        permisos.release();
    }

    // =================================================================
    // Analisi de JSON: APEDACAMENT DIDACTIC, veure l'apartat 15
    // =================================================================

    /**
     * Extraccio per cerca de subcadena. Funciona amb les respostes
     * planes d'aquest servei i es trenca amb imbricacio, arrays o camps
     * repetits. FER-HO BE ES JACKSON, I AIXO ES 11-07.
     */
    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;
        }
        StringBuilder valor = new StringBuilder();
        int j = obre + 1;
        while (j < json.length()) {
            char c = json.charAt(j);
            if (c == '\\' && j + 1 < json.length()) {
                valor.append(json.charAt(j + 1));
                j += 2;
                continue;
            }
            if (c == '"') {
                return valor.toString();
            }
            valor.append(c);
            j++;
        }
        return null;
    }

    private int campEnter(String json, String camp) {
        String marca = "\"" + camp + "\"";
        int i = json.indexOf(marca);
        if (i < 0) {
            return 0;
        }
        int j = json.indexOf(':', i + marca.length()) + 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 boolean isbnValid(String isbn) {
        if (isbn == null || isbn.isBlank() || isbn.length() > 20) {
            return false;
        }
        // Llista blanca: impedeix injectar camins ("../admin") a la URL.
        for (int i = 0; i < isbn.length(); i++) {
            char c = isbn.charAt(i);
            if (!Character.isDigit(c) && c != '-') {
                return false;
            }
        }
        return true;
    }

    // =================================================================
    // Informe i tancament
    // =================================================================

    private void informe(long ms, int total) {
        System.out.println();
        System.out.println("=== ENRIQUIMENT DE CATALEG ===");
        System.out.printf("%-26s %d%n", "Materials", total);
        System.out.printf("%-26s %d%n", "Enriquits", enriquits.sum());
        System.out.printf("%-26s %d%n", "No trobats", noTrobats.sum());
        System.out.printf("%-26s %d%n", "Fallits", fallits.sum());
        System.out.printf("%-26s %d%n", "Portades descarregades",
                portadesDescarregades.sum());
        System.out.printf("%-26s %.1f KB%n", "Bytes de portades",
                bytesPortades.sum() / 1024.0);
        System.out.printf("%-26s %.2f s%n", "Temps total", ms / 1000.0);
        if (total > 0) {
            System.out.printf("%-26s %.1f ms%n", "Mitjana per material",
                    (double) ms / total);
        }
    }

    @Override
    public void close() {
        // Aturada en dues fases (08-05).
        executor.shutdown();
        try {
            if (!executor.awaitTermination(10, TimeUnit.SECONDS)) {
                LOG.warning("Peticions encara actives; es forca el tancament");
                executor.shutdownNow();
            }
        } catch (InterruptedException e) {
            executor.shutdownNow();
            Thread.currentThread().interrupt();       // 08-02
        }
        LOG.info("EnriquidorCataleg tancat");
    }
}

package com.nexussoftware.bibliotech.presentacio;

import com.nexussoftware.bibliotech.xarxa.EnriquidorCataleg;
import com.nexussoftware.bibliotech.xarxa.EnriquidorCataleg.FitxaEnriquida;

import java.nio.file.Path;
import java.util.List;

public class ProvaEnriquidor {

    public static void main(String[] args) {
        List<String> isbns = List.of(
                "978-0000000001", "978-0000000002", "978-0000000003",
                "978-0000000004", "978-0000000005", "978-0000000006",
                "978-0000000007", "978-0000000008", "978-0000000009",
                "978-0000000010", "978-0000000011", "978-0000000012",
                "978-0000000013", "978-0000000014", "978-0000000015",
                "978-0000000016", "978-0000000017", "978-0000000018",
                "978-0000000019", "978-0000000020");

        // AutoCloseable: aturada ordenada de l'executor.
        try (EnriquidorCataleg enriquidor = new EnriquidorCataleg(
                "http://localhost:8080", Path.of("portades"))) {

            List<FitxaEnriquida> fitxes = enriquidor.enriquirIsbns(isbns);

            System.out.println("\n--- RESULTAT ---");
            for (FitxaEnriquida f : fitxes) {
                System.out.printf("  %-18s %-30s %s%n",
                        f.isbn(),
                        f.titol() == null ? "-" : f.titol(),
                        f.estat());
            }
        }
    }
}

Enriquint 20 materials (fins a 8 alhora)...

=== ENRIQUIMENT DE CATALEG ===
Materials                  20
Enriquits                  17
No trobats                 2
Fallits                    1
Portades descarregades     15
Bytes de portades          682.4 KB
Temps total                1.24 s
Mitjana per material       62.0 ms

--- RESULTAT ---
  978-0000000001     Java Eficac                    OK
  978-0000000002     Patrons de Disseny             OK
  978-0000000003     Refactoritzacio                OK
  978-0000000004     -                              NO TROBAT
  ...
  978-0000000019     -                              FALLADA: HttpTimeoutException

package com.nexussoftware.bibliotech.xarxa;

import java.io.IOException;
import java.net.ConnectException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.net.http.HttpTimeoutException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.List;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.Executor;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.ThreadLocalRandom;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.logging.Logger;

/**
 * Client HTTP asincron amb reintents, sobre java.net.http.
 *
 * La clau de l'exercici: els reintents es fan DINS de la cadena
 * asincrona amb thenCompose recursiu i delayedExecutor. Cap fil
 * es bloqueja esperant entre intents.
 */
public class ClientAsincronResistent implements AutoCloseable {

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

    private static final int MAXIM_INTENTS = 4;
    private static final long ESPERA_INICIAL_MS = 200;
    private static final long MAXIM_RETRY_AFTER_MS = 30_000;

    private final HttpClient client;
    private final ExecutorService executor;

    public ClientAsincronResistent() {
        AtomicInteger n = new AtomicInteger(1);
        this.executor = Executors.newFixedThreadPool(8, r -> {
            Thread f = new Thread(r, "http-resistent-" + n.getAndIncrement());
            f.setDaemon(true);
            return f;
        });
        // UN client, reutilitzat: pool de connexions i sessions TLS.
        this.client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(5))
                .followRedirects(HttpClient.Redirect.NORMAL)
                .executor(executor)
                .build();
    }

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

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

    // =================================================================
    // API publica
    // =================================================================

    public CompletableFuture<Resposta> get(String url) {
        HttpRequest peticio = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Accept", "application/json, */*")
                .header("User-Agent", "BiblioTech/1.0")
                .timeout(Duration.ofSeconds(10))
                .GET()
                .build();
        return ambReintents(peticio, 1, ESPERA_INICIAL_MS);
    }

    /**
     * POST SENSE reintents. Si esgota el termini, no sabem si el servidor
     * l'ha processat; reintentar podria duplicar l'operacio.
     */
    public CompletableFuture<Resposta> post(String url, String cos, String tipus) {
        return ambReintents(construirPost(url, cos, tipus, null),
                MAXIM_INTENTS, 0);  // comencar a l'ultim intent = sense reintents
    }

    /**
     * POST AMB reintents, fent servir clau d'idempotencia.
     *
     * La clau es genera UNA VEGADA, fora de la cadena, i viatja igual a
     * tots els reintents. Aixo es el que permet al servidor reconeixer
     * que es la mateixa operacio logica i no repetir-la.
     */
    public CompletableFuture<Resposta> postIdempotent(String url, String cos,
                                                      String tipus) {
        String clau = UUID.randomUUID().toString();
        return ambReintents(construirPost(url, cos, tipus, clau),
                1, ESPERA_INICIAL_MS);
    }

    private HttpRequest construirPost(String url, String cos, String tipus,
                                      String clauIdempotencia) {
        HttpRequest.Builder b = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", tipus == null
                        ? "application/json; charset=utf-8" : tipus)
                .header("Accept", "application/json")
                .header("User-Agent", "BiblioTech/1.0")
                .timeout(Duration.ofSeconds(15))
                .POST(HttpRequest.BodyPublishers.ofString(cos, StandardCharsets.UTF_8));

        if (clauIdempotencia != null) {
            b = b.header("Idempotency-Key", clauIdempotencia);
        }
        return b.build();
    }

    // =================================================================
    // Nucli: reintents DINS de la cadena asincrona
    // =================================================================

    private CompletableFuture<Resposta> ambReintents(HttpRequest peticio,
                                                     int intent, long espera) {

        return client.sendAsync(peticio, BodyHandlers.ofString(StandardCharsets.UTF_8))

                // --- Cas 1: hi ha hagut resposta. Pot ser un codi transitori. ---
                .thenCompose(resposta -> {
                    int codi = resposta.statusCode();

                    if (esTransitori(codi) && intent < MAXIM_INTENTS) {
                        long esperaReal = esperaPerResposta(resposta, espera);
                        LOG.warning(peticio.method() + " " + peticio.uri().getPath()
                                + " -> " + codi + "; reintent " + (intent + 1)
                                + " d'aqui a " + esperaReal + " ms");

                        // AQUI HI HA LA CLAU DE L'EXERCICI.
                        // delayedExecutor retorna un Executor que executa
                        // la tasca DESPRES del retard, sense bloquejar cap fil.
                        // Un Thread.sleep aqui deixaria aturat un fil del pool
                        // durant tota l'espera, que es justament el que volem evitar.
                        Executor retardat = CompletableFuture.delayedExecutor(
                                esperaReal, TimeUnit.MILLISECONDS, executor);

                        // supplyAsync sobre l'executor retardat + thenCompose:
                        // la recursio es converteix en una altra etapa de la cadena.
                        return CompletableFuture
                                .supplyAsync(() -> null, retardat)
                                .thenCompose(v -> ambReintents(peticio,
                                        intent + 1, espera * 2));
                    }

                    return CompletableFuture.completedFuture(new Resposta(
                            codi, resposta.body(), resposta.headers().map(), intent));
                })

                // --- Cas 2: hi ha hagut excepcio. Pot ser transitoria. ---
                .handle((resultat, error) -> {
                    if (error == null) {
                        return CompletableFuture.completedFuture(resultat);
                    }
                    // La causa arriba EMBOLCALLADA en CompletionException (08-07).
                    Throwable causa = error.getCause() != null ? error.getCause() : error;

                    if (esTransitoria(causa) && intent < MAXIM_INTENTS) {
                        long esperaReal = ambJitter(espera);
                        LOG.warning(causa.getClass().getSimpleName() + " a "
                                + peticio.uri().getPath() + "; reintent "
                                + (intent + 1) + " d'aqui a " + esperaReal + " ms");

                        Executor retardat = CompletableFuture.delayedExecutor(
                                esperaReal, TimeUnit.MILLISECONDS, executor);
                        return CompletableFuture
                                .supplyAsync(() -> null, retardat)
                                .thenCompose(v -> ambReintents(peticio,
                                        intent + 1, espera * 2));
                    }

                    // Permanent o sense intents: es propaga la fallada.
                    return CompletableFuture.<Resposta>failedFuture(causa);
                })
                // handle retorna CompletableFuture<CompletableFuture<Resposta>>:
                // thenCompose l'aplana. Es el map/flatMap de 08-07.
                .thenCompose(f -> f);
    }

    // =================================================================
    // Politica
    // =================================================================

    private boolean esTransitori(int codi) {
        // El 500 s'exclou a proposit: sol ser una fallada determinista
        // del servidor que es repetira identicament.
        return codi == 429 || codi == 502 || codi == 503 || codi == 504;
    }

    private boolean esTransitoria(Throwable t) {
        // HttpTimeoutException es subclasse d'IOException, i ConnectException
        // tambe: cal comprovar les concretes ABANS que IOException.
        return t instanceof HttpTimeoutException
                || t instanceof ConnectException
                || (t instanceof IOException && !(t.getMessage() != null
                        && t.getMessage().contains("UnresolvedAddress")));
    }

    private long esperaPerResposta(HttpResponse<?> resposta, long calculada) {
        // firstValue retorna Optional perque la capcalera pot no ser-hi.
        // Aqui el fem servir amb isPresent()/get(); l'estil fluid d'Optional
        // (map, orElseGet, ifPresent) es veu a 10-04.
        java.util.Optional<String> retryAfter =
                resposta.headers().firstValue("Retry-After");

        if (retryAfter.isPresent()) {
            try {
                // Nomes el format en segons; el de data exigeix analitzar
                // dates HTTP, i aixo es fa be a 10-05.
                long ms = Long.parseLong(retryAfter.get().strip()) * 1000;
                return Math.min(ms, MAXIM_RETRY_AFTER_MS);
            } catch (NumberFormatException e) {
                LOG.fine("Retry-After en format de data; s'ignora");
            }
        }
        return ambJitter(calculada);
    }

    /**
     * Aleatoritza l'espera un 20 %.
     * Evita el "ramat atronador": si cent clients fallen alhora i tots
     * reintenten exactament als 200 ms, la rafega sincronitzada torna a
     * tombar el servei que s'estava recuperant, en un cicle indefinit.
     */
    private long ambJitter(long base) {
        if (base <= 0) {
            return 0;
        }
        long variacio = Math.max(1, base / 5);
        return base + ThreadLocalRandom.current().nextLong(-variacio, variacio + 1);
    }

    @Override
    public void close() {
        executor.shutdown();        // aturada en dues fases (08-05)
        try {
            if (!executor.awaitTermination(10, TimeUnit.SECONDS)) {
                executor.shutdownNow();
            }
        } catch (InterruptedException e) {
            executor.shutdownNow();
            Thread.currentThread().interrupt();
        }
    }

    // =================================================================
    // Prova
    // =================================================================

    public static void main(String[] args) {
        String base = args.length > 0 ? args[0] : "http://localhost:8080";

        try (ClientAsincronResistent c = new ClientAsincronResistent()) {

            List<CompletableFuture<Resposta>> futurs = new java.util.ArrayList<>();
            long t0 = System.currentTimeMillis();

            for (int i = 1; i <= 10; i++) {
                futurs.add(c.get(base + "/v1/llibres/978-000000000" + (i % 10))
                        // Blindatge individual ABANS de l'allOf: sense ell, una
                        // fallada tombaria les deu.
                        .exceptionally(e -> new Resposta(-1,
                                "FALLADA: " + e.getCause().getMessage(),
                                Map.of(), MAXIM_INTENTS)));
            }

            CompletableFuture.allOf(futurs.toArray(new CompletableFuture[0])).join();
            long ms = System.currentTimeMillis() - t0;

            int ok = 0, fallides = 0, reintentades = 0;
            for (CompletableFuture<Resposta> f : futurs) {
                Resposta r = f.join();      // segur: allOf ja ha acabat
                if (r.exit()) {
                    ok++;
                } else {
                    fallides++;
                }
                if (r.intents() > 1) {
                    reintentades++;
                }
                System.out.printf("  codi=%-5d intents=%d%n", r.codi(), r.intents());
            }

            System.out.println();
            System.out.printf("Correctes: %d   Fallides: %d   Amb reintent: %d%n",
                    ok, fallides, reintentades);
            System.out.printf("Temps total: %d ms%n", ms);
        }
    }
}

package com.nexussoftware.bibliotech.xarxa;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.LongAdder;

/**
 * Compara quatre estrategies per fer N peticions HTTP.
 * Demostra amb numeros per que l'asincrona acotada es la resposta.
 */
public class ComparadorEstrategies {

    private final String base;
    private final int peticions;
    private final HttpClient client;

    public ComparadorEstrategies(String base, int peticions) {
        this.base = base;
        this.peticions = peticions;
        // UN client per a totes les estrategies: aixi la comparacio es
        // justa i no mesurem el cost de crear clients.
        this.client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(5))
                .build();
    }

    public record Resultat(String estrategia, long ms, int correctes, int fallides,
                           double mitjanaLatenciaMs, int filsMaxims) {
    }

    private HttpRequest peticioDe(int i) {
        return HttpRequest.newBuilder()
                .uri(URI.create(base + "/v1/llibres/978-" + String.format("%010d", i)))
                .header("Accept", "application/json")
                .timeout(Duration.ofSeconds(15))
                .GET()
                .build();
    }

    // =================================================================
    // Vigilant de fils
    // =================================================================

    /** Mostreja Thread.activeCount() en un fil a part durant la mesura. */
    private static class VigilantFils {
        private final AtomicInteger maxim = new AtomicInteger();
        private volatile boolean actiu = true;
        private Thread fil;

        void arrencar() {
            fil = new Thread(() -> {
                while (actiu) {
                    maxim.updateAndGet(m -> Math.max(m, Thread.activeCount()));
                    try {
                        Thread.sleep(10);
                    } catch (InterruptedException e) {
                        Thread.currentThread().interrupt();
                        return;
                    }
                }
            }, "vigilant-fils");
            fil.setDaemon(true);
            fil.start();
        }

        int aturar() {
            actiu = false;
            try {
                fil.join(500);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
            return maxim.get();
        }
    }

    // =================================================================
    // A: sequencial
    // =================================================================

    public Resultat sequencial() {
        VigilantFils vigilant = new VigilantFils();
        vigilant.arrencar();

        int correctes = 0, fallides = 0;
        long sumaLatencies = 0;
        long t0 = System.currentTimeMillis();

        for (int i = 0; i < peticions; i++) {
            long p0 = System.nanoTime();
            try {
                HttpResponse<Void> r = client.send(peticioDe(i),
                        BodyHandlers.discarding());
                if (r.statusCode() == 200) {
                    correctes++;
                } else {
                    fallides++;
                }
            } catch (IOException e) {
                fallides++;
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();      // 08-02
                break;
            }
            sumaLatencies += (System.nanoTime() - p0) / 1_000_000;
        }

        long ms = System.currentTimeMillis() - t0;
        return new Resultat("A. Sequencial (send en bucle)", ms, correctes, fallides,
                peticions == 0 ? 0 : (double) sumaLatencies / peticions,
                vigilant.aturar());
    }

    // =================================================================
    // B: pool de fils amb send bloquejant
    // =================================================================

    public Resultat poolBloquejant() throws InterruptedException {
        VigilantFils vigilant = new VigilantFils();
        vigilant.arrencar();

        AtomicInteger correctes = new AtomicInteger();
        AtomicInteger fallides = new AtomicInteger();
        LongAdder sumaLatencies = new LongAdder();

        ExecutorService pool = Executors.newFixedThreadPool(8);
        CountDownLatch sortida = new CountDownLatch(1);
        CountDownLatch arribada = new CountDownLatch(peticions);

        for (int i = 0; i < peticions; i++) {
            final int n = i;
            pool.execute(() -> {
                try {
                    sortida.await();    // tots arrenquen alhora
                    long p0 = System.nanoTime();
                    // send BLOQUEJA el fil del pool durant tota l'espera
                    // de xarxa. Vuit fils = vuit peticions simultanies,
                    // i set de cada vuit fils estan aturats sense fer res.
                    HttpResponse<Void> r = client.send(peticioDe(n),
                            BodyHandlers.discarding());
                    sumaLatencies.add((System.nanoTime() - p0) / 1_000_000);
                    if (r.statusCode() == 200) {
                        correctes.incrementAndGet();
                    } else {
                        fallides.incrementAndGet();
                    }
                } catch (IOException e) {
                    fallides.incrementAndGet();
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                } finally {
                    arribada.countDown();
                }
            });
        }

        long t0 = System.currentTimeMillis();
        sortida.countDown();
        arribada.await();
        long ms = System.currentTimeMillis() - t0;

        pool.shutdown();
        if (!pool.awaitTermination(5, TimeUnit.SECONDS)) {
            pool.shutdownNow();
        }

        return new Resultat("B. Pool de 8 fils (send bloquejant)", ms,
                correctes.get(), fallides.get(),
                (double) sumaLatencies.sum() / peticions, vigilant.aturar());
    }

    // =================================================================
    // C: asincrona sense limit
    // =================================================================

    public Resultat asincronaSenseLimit() {
        VigilantFils vigilant = new VigilantFils();
        vigilant.arrencar();

        AtomicInteger correctes = new AtomicInteger();
        AtomicInteger fallides = new AtomicInteger();
        LongAdder sumaLatencies = new LongAdder();

        long t0 = System.currentTimeMillis();
        List<CompletableFuture<Void>> futurs = new ArrayList<>(peticions);

        for (int i = 0; i < peticions; i++) {
            long p0 = System.nanoTime();
            futurs.add(client.sendAsync(peticioDe(i), BodyHandlers.discarding())
                    .thenAccept(r -> {
                        sumaLatencies.add((System.nanoTime() - p0) / 1_000_000);
                        if (r.statusCode() == 200) {
                            correctes.incrementAndGet();
                        } else {
                            fallides.incrementAndGet();
                        }
                    })
                    // Blindatge individual: sense ell, una fallada tomba l'allOf.
                    .exceptionally(e -> {
                        fallides.incrementAndGet();
                        return null;
                    }));
        }

        CompletableFuture.allOf(futurs.toArray(new CompletableFuture[0])).join();
        long ms = System.currentTimeMillis() - t0;

        return new Resultat("C. Asincrona sense limit (sendAsync+allOf)", ms,
                correctes.get(), fallides.get(),
                (double) sumaLatencies.sum() / peticions, vigilant.aturar());
    }

    // =================================================================
    // D: asincrona acotada amb Semaphore
    // =================================================================

    public Resultat asincronaAcotada(int simultanies) {
        VigilantFils vigilant = new VigilantFils();
        vigilant.arrencar();

        AtomicInteger correctes = new AtomicInteger();
        AtomicInteger fallides = new AtomicInteger();
        LongAdder sumaLatencies = new LongAdder();
        Semaphore permisos = new Semaphore(simultanies);

        long t0 = System.currentTimeMillis();
        List<CompletableFuture<Void>> futurs = new ArrayList<>(peticions);

        for (int i = 0; i < peticions; i++) {
            try {
                // El semafor limita quantes peticions hi ha EN VOL,
                // no quants fils hi ha. Es la diferencia amb l'estrategia B.
                permisos.acquire();
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                break;
            }
            long p0 = System.nanoTime();
            futurs.add(client.sendAsync(peticioDe(i), BodyHandlers.discarding())
                    .thenAccept(r -> {
                        permisos.release();
                        sumaLatencies.add((System.nanoTime() - p0) / 1_000_000);
                        if (r.statusCode() == 200) {
                            correctes.incrementAndGet();
                        } else {
                            fallides.incrementAndGet();
                        }
                    })
                    .exceptionally(e -> {
                        permisos.release();     // TAMBE en fallar, o es fuga
                        fallides.incrementAndGet();
                        return null;
                    }));
        }

        CompletableFuture.allOf(futurs.toArray(new CompletableFuture[0])).join();
        long ms = System.currentTimeMillis() - t0;

        return new Resultat("D. Asincrona acotada a " + simultanies, ms,
                correctes.get(), fallides.get(),
                (double) sumaLatencies.sum() / peticions, vigilant.aturar());
    }

    // =================================================================
    // Execucio
    // =================================================================

    public void comparar() throws InterruptedException {
        // ESCALFAMENT: la primera ronda carrega classes, compila amb el JIT
        // i estableix les primeres connexions. Sense descartar-la, la primera
        // estrategia mesurada sortiria injustament penalitzada.
        System.out.println("Escalfant...");
        for (int i = 0; i < 5; i++) {
            try {
                client.send(peticioDe(i), BodyHandlers.discarding());
            } catch (Exception ignorada) {
                // L'escalfament no cal que surti be.
            }
        }

        System.out.println("Mesurant " + peticions + " peticions per estrategia...\n");

        List<Resultat> resultats = new ArrayList<>();
        resultats.add(sequencial());
        resultats.add(poolBloquejant());
        resultats.add(asincronaSenseLimit());
        resultats.add(asincronaAcotada(8));

        long referencia = resultats.get(0).ms();

        System.out.printf("%-42s %9s %8s %10s %9s %8s%n",
                "ESTRATEGIA", "TEMPS", "PET/S", "LAT.MITJ.", "FILS", "MILLORA");
        System.out.println("-".repeat(95));
        for (Resultat r : resultats) {
            System.out.printf("%-42s %8d ms %8.0f %8.1f ms %9d %7.1fx%n",
                    r.estrategia(), r.ms(),
                    r.ms() == 0 ? 0 : peticions * 1000.0 / r.ms(),
                    r.mitjanaLatenciaMs(), r.filsMaxims(),
                    r.ms() == 0 ? 0 : (double) referencia / r.ms());
        }
    }

    public static void main(String[] args) throws InterruptedException {
        String base = args.length > 0 ? args[0] : "http://localhost:8080";
        new ComparadorEstrategies(base, 50).comparar();
    }
}

Escalfant...
Mesurant 50 peticions per estrategia...

ESTRATEGIA                                     TEMPS    PET/S  LAT.MITJ.      FILS  MILLORA
-----------------------------------------------------------------------------------------------
A. Sequencial (send en bucle)                 10214 ms        5    204.1 ms         9     1.0x
B. Pool de 8 fils (send bloquejant)            1428 ms       35    221.6 ms        18     7.2x
C. Asincrona sense limit (sendAsync+allOf)      287 ms      174    263.4 ms        14    35.6x
D. Asincrona acotada a 8                       1391 ms       36    215.2 ms        12     7.3x

package com.nexussoftware.bibliotech.xarxa;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Panell d'estat dels serveis dels quals depen BiblioTech.
 * Comprova tots en parallel cada N segons i mostra un panell en consola.
 */
public class PanellEstatServeis implements AutoCloseable {

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

    private static final int HISTORIAL = 20;
    private static final int LIMIT_MS = 3_000;

    /** Un servei a vigilar. */
    public record Servei(String nom, String url, int codiEsperat) {
    }

    public enum Estat {
        AMUNT('#'), DEGRADAT('-'), AVALL('.');

        final char simbol;

        Estat(char simbol) {
            this.simbol = simbol;
        }
    }

    /** Resultat d'una comprovacio. */
    public record Comprovacio(Estat estat, int codi, long latenciaMs,
                              String versio, String detall) {
    }

    private final List<Servei> serveis;
    private final HttpClient client;
    private final ScheduledExecutorService planificador;

    /**
     * Historial per servei. ConcurrentHashMap perque l'escriu el fil
     * del planificador i el llegeixen les etapes asincrones (08-06).
     */
    private final Map<String, Deque<Comprovacio>> historial = new ConcurrentHashMap<>();
    /** Ultim estat conegut, per no repetir l'alerta a cada cicle. */
    private final Map<String, Estat> ultimEstat = new ConcurrentHashMap<>();

    private final AtomicInteger cicles = new AtomicInteger();

    public PanellEstatServeis(List<Servei> serveis) {
        this.serveis = serveis;

        AtomicInteger n = new AtomicInteger(1);
        this.client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(2))
                .followRedirects(HttpClient.Redirect.NORMAL)
                .executor(Executors.newFixedThreadPool(serveis.size(), r -> {
                    Thread f = new Thread(r, "panell-http-" + n.getAndIncrement());
                    f.setDaemon(true);
                    return f;
                }))
                .build();

        this.planificador = Executors.newSingleThreadScheduledExecutor(r -> {
            Thread f = new Thread(r, "panell-planificador");
            f.setDaemon(true);
            return f;
        });

        for (Servei s : serveis) {
            historial.put(s.nom(), new ArrayDeque<>(HISTORIAL));
            ultimEstat.put(s.nom(), Estat.AMUNT);
        }
    }

    // =================================================================
    // Arrencada
    // =================================================================

    public void arrencar(int intervalSegons) {
        // scheduleAtFixedRate de 08-05.
        planificador.scheduleAtFixedRate(this::cicleSegur,
                0, intervalSegons, TimeUnit.SECONDS);
        LOG.info("Panell d'estat en marxa (cada " + intervalSegons + " s)");
    }

    /**
     * Embolcall de seguretat OBLIGATORI.
     *
     * Si una excepcio escapa d'una tasca de scheduleAtFixedRate, la tasca
     * ES CANCELLA EN SILENCI i el panell deixa d'actualitzar-se sense que ningu
     * se n'assabenti: ni excepcio, ni log, ni res. Es el parany de 08-05.
     */
    private void cicleSegur() {
        try {
            cicle();
        } catch (RuntimeException e) {
            LOG.log(Level.SEVERE, "Fallada al cicle del panell", e);
        }
    }

    // =================================================================
    // Un cicle de comprovacio
    // =================================================================

    private void cicle() {
        long t0 = System.currentTimeMillis();

        // 1. Llancar TOTES les comprovacions en parallel.
        List<CompletableFuture<Void>> futurs = new ArrayList<>(serveis.size());
        for (Servei s : serveis) {
            futurs.add(comprovar(s));
        }

        // 2. Esperar-les totes. join() aqui bloqueja el fil del planificador,
        //    que es el correcte: no volem pintar el panell a mitges ni
        //    solapar dos cicles.
        CompletableFuture.allOf(futurs.toArray(new CompletableFuture[0])).join();

        cicles.incrementAndGet();
        pintar(System.currentTimeMillis() - t0);
    }

    private CompletableFuture<Void> comprovar(Servei servei) {
        HttpRequest peticio = HttpRequest.newBuilder()
                .uri(URI.create(servei.url()))
                .header("User-Agent", "BiblioTech-Panell/1.0")
                .header("Accept", "*/*")
                .timeout(Duration.ofMillis(LIMIT_MS))       // limit TOTAL
                .GET()
                .build();

        long inici = System.nanoTime();

        // discarding(): nomes interessa el codi, no el cos. Pero el
        // CONSUMEIX, que es el que permet reutilitzar la connexio.
        return client.sendAsync(peticio, BodyHandlers.discarding())
                .thenAccept(resposta -> {
                    long ms = (System.nanoTime() - inici) / 1_000_000;
                    int codi = resposta.statusCode();

                    Estat estat = codi == servei.codiEsperat()
                            ? Estat.AMUNT
                            : Estat.DEGRADAT;

                    registrar(servei, new Comprovacio(estat, codi, ms,
                            resposta.version().toString(),
                            estat == Estat.DEGRADAT
                                    ? "esperavem " + servei.codiEsperat() : ""));
                })
                // Blindatge individual: un servei caigut no pot impedir
                // que es comprovin els altres ni que es pinti el panell.
                .exceptionally(e -> {
                    long ms = (System.nanoTime() - inici) / 1_000_000;
                    Throwable causa = e.getCause() != null ? e.getCause() : e;
                    registrar(servei, new Comprovacio(Estat.AVALL, -1, ms,
                            "-", causa.getClass().getSimpleName()));
                    return null;
                });
    }

    private void registrar(Servei servei, Comprovacio c) {
        Deque<Comprovacio> cua = historial.get(servei.nom());
        synchronized (cua) {        // ArrayDeque no es segura per a diversos fils
            if (cua.size() >= HISTORIAL) {
                cua.removeFirst();
            }
            cua.addLast(c);
        }

        // Alerta NOMES en el canvi d'estat, no a cada cicle: un
        // servei caigut durant una hora generaria 360 alertes identiques.
        Estat anterior = ultimEstat.put(servei.nom(), c.estat());
        if (anterior != c.estat()) {
            if (c.estat() == Estat.AVALL) {
                LOG.severe("ALERTA: " + servei.nom() + " ha CAIGUT ("
                        + c.detall() + ")");
            } else if (anterior == Estat.AVALL) {
                LOG.info("RECUPERAT: " + servei.nom() + " torna a respondre");
            } else {
                LOG.warning("CANVI: " + servei.nom() + " " + anterior
                        + " -> " + c.estat());
            }
        }
    }

    // =================================================================
    // Pintat
    // =================================================================

    private void pintar(long msCicle) {
        StringBuilder sb = new StringBuilder();
        sb.append("\033[H\033[2J");     // netejar la pantalla
        sb.append("=== PANELL D'ESTAT - BIBLIOTECH ===\n");
        sb.append(String.format("Cicle %d   comprovacio en %d ms%n%n",
                cicles.get(), msCicle));
        sb.append(String.format("%-22s %-11s %7s %6s %-9s %-22s %7s%n",
                "SERVEI", "ESTAT", "LATENCIA", "CODI", "VERSIO",
                "HISTORIAL", "DISPON."));
        sb.append("-".repeat(96)).append('\n');

        for (Servei s : serveis) {
            Deque<Comprovacio> cua = historial.get(s.nom());
            List<Comprovacio> copia;
            synchronized (cua) {
                copia = new ArrayList<>(cua);
            }
            if (copia.isEmpty()) {
                continue;
            }
            Comprovacio ultima = copia.get(copia.size() - 1);

            // Barra d'historial i calcul de disponibilitat.
            StringBuilder barra = new StringBuilder();
            int amunt = 0;
            for (Comprovacio c : copia) {
                barra.append(c.estat().simbol);
                if (c.estat() == Estat.AMUNT) {
                    amunt++;
                }
            }
            double disponibilitat = 100.0 * amunt / copia.size();

            sb.append(String.format("%-22s %-11s %6d ms %6s %-9s %-22s %6.1f%%%n",
                    s.nom(),
                    ultima.estat(),
                    ultima.latenciaMs(),
                    ultima.codi() < 0 ? "-" : String.valueOf(ultima.codi()),
                    ultima.versio().replace("HTTP_", "HTTP/"),
                    barra,
                    disponibilitat));

            if (!ultima.detall().isEmpty()) {
                sb.append(String.format("  %-20s %s%n", "", ultima.detall()));
            }
        }

        sb.append("-".repeat(96)).append('\n');
        sb.append("Llegenda: # amunt   - degradat   . avall\n");
        System.out.print(sb);
    }

    @Override
    public void close() {
        // Aturada en dues fases (08-05).
        planificador.shutdown();
        try {
            if (!planificador.awaitTermination(5, TimeUnit.SECONDS)) {
                planificador.shutdownNow();
            }
        } catch (InterruptedException e) {
            planificador.shutdownNow();
            Thread.currentThread().interrupt();       // 08-02
        }
        LOG.info("Panell d'estat aturat despres de " + cicles.get() + " cicles");
    }

    // =================================================================
    // Arrencada
    // =================================================================

    public static void main(String[] args) throws InterruptedException {
        List<Servei> serveis = List.of(
                new Servei("cataleg-btcp", "http://localhost:9092/", 200),
                new Servei("metadades", "http://localhost:8080/salut", 200),
                new Servei("portades", "http://localhost:8081/salut", 200),
                new Servei("avisos", "http://localhost:8082/salut", 200),
                new Servei("inexistent", "http://localhost:9999/salut", 200));

        PanellEstatServeis panell = new PanellEstatServeis(serveis);

        // Shutdown hook: Ctrl+C, SIGTERM de Docker o systemd (09-03).
        Runtime.getRuntime().addShutdownHook(
                new Thread(panell::close, "panell-aturada"));

        panell.arrencar(10);

        // El planificador fa servir fils daemon: cal mantenir viu el main.
        Thread.currentThread().join();
    }
}

=== PANELL D'ESTAT - BIBLIOTECH ===
Cicle 14   comprovacio en 3012 ms

SERVEI                 ESTAT       LATENCIA   CODI VERSIO    HISTORIAL              DISPON.
------------------------------------------------------------------------------------------------
cataleg-btcp           AMUNT             4 ms    200 HTTP/1_1  ##############          100.0%
metadades              AMUNT            38 ms    200 HTTP/2    #############-           92.9%
  esperavem 200
portades               AMUNT            21 ms    200 HTTP/2    ##############          100.0%
avisos                 DEGRADAT        104 ms    503 HTTP/1_1  ###########---           78.6%
  esperavem 200
inexistent             AVALL          2001 ms      - -         ..............            0.0%
  ConnectException
------------------------------------------------------------------------------------------------
Llegenda: # amunt   - degradat   . avall