// The constructor CONNECTS. If it returns, you are already connected.
// If it cannot, it throws and the object never comes into existence.
Socket socket = new Socket("localhost", 9090);

import java.io.IOException;
import java.net.ConnectException;
import java.net.Socket;
import java.net.UnknownHostException;

try (Socket socket = new Socket("localhost", 9090)) {

    System.out.println("Connected to      : " + socket.getInetAddress().getHostAddress());
    System.out.println("Remote port       : " + socket.getPort());
    System.out.println("Local address     : " + socket.getLocalAddress().getHostAddress());
    System.out.println("Local port        : " + socket.getLocalPort());

} catch (UnknownHostException e) {
    // Failure at step 1: the name could not be resolved.
    System.err.println("No such host: " + e.getMessage());
} catch (ConnectException e) {
    // Failure at step 3: the machine replied RST. Nobody is listening.
    System.err.println("Connection refused: there is no server on that port");
} catch (IOException e) {
    // Any other network failure.
    System.err.println("Network failure: " + e.getMessage());
}

Connected to      : 127.0.0.1
Remote port       : 9090
Local address     : 127.0.0.1
Local port        : 51422

import java.net.InetSocketAddress;
import java.net.Socket;
import java.net.SocketTimeoutException;

// 1. The socket is created UNCONNECTED (no-argument constructor).
Socket socket = new Socket();

// 2. The destination is described with an InetSocketAddress: the (host, port) pair.
InetSocketAddress destination = new InetSocketAddress("192.168.1.50", 9090);

// 3. Connect with an explicit time limit in milliseconds.
try {
    socket.connect(destination, 3000);  // 3 seconds at most
} catch (SocketTimeoutException e) {
    // The deadline expired: the machine has not replied to the SYN.
    // TRANSIENT failure: retrying may make sense.
    System.err.println("The server is not responding within 3 s");
}

// Resolves the name NOW. If it does not resolve, isUnresolved() will be true
// (careful: it does NOT throw here; connect() will).
InetSocketAddress a = new InetSocketAddress("server.nexussoftware.local", 9090);

// Resolves nothing: it leaves the name as it is so that whoever connects
// resolves it (useful with SOCKS proxies, which resolve it themselves).
InetSocketAddress b = InetSocketAddress.createUnresolved("server.local", 9090);

// With an already-resolved InetAddress, without querying DNS.
InetSocketAddress c = new InetSocketAddress(InetAddress.getLoopbackAddress(), 9090);

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.net.Socket;
import java.nio.charset.StandardCharsets;

try (Socket socket = new Socket()) {
    socket.connect(new InetSocketAddress("localhost", 9090), 3000);
    socket.setSoTimeout(10_000);

    // OUTPUT: your text -> characters -> UTF-8 bytes -> network
    //   PrintWriter        gives println() and formatting
    //   BufferedWriter     accumulates so as not to do one network write per character
    //   OutputStreamWriter is the BRIDGE characters -> bytes, with an explicit charset
    PrintWriter writer = new PrintWriter(
            new BufferedWriter(
                    new OutputStreamWriter(socket.getOutputStream(), StandardCharsets.UTF_8)),
            true);                      // <-- autoFlush: flushes on every println()

    // INPUT: network -> UTF-8 bytes -> characters -> lines
    BufferedReader reader = new BufferedReader(
            new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8));

    String greeting = reader.readLine();        // "200 BIBLIOTECH BTCP/1"
    System.out.println("S: " + greeting);

    writer.println("QUERY 978-0000000001");
    System.out.println("C: QUERY 978-0000000001");

    String reply = reader.readLine();           // "200 OK 978-...|Effective Java|BOOK|true"
    System.out.println("S: " + reply);

    writer.println("QUIT");
    System.out.println("S: " + reader.readLine());   // "221 BYE"
}

// BROKEN CLIENT - do not copy it, it is the example of what NOT to do.
try (Socket socket = new Socket()) {
    socket.connect(new InetSocketAddress("localhost", 9090), 3000);

    PrintWriter writer = new PrintWriter(
            new BufferedWriter(
                    new OutputStreamWriter(socket.getOutputStream(), StandardCharsets.UTF_8)));
    //          ^^^^^ the autoFlush "true" is missing

    BufferedReader reader = new BufferedReader(
            new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8));

    writer.println("QUERY 978-0000000001");    // Stays in the BUFFER.

    String reply = reader.readLine();          // <-- BLOCKS HERE FOREVER
    System.out.println(reply);
}

// WAY 1 (recommended for line protocols): autoFlush on PrintWriter.
// The second argument true makes println(), printf() and format()
// flush automatically. CAREFUL: print() with no line break does NOT flush.
PrintWriter writer = new PrintWriter(
        new BufferedWriter(
                new OutputStreamWriter(socket.getOutputStream(), StandardCharsets.UTF_8)),
        true);
writer.println("QUERY 978-0000000001");        // sends itself

// WAY 2: explicit flush. Mandatory if you write with print() and no line break,
// or if the protocol uses \r\n and you write the terminator by hand.
writer.print("QUERY 978-0000000001\n");
writer.flush();                                  // <-- indispensable

// WAY 3: BufferedWriter directly, which additionally DOES throw IOException.
BufferedWriter bw = new BufferedWriter(
        new OutputStreamWriter(socket.getOutputStream(), StandardCharsets.UTF_8));
bw.write("QUERY 978-0000000001");
bw.write('\n');
bw.flush();

// What the client does:
writer.println("QUERY 111");
writer.println("LIST");

