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

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

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

System.out.println(response.statusCode());
System.out.println(response.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()

        // Protocol version. HTTP_2 is the default and it negotiates:
        // if the server does not support it, it falls back to HTTP/1.1 by itself.
        .version(HttpClient.Version.HTTP_2)

        // Time limit for ESTABLISHING the connection. It belongs to the client
        // because it affects all of its requests.
        .connectTimeout(Duration.ofSeconds(5))

        // Redirect policy.
        .followRedirects(HttpClient.Redirect.NORMAL)

        // Executor for the asynchronous operations. If not stated,
        // it uses an internal one. Passing yours gives control and thread names.
        .executor(Executors.newFixedThreadPool(8))

        // Proxy, if the network demands one.
        .proxy(ProxySelector.of(new InetSocketAddress("proxy.nexussoftware.com", 3128)))

        // Basic authentication, for services that use it.
        .authenticator(new Authenticator() {
            @Override
            protected PasswordAuthentication getPasswordAuthentication() {
                return new PasswordAuthentication("bibliotech",
                        "password".toCharArray());
            }
        })

        .build();

HttpClient client = HttpClient.newHttpClient();

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

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

// WRONG. A new client per request.
for (String isbn : isbns) {
    HttpClient client = HttpClient.newHttpClient();       // <-- here is the problem
    HttpResponse<String> r = client.send(requestFor(isbn), ofString());
}

// RIGHT. One, created at startup, reused always.
private static final HttpClient CLIENT = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5))
        .build();

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

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

HttpRequest request = HttpRequest.newBuilder()

        // The URI is mandatory. Notice it is URI, not URL: the modern API
        // uses the right class, without the equals() that does DNS (09-05).
        .uri(URI.create("https://api.nexussoftware.com/v1/books/978-0000000001"))

        // Headers. header() adds; setHeader() replaces if it already exists.
        .header("Accept", "application/json")
        .header("User-Agent", "BiblioTech/1.0")
        .header("Authorization", "Bearer " + token)

        // Several at once: name, value pairs.
        .headers("Accept-Language", "en-GB", "X-Origin", "bibliotech")

        // TOTAL TIME LIMIT of the request. This did NOT exist in
        // HttpURLConnection, which only had a per-operation limit.
        .timeout(Duration.ofSeconds(10))

        // A specific version for this request, if needed.
        .version(HttpClient.Version.HTTP_1_1)

        // The method. One of these, at the end.
        .GET()

        .build();

.GET()                                          // no body
.DELETE()                                       // no body
.POST(HttpRequest.BodyPublishers.ofString(json))
.PUT(HttpRequest.BodyPublishers.ofString(json))
.method("PATCH", HttpRequest.BodyPublishers.ofString(json))   // any other one

// A template with the common parts. Built once.
HttpRequest.Builder template = HttpRequest.newBuilder()
        .header("Accept", "application/json")
        .header("User-Agent", "BiblioTech/1.0")
        .timeout(Duration.ofSeconds(10));

// And for each ISBN, only the URI changes.
// copy() clones the builder: without it, we would modify the template.
HttpRequest r1 = template.copy()
        .uri(URI.create(base + "/978-0000000001")).GET().build();
HttpRequest r2 = template.copy()
        .uri(URI.create(base + "/978-0000000002")).GET().build();

import java.net.http.HttpRequest.BodyPublishers;

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

// Uploading a file WITHOUT loading it into memory: it is read as it is sent.
// With HttpURLConnection the streaming had to be done by hand.
HttpRequest upload = HttpRequest.newBuilder()
        .uri(URI.create(base + "/v1/catalog/import"))
        .header("Content-Type", "text/csv; charset=utf-8")
        .POST(BodyPublishers.ofFile(Path.of("catalog.csv")))
        .build();

// A form: here URLEncoder IS the right tool (09-05).
String form = "isbn=" + URLEncoder.encode(isbn, UTF_8)
        + "&employee=" + URLEncoder.encode(employee, UTF_8);
HttpRequest formRequest = HttpRequest.newBuilder()
        .uri(URI.create(base + "/v1/loans"))
        .header("Content-Type", "application/x-www-form-urlencoded; charset=utf-8")
        .POST(BodyPublishers.ofString(form))
        .build();

import java.net.http.HttpResponse.BodyHandlers;

// Text. The explicit charset, as always.
HttpResponse<String> text = client.send(request,
        BodyHandlers.ofString(StandardCharsets.UTF_8));

// Straight to a file. Goodbye to the copy loop of 09-05.
HttpResponse<Path> file = client.send(request,
        BodyHandlers.ofFile(Path.of("covers", isbn + ".jpg")));
System.out.println("Saved in " + file.body());

// As a stream, to process without loading it whole.
HttpResponse<InputStream> stream = client.send(request,
        BodyHandlers.ofInputStream());
try (InputStream input = stream.body()) {
    // ... module 7's InputStream, once again ...
}

// Only the status code is of interest (like a HEAD).
HttpResponse<Void> statusOnly = client.send(request, BodyHandlers.discarding());

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

int code = r.statusCode();                // 200
String body = r.body();                   // the body, of type T
HttpHeaders headers = r.headers();        // the headers
URI uri = r.uri();                        // the FINAL URI (after redirects)
HttpClient.Version version = r.version(); // HTTP_2 or HTTP_1_1
HttpRequest original = r.request();       // the request that produced it

// The headers, with a decent API:
Optional<String> type = r.headers().firstValue("Content-Type");
List<String> all = r.headers().allValues("Set-Cookie");
OptionalLong length = r.headers().firstValueAsLong("Content-Length");

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

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

    // MANDATORY: check the code. A 500 does NOT throw.
    if (r.statusCode() != 200) {
        throw new BiblioTechException("The service replied " + r.statusCode()
                + ": " + trim(r.body()));
    }
    process(r.body());

} catch (HttpTimeoutException e) {
    // Transient: worth a retry with increasing backoff.
    throw new BiblioTechException("The service is not replying in time", e);

} catch (IOException e) {
    throw new BiblioTechException("Network error querying the service", e);

} catch (InterruptedException e) {
    Thread.currentThread().interrupt();     // 08-02: ALWAYS restore the flag
    throw new BiblioTechException("Query interrupted", e);
}

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

client.sendAsync(request, BodyHandlers.ofString(UTF_8))
        .thenApply(HttpResponse::body)              // extract the body
        .thenApply(this::parseMetadata)             // turn it into an object
        .thenAccept(m -> System.out.println(m.title()))
        .exceptionally(e -> {
            LOG.warning("Failure: " + e.getMessage());
            return null;
        });
// The current thread carries on working. It has waited for nothing.

// WRONG: writing to disk on an internal HttpClient thread.
client.sendAsync(request, BodyHandlers.ofString(UTF_8))
        .thenApply(r -> { writeToDisk(r.body()); return r; });

// RIGHT: the expensive work goes to our executor.
client.sendAsync(request, BodyHandlers.ofString(UTF_8))
        .thenApplyAsync(r -> { writeToDisk(r.body()); return r; }, ioExecutor);

