https://api.nexussoftware.com:8443/v1/books/search?isbn=978-0000000001&format=json#summary
 \___/   \____________________/\__/\_______________/\__________________________/\_______/
   |               |            |         |                     |                    |
scheme           host         port      path                  query             fragment

import java.net.URL;

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

System.out.println("Protocol   : " + url.getProtocol());  // https
System.out.println("Host       : " + url.getHost());      // api.nexussoftware.com
System.out.println("Port       : " + url.getPort());      // 8443
System.out.println("Default    : " + url.getDefaultPort()); // 443
System.out.println("Path       : " + url.getPath());      // /v1/books/search
System.out.println("Query      : " + url.getQuery());     // isbn=978-...&format=json
System.out.println("Fragment   : " + url.getRef());       // summary
System.out.println("File       : " + url.getFile());      // path + ? + query

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

// This comparison PERFORMS A DNS LOOKUP and may take seconds.
// And it returns true if both names resolve to the same address.
boolean same = a.equals(b);

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

// 1. Build and manipulate with URI: strict validation, no DNS.
URI uri = new URI("https", "api.nexussoftware.com", "/v1/books/search",
                  "isbn=978-0000000001", null);
//                 scheme   host          path        query           fragment

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

// 2. Convert to URL only in order to connect.
URL url = uri.toURL();

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

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

Searching for the title "Naïve Set Theory":

  WRONG: /search?title=Naïve Set Theory
         -> The space breaks the HTTP request (the server thinks the path
            ends at "Naïve" and that "Set" is the protocol version).
         -> The ï, unencoded, arrives as bytes the server may
            interpret in another encoding.

  RIGHT: /search?title=Na%C3%AFve+Set+Theory
         -> The space is +, and the ï is its two UTF-8 bytes: C3 AF.

  Searching for author = "Bloch & Gamma"

  WRONG: /search?author=Bloch & Gamma&admin=true
         -> The server sees TWO parameters: author="Bloch " and " Gamma"
         -> And if the attacker writes "&admin=true", they inject a parameter.

  RIGHT: /search?author=Bloch+%26+Gamma

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

String title = "Naïve Set Theory";
String encoded = URLEncoder.encode(title, StandardCharsets.UTF_8);
System.out.println(encoded);        // Na%C3%AFve+Set+Theory

String back = URLDecoder.decode(encoded, StandardCharsets.UTF_8);
System.out.println(back);           // Naïve Set Theory

// WRONG: in the path, + does not mean space.
String path = "/books/" + URLEncoder.encode("Effective Java", UTF_8);
// -> /books/Effective+Java   (the server will look for a book with a + in the title)

// RIGHT: let URI encode the path correctly.
URI uri = new URI("https", "api.nexussoftware.com",
                  "/books/Effective Java", null, null);
// -> https://api.nexussoftware.com/books/Effective%20Java

package com.nexussoftware.bibliotech.network;

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

/**
 * Builder of query strings with correct encoding.
 * LinkedHashMap so the order is predictable (useful when debugging and caching).
 */
public class UrlQuery {

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

    public UrlQuery with(String key, String value) {
        if (value != null) {
            parameters.put(key, value);
        }
        return this;    // chainable
    }

    public UrlQuery with(String key, int value) {
        parameters.put(key, String.valueOf(value));
        return this;
    }

    /** Returns "a=1&b=2" with everything encoded, or "" if there are no parameters. */
    public String build() {
        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> e : parameters.entrySet()) {
            if (sb.length() > 0) {
                sb.append('&');
            }
            // BOTH the key AND the value are encoded: a key with
            // odd characters breaks the request just as a value does.
            sb.append(URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8));
            sb.append('=');
            sb.append(URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8));
        }
        return sb.toString();
    }
}

String query = new UrlQuery()
        .with("title", "Naïve Set Theory")
        .with("author", "Bloch & Gamma")
        .with("max", 10)
        .build();
// title=Na%C3%AFve+Set+Theory&author=Bloch+%26+Gamma&max=10

GET /v1/books/978-0000000001 HTTP/1.1\r\n       <- request line
Host: api.nexussoftware.com\r\n                 <- headers
Accept: application/json\r\n
User-Agent: BiblioTech/1.0\r\n
Connection: close\r\n
\r\n                                            <- EMPTY LINE: end of headers
                                                <- (the body would go here, if there were one)

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

HTTP/1.1 200 OK\r\n                             <- status line
Content-Type: application/json; charset=utf-8\r\n  <- headers
Content-Length: 79\r\n
Date: Wed, 05 Aug 2026 09:14:22 GMT\r\n
Server: nginx/1.24.0\r\n
\r\n                                            <- empty line
{"isbn":"978-0000000001","title":"Effective Java","author":"Bloch","pages":416}

nc -l 8080

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

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

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

{"isbn":"978-0000000001","title":"Effective Java"}

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

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

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

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

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

package com.nexussoftware.bibliotech.network;

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

/** An HTTP GET request with HttpURLConnection, done correctly. */
public class GetExample {

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

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

        // 1. openConnection() does NOT connect: it returns a configuration object.
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();