// What the server may read with a read() over raw bytes:
//   Case A: "QUERY 111\nLIST\n"      (both messages together)
//   Case B: "QUERY 111\n"            then "LIST\n"      (one and one)
//   Case C: "QUER"                   then "Y 111\nLI"   then "ST\n"

String line;
while ((line = reader.readLine()) != null) {
    // Here 'line' is ALWAYS a complete protocol message.
    // readLine() has already resolved the fragmentation for you.
    process(line);
}
// We leave the loop when readLine() returns null:
// the other end has closed its side of the connection.

// Length prefix: first how many bytes are coming, then the bytes.
byte[] data = review.getBytes(StandardCharsets.UTF_8);
dataOutput.writeInt(data.length);        // 4 bytes in big-endian
dataOutput.write(data);                  // the data, with no restrictions
dataOutput.flush();

// When reading:
int length = dataInput.readInt();
if (length < 0 || length > MAX_ALLOWED) {
    // ESSENTIAL: otherwise a malicious client asks for a 2 GB array
    // and causes an OutOfMemoryError with a 4-byte request.
    throw new ProtocolException("Invalid declared length: " + length);
}
byte[] data = dataInput.readNBytes(length);
String review = new String(data, StandardCharsets.UTF_8);

try (Socket socket = new Socket()) {
    socket.connect(destination, 3000);
    // ... conversation ...
}   // socket.close() guaranteed, including if an exception is thrown

// UNNECESSARY and also misleading: it suggests they are independent
// resources when in reality all three are the same socket.
try (Socket socket = new Socket();
     PrintWriter writer = new PrintWriter(...);
     BufferedReader reader = new BufferedReader(...)) {

// Client that uploads a file to the server and then waits for the summary.
try (Socket socket = new Socket()) {
    socket.connect(destination, 3000);

    // 1. Send the complete content.
    try (OutputStream output = socket.getOutputStream()) {
        // CAREFUL: this try-with-resources would close the whole socket. Wrong.
    }
}

try (Socket socket = new Socket()) {
    socket.connect(destination, 3000);

    // 1. Send the whole content and FLUSH.
    OutputStream output = socket.getOutputStream();
    Files.copy(Path.of("catalog.csv"), output);
    output.flush();

    // 2. Say "I have finished talking" WITHOUT closing the connection.
    //    The server will see end of stream and know it can process.
    socket.shutdownOutput();

    // 3. Carry on listening: the read direction is still open.
    BufferedReader reader = new BufferedReader(
            new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8));
    String summary;
    while ((summary = reader.readLine()) != null) {
        System.out.println("S: " + summary);
    }
}   // now yes, a complete close

socket.setSoTimeout(10_000);       // 10 seconds per read

try {
    String line = reader.readLine();
    if (line == null) {
        System.out.println("The other end closed in an orderly way");
    } else {
        process(line);
    }
} catch (SocketTimeoutException e) {
    // 10 s have gone by without a single byte arriving.
    // VERY IMPORTANT: the socket is STILL VALID. The read can be retried.
    System.out.println("No data in 10 s; the socket is still usable");
}

socket.setSoTimeout(1000);          // poll once a second
while (!Thread.currentThread().isInterrupted() && running) {
    try {
        String line = reader.readLine();
        if (line == null) {
            break;                  // the other end closed
        }
        process(line);
    } catch (SocketTimeoutException e) {
        // One second with no data: we take the chance to check
        // the cancellation flag of module 8 and go back to waiting.
        continue;
    }
}

Without TCP_NODELAY, interactive protocol:

  Client: sends "QUERY 111\n"   (10 bytes)  --> goes out at once (nothing pending)
  Server: receives, processes, replies
  Client: sends "LIST\n"        (5 bytes)   --> WAITS: there is an unacknowledged send
          ...                                   up to 200 ms of artificial delay

socket.setTcpNoDelay(true);     // true = NO Nagle algorithm = send now

package com.nexussoftware.bibliotech.network;

import com.nexussoftware.bibliotech.exception.BiblioTechException;

import java.io.IOException;
import java.net.ConnectException;
import java.net.NoRouteToHostException;
import java.net.SocketException;
import java.net.SocketTimeoutException;
import java.net.UnknownHostException;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Translates network exceptions into BiblioTech domain exceptions
 * and decides whether the failure is transient (worth a retry) or permanent.
 * This is the ERROR BOUNDARY of 06-07 applied to the network.
 */
public final class NetworkErrorTranslator {

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

    private NetworkErrorTranslator() {
    }

    /** The result of classifying a network failure. */
    public record Classification(String userMessage, boolean transientFailure) {
    }

    public static Classification classify(IOException e, String destination) {
        if (e instanceof UnknownHostException) {
            LOG.severe("Unresolvable name: " + destination);
            return new Classification(
                    "The catalogue server cannot be found. Check the configuration.", false);
        }
        if (e instanceof ConnectException) {
            // Mind the order: ConnectException is a subclass of SocketException,
            // so it must be checked FIRST.
            LOG.severe("Connection refused by " + destination + ": the server is not running");
            return new Classification(
                    "The catalogue server is unavailable.", false);
        }
        if (e instanceof SocketTimeoutException) {
            LOG.warning("Timed out with " + destination);
            return new Classification(
                    "The catalogue server is taking too long to reply.", true);
        }
        if (e instanceof NoRouteToHostException) {
            LOG.severe("No route to " + destination);
            return new Classification(
                    "There is no connection to the server's network.", false);
        }
        if (e instanceof SocketException) {
            // "Connection reset", "Broken pipe" and the like.
            LOG.warning("Broken connection with " + destination + ": " + e.getMessage());
            return new Classification(
                    "The connection with the catalogue has been lost.", true);
        }
        LOG.log(Level.SEVERE, "Unclassified network failure with " + destination, e);
        return new Classification("Communication error with the catalogue.", false);
    }