CompletableFuture<Metadata> future =
        client.sendAsync(requestFor(isbn), BodyHandlers.ofString(UTF_8))
                .thenApply(r -> {
                    // The code is checked HERE, inside the chain.
                    if (r.statusCode() == 404) {
                        return null;
                    }
                    if (r.statusCode() != 200) {
                        // Throwing inside the chain makes it fail,
                        // and the failure reaches the exceptionally.
                        throw new CompletionException(
                                new BiblioTechException("HTTP " + r.statusCode()));
                    }
                    return r.body();
                })
                .thenApply(this::parseMetadata);

// First the metadata, and with the URL it carries, the cover.
CompletableFuture<Path> future =
        client.sendAsync(metadataRequest(isbn), BodyHandlers.ofString(UTF_8))
                .thenApply(r -> parseMetadata(r.body()))
                .thenCompose(m -> {
                    // It returns a CompletableFuture -> thenCompose, not thenApply.
                    // With thenApply we would get a
                    // CompletableFuture<CompletableFuture<HttpResponse<Path>>>.
                    HttpRequest r = HttpRequest.newBuilder()
                            .uri(URI.create(m.coverUrl()))
                            .timeout(Duration.ofSeconds(30))
                            .GET().build();
                    return client.sendAsync(r,
                            BodyHandlers.ofFile(Path.of("covers", isbn + ".jpg")));
                })
                .thenApply(HttpResponse::body);

// Two different services, queried IN PARALLEL.
CompletableFuture<String> metadata =
        client.sendAsync(metadataRequest(isbn), BodyHandlers.ofString(UTF_8))
                .thenApply(HttpResponse::body);

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

// The total time is that of the SLOWEST, not the sum.
CompletableFuture<String> card = metadata.thenCombine(reviews,
        (m, v) -> composeCard(m, v));

client.sendAsync(request, BodyHandlers.ofString(UTF_8))
        .thenApply(this::process)
        .orTimeout(15, TimeUnit.SECONDS)        // deadline for the WHOLE chain
        .exceptionally(e -> {
            if (e.getCause() instanceof TimeoutException) {
                LOG.warning("The complete chain exceeded 15 s");
            }
            return defaultResponse();
        });

package com.nexussoftware.bibliotech.network;

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;

/** Querying several ISBNs in parallel with allOf. */
public class ParallelQuery {

    private final HttpClient client;
    private final String base;

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

    public List<String> queryAll(List<String> isbns) {
        List<CompletableFuture<String>> futures = new ArrayList<>();

        // 1. Launch ALL the requests. sendAsync returns instantly,
        //    so this loop finishes in microseconds and the N requests
        //    are all in flight simultaneously.
        for (String isbn : isbns) {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(base + "/v1/books/" + isbn))
                    .header("Accept", "application/json")
                    .timeout(Duration.ofSeconds(10))
                    .GET()
                    .build();

            CompletableFuture<String> future =
                    client.sendAsync(request, BodyHandlers.ofString(StandardCharsets.UTF_8))
                            .thenApply(r -> r.statusCode() == 200
                                    ? r.body()
                                    : "ERROR " + r.statusCode() + " on " + isbn)
                            // SHIELD EVERY FUTURE BEFORE AGGREGATING IT.
                            // Without this, a single failure fails the whole
                            // allOf and we lose the N-1 good responses.
                            // It is the classic trap of 08-07.
                            .exceptionally(e -> "FAILURE on " + isbn + ": "
                                    + e.getCause().getMessage());

            futures.add(future);
        }

        // 2. allOf completes when ALL of them finish.
        CompletableFuture<Void> all = CompletableFuture.allOf(
                futures.toArray(new CompletableFuture[0]));

        // 3. Collect. join() here is safe because allOf has already
        //    guaranteed that they are all complete: it blocks nothing.
        return all.thenApply(v -> {
            List<String> results = new ArrayList<>(futures.size());
            for (CompletableFuture<String> f : futures) {
                results.add(f.join());
            }
            return results;
        }).join();      // the only real block, and it is deliberate
    }
}

// BROKEN CODE. Very common.
HttpResponse<String> r = client.send(request, BodyHandlers.ofString(UTF_8));
Metadata m = parse(r.body());            // <-- if it was a 500, body() is
                                         //     the server's error page

client.sendAsync(request, BodyHandlers.ofString(UTF_8))
        .thenApply(r -> {
            if (r.statusCode() == 404) {
                return null;        // "it does not exist" is a result, not an error
            }
            if (r.statusCode() / 100 == 5) {
                // Throwing inside a stage fails the future,
                // and the failure propagates to the first handler.
                throw new CompletionException(
                        new BiblioTechException("Server failure: " + r.statusCode()));
            }
            if (r.statusCode() != 200) {
                throw new CompletionException(
                        new BiblioTechException("Unexpected response: " + r.statusCode()));
            }
            return r.body();
        })
        .exceptionally(e -> {
            // CAREFUL: the cause arrives WRAPPED in CompletionException (08-07).
            Throwable cause = e.getCause() != null ? e.getCause() : e;
            LOG.warning("Query failed: " + cause.getMessage());
            return null;
        });

HTTP/1.1, six requests in parallel:
  connection 1: [handshake][TLS][request A............]
  connection 2: [handshake][TLS][request B............]
  ... six connections, six setups ...

HTTP/2, six requests in parallel:
  connection 1: [handshake][TLS][A|B|C|A|D|B|E|C|F|...]
  ... ONE connection, ONE setup, interleaved streams ...

// Check which version was actually negotiated.
HttpResponse<String> r = client.send(request, BodyHandlers.ofString(UTF_8));
System.out.println("Negotiated version: " + r.version());   // HTTP_2 or HTTP_1_1

package com.nexussoftware.bibliotech.network;

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;

/**
 * A minimal WebSocket example: BiblioTech would receive notices from the
 * server in real time ("the book you were waiting for is available") without polling.
 */
public class WebSocketNotices {

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

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