        try {
            // 2. Configuration. ALL of this must go BEFORE getResponseCode().
            connection.setRequestMethod("GET");
            connection.setRequestProperty("Accept", "application/json");
            connection.setRequestProperty("User-Agent", "BiblioTech/1.0");
            connection.setRequestProperty("Accept-Charset", "UTF-8");

            // NEVER without time limits. Both of them, and they differ (09-02).
            connection.setConnectTimeout(5_000);    // establishing the connection
            connection.setReadTimeout(10_000);      // waiting for data

            // 3. HERE it really connects and reads the response.
            int code = connection.getResponseCode();
            String message = connection.getResponseMessage();
            System.out.println("Status: " + code + " " + message);

            // 4. Response headers.
            System.out.println("Content-Type  : " + connection.getContentType());
            System.out.println("Content-Length: " + connection.getContentLengthLong());

            for (Map.Entry<String, List<String>> e : connection.getHeaderFields().entrySet()) {
                // CAREFUL: the null key holds the STATUS LINE.
                // It is an API oddity that surprises you the first time.
                String name = e.getKey() == null ? "(status line)" : e.getKey();
                System.out.println("  " + name + ": " + e.getValue());
            }

            // 5. The body: getInputStream if it went well, getErrorStream if not.
            //    THIS distinction is classic mistake number two.
            InputStream body = (code >= 200 && code < 400)
                    ? connection.getInputStream()
                    : connection.getErrorStream();

            if (body == null) {
                System.out.println("(no body)");
                return;
            }

            Charset charset = charsetOf(connection.getContentType());
            try (BufferedReader reader = new BufferedReader(
                    new InputStreamReader(body, charset))) {
                String line;
                while ((line = reader.readLine()) != null) {
                    System.out.println(line);
                }
            }

        } finally {
            // 6. disconnect() releases the connection (or returns it to the internal pool).
            connection.disconnect();
        }
    }

    /**
     * Extracts the charset from the Content-Type. Assuming UTF-8 works
     * almost always and fails exactly when it hurts most.
     */
    static Charset charsetOf(String contentType) {
        if (contentType != null) {
            for (String part : contentType.split(";")) {
                String p = part.strip();
                if (p.toLowerCase().startsWith("charset=")) {
                    String name = p.substring("charset=".length())
                            .replace("\"", "").strip();
                    try {
                        return Charset.forName(name);
                    } catch (Exception e) {
                        LOG.warning("Unknown charset: " + name + "; using UTF-8");
                    }
                }
            }
        }
        return StandardCharsets.UTF_8;      // sensible fallback
    }
}

connection.setConnectTimeout(5_000);    // establishing the TCP connection
connection.setReadTimeout(10_000);      // waiting for data, per operation

// BROKEN CODE.
int code = connection.getResponseCode();
InputStream input = connection.getInputStream();   // <-- THROWS on a 404

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

{"error":"invalid_isbn","message":"The ISBN must have 13 digits","field":"isbn"}

int code = connection.getResponseCode();

InputStream body = (code >= 200 && code < 400)
        ? connection.getInputStream()
        : connection.getErrorStream();

/**
 * Reads the response body, whether it comes through the normal stream or the error one.
 * Returns an empty string if there is no body.
 */
static String readBody(HttpURLConnection connection, int code) throws IOException {
    InputStream input = (code >= 200 && code < 400)
            ? connection.getInputStream()
            : connection.getErrorStream();

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

    Charset charset = charsetOf(connection.getContentType());
    // readAllBytes is convenient but UNBOUNDED: a giant response
    // exhausts memory. We bound it, as in 09-03.
    try (InputStream stream = input) {
        byte[] bytes = stream.readNBytes(MAX_BODY);
        if (bytes.length == MAX_BODY) {
            LOG.warning("Response truncated to " + MAX_BODY + " bytes");
        }
        return new String(bytes, charset);
    }
}

package com.nexussoftware.bibliotech.network;

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

/** POST with a JSON body using HttpURLConnection. */
public class PostExample {

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