    /** Turns the failure into the domain exception, preserving the cause. */
    public static BiblioTechException translate(IOException e, String destination) {
        Classification c = classify(e, destination);
        return new BiblioTechException(c.userMessage(), e);
    }
}

package com.nexussoftware.bibliotech.network;

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.IOException;
import java.net.Socket;
import java.nio.charset.StandardCharsets;

/**
 * Binary variant of sending a material card.
 * Used when volume matters more than readability.
 */
public final class BinaryProtocol {

    /** Defensive limit: no legitimate text field exceeds this. */
    private static final int MAX_TEXT = 4096;

    private BinaryProtocol() {
    }

    public static void sendCard(Socket socket, String isbn, String title,
                                int pages, boolean available) throws IOException {
        // We buffer: without BufferedOutputStream, each writeInt would be
        // potentially an independent network operation.
        DataOutputStream output = new DataOutputStream(
                new BufferedOutputStream(socket.getOutputStream()));

        writeText(output, isbn);            // length (int) + UTF-8 bytes
        writeText(output, title);
        output.writeInt(pages);             // 4 bytes, big-endian
        output.writeBoolean(available);     // 1 byte
        output.flush();                     // indispensable, as always
    }

    public static String receiveTitle(Socket socket) throws IOException {
        DataInputStream input = new DataInputStream(
                new BufferedInputStream(socket.getInputStream()));

        String isbn = readText(input);
        String title = readText(input);
        int pages = input.readInt();
        boolean available = input.readBoolean();

        return title + " (" + isbn + ", " + pages + " pp., "
                + (available ? "available" : "on loan") + ")";
    }

    /** Writes a text with a length prefix: 4 bytes of size + UTF-8 bytes. */
    private static void writeText(DataOutputStream output, String text)
            throws IOException {
        byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
        output.writeInt(bytes.length);
        output.write(bytes);
    }

    /** Reads a text with a length prefix, VALIDATING the declared length. */
    private static String readText(DataInputStream input) throws IOException {
        int length = input.readInt();

        // Without this check, a malicious client sends the int 2_000_000_000
        // and we cause an OutOfMemoryError with a 4-byte request.
        if (length < 0 || length > MAX_TEXT) {
            throw new IOException("Invalid text length: " + length);
        }

        // readNBytes reads EXACTLY n bytes or throws EOFException if the
        // stream ends first. A bare read(byte[]) could read less and
        // leave you with incomplete data unnoticed: a classic mistake.
        byte[] bytes = input.readNBytes(length);
        if (bytes.length < length) {
            throw new java.io.EOFException("Stream ended in the middle of a text");
        }
        return new String(bytes, StandardCharsets.UTF_8);
    }
}

// TEMPTING AND DANGEROUS. Do not do this in a network server.
ObjectOutputStream output = new ObjectOutputStream(socket.getOutputStream());
output.writeObject(book);
output.flush();

// And on the other side:
ObjectInputStream input = new ObjectInputStream(socket.getInputStream());
Book book = (Book) input.readObject();           // <-- HERE IS THE HOLE

ObjectInputStream input = new ObjectInputStream(socket.getInputStream());
// Strict allow list: only these classes, at most 1000 objects,
// at most 100 KB, maximum depth 10. Everything else, rejected.
input.setObjectInputFilter(ObjectInputFilter.Config.createFilter(
        "com.nexussoftware.bibliotech.domain.Book;"
        + "java.lang.String;"
        + "maxdepth=10;maxarray=1000;maxbytes=102400;"
        + "!*"));         // the trailing !* rejects everything not listed

package com.nexussoftware.bibliotech.network;

import com.nexussoftware.bibliotech.exception.BiblioTechException;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.net.InetSocketAddress;
import java.net.Socket;
import java.net.SocketTimeoutException;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Client for BiblioTech's BTCP/1 protocol.
 *
 * Talks to the catalogue server defined in 09-01 and implemented in 09-03.
 * Implements AutoCloseable: it says goodbye with QUIT and closes the socket.
 *
 * It is NOT thread-safe: a socket is a conversation, and two threads
 * writing at once would interleave their requests. One thread, one client.
 */
public class CatalogClient implements AutoCloseable {

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

    private static final int CONNECT_TIMEOUT_MS = 3_000;
    private static final int READ_TIMEOUT_MS = 10_000;
    private static final String EXPECTED_VERSION = "BTCP/1";
    /** Cap on the lines of a multi-line reply: a defence against a hostile server. */
    private static final int MAX_LINES = 10_000;

    private final String host;
    private final int port;

    private Socket socket;
    private BufferedReader reader;
    private PrintWriter writer;

    public CatalogClient(String host, int port) {
        this.host = host;
        this.port = port;
    }

    /** The card of a material exactly as the protocol returns it. */
    public record ProtocolCard(String isbn, String title, String type, boolean available) {

        /** Turns a line "isbn|title|type|available" into a card. */
        static ProtocolCard fromLine(String line) throws BiblioTechException {
            // -1 in split keeps the trailing empty fields;
            // without it, "111|Title|BOOK|" would give 3 fields instead of 4.
            String[] fields = line.split("\\|", -1);
            if (fields.length != 4) {
                throw new BiblioTechException(
                        "Server reply with an invalid format: " + line);
            }
            return new ProtocolCard(fields[0], fields[1], fields[2],
                    Boolean.parseBoolean(fields[3]));
        }
    }