        // The Listener receives the events. Notice the request(1) at the end
        // of each method: WebSocket uses BACKPRESSURE, and the next message
        // has to be asked for explicitly.
        WebSocket.Listener listener = new WebSocket.Listener() {

            @Override
            public void onOpen(WebSocket ws) {
                LOG.info("WebSocket connection opened");
                ws.request(1);      // we ask for the first message
            }

            @Override
            public CompletionStage<?> onText(WebSocket ws, CharSequence data,
                                             boolean last) {
                System.out.println("NOTICE: " + data);
                ws.request(1);      // and the next one
                return null;
            }

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

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

        // buildAsync returns a CompletableFuture<WebSocket>: total
        // consistency with the rest of the API.
        WebSocket ws = client.newWebSocketBuilder()
                .buildAsync(URI.create("ws://localhost:8080/notices"), listener)
                .join();

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

        Thread.sleep(30_000);       // we listen for 30 seconds

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

// BY HAND. It works for simple cases, and IT MUST BE ESCAPED.
String json = "{"
        + "\"isbn\":\"" + escape(isbn) + "\","
        + "\"employee\":\"" + escape(employee) + "\","
        + "\"days\":" + days
        + "}";

/**
 * Minimal JSON escaping. The characters that BREAK the document
 * if they are not escaped are: the double quote, the backslash
 * and the control characters.
 */
static String escape(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();
}

/**
 * Extracts "field":"value" from a JSON document BY SUBSTRING SEARCH.
 *
 * THIS IS A TEACHING STOPGAP AND IT HAS TO BE SAID PLAINLY.
 *
 * It works with flat, simple responses like this service's,
 * and IT BREAKS with:
 *   - values containing the searched substring
 *   - escaped quotes inside a value ("Effective \"Java\"")
 *   - nested objects or arrays
 *   - a field with the same name inside an inner object
 *   - null, numeric or boolean values where text is expected
 *   - different spacing around the colon
 *
 * DOING IT PROPERLY REQUIRES A JSON LIBRARY, AND THAT IS 11-07 (JACKSON),
 * where one line -mapper.readValue(json, Metadata.class)- replaces
 * all of this and on top of that converts straight into the record. Do not
 * take this code to production.
 */
static String textField(String json, String field) {
    String mark = "\"" + field + "\"";
    int i = json.indexOf(mark);
    if (i < 0) {
        return null;
    }
    int colon = json.indexOf(':', i + mark.length());
    if (colon < 0) {
        return null;
    }
    int open = json.indexOf('"', colon);
    if (open < 0) {
        return null;
    }
    // We look for the closing quote, skipping escaped ones.
    int j = open + 1;
    StringBuilder value = new StringBuilder();
    while (j < json.length()) {
        char c = json.charAt(j);
        if (c == '\\' && j + 1 < json.length()) {
            value.append(json.charAt(j + 1));
            j += 2;
            continue;
        }
        if (c == '"') {
            return value.toString();
        }
        value.append(c);
        j++;
    }
    return null;
}

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

HttpRequest request = HttpRequest.newBuilder()
        .timeout(Duration.ofSeconds(10))            // total for the request
        .build();

// The client generates a UNIQUE identifier per logical operation
// -not per attempt- and sends it. The server stores the keys it has
// already seen and returns the previous result instead of repeating the
// operation. With this, retrying IS safe.
String key = UUID.randomUUID().toString();

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(base + "/v1/loans"))
        .header("Idempotency-Key", key)         // the SAME on every retry
        .header("Content-Type", "application/json")
        .POST(BodyPublishers.ofString(json))
        .build();

// WRONG: the token ends up in the log file, and from there in the
// backup, in the log aggregation system and in any support
// screenshot.
LOG.info("Request: " + request.headers());

// RIGHT: only what may be logged.
LOG.info(() -> "GET " + request.uri().getPath()
        + " -> " + response.statusCode()
        + " (" + ms + " ms)");

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

HttpClient client = HttpClient.newBuilder()
        .sslContext(contextWithOwnStore())           // NOT a TrustManager that accepts everything
        .build();

package com.nexussoftware.bibliotech.network;

import com.nexussoftware.bibliotech.domain.Material;
import com.nexussoftware.bibliotech.service.ConcurrentCatalog;

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;

/**
 * Enriches BiblioTech's catalogue with data from the external metadata
 * service, querying ALL the ISBNs in parallel and downloading
 * the covers without blocking a single thread.
 *
 * It solves the problem CoverSynchroniser (09-05) left open,
 * which was sequential and spent all its time waiting for the network.
 *
 * It applies: a reused HttpClient, sendAsync + thenCompose + allOf from 08-07,
 * a Semaphore from 08-05 to bound the parallelism, and LongAdder from 08-06
 * for the metrics.
 */
public class CatalogEnricher implements AutoCloseable {

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

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

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

    /**
     * Bounds the parallelism. Without it, a thousand ISBNs would produce a
     * thousand simultaneous requests and the service would return 429 or
     * block our IP. It is the Semaphore of 08-05, applied to the network.
     */
    private final Semaphore permits = new Semaphore(MAX_SIMULTANEOUS);

    // Metrics with no contention (08-06).
    private final LongAdder enriched = new LongAdder();
    private final LongAdder notFound = new LongAdder();
    private final LongAdder coversDownloaded = new LongAdder();
    private final LongAdder failed = new LongAdder();
    private final LongAdder coverBytes = new LongAdder();

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

        // Our own executor with NAMED threads (08-02): in a thread dump
        // and in every log line you will know who is doing what.
        AtomicInteger n = new AtomicInteger(1);
        this.executor = Executors.newFixedThreadPool(MAX_SIMULTANEOUS, r -> {
            Thread t = new Thread(r, "bibliotech-http-" + n.getAndIncrement());
            t.setDaemon(true);
            return t;
        });