        try {
            connection.setRequestMethod("POST");

            // setDoOutput(true) is what enables getOutputStream().
            // CAREFUL: it also changes the default method to POST, so
            // if you call setDoOutput(true) after a setRequestMethod("GET"),
            // the request goes out as POST. A classic trap of this API.
            connection.setDoOutput(true);

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

            // The body, built by hand. Escaping the quotes and the
            // backslashes is essential; doing it PROPERLY requires a JSON
            // library, and that is 11-07.
            String json = "{\"isbn\":\"978-0000000001\",\"employee\":\"Marta Ruiz\"}";
            byte[] body = json.getBytes(StandardCharsets.UTF_8);

            // Content-Length in BYTES, not in characters: with accents
            // they differ, and a wrong value corrupts the request.
            connection.setFixedLengthStreamingMode(body.length);

            try (OutputStream output = connection.getOutputStream()) {
                output.write(body);
                output.flush();     // the usual flush
            }

            int code = connection.getResponseCode();
            System.out.println("Status: " + code);
            System.out.println("Body: " + readBody(connection, code));

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

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

// Here it IS correct to use URLEncoder: this is exactly its format.
String body = new UrlQuery()
        .with("isbn", "978-0000000001")
        .with("employee", "Marta Ruiz")
        .build();
// isbn=978-0000000001&employee=Marta+Ruiz

// Global, for the whole JVM. Avoid it: it affects code that is not yours.
HttpURLConnection.setFollowRedirects(false);

// Per instance. This is the one you should use.
connection.setInstanceFollowRedirects(false);

/** Follows redirects by hand, with a limit and scheme control. */
static HttpURLConnection followRedirects(URL url, int maxHops)
        throws IOException {
    URL current = url;
    for (int hop = 0; hop <= maxHops; hop++) {
        HttpURLConnection connection = (HttpURLConnection) current.openConnection();
        connection.setInstanceFollowRedirects(false);   // we manage them ourselves
        connection.setConnectTimeout(5_000);
        connection.setReadTimeout(10_000);

        int code = connection.getResponseCode();
        if (code < 300 || code >= 400) {
            return connection;      // not a redirect: we have arrived
        }

        String target = connection.getHeaderField("Location");
        connection.disconnect();

        if (target == null) {
            throw new IOException("Redirect " + code + " with no Location header");
        }
        // resolve() handles relative Location values ("/new/path"),
        // which are perfectly legal and surprising if unexpected.
        current = current.toURI().resolve(target).toURL();
        LOG.info("Redirect " + code + " -> " + current);
    }
    throw new IOException("Too many redirects (more than " + maxHops + ")");
}

// If you set this BY HAND, YOU have to decompress.
connection.setRequestProperty("Accept-Encoding", "gzip");

int code = connection.getResponseCode();
InputStream input = connection.getInputStream();

if ("gzip".equalsIgnoreCase(connection.getContentEncoding())) {
    input = new GZIPInputStream(input);         // a module 7 decorator
}

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

// ... the same as always ...

// Additional methods, if you need to inspect the certificate:
System.out.println("Cipher     : " + connection.getCipherSuite());
System.out.println("Certificate: " + connection.getServerCertificates()[0]);

GET /v1/books/{isbn}
  200 -> {"isbn":"...","title":"...","author":"...","pages":416,
          "cover":"https://metadata.nexussoftware.local/covers/978-0000000001.jpg"}
  404 -> {"error":"not_found","message":"Unknown ISBN"}
  429 -> Retry-After header with the seconds to wait

GET /covers/{isbn}.jpg
  200 -> binary JPEG image

package com.nexussoftware.bibliotech.network;

import com.nexussoftware.bibliotech.exception.BiblioTechException;

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

/**
 * Client of Nexus Software's external metadata service,
 * with HttpURLConnection.
 *
 * It shows the correct use of the old API: time limits, explicit checking
 * of the status code, getErrorStream for errors, bounded reading
 * and translation into domain exceptions.
 */
public class MetadataClient {

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

    private static final int CONNECT_TIMEOUT_MS = 5_000;
    private static final int READ_TIMEOUT_MS = 10_000;
    /** No legitimate metadata card exceeds this. A memory defence. */
    private static final int MAX_BODY = 256 * 1024;
    /** No legitimate cover exceeds this. */
    private static final long MAX_COVER = 5L * 1024 * 1024;
    private static final String USER_AGENT = "BiblioTech/1.0 (+https://nexussoftware.com)";

    private final String base;

    public MetadataClient(String base) {
        // It is normalised so paths can be concatenated without duplicating slashes.
        this.base = base.endsWith("/") ? base.substring(0, base.length() - 1) : base;
    }

    /** The metadata of a book exactly as the service returns it. */
    public record Metadata(String isbn, String title, String author,
                           int pages, String coverUrl) {
    }

    // =================================================================
    // Metadata query
    // =================================================================

    /** Queries an ISBN. Returns null if the service does not know it (404). */
    public Metadata query(String isbn) throws BiblioTechException {
        validateIsbn(isbn);

        HttpURLConnection connection = null;
        try {
            // The ISBN goes in the PATH, so it is encoded with URI's
            // multi-argument constructor, not with URLEncoder (which would use + for space).
            URI uri = new URI("http", null, hostOf(base), portOf(base),
                    pathOf(base) + "/v1/books/" + isbn, null, null);
            URL url = uri.toURL();

            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.setRequestProperty("Accept", "application/json");
            connection.setRequestProperty("User-Agent", USER_AGENT);
            connection.setConnectTimeout(CONNECT_TIMEOUT_MS);
            connection.setReadTimeout(READ_TIMEOUT_MS);
            connection.setInstanceFollowRedirects(true);

            // HERE it really connects.
            int code = connection.getResponseCode();
            LOG.fine(() -> "GET " + url + " -> " + code);

            // A 404 is not a program error: it is "I do not have it".
            if (code == HttpURLConnection.HTTP_NOT_FOUND) {
                consumeAndClose(connection, code);
                return null;
            }

            // 429: the service is asking us to slow down.
            if (code == 429) {
                String wait = connection.getHeaderField("Retry-After");
                consumeAndClose(connection, code);
                throw new BiblioTechException(
                        "The metadata service has rate-limited the requests."
                        + (wait == null ? "" : " Retry in " + wait + " s."));
            }

            if (code != HttpURLConnection.HTTP_OK) {
                // The error body almost always explains what happened:
                // reading it is the difference between debugging in two minutes
                // or in two hours.
                String detail = readBody(connection, code);
                LOG.warning("Response " + code + " from the service: " + trim(detail));
                throw new BiblioTechException(
                        "The metadata service replied " + code);
            }

            String body = readBody(connection, code);
            return parse(body, isbn);

        } catch (SocketTimeoutException e) {
            // TRANSIENT: worth a retry with increasing backoff.
            LOG.warning("Timed out querying the metadata of " + isbn);
            throw new BiblioTechException(
                    "The metadata service is not replying in time.", e);

        } catch (UnknownHostException e) {
            // PERMANENT: misconfiguration.
            LOG.severe("Unresolvable metadata host: " + base);
            throw new BiblioTechException(
                    "The metadata service cannot be found.", e);

        } catch (IOException | java.net.URISyntaxException e) {
            LOG.log(Level.WARNING, "Failure querying the metadata of " + isbn, e);
            throw new BiblioTechException(
                    "Error querying the metadata service.", e);

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

    // =================================================================
    // Cover download (binary to disk)
    // =================================================================

    /**
     * Downloads the cover to a file. It combines HTTP with module 7's NIO.2.
     * ATOMIC write: first to a temporary file, then moved. That way an
     * interrupted download never leaves a half-written JPEG in the catalogue.
     */
    public Path downloadCover(String coverUrl, Path target)
            throws BiblioTechException {

        HttpURLConnection connection = null;
        Path temporary = null;

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

            // http and https only: without this, a "file:///etc/passwd" URL
            // received from the service would make us read local files.
            String scheme = url.getProtocol();
            if (!scheme.equals("http") && !scheme.equals("https")) {
                throw new BiblioTechException("Scheme not allowed: " + scheme);
            }

            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("GET");
            connection.setRequestProperty("Accept", "image/jpeg, image/png, image/*");
            connection.setRequestProperty("User-Agent", USER_AGENT);
            connection.setConnectTimeout(CONNECT_TIMEOUT_MS);
            connection.setReadTimeout(30_000);      // an image takes longer

            int code = connection.getResponseCode();
            if (code != HttpURLConnection.HTTP_OK) {
                consumeAndClose(connection, code);
                throw new BiblioTechException(
                        "The cover could not be downloaded: HTTP " + code);
            }

            // Content-Length is INDICATIVE: it may be missing (-1) or lie.
            // It is checked before AND during the download.
            long announced = connection.getContentLengthLong();
            if (announced > MAX_COVER) {
                consumeAndClose(connection, code);
                throw new BiblioTechException(
                        "Cover too large: " + announced + " bytes");
            }

            String type = connection.getContentType();
            if (type != null && !type.startsWith("image/")) {
                consumeAndClose(connection, code);
                throw new BiblioTechException("The resource is not an image: " + type);
            }

            Files.createDirectories(target.getParent());
            temporary = Files.createTempFile(target.getParent(), "cover-", ".tmp");

            long downloaded = 0;
            try (InputStream input = connection.getInputStream();
                 OutputStream output = Files.newOutputStream(temporary)) {

                byte[] buffer = new byte[8192];
                int read;
                while ((read = input.read(buffer)) != -1) {
                    downloaded += read;
                    // The limit is checked DURING the download as well:
                    // the Content-Length may lie or be absent.
                    if (downloaded > MAX_COVER) {
                        throw new BiblioTechException(
                                "The cover exceeds the limit during the download");
                    }
                    // write(buffer, 0, read): never buffer.length (module 7).
                    output.write(buffer, 0, read);
                }
            }

            // Atomic move: the final file appears complete or it does not appear.
            Files.move(temporary, target,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            temporary = null;   // no longer needs cleaning up

            long total = downloaded;
            LOG.info(() -> "Cover downloaded: " + target + " (" + total + " bytes)");
            return target;

        } catch (SocketTimeoutException e) {
            throw new BiblioTechException("Timed out downloading the cover.", e);

        } catch (IOException e) {
            LOG.log(Level.WARNING, "Failure downloading " + coverUrl, e);
            throw new BiblioTechException("The cover could not be downloaded.", e);

        } finally {
            if (connection != null) {
                connection.disconnect();
            }
            // Cleaning up the temporary file if something failed halfway.
            if (temporary != null) {
                try {
                    Files.deleteIfExists(temporary);
                } catch (IOException e) {
                    LOG.fine("Could not delete the temporary file: " + temporary);
                }
            }
        }
    }

    // =================================================================
    // Utilities
    // =================================================================

    private String readBody(HttpURLConnection connection, int code) throws IOException {
        // The distinction everybody forgets: with 4xx/5xx you have to
        // use getErrorStream, because getInputStream THROWS.
        InputStream input = (code >= 200 && code < 400)
                ? connection.getInputStream()
                : connection.getErrorStream();

        if (input == null) {
            return "";
        }
        Charset charset = charsetOf(connection.getContentType());
        try (InputStream stream = input) {
            // Bounded readNBytes, not readAllBytes: a huge response
            // must not exhaust our memory.
            byte[] bytes = stream.readNBytes(MAX_BODY);
            if (bytes.length == MAX_BODY) {
                LOG.warning("Response truncated to " + MAX_BODY + " bytes");
            }
            return new String(bytes, charset);
        }
    }

    /**
     * Consumes and closes the body even when we do not care about it.
     * Without this, the connection does not return to the internal pool and
     * the reuse is lost, which in HTTP is worth a full network round trip.
     */
    private void consumeAndClose(HttpURLConnection connection, int code) {
        try {
            InputStream input = (code >= 200 && code < 400)
                    ? connection.getInputStream()
                    : connection.getErrorStream();
            if (input != null) {
                try (InputStream stream = input) {
                    stream.readNBytes(MAX_BODY);
                }
            }
        } catch (IOException e) {
            LOG.fine("Failure consuming the body: " + e.getMessage());
        }
    }

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

    /**
     * Extraction of JSON fields BY SUBSTRING SEARCH.
     *
     * THIS IS A TEACHING STOPGAP, and it has to be said plainly.
     * It works with this service's particular, simple response, and it
     * breaks with: values containing the searched substring, escapes (\"),
     * nesting, arrays, different spacing, fields in another order or
     * null values. Parsing JSON properly requires a library, and
     * that is done with JACKSON IN 11-07. Do not take this to production.
     */
    private Metadata parse(String json, String requestedIsbn)
            throws BiblioTechException {
        try {
            String title = textField(json, "title");
            String author = textField(json, "author");
            String cover = textField(json, "cover");
            int pages = intField(json, "pages");

            if (title == null) {
                throw new BiblioTechException(
                        "Service response without the 'title' field");
            }
            return new Metadata(requestedIsbn, title,
                    author == null ? "(unknown)" : author,
                    pages, cover);

        } catch (RuntimeException e) {
            throw new BiblioTechException(
                    "The service response could not be interpreted", e);
        }
    }

    /** Looks for "field":"value" and returns the value. A stopgap, see the comment. */
    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;
        }
        int close = json.indexOf('"', open + 1);
        if (close < 0) {
            return null;
        }
        return json.substring(open + 1, close);
    }

    /** Looks for "field":123 and returns the number, or 0 if it is not found. */
    private int intField(String json, String field) {
        String mark = "\"" + field + "\"";
        int i = json.indexOf(mark);
        if (i < 0) {
            return 0;
        }
        int colon = json.indexOf(':', i + mark.length());
        if (colon < 0) {
            return 0;
        }
        int j = colon + 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 void validateIsbn(String isbn) throws BiblioTechException {
        if (isbn == null || isbn.isBlank() || isbn.length() > 20) {
            throw new BiblioTechException("Invalid ISBN");
        }
        // Allow list: digits and hyphens only. It prevents injecting paths
        // ("../admin") or parameters ("?x=1") into the URL.
        for (int i = 0; i < isbn.length(); i++) {
            char c = isbn.charAt(i);
            if (!Character.isDigit(c) && c != '-') {
                throw new BiblioTechException("ISBN with characters that are not allowed");
            }
        }
    }

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

    // Simple decomposition of the base URL for the URI constructor.
    private String hostOf(String base) throws java.net.URISyntaxException {
        return new URI(base).getHost();
    }

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

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

printf 'HTTP/1.1 200 OK\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: 144\r\nConnection: close\r\n\r\n{"isbn":"978-0000000001","title":"Effective Java","author":"Joshua Bloch","pages":416,"cover":"http://localhost:8080/covers/978-0000000001.jpg"}' | nc -l 8080

package com.nexussoftware.bibliotech.presentation;

import com.nexussoftware.bibliotech.exception.BiblioTechException;
import com.nexussoftware.bibliotech.network.MetadataClient;
import com.nexussoftware.bibliotech.network.MetadataClient.Metadata;

import java.nio.file.Path;

public class MetadataTest {

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

        try {
            Metadata m = client.query("978-0000000001");
            if (m == null) {
                System.out.println("The service does not know that ISBN");
                return;
            }
            System.out.println("Title  : " + m.title());
            System.out.println("Author : " + m.author());
            System.out.println("Pages  : " + m.pages());
            System.out.println("Cover  : " + m.coverUrl());

            if (m.coverUrl() != null) {
                Path target = Path.of("covers", m.isbn() + ".jpg");
                client.downloadCover(m.coverUrl(), target);
                System.out.println("Saved in " + target.toAbsolutePath());
            }

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

Title  : Effective Java
Author : Joshua Bloch
Pages  : 416
Cover  : http://localhost:8080/covers/978-0000000001.jpg

package com.nexussoftware.bibliotech.network;

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

/**
 * HTTP inspector: a complete report of a URL, in the style of curl -v.
 * A diagnostic tool for Nexus Software's systems team.
 */
public class HttpInspector {

    private static final int MAX_HOPS = 5;
    private static final int CONNECT_TIMEOUT_MS = 5_000;
    private static final int READ_TIMEOUT_MS = 10_000;
    private static final int MAX_BODY = 1024 * 1024;

    /** One hop of the redirect chain. */
    private record Hop(String url, int code, String message, String target) {
    }

    public void inspect(String urlText) {
        System.out.println("=".repeat(78));
        System.out.println("INSPECTION OF: " + urlText);
        System.out.println("=".repeat(78));

        URL url;
        try {
            // URI validates the syntax strictly; URL does not.
            url = URI.create(urlText).toURL();
        } catch (Exception e) {
            System.out.println("Invalid URL: " + e.getMessage());
            return;
        }

        showParts(url);

        List<Hop> chain = new ArrayList<>();
        URL current = url;
        HttpURLConnection connection = null;

        try {
            // --- Follow the redirect chain by hand ---
            for (int hop = 0; hop <= MAX_HOPS; hop++) {
                connection = open(current, "HEAD");

                long t0 = System.nanoTime();
                int code = connection.getResponseCode();
                long msConnect = (System.nanoTime() - t0) / 1_000_000;

                // Many servers do not accept HEAD and return 405.
                // We retry with GET, which is always supported.
                if (code == HttpURLConnection.HTTP_BAD_METHOD) {
                    System.out.println("\n(HEAD returned 405; retrying with GET)");
                    connection.disconnect();
                    connection = open(current, "GET");
                    t0 = System.nanoTime();
                    code = connection.getResponseCode();
                    msConnect = (System.nanoTime() - t0) / 1_000_000;
                }

                String target = connection.getHeaderField("Location");
                chain.add(new Hop(current.toString(), code,
                        connection.getResponseMessage(), target));

                if (code < 300 || code >= 400 || target == null) {
                    showResponse(connection, code, msConnect);
                    break;
                }

                // Location may be relative: resolve() handles it.
                current = current.toURI().resolve(target).toURL();
                connection.disconnect();
                connection = null;
            }

            showChain(chain);

        } catch (UnknownHostException e) {
            System.out.println("\nHost DOES NOT RESOLVE: " + e.getMessage());
        } catch (ConnectException e) {
            System.out.println("\nCONNECTION REFUSED: there is no server on that port");
        } catch (SocketTimeoutException e) {
            System.out.println("\nTIMED OUT: the server is not replying");
        } catch (Exception e) {
            System.out.println("\nFAILURE: " + e);
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }

    private HttpURLConnection open(URL url, String method) throws IOException {
        HttpURLConnection c = (HttpURLConnection) url.openConnection();
        c.setRequestMethod(method);
        c.setRequestProperty("User-Agent", "BiblioTech-Inspector/1.0");
        c.setRequestProperty("Accept", "*/*");
        c.setConnectTimeout(CONNECT_TIMEOUT_MS);
        c.setReadTimeout(READ_TIMEOUT_MS);
        // We manage them ourselves, so we can show them.
        c.setInstanceFollowRedirects(false);
        return c;
    }

    private void showParts(URL url) {
        // getPort() returns -1 if it is not explicit: it has to be combined
        // with getDefaultPort() to know the effective port.
        int port = url.getPort() != -1 ? url.getPort() : url.getDefaultPort();

        System.out.println("\n--- PARTS OF THE URL ---");
        System.out.printf("  %-16s %s%n", "Scheme", url.getProtocol());
        System.out.printf("  %-16s %s%n", "Host", url.getHost());
        System.out.printf("  %-16s %d%s%n", "Port", port,
                url.getPort() == -1 ? "  (default for the scheme)" : "  (explicit)");
        System.out.printf("  %-16s %s%n", "Path",
                url.getPath().isEmpty() ? "/" : url.getPath());
        System.out.printf("  %-16s %s%n", "Query",
                url.getQuery() == null ? "(none)" : url.getQuery());
        System.out.printf("  %-16s %s%n", "Fragment",
                url.getRef() == null ? "(none)"
                        : url.getRef() + "  <- NOT sent to the server");
    }

    private void showResponse(HttpURLConnection c, int code, long ms)
            throws IOException {
        System.out.println("\n--- RESPONSE ---");
        System.out.printf("  %-16s %d %s   (%s)%n", "Status", code,
                c.getResponseMessage(), family(code));
        System.out.printf("  %-16s %d ms%n", "Time", ms);

        System.out.println("\n--- HEADERS ---");
        // TreeMap for alphabetical order. The null key carries the status line.
        Map<String, List<String>> headers = new TreeMap<>((a, b) -> {
            if (a == null) return -1;
            if (b == null) return 1;
            return a.compareToIgnoreCase(b);
        });
        headers.putAll(c.getHeaderFields());

        for (Map.Entry<String, List<String>> e : headers.entrySet()) {
            String name = e.getKey() == null ? "(status line)" : e.getKey();
            for (String value : e.getValue()) {
                System.out.printf("  %-24s %s%n", name + ":", value);
            }
        }

        System.out.println("\n--- CONTENT ---");
        System.out.printf("  %-16s %s%n", "Type",
                c.getContentType() == null ? "(not stated)" : c.getContentType());
        System.out.printf("  %-16s %s%n", "Charset",
                MetadataClient.charsetOf(c.getContentType()));
        long length = c.getContentLengthLong();
        System.out.printf("  %-16s %s%n", "Length",
                length < 0 ? "(not stated: chunked or close)" : length + " bytes");
        System.out.printf("  %-16s %s%n", "Compression",
                c.getContentEncoding() == null ? "(none)" : c.getContentEncoding());

        // With HEAD there is no body, but with the fallback GET there is.
        if ("GET".equals(c.getRequestMethod())) {
            InputStream input = (code >= 200 && code < 400)
                    ? c.getInputStream() : c.getErrorStream();
            if (input != null) {
                try (InputStream stream = input) {
                    byte[] bytes = stream.readNBytes(MAX_BODY);
                    System.out.printf("  %-16s %d bytes read%n",
                            "Actual body", bytes.length);
                    String text = new String(bytes,
                            MetadataClient.charsetOf(c.getContentType()));
                    System.out.println("\n--- FIRST LINES OF THE BODY ---");
                    String[] lines = text.split("\n", 6);
                    for (int i = 0; i < Math.min(5, lines.length); i++) {
                        // We truncate: never dump network data without a limit.
                        String l = lines[i];
                        System.out.println("  " + (l.length() > 100
                                ? l.substring(0, 100) + "..." : l));
                    }
                }
            }
        }
    }

    private void showChain(List<Hop> chain) {
        if (chain.size() <= 1) {
            return;
        }
        System.out.println("\n--- REDIRECT CHAIN (" + chain.size() + ") ---");
        for (int i = 0; i < chain.size(); i++) {
            Hop h = chain.get(i);
            System.out.printf("  %d. %d %s%n     %s%n", i + 1, h.code(),
                    h.message(), h.url());
            if (h.target() != null) {
                System.out.println("     -> Location: " + h.target());
            }
        }
    }

    private String family(int code) {
        return switch (code / 100) {
            case 1 -> "informational";
            case 2 -> "SUCCESS";
            case 3 -> "redirect";
            case 4 -> "CLIENT ERROR";
            case 5 -> "SERVER ERROR";
            default -> "unknown";
        };
    }

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

==============================================================================
INSPECTION OF: http://localhost:8080/v1/books/978-0000000001?format=json#summary
==============================================================================

--- PARTS OF THE URL ---
  Scheme           http
  Host             localhost
  Port             8080  (explicit)
  Path             /v1/books/978-0000000001
  Query            format=json
  Fragment         summary  <- NOT sent to the server

--- RESPONSE ---
  Status           200 OK   (SUCCESS)
  Time             4 ms

--- HEADERS ---
  (status line):           HTTP/1.1 200 OK
  Content-Length:          50
  Content-Type:            application/json; charset=utf-8

--- CONTENT ---
  Type             application/json; charset=utf-8
  Charset          UTF-8
  Length           50 bytes
  Compression      (none)

--- REDIRECT CHAIN (2) ---
  1. 302 Found
     http://localhost:8080/v1/books/978-0000000001?format=json
     -> Location: /v2/books/978-0000000001
  2. 200 OK
     http://localhost:8080/v2/books/978-0000000001

package com.nexussoftware.bibliotech.network;

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

/**
 * HTTP client with a correct retry policy.
 *
 * The rule that governs everything: retry what is TRANSIENT
 * (timeouts, 429, infrastructure 5xx) and never what is
 * PERMANENT (4xx, non-existent host).
 */
public class ResilientHttpClient {

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

    private static final int MAX_ATTEMPTS = 4;
    private static final int INITIAL_WAIT_MS = 200;
    private static final int MAX_RETRY_AFTER_S = 30;
    private static final int MAX_BODY = 1024 * 1024;
    private static final int CONNECT_TIMEOUT_MS = 5_000;
    private static final int READ_TIMEOUT_MS = 10_000;

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

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

    // =================================================================
    // GET: idempotent, retried
    // =================================================================

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

    // =================================================================
    // POST: NOT idempotent, NOT retried by default
    // =================================================================

    /**
     * POST with no retries.
     *
     * WHY IT IS DIFFERENT: if a POST times out, WE DO NOT KNOW
     * whether the server processed it. The request may have arrived, been
     * executed and only the reply lost. Retrying would duplicate the operation:
     * two loans, two charges, two orders.
     *
     * The professional solution is the IDEMPOTENCY KEY: the client generates
     * a unique identifier per operation, sends it in a header
     * (Idempotency-Key) and the server rejects the second request with the
     * same key. With that, retrying IS safe. Without it, it is not.
     */
    public Response post(String url, String body, String contentType)
            throws IOException {
        return execute(url, "POST", body, contentType, false);
    }

    /** POST with retries: only if the service guarantees idempotence. */
    public Response postIdempotent(String url, String body, String contentType)
            throws IOException {
        return execute(url, "POST", body, contentType, true);
    }

    // =================================================================
    // Core
    // =================================================================

    private Response execute(String urlText, String method, String body,
                             String contentType, boolean retry)
            throws IOException {

        URL url = URI.create(urlText).toURL();
        int wait = INITIAL_WAIT_MS;
        IOException lastFailure = null;
        int maximum = retry ? MAX_ATTEMPTS : 1;

        for (int attempt = 1; attempt <= maximum; attempt++) {
            HttpURLConnection connection = null;
            try {
                connection = (HttpURLConnection) url.openConnection();
                connection.setRequestMethod(method);
                connection.setRequestProperty("User-Agent", "BiblioTech/1.0");
                connection.setRequestProperty("Accept", "application/json, */*");
                connection.setConnectTimeout(CONNECT_TIMEOUT_MS);
                connection.setReadTimeout(READ_TIMEOUT_MS);

                if (body != null) {
                    connection.setDoOutput(true);
                    connection.setRequestProperty("Content-Type",
                            contentType == null ? "application/json; charset=utf-8"
                                    : contentType);
                    byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
                    // Length in BYTES, not in characters.
                    connection.setFixedLengthStreamingMode(bytes.length);
                    try (OutputStream output = connection.getOutputStream()) {
                        output.write(bytes);
                        output.flush();
                    }
                }

                int code = connection.getResponseCode();
                Map<String, List<String>> headers = connection.getHeaderFields();

                final int n = attempt;
                LOG.fine(() -> method + " " + url + " -> " + code
                        + " (attempt " + n + ")");

                // A transient code: worth a retry if there is room left.
                if (isTransient(code) && attempt < maximum) {
                    long waitMs = waitAfterCode(connection, code, wait);
                    consume(connection, code);
                    LOG.warning(method + " " + url + " -> " + code
                            + "; retry " + (attempt + 1) + " in " + waitMs + " ms");
                    sleep(waitMs);
                    wait *= 2;
                    continue;
                }

                String text = readBody(connection, code);
                return new Response(code, text, headers, attempt);

            } catch (UnknownHostException e) {
                // PERMANENT: retrying will not make the name exist.
                LOG.severe("Unresolvable host: " + url.getHost());
                throw e;

            } catch (SocketTimeoutException | ConnectException e) {
                // TRANSIENT: they may resolve themselves.
                lastFailure = e;
                if (attempt >= maximum) {
                    break;
                }
                long waitMs = withJitter(wait);
                LOG.warning(e.getClass().getSimpleName() + " on " + url
                        + "; retry " + (attempt + 1) + " in " + waitMs + " ms");
                sleep(waitMs);
                wait *= 2;

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

        throw lastFailure != null ? lastFailure
                : new IOException("No response after " + maximum + " attempts");
    }

    // =================================================================
    // Retry policy
    // =================================================================

    private boolean isTransient(int code) {
        // 429: we are being asked to slow down. 502/503/504: infrastructure failures.
        // The 500 is NOT included: it is usually a deterministic failure that will repeat.
        // Nor are the 4xx: the request is wrong and retrying it gives the same result.
        return code == 429 || code == 502 || code == 503 || code == 504;
    }

    /** If the server says how long to wait, we do as it says. */
    private long waitAfterCode(HttpURLConnection connection, int code, int computed) {
        String retryAfter = connection.getHeaderField("Retry-After");
        if (retryAfter != null) {
            try {
                // Retry-After accepts two formats: seconds, or an HTTP date.
                // Here we only handle the seconds one; the date one requires
                // date parsing, and that is done properly in 10-05.
                long seconds = Long.parseLong(retryAfter.strip());
                long capped = Math.min(seconds, MAX_RETRY_AFTER_S);
                LOG.info("The server asks us to wait " + seconds
                        + " s (we apply " + capped + " s)");
                return capped * 1000;
            } catch (NumberFormatException e) {
                LOG.fine("Retry-After in date format; ignored: " + retryAfter);
            }
        }
        return withJitter(computed);
    }

    /**
     * Adds a random component of up to 20 %.
     *
     * WHAT PROBLEM IT AVOIDS: the "thundering herd". If a hundred clients fail at
     * the same time because the server went down, and they all retry exactly at
     * 200 ms, the hundred requests arrive together again and take it down once
     * more, in a cycle that repeats indefinitely. Spreading the
     * retries out breaks the synchronisation and distributes the load over time.
     */
    private long withJitter(long base) {
        long variation = (long) (base * 0.2);
        return base + ThreadLocalRandom.current().nextLong(-variation, variation + 1);
    }

    private void sleep(long ms) throws IOException {
        try {
            Thread.sleep(Math.max(0, ms));
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();     // 08-02: restore the flag
            throw new IOException("Retry interrupted", e);
        }
    }

    // =================================================================
    // Utilities
    // =================================================================

    private String readBody(HttpURLConnection connection, int code) throws IOException {
        InputStream input = (code >= 200 && code < 400)
                ? connection.getInputStream() : connection.getErrorStream();
        if (input == null) {
            return "";
        }
        try (InputStream stream = input) {
            byte[] bytes = stream.readNBytes(MAX_BODY);
            return new String(bytes, MetadataClient.charsetOf(connection.getContentType()));
        }
    }

    /** Consumes the body so the connection returns to the internal pool. */
    private void consume(HttpURLConnection connection, int code) {
        try {
            InputStream input = (code >= 200 && code < 400)
                    ? connection.getInputStream() : connection.getErrorStream();
            if (input != null) {
                try (InputStream stream = input) {
                    stream.readNBytes(MAX_BODY);
                }
            }
        } catch (IOException e) {
            LOG.fine("Failure consuming the body: " + e.getMessage());
        }
    }
}

WARNING: GET http://localhost:8080/v1/books -> 503; retry 2 in 2000 ms
INFO: The server asks us to wait 2 s (we apply 2 s)
WARNING: GET http://localhost:8080/v1/books -> 503; retry 3 in 431 ms
Response[code=200, attempts=3]

package com.nexussoftware.bibliotech.network;

import com.nexussoftware.bibliotech.domain.Material;
import com.nexussoftware.bibliotech.exception.BiblioTechException;
import com.nexussoftware.bibliotech.service.ConcurrentCatalog;
import com.nexussoftware.bibliotech.network.MetadataClient.Metadata;

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

/**
 * Synchronises BiblioTech's catalogue covers with the external
 * metadata service. Sequential and respectful of the service.
 */
public class CoverSynchroniser {

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

    private static final long MAX_COVER = 5L * 1024 * 1024;
    private static final int REQUESTS_PER_SECOND = 2;
    private static final int CONNECT_TIMEOUT_MS = 5_000;
    private static final int READ_TIMEOUT_MS = 30_000;
    private static final String USER_AGENT = "BiblioTech/1.0";

    private final ConcurrentCatalog catalog;
    private final MetadataClient metadata;
    private final Path directory;

    /** Instant of the last network access, for the rate limiter. */
    private long lastRequest = 0;

    private int downloaded = 0;
    private int upToDate = 0;
    private int skipped = 0;
    private int failed = 0;
    private long totalBytes = 0;

    public CoverSynchroniser(ConcurrentCatalog catalog,
                             MetadataClient metadata, Path directory) {
        this.catalog = catalog;
        this.metadata = metadata;
        this.directory = directory;
    }

    public void synchronise() throws IOException {
        Files.createDirectories(directory);
        long start = System.currentTimeMillis();

        List<Material> materials = catalog.all();
        System.out.println("Synchronising the covers of " + materials.size()
                + " materials...\n");

        // SEQUENTIAL on purpose. Doing it in PARALLEL -which would cut the
        // total time drastically, because almost all of it is network waiting-
        // requires the asynchronous HttpClient with sendAsync and allOf, and that
        // is exactly what is done in 09-06.
        for (Material material : materials) {
            process(material);
        }

        report(System.currentTimeMillis() - start);
    }

    private void process(Material material) {
        String isbn = material.getIsbn();
        Path target = directory.resolve(isbn + ".jpg");

        try {
            rateLimit();
            Metadata m = metadata.query(isbn);

            if (m == null || m.coverUrl() == null || m.coverUrl().isBlank()) {
                System.out.printf("  %-18s SKIPPED (no cover in the service)%n", isbn);
                skipped++;
                return;
            }

            rateLimit();
            long bytes = downloadIfChanged(m.coverUrl(), target, isbn);

            if (bytes < 0) {
                upToDate++;         // 304: we already had it up to date
            } else if (bytes == 0) {
                skipped++;          // rejected by type or size
            } else {
                downloaded++;
                totalBytes += bytes;
            }

        } catch (BiblioTechException | IOException e) {
            failed++;
            System.out.printf("  %-18s FAILED: %s%n", isbn, e.getMessage());
            LOG.log(Level.FINE, "Failure synchronising " + isbn, e);
        }
    }

    /**
     * Downloads the cover if it has changed.
     * @return bytes downloaded; -1 if the server returned 304; 0 if it was rejected.
     */
    private long downloadIfChanged(String urlText, Path target, String isbn)
            throws IOException, BiblioTechException {

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

        // --- Phase 1: HEAD to check the type and the size ---
        HttpURLConnection head = (HttpURLConnection) url.openConnection();
        try {
            head.setRequestMethod("HEAD");
            head.setRequestProperty("User-Agent", USER_AGENT);
            head.setConnectTimeout(CONNECT_TIMEOUT_MS);
            head.setReadTimeout(READ_TIMEOUT_MS);

            int code = head.getResponseCode();
            if (code == HttpURLConnection.HTTP_OK) {
                String type = head.getContentType();
                long length = head.getContentLengthLong();

                if (type != null && !type.startsWith("image/")) {
                    System.out.printf("  %-18s SKIPPED (not an image: %s)%n", isbn, type);
                    return 0;
                }
                if (length > MAX_COVER) {
                    System.out.printf("  %-18s SKIPPED (%d bytes, over the limit)%n",
                            isbn, length);
                    return 0;
                }
            }
            // A failing HEAD does not stop us trying the GET: many
            // servers do not implement it properly.
        } finally {
            head.disconnect();
        }

        // --- Phase 2: conditional GET ---
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        Path temporary = null;
        try {
            connection.setRequestMethod("GET");
            connection.setRequestProperty("User-Agent", USER_AGENT);
            connection.setRequestProperty("Accept", "image/jpeg, image/png, image/*");
            connection.setConnectTimeout(CONNECT_TIMEOUT_MS);
            connection.setReadTimeout(READ_TIMEOUT_MS);

            // CONDITIONAL DOWNLOAD: if we already have the file, we ask the
            // server to send it only if it has changed since then.
            // A 304 saves the entire transfer.
            if (Files.exists(target)) {
                long modified = Files.getLastModifiedTime(target).toMillis();
                connection.setRequestProperty("If-Modified-Since",
                        httpDate(new Date(modified)));
            }

            int code = connection.getResponseCode();

            if (code == HttpURLConnection.HTTP_NOT_MODIFIED) {     // 304
                System.out.printf("  %-18s UP TO DATE (304, not changed)%n", isbn);
                return -1;
            }
            if (code != HttpURLConnection.HTTP_OK) {
                throw new IOException("HTTP " + code + " downloading the cover");
            }

            // Download to a TEMPORARY file: an interruption does not leave a
            // half-written JPEG that looks valid until somebody tries to open it.
            temporary = Files.createTempFile(directory, "cover-", ".tmp");
            long received = 0;

            try (InputStream input = connection.getInputStream();
                 OutputStream output = Files.newOutputStream(temporary)) {
                byte[] buffer = new byte[8192];
                int read;
                while ((read = input.read(buffer)) != -1) {
                    received += read;
                    // The limit is checked HERE too: the HEAD's Content-Length
                    // may be missing or lying.
                    if (received > MAX_COVER) {
                        throw new IOException("The cover exceeds the limit while downloading");
                    }
                    output.write(buffer, 0, read);      // never buffer.length
                }
            }

            Files.move(temporary, target,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            temporary = null;

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

        } finally {
            connection.disconnect();
            if (temporary != null) {
                try {
                    Files.deleteIfExists(temporary);
                } catch (IOException e) {
                    LOG.fine("Could not delete the temporary file " + temporary);
                }
            }
        }
    }

    /**
     * HTTP date format (RFC 7231): "Wed, 05 Aug 2026 09:14:22 GMT".
     *
     * SimpleDateFormat is used because java.time is 10-05. Two details
     * that are essential and that almost everybody forgets:
     *   - Locale.US: without it, the day and month names come out in the
     *     system language ("mié", "ago") and the server does not understand them.
     *   - The GMT zone: the format demands it explicitly.
     * In 10-05 this is done with DateTimeFormatter.RFC_1123_DATE_TIME,
     * which is immutable and thread-safe; SimpleDateFormat is NOT.
     */
    private String httpDate(Date date) {
        SimpleDateFormat format = new SimpleDateFormat(
                "EEE, dd MMM yyyy HH:mm:ss zzz", Locale.US);
        format.setTimeZone(TimeZone.getTimeZone("GMT"));
        return format.format(date);
    }

    /**
     * Rate limiter: no more than REQUESTS_PER_SECOND to the service.
     * Being a good citizen stops your IP being blocked, and avoids
     * provoking the 429s that would then have to be handled.
     */
    private void rateLimit() {
        long interval = 1000 / REQUESTS_PER_SECOND;
        long since = System.currentTimeMillis() - lastRequest;
        if (since < interval) {
            try {
                Thread.sleep(interval - since);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();     // 08-02
            }
        }
        lastRequest = System.currentTimeMillis();
    }

    private void report(long ms) {
        System.out.println();
        System.out.println("=== COVER SYNCHRONISATION ===");
        System.out.printf("%-22s %d%n", "Downloaded", downloaded);
        System.out.printf("%-22s %d%n", "Up to date (304)", upToDate);
        System.out.printf("%-22s %d%n", "Skipped", skipped);
        System.out.printf("%-22s %d%n", "Failed", failed);
        System.out.printf("%-22s %.1f KB%n", "Bytes downloaded", totalBytes / 1024.0);
        System.out.printf("%-22s %.1f s%n", "Total time", ms / 1000.0);
        System.out.printf("%-22s %s%n", "Directory", directory.toAbsolutePath());
    }
}

Synchronising the covers of 5 materials...

  978-0000000001     DOWNLOADED (48213 bytes)
  978-0000000002     UP TO DATE (304, not changed)
  978-0000000003     DOWNLOADED (39104 bytes)
  978-0000000004     SKIPPED (no cover in the service)
  978-0000000005     FAILED: HTTP 404 downloading the cover

=== COVER SYNCHRONISATION ===
Downloaded             2
Up to date (304)       1
Skipped                1
Failed                 1
Bytes downloaded       85.3 KB
Total time             5.4 s