    // ---------------------------------------------------------------
    // Connection
    // ---------------------------------------------------------------

    /** Connects and verifies the server's greeting. */
    public void connect() throws BiblioTechException {
        try {
            socket = new Socket();

            // Interactive protocol of short messages: no Nagle.
            socket.setTcpNoDelay(true);

            // CONNECTION time limit: never the constructor that connects.
            socket.connect(new InetSocketAddress(host, port), CONNECT_TIMEOUT_MS);

            // READ time limit: different from the previous one, and just as mandatory.
            socket.setSoTimeout(READ_TIMEOUT_MS);

            // The stream stack of module 7, with an EXPLICIT charset in both directions.
            writer = new PrintWriter(
                    new BufferedWriter(
                            new OutputStreamWriter(socket.getOutputStream(),
                                    StandardCharsets.UTF_8)),
                    true);      // autoFlush: every println() is sent
            reader = new BufferedReader(
                    new InputStreamReader(socket.getInputStream(),
                            StandardCharsets.UTF_8));

            // The server speaks first: we check it is who we say
            // and that it speaks our version before sending anything.
            String greeting = reader.readLine();
            if (greeting == null) {
                throw new BiblioTechException(
                        "The server closed the connection without greeting");
            }
            if (!greeting.startsWith("200 ") || !greeting.contains(EXPECTED_VERSION)) {
                throw new BiblioTechException(
                        "Unexpected greeting from the server: '" + greeting + "'");
            }
            LOG.info(() -> "Connected to the catalogue " + host + ":" + port
                    + " (" + greeting + ")");

        } catch (IOException e) {
            closeSocketQuietly();
            throw NetworkErrorTranslator.translate(e, host + ":" + port);
        }
    }

    // ---------------------------------------------------------------
    // Protocol operations
    // ---------------------------------------------------------------

    /** QUERY <isbn>. Returns null if the material does not exist (404). */
    public ProtocolCard query(String isbn) throws BiblioTechException {
        validateArgument(isbn, "the ISBN");
        String reply = exchange("QUERY " + isbn);

        if (reply.startsWith("200 OK ")) {
            return ProtocolCard.fromLine(reply.substring("200 OK ".length()));
        }
        if (reply.startsWith("404 ")) {
            return null;        // "not found" is a result, not an error
        }
        throw protocolError(reply);
    }

    /** LIST. Returns every card in the catalogue. */
    public List<ProtocolCard> list() throws BiblioTechException {
        String header = exchange("LIST");

        if (!header.startsWith("201 LIST ")) {
            throw protocolError(header);
        }

        int announced = intOf(header.substring("201 LIST ".length()).strip(), header);
        if (announced < 0 || announced > MAX_LINES) {
            throw new BiblioTechException(
                    "The server announces a number of lines out of range: " + announced);
        }

        List<ProtocolCard> cards = new ArrayList<>(announced);
        try {
            String line;
            while ((line = reader.readLine()) != null) {
                if (line.equals(".")) {
                    break;      // end of the multi-line reply
                }
                if (cards.size() >= MAX_LINES) {
                    throw new BiblioTechException(
                            "The server is sending more lines than allowed");
                }
                cards.add(ProtocolCard.fromLine(line));
            }
            if (line == null) {
                throw new BiblioTechException(
                        "The server closed the connection in the middle of the list");
            }
        } catch (SocketTimeoutException e) {
            throw new BiblioTechException(
                    "The server stopped replying in the middle of the list", e);
        } catch (IOException e) {
            throw NetworkErrorTranslator.translate(e, host + ":" + port);
        }

        // The announced number is redundant on purpose: if it does not match,
        // there is a problem and it is better to know than to ignore it.
        if (cards.size() != announced) {
            LOG.warning("The server announced " + announced + " lines and sent "
                    + cards.size());
        }
        return cards;
    }

    /** LEND <isbn> <employee>. Returns true if the loan was registered. */
    public boolean lend(String isbn, String employee) throws BiblioTechException {
        validateArgument(isbn, "the ISBN");
        validateArgument(employee, "the employee");

        String reply = exchange("LEND " + isbn + " " + employee);

        if (reply.startsWith("200 ")) {
            return true;
        }
        if (reply.startsWith("409 ") || reply.startsWith("404 ")) {
            LOG.info(() -> "Loan rejected: " + reply);
            return false;
        }
        throw protocolError(reply);
    }

    // ---------------------------------------------------------------
    // Core: send one line and read one reply
    // ---------------------------------------------------------------

    private String exchange(String request) throws BiblioTechException {
        if (socket == null || socket.isClosed()) {
            throw new BiblioTechException("The client is not connected");
        }
        try {
            // The protocol specifies \n, not the platform separator:
            // that is why we write it by hand instead of using println(String).
            writer.print(request + "\n");
            writer.flush();         // MANDATORY: print() does not trigger autoFlush

            // PrintWriter swallows IOException; checkError() is the only
            // way of finding out that the write failed.
            if (writer.checkError()) {
                throw new BiblioTechException(
                        "Failed to send the request to the catalogue server");
            }

            String reply = reader.readLine();
            if (reply == null) {
                throw new BiblioTechException(
                        "The server closed the connection without replying to: " + request);
            }
            LOG.fine(() -> "C: " + request + "  ->  S: " + reply);
            return reply;

        } catch (SocketTimeoutException e) {
            throw new BiblioTechException(
                    "The server did not reply within " + READ_TIMEOUT_MS + " ms", e);
        } catch (IOException e) {
            throw NetworkErrorTranslator.translate(e, host + ":" + port);
        }
    }