        // ONE client, created once and reused: connection pool,
        // reused TLS sessions and HTTP/2 multiplexing.
        this.client = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_2)
                .connectTimeout(Duration.ofSeconds(5))
                .followRedirects(HttpClient.Redirect.NORMAL)
                .executor(executor)
                .build();
    }

    /** The enriched card of a material. */
    public record EnrichedCard(String isbn, String title, String author,
                               int pages, Path cover, String status) {
    }

    // =================================================================
    // Entry point
    // =================================================================

    public List<EnrichedCard> enrich(ConcurrentCatalog catalog) {
        List<Material> materials = catalog.all();
        List<String> isbns = new ArrayList<>(materials.size());
        for (Material m : materials) {
            isbns.add(m.getIsbn());
        }
        return enrichIsbns(isbns);
    }

    public List<EnrichedCard> enrichIsbns(List<String> isbns) {
        long start = System.currentTimeMillis();
        System.out.println("Enriching " + isbns.size()
                + " materials (up to " + MAX_SIMULTANEOUS + " at a time)...\n");

        try {
            Files.createDirectories(coverDirectory);
        } catch (Exception e) {
            LOG.log(Level.WARNING, "Could not create the cover directory", e);
        }

        // --- 1. Launch ALL the chains ---
        // sendAsync returns instantly, so this loop finishes in
        // microseconds with N chains under way.
        List<CompletableFuture<EnrichedCard>> futures =
                new ArrayList<>(isbns.size());
        for (String isbn : isbns) {
            futures.add(chainFor(isbn));
        }

        // --- 2. Wait for them all ---
        CompletableFuture<Void> all = CompletableFuture.allOf(
                futures.toArray(new CompletableFuture[0]));

        // --- 3. Collect ---
        List<EnrichedCard> cards = all.thenApply(v -> {
            List<EnrichedCard> list = new ArrayList<>(futures.size());
            for (CompletableFuture<EnrichedCard> f : futures) {
                // join() is safe: allOf has already guaranteed they are all complete.
                list.add(f.join());
            }
            return list;
        }).join();      // the only real block, deliberate

        report(System.currentTimeMillis() - start, isbns.size());
        return cards;
    }

    // =================================================================
    // The asynchronous chain of ONE material
    // =================================================================

    private CompletableFuture<EnrichedCard> chainFor(String isbn) {
        if (!validIsbn(isbn)) {
            failed.increment();
            return CompletableFuture.completedFuture(
                    new EnrichedCard(isbn, null, null, 0, null, "INVALID ISBN"));
        }

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(base + "/v1/books/" + isbn))
                .header("Accept", "application/json")
                .header("User-Agent", USER_AGENT)
                .timeout(Duration.ofSeconds(10))    // TOTAL limit, not per operation
                .GET()
                .build();

        // acquirePermit blocks if there are already 8 in flight. It is done BEFORE
        // the sendAsync so the semaphore limits real requests.
        acquirePermit();

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

                // --- Stage 1: check the code and keep the body ---
                .thenApply(response -> {
                    releasePermit();

                    int code = response.statusCode();
                    LOG.fine(() -> "GET /v1/books/" + isbn + " -> " + code);

                    if (code == 404) {
                        return null;        // "I do not have it" is a result
                    }
                    if (code != 200) {
                        // Throwing here fails the future; the failure reaches
                        // the exceptionally at the end.
                        throw new CompletionException(
                                new java.io.IOException("HTTP " + code
                                        + " querying " + isbn));
                    }
                    return response.body();
                })

                // --- Stage 2: parse the JSON ---
                .thenApply(body -> {
                    if (body == null) {
                        notFound.increment();
                        return new EnrichedCard(isbn, null, null, 0, null,
                                "NOT FOUND");
                    }
                    String title = textField(body, "title");
                    String author = textField(body, "author");
                    String cover = textField(body, "cover");
                    int pages = intField(body, "pages");

                    if (title == null) {
                        throw new CompletionException(
                                new java.io.IOException("Response with no title"));
                    }
                    enriched.increment();
                    return new EnrichedCard(isbn, title,
                            author == null ? "(unknown)" : author,
                            pages,
                            cover == null ? null : Path.of(cover),      // placeholder
                            "OK");
                })

                // --- Stage 3: download the cover, if there is one ---
                // thenCompose because it returns ANOTHER CompletableFuture:
                // with thenApply we would have a future of a future (08-07).
                .thenCompose(card -> {
                    if (card.cover() == null) {
                        return CompletableFuture.completedFuture(card);
                    }
                    // The 'cover' field provisionally carries the URL.
                    String url = card.cover().toString();
                    return downloadCover(url, isbn)
                            .thenApply(path -> new EnrichedCard(
                                    card.isbn(), card.title(), card.author(),
                                    card.pages(), path,
                                    path == null ? "OK (no cover)" : "OK"));
                })

                // --- Deadline for the COMPLETE chain ---
                .orTimeout(30, TimeUnit.SECONDS)

                // --- Shielding: MANDATORY before aggregating into the allOf ---
                // Without this, a single failure fails the whole allOf and
                // we lose every good card. Classic trap of 08-07.
                .exceptionally(e -> {
                    releasePermit();        // in case it failed before releasing it
                    failed.increment();
                    // The cause arrives WRAPPED in CompletionException.
                    Throwable cause = e.getCause() != null ? e.getCause() : e;
                    LOG.warning("Failure enriching " + isbn + ": "
                            + cause.getMessage());
                    return new EnrichedCard(isbn, null, null, 0, null,
                            "FAILED: " + cause.getClass().getSimpleName());
                });
    }

    /** Downloads the cover to disk. Returns null if it could not be done. */
    private CompletableFuture<Path> downloadCover(String url, String isbn) {
        if (!url.startsWith("http://") && !url.startsWith("https://")) {
            // Without this check, a "file:///etc/passwd" URL received
            // from the service would make us read local files.
            LOG.warning("Scheme not allowed in the cover of " + isbn);
            return CompletableFuture.completedFuture(null);
        }

        Path target = coverDirectory.resolve(isbn + ".jpg");

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

        acquirePermit();

        // BodyHandlers.ofFile writes straight to disk, without loading
        // the image into memory and without the copy loop of 09-05.
        return client.sendAsync(request, BodyHandlers.ofFile(target))
                .thenApply(response -> {
                    releasePermit();
                    if (response.statusCode() != 200) {
                        LOG.fine("Cover of " + isbn + ": HTTP "
                                + response.statusCode());
                        return null;
                    }
                    Path path = response.body();
                    try {
                        long size = Files.size(path);
                        if (size > MAX_COVER) {
                            Files.deleteIfExists(path);
                            LOG.warning("Cover of " + isbn + " too large");
                            return null;
                        }
                        coverBytes.add(size);
                    } catch (Exception e) {
                        LOG.fine("Could not check the size: " + e.getMessage());
                    }
                    coversDownloaded.increment();
                    return path;
                })
                .exceptionally(e -> {
                    releasePermit();
                    LOG.fine("Failure downloading the cover of " + isbn);
                    return null;    // no cover is not an enrichment failure
                });
    }

    // =================================================================
    // Semaphore
    // =================================================================

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

    private void releasePermit() {
        permits.release();
    }

    // =================================================================
    // JSON parsing: A TEACHING STOPGAP, see section 15
    // =================================================================

    /**
     * Extraction by substring search. It works with this service's flat
     * responses and breaks with nesting, arrays or repeated fields.
     * DOING IT PROPERLY IS JACKSON, AND THAT IS 11-07.
     */
    private String textField(String json, String field) {
        String mark = "\"" + field + "\"";
        int i = json.indexOf(mark);
        if (i < 0) {
            return null;
        }
        int colon = json.indexOf(':', i + mark.length());
        if (colon < 0) {
            return null;
        }
        int open = json.indexOf('"', colon);
        if (open < 0) {
            return null;
        }
        StringBuilder value = new StringBuilder();
        int j = open + 1;
        while (j < json.length()) {
            char c = json.charAt(j);
            if (c == '\\' && j + 1 < json.length()) {
                value.append(json.charAt(j + 1));
                j += 2;
                continue;
            }
            if (c == '"') {
                return value.toString();
            }
            value.append(c);
            j++;
        }
        return null;
    }

    private int intField(String json, String field) {
        String mark = "\"" + field + "\"";
        int i = json.indexOf(mark);
        if (i < 0) {
            return 0;
        }
        int j = json.indexOf(':', i + mark.length()) + 1;
        while (j < json.length() && !Character.isDigit(json.charAt(j))) {
            if (json.charAt(j) == ',' || json.charAt(j) == '}') {
                return 0;
            }
            j++;
        }
        int start = j;
        while (j < json.length() && Character.isDigit(json.charAt(j))) {
            j++;
        }
        return start == j ? 0 : Integer.parseInt(json.substring(start, j));
    }

    private boolean validIsbn(String isbn) {
        if (isbn == null || isbn.isBlank() || isbn.length() > 20) {
            return false;
        }
        // Allow list: it prevents injecting paths ("../admin") into the URL.
        for (int i = 0; i < isbn.length(); i++) {
            char c = isbn.charAt(i);
            if (!Character.isDigit(c) && c != '-') {
                return false;
            }
        }
        return true;
    }

    // =================================================================
    // Report and shutdown
    // =================================================================

    private void report(long ms, int total) {
        System.out.println();
        System.out.println("=== CATALOGUE ENRICHMENT ===");
        System.out.printf("%-26s %d%n", "Materials", total);
        System.out.printf("%-26s %d%n", "Enriched", enriched.sum());
        System.out.printf("%-26s %d%n", "Not found", notFound.sum());
        System.out.printf("%-26s %d%n", "Failed", failed.sum());
        System.out.printf("%-26s %d%n", "Covers downloaded",
                coversDownloaded.sum());
        System.out.printf("%-26s %.1f KB%n", "Cover bytes",
                coverBytes.sum() / 1024.0);
        System.out.printf("%-26s %.2f s%n", "Total time", ms / 1000.0);
        if (total > 0) {
            System.out.printf("%-26s %.1f ms%n", "Mean per material",
                    (double) ms / total);
        }
    }

    @Override
    public void close() {
        // Two-phase shutdown (08-05).
        executor.shutdown();
        try {
            if (!executor.awaitTermination(10, TimeUnit.SECONDS)) {
                LOG.warning("Requests still active; forcing the shutdown");
                executor.shutdownNow();
            }
        } catch (InterruptedException e) {
            executor.shutdownNow();
            Thread.currentThread().interrupt();       // 08-02
        }
        LOG.info("CatalogEnricher closed");
    }
}