    // ---------------------------------------------------------------
    // Validation and utilities
    // ---------------------------------------------------------------

    /**
     * An argument with a line break breaks the protocol: it would inject
     * an extra request. Validating the OUTPUT is as important as
     * validating the input.
     */
    private void validateArgument(String value, String name) throws BiblioTechException {
        if (value == null || value.isBlank()) {
            throw new BiblioTechException("Missing " + name);
        }
        if (value.indexOf('\n') >= 0 || value.indexOf('\r') >= 0) {
            throw new BiblioTechException(
                    "Invalid value for " + name + ": it contains line breaks");
        }
    }

    private int intOf(String text, String context) throws BiblioTechException {
        try {
            return Integer.parseInt(text);
        } catch (NumberFormatException e) {
            throw new BiblioTechException(
                    "Invalid number in the server reply: '" + context + "'", e);
        }
    }

    private BiblioTechException protocolError(String reply) {
        return new BiblioTechException(
                "Unexpected reply from the catalogue server: " + reply);
    }

    private void closeSocketQuietly() {
        if (socket != null) {
            try {
                socket.close();
            } catch (IOException ignored) {
                // While closing there is nothing left to save.
            }
        }
    }

    // ---------------------------------------------------------------
    // Closing
    // ---------------------------------------------------------------

    @Override
    public void close() {
        if (socket == null || socket.isClosed()) {
            return;
        }
        try {
            // A polite farewell: the server can tell an orderly close
            // from a crash and release resources calmly.
            writer.print("QUIT\n");
            writer.flush();

            // We give it little leeway: if it does not answer, we close anyway.
            socket.setSoTimeout(1_000);
            String bye = reader.readLine();
            LOG.fine(() -> "Farewell from the server: " + bye);

        } catch (IOException e) {
            // While closing, a failure changes nothing: log it and carry on.
            LOG.log(Level.FINE, "Failure during the farewell", e);
        } finally {
            closeSocketQuietly();
            LOG.info(() -> "Connection with " + host + ":" + port + " closed");
        }
    }
}

package com.nexussoftware.bibliotech.presentation;

import com.nexussoftware.bibliotech.exception.BiblioTechException;
import com.nexussoftware.bibliotech.network.CatalogClient;
import com.nexussoftware.bibliotech.network.CatalogClient.ProtocolCard;

import java.util.List;

/** Manual test of the BTCP/1 client against a server. */
public class CatalogClientTest {

    public static void main(String[] args) {
        String host = args.length > 0 ? args[0] : "localhost";
        int port = args.length > 1 ? Integer.parseInt(args[1]) : 9090;

        // CatalogClient is AutoCloseable: try-with-resources as always.
        try (CatalogClient client = new CatalogClient(host, port)) {
            client.connect();

            System.out.println("--- QUERY for an existing ISBN ---");
            ProtocolCard card = client.query("978-0000000001");
            if (card == null) {
                System.out.println("Not found");
            } else {
                System.out.printf("%s - %s [%s] %s%n",
                        card.isbn(), card.title(), card.type(),
                        card.available() ? "available" : "on loan");
            }

            System.out.println();
            System.out.println("--- QUERY for a non-existent ISBN ---");
            System.out.println(client.query("000-0000000000") == null
                    ? "Not found (correct)" : "Unexpected");

            System.out.println();
            System.out.println("--- LIST ---");
            List<ProtocolCard> catalog = client.list();
            for (ProtocolCard c : catalog) {
                System.out.println("  " + c.isbn() + "  " + c.title());
            }
            System.out.println("Total: " + catalog.size());

            System.out.println();
            System.out.println("--- LEND ---");
            boolean ok = client.lend("978-0000000002", "Diego_Alonso");
            System.out.println(ok ? "Loan registered" : "Loan rejected");

        } catch (BiblioTechException e) {
            // Error boundary: here there are no sockets left, only the domain.
            System.err.println("ERROR: " + e.getMessage());
            if (e.getCause() != null) {
                System.err.println("Technical cause: " + e.getCause());
            }
        }
    }
}

nc -l 9090

javac -d classes $(find src -name "*.java")
java -cp classes com.nexussoftware.bibliotech.presentation.CatalogClientTest

TERMINAL 1 (you, playing the server with nc -l 9090)
-----------------------------------------------------
200 BIBLIOTECH BTCP/1                                   <-- YOU TYPE (and Enter)
QUERY 978-0000000001                                        (sent by the client)
200 OK 978-0000000001|Effective Java|BOOK|true           <-- YOU TYPE
QUERY 000-0000000000
404 NOT FOUND 000-0000000000                            <-- YOU TYPE
LIST
201 LIST 3                                              <-- YOU TYPE
978-0000000001|Effective Java|BOOK|true                 <-- YOU TYPE
978-0000000002|Design Patterns|BOOK|false               <-- YOU TYPE
978-0000000003|Refactoring|BOOK|true                    <-- YOU TYPE
.                                                       <-- YOU TYPE
LEND 978-0000000002 Diego_Alonso
409 NOT AVAILABLE 978-0000000002                        <-- YOU TYPE
QUIT
221 BYE                                                 <-- YOU TYPE

TERMINAL 2 (the Java client)
-----------------------------------------------------
--- QUERY for an existing ISBN ---
978-0000000001 - Effective Java [BOOK] available

--- QUERY for a non-existent ISBN ---
Not found (correct)

--- LIST ---
  978-0000000001  Effective Java
  978-0000000002  Design Patterns
  978-0000000003  Refactoring
Total: 3

--- LEND ---
Loan rejected

package com.nexussoftware.bibliotech.network;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.net.ConnectException;
import java.net.InetSocketAddress;
import java.net.Socket;
import java.net.SocketTimeoutException;
import java.nio.charset.StandardCharsets;

/**
 * Echo client that measures round-trip latency.
 * Useful for comparing the effect of setTcpNoDelay and for measuring the network.
 */
public class EchoClient {

    private final String host;
    private final int port;
    private final boolean noNagle;

    public EchoClient(String host, int port, boolean noNagle) {
        this.host = host;
        this.port = port;
        this.noNagle = noNagle;
    }

    /** The result of one round of measurements. */
    public record Measurement(int sent, int mismatches,
                              double minMs, double avgMs, double maxMs) {
    }

    public Measurement measure(int repetitions) throws IOException {
        try (Socket socket = new Socket()) {

            // Options BEFORE using the socket.
            socket.setTcpNoDelay(noNagle);
            socket.connect(new InetSocketAddress(host, port), 2_000);
            socket.setSoTimeout(5_000);

            PrintWriter writer = new PrintWriter(
                    new BufferedWriter(
                            new OutputStreamWriter(socket.getOutputStream(),
                                    StandardCharsets.UTF_8)),
                    true);
            BufferedReader reader = new BufferedReader(
                    new InputStreamReader(socket.getInputStream(),
                            StandardCharsets.UTF_8));

            double min = Double.MAX_VALUE;
            double max = 0;
            double sum = 0;
            int mismatches = 0;
            int completed = 0;

            for (int i = 1; i <= repetitions; i++) {
                String message = "PING-" + i + "-BiblioTech";

                long t0 = System.nanoTime();
                writer.println(message);            // autoFlush: sent right away
                String echo = reader.readLine();    // we wait for the return
                long t1 = System.nanoTime();

                if (echo == null) {
                    System.out.println("The server closed after " + completed + " echoes");
                    break;
                }

                double ms = (t1 - t0) / 1_000_000.0;
                min = Math.min(min, ms);
                max = Math.max(max, ms);
                sum += ms;
                completed++;

                // The echo must be identical: if it is not, there is a problem
                // of charset, of delimiter or of protocol desynchronisation.
                if (!message.equals(echo)) {
                    mismatches++;
                    System.out.println("  MISMATCH: I sent '" + message
                            + "' and received '" + echo + "'");
                }
                System.out.printf("  %2d) %.2f ms%n", i, ms);
            }

            if (completed == 0) {
                return new Measurement(0, 0, 0, 0, 0);
            }
            return new Measurement(completed, mismatches, min, sum / completed, max);
        }
    }

    public static void main(String[] args) {
        String host = args.length > 0 ? args[0] : "localhost";
        int port = args.length > 1 ? Integer.parseInt(args[1]) : 9090;

        for (boolean noNagle : new boolean[]{true, false}) {
            System.out.println("=== setTcpNoDelay(" + noNagle + ") ===");
            try {
                Measurement m = new EchoClient(host, port, noNagle).measure(10);
                System.out.printf(
                        "  Echoes: %d   Mismatches: %d%n"
                        + "  min %.2f ms   avg %.2f ms   max %.2f ms%n%n",
                        m.sent(), m.mismatches(), m.minMs(), m.avgMs(), m.maxMs());

            } catch (ConnectException e) {
                // Nobody is listening: there is no point in retrying.
                System.err.println("  There is no echo server on " + host + ":" + port);
                System.err.println("  Start it with:  while true; do nc -l "
                        + port + " -c cat; done");
                return;

            } catch (SocketTimeoutException e) {
                // Transient: the machine does not reply in time.
                System.err.println("  Timed out talking to " + host);

            } catch (IOException e) {
                System.err.println("  Network failure: " + e);
            }
        }
    }
}

=== setTcpNoDelay(true) ===
   1) 1.84 ms
   2) 0.21 ms
   ...
  Echoes: 10   Mismatches: 0
  min 0.14 ms   avg 0.31 ms   max 1.84 ms

package com.nexussoftware.bibliotech.network;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.ConnectException;
import java.net.InetSocketAddress;
import java.net.Socket;
import java.net.SocketTimeoutException;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;

/**
 * Service detector: checks which ports in a range have something listening.
 *
 * LEGAL AND ETHICAL WARNING: scanning ports of machines that are not yours
 * without written authorisation is, in many countries, an offence of
 * unauthorised access to computer systems, and in practically all of them a
 * reason to be blocked by your provider. This tool is intended ONLY for
 * localhost and for machines belonging to Nexus Software with authorisation
 * from the systems department. A scan generates traffic and alerts in any modern IDS.
 */
public class ServiceDetector {

    /** The state of a port. An enum like those of 04-07. */
    public enum State {
        OPEN("there is a service listening"),
        CLOSED("the machine replies RST: nobody is on that port"),
        FILTERED("no reply: a firewall dropping, or a machine down");

        private final String description;

        State(String description) {
            this.description = description;
        }

        public String description() {
            return description;
        }
    }

    private static final Map<Integer, String> SERVICES = new HashMap<>();

    static {
        SERVICES.put(21, "FTP");
        SERVICES.put(22, "SSH");
        SERVICES.put(25, "SMTP");
        SERVICES.put(53, "DNS");
        SERVICES.put(80, "HTTP");
        SERVICES.put(443, "HTTPS");
        SERVICES.put(3306, "MySQL");
        SERVICES.put(5432, "PostgreSQL");
        SERVICES.put(6379, "Redis");
        SERVICES.put(8080, "Alternative HTTP");
        SERVICES.put(9090, "BiblioTech BTCP/1");
        SERVICES.put(9091, "BiblioTech discovery");
    }