package com.nexussoftware.bibliotech.presentation;

import com.nexussoftware.bibliotech.network.CatalogEnricher;
import com.nexussoftware.bibliotech.network.CatalogEnricher.EnrichedCard;

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

public class EnricherTest {

    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: orderly shutdown of the executor.
        try (CatalogEnricher enricher = new CatalogEnricher(
                "http://localhost:8080", Path.of("covers"))) {

            List<EnrichedCard> cards = enricher.enrichIsbns(isbns);

            System.out.println("\n--- RESULT ---");
            for (EnrichedCard c : cards) {
                System.out.printf("  %-18s %-30s %s%n",
                        c.isbn(),
                        c.title() == null ? "-" : c.title(),
                        c.status());
            }
        }
    }
}

Enriching 20 materials (up to 8 at a time)...

=== CATALOGUE ENRICHMENT ===
Materials                  20
Enriched                   17
Not found                  2
Failed                     1
Covers downloaded          15
Cover bytes                682.4 KB
Total time                 1.24 s
Mean per material          62.0 ms

--- RESULT ---
  978-0000000001     Effective Java                 OK
  978-0000000002     Design Patterns                OK
  978-0000000003     Refactoring                    OK
  978-0000000004     -                              NOT FOUND
  ...
  978-0000000019     -                              FAILED: HttpTimeoutException

package com.nexussoftware.bibliotech.network;

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;

/**
 * Asynchronous HTTP client with retries, over java.net.http.
 *
 * The key point of the exercise: the retries happen INSIDE the asynchronous
 * chain with a recursive thenCompose and delayedExecutor. No thread
 * blocks while waiting between attempts.
 */
public class ResilientAsyncClient implements AutoCloseable {

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

    private static final int MAX_ATTEMPTS = 4;
    private static final long INITIAL_WAIT_MS = 200;
    private static final long MAX_RETRY_AFTER_MS = 30_000;

    private final HttpClient client;
    private final ExecutorService executor;

    public ResilientAsyncClient() {
        AtomicInteger n = new AtomicInteger(1);
        this.executor = Executors.newFixedThreadPool(8, r -> {
            Thread t = new Thread(r, "http-resilient-" + n.getAndIncrement());
            t.setDaemon(true);
            return t;
        });
        // ONE client, reused: connection pool and TLS sessions.
        this.client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(5))
                .followRedirects(HttpClient.Redirect.NORMAL)
                .executor(executor)
                .build();
    }

    public record Response(int code, String body,
                           Map<String, List<String>> headers, int attempts) {

        public boolean success() {
            return code >= 200 && code < 300;
        }
    }

    // =================================================================
    // Public API
    // =================================================================

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

    /**
     * POST WITHOUT retries. If it times out, we do not know whether the server
     * processed it; retrying could duplicate the operation.
     */
    public CompletableFuture<Response> post(String url, String body, String type) {
        return withRetries(buildPost(url, body, type, null),
                MAX_ATTEMPTS, 0);   // starting at the last attempt = no retries
    }

    /**
     * POST WITH retries, using an idempotency key.
     *
     * The key is generated ONCE, outside the chain, and travels the same on
     * every retry. That is what lets the server recognise that it is the
     * same logical operation and not repeat it.
     */
    public CompletableFuture<Response> postIdempotent(String url, String body,
                                                      String type) {
        String key = UUID.randomUUID().toString();
        return withRetries(buildPost(url, body, type, key),
                1, INITIAL_WAIT_MS);
    }

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

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

    // =================================================================
    // Core: retries INSIDE the asynchronous chain
    // =================================================================

    private CompletableFuture<Response> withRetries(HttpRequest request,
                                                    int attempt, long wait) {

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

                // --- Case 1: there was a response. It may be a transient code. ---
                .thenCompose(response -> {
                    int code = response.statusCode();

                    if (isTransient(code) && attempt < MAX_ATTEMPTS) {
                        long realWait = waitAfter(response, wait);
                        LOG.warning(request.method() + " " + request.uri().getPath()
                                + " -> " + code + "; retry " + (attempt + 1)
                                + " in " + realWait + " ms");

                        // HERE IS THE KEY POINT OF THE EXERCISE.
                        // delayedExecutor returns an Executor that runs
                        // the task AFTER the delay, blocking no thread.
                        // A Thread.sleep here would leave a pool thread parked
                        // for the whole wait, which is exactly what we want to avoid.
                        Executor delayed = CompletableFuture.delayedExecutor(
                                realWait, TimeUnit.MILLISECONDS, executor);

                        // supplyAsync on the delayed executor + thenCompose:
                        // the recursion becomes another stage of the chain.
                        return CompletableFuture
                                .supplyAsync(() -> null, delayed)
                                .thenCompose(v -> withRetries(request,
                                        attempt + 1, wait * 2));
                    }

                    return CompletableFuture.completedFuture(new Response(
                            code, response.body(), response.headers().map(), attempt));
                })

                // --- Case 2: there was an exception. It may be transient. ---
                .handle((result, error) -> {
                    if (error == null) {
                        return CompletableFuture.completedFuture(result);
                    }
                    // The cause arrives WRAPPED in CompletionException (08-07).
                    Throwable cause = error.getCause() != null ? error.getCause() : error;

                    if (isTransient(cause) && attempt < MAX_ATTEMPTS) {
                        long realWait = withJitter(wait);
                        LOG.warning(cause.getClass().getSimpleName() + " on "
                                + request.uri().getPath() + "; retry "
                                + (attempt + 1) + " in " + realWait + " ms");

                        Executor delayed = CompletableFuture.delayedExecutor(
                                realWait, TimeUnit.MILLISECONDS, executor);
                        return CompletableFuture
                                .supplyAsync(() -> null, delayed)
                                .thenCompose(v -> withRetries(request,
                                        attempt + 1, wait * 2));
                    }

                    // Permanent or out of attempts: the failure is propagated.
                    return CompletableFuture.<Response>failedFuture(cause);
                })
                // handle returns CompletableFuture<CompletableFuture<Response>>:
                // thenCompose flattens it. It is the map/flatMap of 08-07.
                .thenCompose(f -> f);
    }

    // =================================================================
    // Policy
    // =================================================================

    private boolean isTransient(int code) {
        // The 500 is excluded on purpose: it is usually a deterministic
        // server failure that will repeat identically.
        return code == 429 || code == 502 || code == 503 || code == 504;
    }

    private boolean isTransient(Throwable t) {
        // HttpTimeoutException is a subclass of IOException, and so is
        // ConnectException: the concrete ones must be checked BEFORE IOException.
        return t instanceof HttpTimeoutException
                || t instanceof ConnectException
                || (t instanceof IOException && !(t.getMessage() != null
                        && t.getMessage().contains("UnresolvedAddress")));
    }

    private long waitAfter(HttpResponse<?> response, long computed) {
        // firstValue returns Optional because the header may be absent.
        // Here we use it with isPresent()/get(); Optional's fluent style
        // (map, orElseGet, ifPresent) is covered in 10-04.
        java.util.Optional<String> retryAfter =
                response.headers().firstValue("Retry-After");

        if (retryAfter.isPresent()) {
            try {
                // The seconds format only; the date one requires parsing
                // HTTP dates, and that is done properly in 10-05.
                long ms = Long.parseLong(retryAfter.get().strip()) * 1000;
                return Math.min(ms, MAX_RETRY_AFTER_MS);
            } catch (NumberFormatException e) {
                LOG.fine("Retry-After in date format; ignored");
            }
        }
        return withJitter(computed);
    }

    /**
     * Randomises the wait by 20 %.
     * It avoids the "thundering herd": if a hundred clients fail at once and all
     * retry exactly at 200 ms, the synchronised burst takes down again
     * the service that was recovering, in an endless cycle.
     */
    private long withJitter(long base) {
        if (base <= 0) {
            return 0;
        }
        long variation = Math.max(1, base / 5);
        return base + ThreadLocalRandom.current().nextLong(-variation, variation + 1);
    }

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

    // =================================================================
    // Test
    // =================================================================

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

        try (ResilientAsyncClient c = new ResilientAsyncClient()) {

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

            for (int i = 1; i <= 10; i++) {
                futures.add(c.get(base + "/v1/books/978-000000000" + (i % 10))
                        // Individual shielding BEFORE the allOf: without it, one
                        // failure would take down all ten.
                        .exceptionally(e -> new Response(-1,
                                "FAILURE: " + e.getCause().getMessage(),
                                Map.of(), MAX_ATTEMPTS)));
            }

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

            int ok = 0, failed = 0, retried = 0;
            for (CompletableFuture<Response> f : futures) {
                Response r = f.join();      // safe: allOf has already finished
                if (r.success()) {
                    ok++;
                } else {
                    failed++;
                }
                if (r.attempts() > 1) {
                    retried++;
                }
                System.out.printf("  code=%-5d attempts=%d%n", r.code(), r.attempts());
            }

            System.out.println();
            System.out.printf("Successful: %d   Failed: %d   With retry: %d%n",
                    ok, failed, retried);
            System.out.printf("Total time: %d ms%n", ms);
        }
    }
}

package com.nexussoftware.bibliotech.network;

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;

/**
 * Compares four strategies for making N HTTP requests.
 * It proves with numbers why the bounded asynchronous one is the answer.
 */
public class StrategyComparator {

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