    public void scan(String host, int from, int to, int timeoutMs) {
        System.out.printf("Scanning %s ports %d-%d (timeout %d ms)%n%n",
                host, from, to, timeoutMs);
        System.out.printf("%-8s %-10s %-24s %s%n", "PORT", "STATE", "SERVICE", "GREETING");
        System.out.println("-".repeat(90));

        int open = 0, closed = 0, filtered = 0;

        for (int port = from; port <= to; port++) {
            State state = probe(host, port, timeoutMs);

            switch (state) {
                case OPEN -> open++;
                case CLOSED -> closed++;
                case FILTERED -> filtered++;
            }

            // We only show the interesting ones: a table with 65535 CLOSED
            // helps nobody.
            if (state == State.OPEN) {
                String greeting = readGreeting(host, port, 500);
                System.out.printf("%-8d %-10s %-24s %s%n",
                        port, state,
                        SERVICES.getOrDefault(port, "(unknown)"),
                        greeting == null ? "(no greeting)" : greeting);
            } else if (state == State.FILTERED) {
                System.out.printf("%-8d %-10s %-24s %s%n",
                        port, state,
                        SERVICES.getOrDefault(port, "(unknown)"), "");
            }
        }

        System.out.println("-".repeat(90));
        System.out.printf("Open: %d   Closed: %d   Filtered: %d%n",
                open, closed, filtered);
        for (State s : State.values()) {
            System.out.printf("  %-10s %s%n", s, s.description());
        }
    }

    /** Tries to connect and classifies the result by the TYPE of exception. */
    private State probe(String host, int port, int timeoutMs) {
        try (Socket socket = new Socket()) {
            socket.connect(new InetSocketAddress(host, port), timeoutMs);
            return State.OPEN;

        } catch (SocketTimeoutException e) {
            // Nobody replied to the SYN: usually a firewall with a DROP policy.
            return State.FILTERED;

        } catch (ConnectException e) {
            // The machine replied RST: it is alive, but that port has no service.
            // THIS IS VALUABLE INFORMATION: it tells "machine down" from "port closed".
            return State.CLOSED;

        } catch (IOException e) {
            // NoRouteToHost and the like.
            return State.FILTERED;
        }
    }

    /**
     * Many protocols greet on connect (SMTP, FTP, SSH, BTCP/1).
     * A timeout here is NOT a failure: it means the service expects
     * you to speak first (like HTTP).
     */
    private String readGreeting(String host, int port, int timeoutMs) {
        try (Socket socket = new Socket()) {
            socket.connect(new InetSocketAddress(host, port), timeoutMs);
            socket.setSoTimeout(timeoutMs);

            BufferedReader reader = new BufferedReader(
                    new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8));
            String line = reader.readLine();

            if (line == null) {
                return null;
            }
            // We truncate: a huge greeting does not fit in the table, and besides
            // we do not want to dump arbitrary network data onto the console.
            return line.length() > 45 ? line.substring(0, 45) + "..." : line;

        } catch (IOException e) {
            return null;
        }
    }

    public static void main(String[] args) {
        ServiceDetector detector = new ServiceDetector();
        // ONLY localhost by default: scanning another machine requires authorisation.
        detector.scan("localhost", 9080, 9100, 300);
    }
}

Scanning localhost ports 9080-9100 (timeout 300 ms)

PORT     STATE      SERVICE                  GREETING
------------------------------------------------------------------------------------------
9090     OPEN       BiblioTech BTCP/1        (no greeting)
------------------------------------------------------------------------------------------
Open: 1   Closed: 20   Filtered: 0

package com.nexussoftware.bibliotech.network;

import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.InetSocketAddress;
import java.net.Socket;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.logging.Logger;

/**
 * Sender of a catalogue file over TCP.
 *
 * Protocol (binary, with length prefix):
 *   [int  ] length of the name in UTF-8 bytes
 *   [bytes] name
 *   [long ] size of the content in bytes
 *   [bytes] content
 *   -- shutdownOutput --
 *   [line ] summary from the receiver, as UTF-8 text
 */
public class FileSender {

    private static final Logger LOG = Logger.getLogger(FileSender.class.getName());
    private static final int BLOCK = 8192;