    public StrategyComparator(String base, int requests) {
        this.base = base;
        this.requests = requests;
        // ONE client for every strategy: that way the comparison is
        // fair and we do not measure the cost of creating clients.
        this.client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(5))
                .build();
    }

    public record Result(String strategy, long ms, int successful, int failed,
                         double meanLatencyMs, int maxThreads) {
    }

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

    // =================================================================
    // Thread watcher
    // =================================================================

    /** Samples Thread.activeCount() on a separate thread during the measurement. */
    private static class ThreadWatcher {
        private final AtomicInteger maximum = new AtomicInteger();
        private volatile boolean active = true;
        private Thread thread;

        void start() {
            thread = new Thread(() -> {
                while (active) {
                    maximum.updateAndGet(m -> Math.max(m, Thread.activeCount()));
                    try {
                        Thread.sleep(10);
                    } catch (InterruptedException e) {
                        Thread.currentThread().interrupt();
                        return;
                    }
                }
            }, "thread-watcher");
            thread.setDaemon(true);
            thread.start();
        }

        int stop() {
            active = false;
            try {
                thread.join(500);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
            return maximum.get();
        }
    }

    // =================================================================
    // A: sequential
    // =================================================================

    public Result sequential() {
        ThreadWatcher watcher = new ThreadWatcher();
        watcher.start();

        int successful = 0, failed = 0;
        long latencySum = 0;
        long t0 = System.currentTimeMillis();

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

        long ms = System.currentTimeMillis() - t0;
        return new Result("A. Sequential (send in a loop)", ms, successful, failed,
                requests == 0 ? 0 : (double) latencySum / requests,
                watcher.stop());
    }

    // =================================================================
    // B: thread pool with blocking send
    // =================================================================

    public Result blockingPool() throws InterruptedException {
        ThreadWatcher watcher = new ThreadWatcher();
        watcher.start();

        AtomicInteger successful = new AtomicInteger();
        AtomicInteger failed = new AtomicInteger();
        LongAdder latencySum = new LongAdder();

        ExecutorService pool = Executors.newFixedThreadPool(8);
        CountDownLatch start = new CountDownLatch(1);
        CountDownLatch finish = new CountDownLatch(requests);

        for (int i = 0; i < requests; i++) {
            final int n = i;
            pool.execute(() -> {
                try {
                    start.await();      // they all start at once
                    long p0 = System.nanoTime();
                    // send BLOCKS the pool thread for the whole network
                    // wait. Eight threads = eight simultaneous requests,
                    // and seven of every eight threads sit doing nothing.
                    HttpResponse<Void> r = client.send(requestFor(n),
                            BodyHandlers.discarding());
                    latencySum.add((System.nanoTime() - p0) / 1_000_000);
                    if (r.statusCode() == 200) {
                        successful.incrementAndGet();
                    } else {
                        failed.incrementAndGet();
                    }
                } catch (IOException e) {
                    failed.incrementAndGet();
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                } finally {
                    finish.countDown();
                }
            });
        }

        long t0 = System.currentTimeMillis();
        start.countDown();
        finish.await();
        long ms = System.currentTimeMillis() - t0;

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

        return new Result("B. Pool of 8 threads (blocking send)", ms,
                successful.get(), failed.get(),
                (double) latencySum.sum() / requests, watcher.stop());
    }

    // =================================================================
    // C: asynchronous, unbounded
    // =================================================================

    public Result asyncUnbounded() {
        ThreadWatcher watcher = new ThreadWatcher();
        watcher.start();

        AtomicInteger successful = new AtomicInteger();
        AtomicInteger failed = new AtomicInteger();
        LongAdder latencySum = new LongAdder();

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

        for (int i = 0; i < requests; i++) {
            long p0 = System.nanoTime();
            futures.add(client.sendAsync(requestFor(i), BodyHandlers.discarding())
                    .thenAccept(r -> {
                        latencySum.add((System.nanoTime() - p0) / 1_000_000);
                        if (r.statusCode() == 200) {
                            successful.incrementAndGet();
                        } else {
                            failed.incrementAndGet();
                        }
                    })
                    // Individual shielding: without it, one failure fails the allOf.
                    .exceptionally(e -> {
                        failed.incrementAndGet();
                        return null;
                    }));
        }

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

        return new Result("C. Async unbounded (sendAsync + allOf)", ms,
                successful.get(), failed.get(),
                (double) latencySum.sum() / requests, watcher.stop());
    }

    // =================================================================
    // D: asynchronous bounded with a Semaphore
    // =================================================================

    public Result asyncBounded(int simultaneous) {
        ThreadWatcher watcher = new ThreadWatcher();
        watcher.start();

        AtomicInteger successful = new AtomicInteger();
        AtomicInteger failed = new AtomicInteger();
        LongAdder latencySum = new LongAdder();
        Semaphore permits = new Semaphore(simultaneous);

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

        for (int i = 0; i < requests; i++) {
            try {
                // The semaphore limits how many requests are IN FLIGHT,
                // not how many threads there are. That is the difference from strategy B.
                permits.acquire();
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                break;
            }
            long p0 = System.nanoTime();
            futures.add(client.sendAsync(requestFor(i), BodyHandlers.discarding())
                    .thenAccept(r -> {
                        permits.release();
                        latencySum.add((System.nanoTime() - p0) / 1_000_000);
                        if (r.statusCode() == 200) {
                            successful.incrementAndGet();
                        } else {
                            failed.incrementAndGet();
                        }
                    })
                    .exceptionally(e -> {
                        permits.release();      // ALSO on failure, or it leaks
                        failed.incrementAndGet();
                        return null;
                    }));
        }

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

        return new Result("D. Async bounded to " + simultaneous, ms,
                successful.get(), failed.get(),
                (double) latencySum.sum() / requests, watcher.stop());
    }

    // =================================================================
    // Running it
    // =================================================================

    public void compare() throws InterruptedException {
        // WARM-UP: the first round loads classes, compiles with the JIT
        // and establishes the first connections. Without discarding it, the first
        // strategy measured would be unfairly penalised.
        System.out.println("Warming up...");
        for (int i = 0; i < 5; i++) {
            try {
                client.send(requestFor(i), BodyHandlers.discarding());
            } catch (Exception ignored) {
                // The warm-up does not have to succeed.
            }
        }

        System.out.println("Measuring " + requests + " requests per strategy...\n");

        List<Result> results = new ArrayList<>();
        results.add(sequential());
        results.add(blockingPool());
        results.add(asyncUnbounded());
        results.add(asyncBounded(8));

        long reference = results.get(0).ms();

        System.out.printf("%-42s %9s %8s %10s %9s %8s%n",
                "STRATEGY", "TIME", "REQ/S", "MEAN LAT.", "THREADS", "GAIN");
        System.out.println("-".repeat(95));
        for (Result r : results) {
            System.out.printf("%-42s %8d ms %8.0f %8.1f ms %9d %7.1fx%n",
                    r.strategy(), r.ms(),
                    r.ms() == 0 ? 0 : requests * 1000.0 / r.ms(),
                    r.meanLatencyMs(), r.maxThreads(),
                    r.ms() == 0 ? 0 : (double) reference / r.ms());
        }
    }

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

Warming up...
Measuring 50 requests per strategy...

STRATEGY                                        TIME    REQ/S  MEAN LAT.   THREADS     GAIN
-----------------------------------------------------------------------------------------------
A. Sequential (send in a loop)               10214 ms        5    204.1 ms         9     1.0x
B. Pool of 8 threads (blocking send)          1428 ms       35    221.6 ms        18     7.2x
C. Async unbounded (sendAsync + allOf)         287 ms      174    263.4 ms        14    35.6x
D. Async bounded to 8                         1391 ms       36    215.2 ms        12     7.3x

package com.nexussoftware.bibliotech.network;

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;

/**
 * Status dashboard of the services BiblioTech depends on.
 * It checks them all in parallel every N seconds and shows a console dashboard.
 */
public class ServiceStatusDashboard implements AutoCloseable {

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

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

    /** A service to watch. */
    public record Service(String name, String url, int expectedCode) {
    }

    public enum Status {
        UP('#'), DEGRADED('-'), DOWN('.');

        final char symbol;

        Status(char symbol) {
            this.symbol = symbol;
        }
    }

    /** The result of one check. */
    public record Check(Status status, int code, long latencyMs,
                        String version, String detail) {
    }

    private final List<Service> services;
    private final HttpClient client;
    private final ScheduledExecutorService scheduler;

    /**
     * History per service. ConcurrentHashMap because the scheduler thread
     * writes it and the asynchronous stages read it (08-06).
     */
    private final Map<String, Deque<Check>> history = new ConcurrentHashMap<>();
    /** Last known status, so as not to repeat the alert on every cycle. */
    private final Map<String, Status> lastStatus = new ConcurrentHashMap<>();

    private final AtomicInteger cycles = new AtomicInteger();

    public ServiceStatusDashboard(List<Service> services) {
        this.services = services;

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

        this.scheduler = Executors.newSingleThreadScheduledExecutor(r -> {
            Thread t = new Thread(r, "dashboard-scheduler");
            t.setDaemon(true);
            return t;
        });

        for (Service s : services) {
            history.put(s.name(), new ArrayDeque<>(HISTORY_SIZE));
            lastStatus.put(s.name(), Status.UP);
        }
    }

    // =================================================================
    // Startup
    // =================================================================

    public void start(int intervalSeconds) {
        // scheduleAtFixedRate from 08-05.
        scheduler.scheduleAtFixedRate(this::safeCycle,
                0, intervalSeconds, TimeUnit.SECONDS);
        LOG.info("Status dashboard running (every " + intervalSeconds + " s)");
    }

    /**
     * MANDATORY safety wrapper.
     *
     * If an exception escapes a scheduleAtFixedRate task, the task
     * IS CANCELLED SILENTLY and the dashboard stops updating without anybody
     * noticing: no exception, no log, nothing. It is the trap of 08-05.
     */
    private void safeCycle() {
        try {
            cycle();
        } catch (RuntimeException e) {
            LOG.log(Level.SEVERE, "Failure in the dashboard cycle", e);
        }
    }

    // =================================================================
    // One check cycle
    // =================================================================

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

        // 1. Launch ALL the checks in parallel.
        List<CompletableFuture<Void>> futures = new ArrayList<>(services.size());
        for (Service s : services) {
            futures.add(check(s));
        }

        // 2. Wait for them all. join() here blocks the scheduler thread,
        //    which is correct: we do not want to paint a half-finished
        //    dashboard or overlap two cycles.
        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();

        cycles.incrementAndGet();
        render(System.currentTimeMillis() - t0);
    }

    private CompletableFuture<Void> check(Service service) {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(service.url()))
                .header("User-Agent", "BiblioTech-Dashboard/1.0")
                .header("Accept", "*/*")
                .timeout(Duration.ofMillis(LIMIT_MS))       // TOTAL limit
                .GET()
                .build();

        long start = System.nanoTime();

        // discarding(): only the code is of interest, not the body. But it
        // CONSUMES it, which is what allows the connection to be reused.
        return client.sendAsync(request, BodyHandlers.discarding())
                .thenAccept(response -> {
                    long ms = (System.nanoTime() - start) / 1_000_000;
                    int code = response.statusCode();

                    Status status = code == service.expectedCode()
                            ? Status.UP
                            : Status.DEGRADED;

                    store(service, new Check(status, code, ms,
                            response.version().toString(),
                            status == Status.DEGRADED
                                    ? "expected " + service.expectedCode() : ""));
                })
                // Individual shielding: a service that is down cannot stop
                // the others being checked or the dashboard being painted.
                .exceptionally(e -> {
                    long ms = (System.nanoTime() - start) / 1_000_000;
                    Throwable cause = e.getCause() != null ? e.getCause() : e;
                    store(service, new Check(Status.DOWN, -1, ms,
                            "-", cause.getClass().getSimpleName()));
                    return null;
                });
    }

    private void store(Service service, Check c) {
        Deque<Check> queue = history.get(service.name());
        synchronized (queue) {      // ArrayDeque is not thread-safe
            if (queue.size() >= HISTORY_SIZE) {
                queue.removeFirst();
            }
            queue.addLast(c);
        }

        // Alert ONLY on a status change, not on every cycle: a
        // service down for an hour would generate 360 identical alerts.
        Status previous = lastStatus.put(service.name(), c.status());
        if (previous != c.status()) {
            if (c.status() == Status.DOWN) {
                LOG.severe("ALERT: " + service.name() + " has GONE DOWN ("
                        + c.detail() + ")");
            } else if (previous == Status.DOWN) {
                LOG.info("RECOVERED: " + service.name() + " is replying again");
            } else {
                LOG.warning("CHANGE: " + service.name() + " " + previous
                        + " -> " + c.status());
            }
        }
    }

    // =================================================================
    // Painting
    // =================================================================

    private void render(long cycleMs) {
        StringBuilder sb = new StringBuilder();
        sb.append("\033[H\033[2J");     // clear the screen
        sb.append("=== STATUS DASHBOARD - BIBLIOTECH ===\n");
        sb.append(String.format("Cycle %d   check in %d ms%n%n",
                cycles.get(), cycleMs));
        sb.append(String.format("%-22s %-11s %7s %6s %-9s %-22s %7s%n",
                "SERVICE", "STATUS", "LATENCY", "CODE", "VERSION",
                "HISTORY", "AVAIL."));
        sb.append("-".repeat(96)).append('\n');

        for (Service s : services) {
            Deque<Check> queue = history.get(s.name());
            List<Check> copy;
            synchronized (queue) {
                copy = new ArrayList<>(queue);
            }
            if (copy.isEmpty()) {
                continue;
            }
            Check last = copy.get(copy.size() - 1);

            // History bar and availability calculation.
            StringBuilder bar = new StringBuilder();
            int up = 0;
            for (Check c : copy) {
                bar.append(c.status().symbol);
                if (c.status() == Status.UP) {
                    up++;
                }
            }
            double availability = 100.0 * up / copy.size();

            sb.append(String.format("%-22s %-11s %6d ms %6s %-9s %-22s %6.1f%%%n",
                    s.name(),
                    last.status(),
                    last.latencyMs(),
                    last.code() < 0 ? "-" : String.valueOf(last.code()),
                    last.version().replace("HTTP_", "HTTP/"),
                    bar,
                    availability));

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

        sb.append("-".repeat(96)).append('\n');
        sb.append("Key: # up   - degraded   . down\n");
        System.out.print(sb);
    }

    @Override
    public void close() {
        // Two-phase shutdown (08-05).
        scheduler.shutdown();
        try {
            if (!scheduler.awaitTermination(5, TimeUnit.SECONDS)) {
                scheduler.shutdownNow();
            }
        } catch (InterruptedException e) {
            scheduler.shutdownNow();
            Thread.currentThread().interrupt();       // 08-02
        }
        LOG.info("Status dashboard stopped after " + cycles.get() + " cycles");
    }

    // =================================================================
    // Startup
    // =================================================================

    public static void main(String[] args) throws InterruptedException {
        List<Service> services = List.of(
                new Service("catalog-btcp", "http://localhost:9092/", 200),
                new Service("metadata", "http://localhost:8080/health", 200),
                new Service("covers", "http://localhost:8081/health", 200),
                new Service("notices", "http://localhost:8082/health", 200),
                new Service("missing", "http://localhost:9999/health", 200));

        ServiceStatusDashboard dashboard = new ServiceStatusDashboard(services);

        // Shutdown hook: Ctrl+C, SIGTERM from Docker or systemd (09-03).
        Runtime.getRuntime().addShutdownHook(
                new Thread(dashboard::close, "dashboard-shutdown"));

        dashboard.start(10);

        // The scheduler uses daemon threads: main has to be kept alive.
        Thread.currentThread().join();
    }
}

=== STATUS DASHBOARD - BIBLIOTECH ===
Cycle 14   check in 3012 ms

SERVICE                STATUS      LATENCY   CODE VERSION   HISTORY                 AVAIL.
------------------------------------------------------------------------------------------------
catalog-btcp           UP                4 ms    200 HTTP/1_1  ##############          100.0%
metadata               UP               38 ms    200 HTTP/2    #############-           92.9%
  expected 200
covers                 UP               21 ms    200 HTTP/2    ##############          100.0%
notices                DEGRADED        104 ms    503 HTTP/1_1  ###########---           78.6%
  expected 200
missing                DOWN           2001 ms      - -         ..............            0.0%
  ConnectException
------------------------------------------------------------------------------------------------
Key: # up   - degraded   . down