    public void send(String host, int port, Path file) throws IOException {
        if (!Files.isRegularFile(file)) {
            throw new IOException("Not a file: " + file);
        }
        long size = Files.size(file);

        try (Socket socket = new Socket()) {
            socket.connect(new InetSocketAddress(host, port), 3_000);
            socket.setSoTimeout(30_000);

            DataOutputStream output = new DataOutputStream(
                    new BufferedOutputStream(socket.getOutputStream()));

            // --- Header: name with a length prefix ---
            // We send ONLY the file name, never the full path:
            // the receiver decides where to store it.
            byte[] name = file.getFileName().toString()
                    .getBytes(StandardCharsets.UTF_8);
            output.writeInt(name.length);
            output.write(name);
            output.writeLong(size);

            // --- Content in blocks ---
            long sent = 0;
            try (InputStream fileInput =
                         new BufferedInputStream(Files.newInputStream(file))) {
                byte[] buffer = new byte[BLOCK];
                int read;
                while ((read = fileInput.read(buffer)) != -1) {
                    // read may return LESS than BLOCK: we must write
                    // exactly 'read' bytes, never buffer.length.
                    output.write(buffer, 0, read);
                    sent += read;
                }
            }
            output.flush();     // the usual flush, before closing the direction

            LOG.info(() -> "Sent " + size + " bytes of " + file.getFileName());

            // --- shutdownOutput: INDISPENSABLE ---
            // The receiver reads until the stream is exhausted. Without this
            // half-close, the receiver would go on waiting for more bytes
            // indefinitely and we would wait for its summary: a perfect deadlock.
            // We cannot use socket.close() because we still have to READ.
            socket.shutdownOutput();

            // --- Summary from the receiver (the read direction is still open) ---
            BufferedReader reader = new BufferedReader(
                    new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8));
            String summary = reader.readLine();
            System.out.println("Receiver: " + (summary == null ? "(no reply)" : summary));

            if (sent != size) {
                LOG.warning("The file changed size during the send");
            }
        }
    }

    public static void main(String[] args) throws IOException {
        Path file = Path.of(args.length > 0 ? args[0] : "catalog.csv");
        new FileSender().send("localhost", 9091, file);
    }
}

package com.nexussoftware.bibliotech.network;

import java.io.BufferedOutputStream;
import java.io.BufferedWriter;
import java.io.DataInputStream;
import java.io.EOFException;
import java.io.IOException;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.net.ServerSocket;
import java.net.Socket;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Receiver of the file. A minimal single-connection server:
 * the concurrent, complete version is written in 09-03.
 */
public class FileReceiver {

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

    private static final int MAX_NAME = 255;
    private static final long MAX_SIZE = 10L * 1024 * 1024;        // 10 MB
    private static final Path TARGET_DIR = Path.of("received");

    public void listen(int port) throws IOException {
        Files.createDirectories(TARGET_DIR);

        try (ServerSocket server = new ServerSocket(port)) {
            LOG.info(() -> "Receiver listening on port " + port);

            // accept() blocks until a connection arrives and returns
            // an ALREADY connected Socket. All the detail, in 09-03.
            try (Socket socket = server.accept()) {
                socket.setSoTimeout(30_000);
                LOG.info(() -> "Connection from " + socket.getRemoteSocketAddress());
                serve(socket);
            }
        }
    }

    private void serve(Socket socket) throws IOException {
        DataInputStream input = new DataInputStream(socket.getInputStream());

        String summary;
        try {
            // --- Name, with a VALIDATED length prefix ---
            int nameLength = input.readInt();
            if (nameLength <= 0 || nameLength > MAX_NAME) {
                throw new IOException("Invalid name length: " + nameLength);
            }
            byte[] nameBytes = input.readNBytes(nameLength);
            if (nameBytes.length < nameLength) {
                throw new EOFException("Stream cut while reading the name");
            }
            String name = new String(nameBytes, StandardCharsets.UTF_8);

            // --- Sanitising the name: PATH TRAVERSAL ---
            // Without this, a malicious sender sends "../../etc/cron.d/backdoor"
            // and we write wherever they like. It is a classic vulnerability.
            if (name.contains("/") || name.contains("\\")
                    || name.contains("..") || name.isBlank()) {
                throw new IOException("File name not allowed: " + name);
            }

            // --- Size, also validated ---
            long size = input.readLong();
            if (size < 0 || size > MAX_SIZE) {
                throw new IOException("Size out of range: " + size);
            }

            // --- Content ---
            Path target = TARGET_DIR.resolve(name).normalize();
            // Belt and braces: we check that the result is still inside
            // the intended directory, in case something slipped past earlier.
            if (!target.startsWith(TARGET_DIR)) {
                throw new IOException("Resulting path outside the directory: " + target);
            }

            long received = 0;
            try (OutputStream fileOutput =
                         new BufferedOutputStream(Files.newOutputStream(target))) {
                byte[] buffer = new byte[8192];
                int read;
                // We read until end of stream: it is the sender's shutdownOutput()
                // that produces this -1. Without it, this loop would never end.
                while ((read = input.read(buffer)) != -1) {
                    if (received + read > size) {
                        throw new IOException(
                                "The sender is sending more bytes than announced");
                    }
                    fileOutput.write(buffer, 0, read);
                    received += read;
                }
            }

            if (received != size) {
                throw new EOFException(size
                        + " bytes were announced and " + received + " arrived");
            }

            long finalReceived = received;
            LOG.info(() -> "Saved " + target + " (" + finalReceived + " bytes)");
            summary = "200 OK " + name + " " + received + " bytes";

        } catch (IOException e) {
            LOG.log(Level.WARNING, "Transfer rejected", e);
            summary = "400 REJECTED " + e.getMessage();
        }

        // --- Text reply, with an explicit charset ---
        BufferedWriter writer = new BufferedWriter(
                new OutputStreamWriter(socket.getOutputStream(), StandardCharsets.UTF_8));
        writer.write(summary);
        writer.write('\n');
        writer.flush();         // without this, the sender would wait forever
    }

    public static void main(String[] args) throws IOException {
        new FileReceiver().listen(9091);
    }
}

# Terminal 1
java -cp classes com.nexussoftware.bibliotech.network.FileReceiver

# Terminal 2
java -cp classes com.nexussoftware.bibliotech.network.FileSender catalog.csv

Terminal 1:
INFO: Receiver listening on port 9091
INFO: Connection from /127.0.0.1:52104
INFO: Saved received/catalog.csv (2847 bytes)

Terminal 2:
INFO: Sent 2847 bytes of catalog.csv
Receiver: 200 OK catalog.csv 2847 bytes