type,reference,title,author,year,available
BOOK,978-0000000001,Effective Java,Joshua Bloch,2018,true
BOOK,978-0000000002,Design Patterns,Erich Gamma,1994,false
BOOK,978-0000000003,Refactoring,Martin Fowler,1999,true

title,author,notes
Effective Java,Bloch,No notes
"Java: the language, the machine and the ecosystem",Bloch,"Contains a comma"
"The book called ""Refactoring""",Fowler,"Contains doubled quotes"
"Title with
a line break",Author,"A field can span several physical lines"
No quotes,,"Empty field in the middle"

// NAIVE: it works with simple data and fails with real data
String[] fields = line.split(",");

String line = "\"Java: the language, the machine and the ecosystem\",Bloch,2018";
String[] fields = line.split(",");

// fields.length == 4, not 3
// fields[0] == "\"Java: the language"
// fields[1] == " the machine and the ecosystem\""
// fields[2] == "Bloch"
// fields[3] == "2018"

"Effective Java,Bloch,".split(",");        // 2 elements: it discards trailing empties
"Effective Java,Bloch,".split(",", -1);    // 3 elements: correct

String first = fields[0];                 // "\uFEFFtype", not "type"
first.equals("type");                     // false
first.length();                           // 5, not 4

/**
 * Escapes a field per RFC 4180.
 *
 * A field needs quotes if it contains the separator, a quote, a line break,
 * or spaces at the beginning or the end (which many tools trim without
 * warning).
 *
 * Interior quotes are DOUBLED, not preceded by a backslash: CSV does not
 * use backslashes.
 */
public static String escape(String field, char separator) {
    if (field == null) {
        return "";                     // null and empty are written the same (section 5)
    }

    boolean needsQuotes =
            field.indexOf(separator) >= 0
            || field.indexOf('"') >= 0
            || field.indexOf('\n') >= 0
            || field.indexOf('\r') >= 0
            || field.startsWith(" ")
            || field.endsWith(" ");

    if (!needsQuotes) {
        return field;
    }
    // Double the interior quotes and wrap in quotes
    return '"' + field.replace("\"", "\"\"") + '"';
}

/** Undoes the escaping of an already-extracted field. */
public static String unescape(String field) {
    if (field == null || field.isEmpty()) {
        return "";
    }
    String clean = field.trim();

    if (clean.length() >= 2 && clean.startsWith("\"") && clean.endsWith("\"")) {
        clean = clean.substring(1, clean.length() - 1);
        clean = clean.replace("\"\"", "\"");
    }
    return clean;
}

package com.nexussoftware.bibliotech.infrastructure;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.Reader;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;

/**
 * CSV reader conforming to RFC 4180.
 *
 * It handles correctly:
 *   - separators inside quoted fields
 *   - quotes escaped by doubling
 *   - line breaks inside a field (a record spans several lines)
 *   - empty fields, including the last one
 *   - the BOM at the start of the file
 *
 * It does NOT handle (and it says so honestly):
 *   - the distinction between null and the empty string: CSV does not have it
 *   - encodings other than the one it is given
 *
 * It is Closeable: it closes the Reader it wraps (06-06).
 */
public class CsvReader implements AutoCloseable {

    /** Byte order mark that Excel writes at the start of UTF-8 files. */
    private static final char BOM = '\uFEFF';

    private static final char QUOTE = '"';

    private final BufferedReader reader;
    private final char separator;

    private boolean firstRead = true;
    private int recordNumber = 0;
    private int physicalLineNumber = 0;

    public CsvReader(Reader source, char separator) {
        Objects.requireNonNull(source, "The source cannot be null");
        this.reader = (source instanceof BufferedReader br)
                ? br
                : new BufferedReader(source);       // do not wrap twice (07-04)
        this.separator = separator;
    }

    public CsvReader(Reader source) {
        this(source, ',');
    }

    /**
     * Reads the next record.
     *
     * A record can span SEVERAL physical lines if some field has a line break
     * inside it. That is why one readLine() per record is not enough.
     *
     * @return the already-unescaped fields, or null if there are no more records
     * @throws CsvFormatException if the record is malformed
     */
    public List<String> next() throws IOException {
        String line = reader.readLine();
        if (line == null) {
            return null;                             // the end (07-04)
        }
        physicalLineNumber++;

        // Strip the BOM ONLY from the first line
        if (firstRead) {
            firstRead = false;
            if (!line.isEmpty() && line.charAt(0) == BOM) {
                line = line.substring(1);
            }
        }

        List<String> fields = new ArrayList<>();
        StringBuilder field = new StringBuilder();
        boolean insideQuotes = false;
        int index = 0;

        while (true) {
            if (index >= line.length()) {
                if (!insideQuotes) {
                    break;                           // end of the record
                }
                // We are INSIDE quotes: the field continues on the next
                // physical line. The line break is restored.
                String continuation = reader.readLine();
                if (continuation == null) {
                    throw new CsvFormatException(physicalLineNumber,
                            "The file ends with an unclosed quote");
                }
                physicalLineNumber++;
                field.append('\n');
                line = continuation;
                index = 0;
                continue;
            }

            char c = line.charAt(index);

            if (insideQuotes) {
                if (c == QUOTE) {
                    // A quote inside quotes: either it closes, or it is doubled
                    if (index + 1 < line.length() && line.charAt(index + 1) == QUOTE) {
                        field.append(QUOTE);         // doubled: one literal quote
                        index += 2;
                    } else {
                        insideQuotes = false;        // it closes the field
                        index++;
                    }
                } else {
                    field.append(c);
                    index++;
                }

            } else {
                if (c == QUOTE && field.isEmpty()) {
                    // Quotes at the START of the field: they open
                    insideQuotes = true;
                    index++;
                } else if (c == separator) {
                    fields.add(field.toString());
                    field.setLength(0);
                    index++;
                } else {
                    field.append(c);
                    index++;
                }
            }
        }

        fields.add(field.toString());                // the last field, always
        recordNumber++;
        return fields;
    }

    /**
     * Reads all the remaining records.
     *
     * WARNING: it loads the whole file into memory (07-01). For large files,
     * use next() in a loop.
     */
    public List<List<String>> readAll() throws IOException {
        List<List<String>> records = new ArrayList<>();
        List<String> record;
        while ((record = next()) != null) {
            records.add(record);
        }
        return records;
    }

    public int getRecordNumber()       { return recordNumber; }
    public int getPhysicalLineNumber() { return physicalLineNumber; }

    @Override
    public void close() throws IOException {
        reader.close();
    }

    /** Format failure with the exact physical line (06-04). */
    public static class CsvFormatException extends IOException {

        private static final long serialVersionUID = 1L;

        private final int line;

        public CsvFormatException(int line, String message) {
            super("Line " + line + ": " + message);
            this.line = line;
        }

        public int getLine() { return line; }
    }
}

public class CsvReaderTest {

    public static void main(String[] args) throws IOException {
        String content = String.join("\n",
                "title,author,year",
                "Effective Java,Joshua Bloch,2018",
                "\"Java: the language, the machine\",Bloch,2018",
                "\"The book \"\"Refactoring\"\"\",Fowler,1999",
                "\"Title with",
                "a line break\",Author,2020",
                "No quotes,,2021",
                "Last field empty,Author,");

        try (CsvReader csv = new CsvReader(new java.io.StringReader(content))) {
            List<String> record;
            while ((record = csv.next()) != null) {
                System.out.printf("[%d] %d fields: %s%n",
                        csv.getRecordNumber(), record.size(), record);
            }
        }
    }
}

[1] 3 fields: [title, author, year]
[2] 3 fields: [Effective Java, Joshua Bloch, 2018]
[3] 3 fields: [Java: the language, the machine, Bloch, 2018]
[4] 3 fields: [The book "Refactoring", Fowler, 1999]
[5] 3 fields: [Title with
a line break, Author, 2020]
[6] 3 fields: [No quotes, , 2021]
[7] 3 fields: [Last field empty, Author, ]

package com.nexussoftware.bibliotech.infrastructure;

import java.io.IOException;
import java.io.Writer;
import java.util.List;
import java.util.Objects;

/**
 * CSV writer conforming to RFC 4180.
 *
 * It quotes and escapes whatever is needed, so that what is written can be
 * read back with CsvReader without losing anything.
 */
public class CsvWriter implements AutoCloseable {

    private static final char QUOTE = '"';

    private final Writer output;
    private final char separator;
    private final String lineEnding;

    private int recordsWritten = 0;

    /**
     * @param output     destination, normally a BufferedWriter (07-04)
     * @param separator  ',' or ';'
     * @param lineEnding "\n" for files that are versioned; CRLF if the
     *                   consumer demands it. RFC 4180 asks for CRLF.
     */
    public CsvWriter(Writer output, char separator, String lineEnding) {
        this.output = Objects.requireNonNull(output, "The output cannot be null");
        this.separator = separator;
        this.lineEnding = Objects.requireNonNull(lineEnding);
    }

    public CsvWriter(Writer output) {
        this(output, ',', "\n");
    }

    /** Writes a complete record. */
    public void writeRecord(List<String> fields) throws IOException {
        Objects.requireNonNull(fields, "The fields cannot be null");

        for (int i = 0; i < fields.size(); i++) {
            if (i > 0) {
                output.write(separator);
            }
            output.write(escape(fields.get(i)));
        }
        output.write(lineEnding);
        recordsWritten++;
    }

    /** Varargs variant, convenient for short calls. */
    public void writeRecord(String... fields) throws IOException {
        writeRecord(List.of(fields));
    }

    /** Writes the header. It is an ordinary record; the name is documentation. */
    public void writeHeader(String... names) throws IOException {
        writeRecord(names);
    }

    /**
     * Escapes a field per RFC 4180.
     *
     * It is quoted if it contains the separator, a quote, a line break, or
     * spaces at the ends (which many tools trim).
     */
    private String escape(String field) {
        if (field == null || field.isEmpty()) {
            return "";
        }
        boolean needs = field.indexOf(separator) >= 0
                || field.indexOf(QUOTE) >= 0
                || field.indexOf('\n') >= 0
                || field.indexOf('\r') >= 0
                || field.charAt(0) == ' '
                || field.charAt(field.length() - 1) == ' ';

        if (!needs) {
            return field;
        }
        return QUOTE + field.replace("\"", "\"\"") + QUOTE;
    }

    public int getRecordsWritten() { return recordsWritten; }

    /** Explicit flush: useful if the consumer reads while we write (07-02). */
    public void flush() throws IOException {
        output.flush();
    }

    @Override
    public void close() throws IOException {
        output.close();          // the Writer's close does a flush (07-02)
    }
}

public class RoundTripTest {

    public static void main(String[] args) throws IOException {
        List<List<String>> originals = List.of(
                List.of("title", "author", "notes"),
                List.of("Effective Java", "Bloch", ""),
                List.of("Java: the language, the machine", "Bloch", "with a comma"),
                List.of("The book \"Refactoring\"", "Fowler", "with quotes"),
                List.of("Title with\na break", "Author", "with a break"),
                List.of("  spaces  ", "Author", "with spaces"));

        // Write to memory (07-03)
        java.io.StringWriter memory = new java.io.StringWriter();
        try (CsvWriter writer = new CsvWriter(memory)) {
            for (List<String> r : originals) {
                writer.writeRecord(r);
            }
        }

        System.out.println("=== CSV GENERATED ===");
        System.out.println(memory);

        // Read it back
        System.out.println("=== ROUND-TRIP CHECK ===");
        try (CsvReader reader = new CsvReader(new java.io.StringReader(memory.toString()))) {
            int i = 0;
            List<String> read;
            boolean allGood = true;

            while ((read = reader.next()) != null) {
                boolean same = read.equals(originals.get(i));
                allGood &= same;
                System.out.printf("  [%d] %s  %s%n", i, same ? "OK  " : "FAIL", read);
                i++;
            }
            System.out.println(allGood
                    ? "  All the records come back IDENTICAL."
                    : "  THERE IS DATA LOSS.");
        }
    }
}

=== CSV GENERATED ===
title,author,notes
Effective Java,Bloch,
"Java: the language, the machine",Bloch,with a comma
"The book ""Refactoring""",Fowler,with quotes
"Title with
a break",Author,with a break
"  spaces  ",Author,with spaces

=== ROUND-TRIP CHECK ===
  [0] OK   [title, author, notes]
  [1] OK   [Effective Java, Bloch, ]
  [2] OK   [Java: the language, the machine, Bloch, with a comma]
  [3] OK   [The book "Refactoring", Fowler, with quotes]
  [4] OK   [Title with
a break, Author, with a break]
  [5] OK   [  spaces  , Author, with spaces]
  All the records come back IDENTICAL.

title,rate
Effective Java,0,25

import java.util.Locale;

// WRITING: pin the Locale so that the decimal is ALWAYS the dot
String rate = String.format(Locale.ROOT, "%.2f", 0.25);        // "0.25"

// Without a Locale, on a Spanish machine:
String bad = String.format("%.2f", 0.25);                      // "0,25"  <-- ambiguous

// READING: always parse with a dot
double value = Double.parseDouble("0.25");     // Double.parseDouble ALWAYS uses a dot

// If the file has a decimal comma, it has to be normalised first
double valueEs = Double.parseDouble("0,25".replace(',', '.'));

/** Parses a decimal accepting a dot or a comma. Tolerant reading, strict writing. */
private static double parseDecimal(String text, String field, int line) {
    if (text == null || text.isBlank()) {
        return 0.0;
    }
    try {
        return Double.parseDouble(text.trim().replace(',', '.'));
    } catch (NumberFormatException e) {
        throw new IllegalArgumentException(String.format(
                "Line %d: the field '%s' is not a valid number: '%s'",
                line, field, text), e);            // chain the cause (06-03)
    }
}

package com.nexussoftware.bibliotech.service;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Objects;
import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.domain.Book;
import com.nexussoftware.bibliotech.domain.Material;
import com.nexussoftware.bibliotech.domain.DuplicateReferenceException;
import com.nexussoftware.bibliotech.infrastructure.CsvWriter;
import com.nexussoftware.bibliotech.infrastructure.CsvReader;

/**
 * Exports and imports the BiblioTech catalogue in CSV per RFC 4180.
 *
 * It replaces the 07-02 version, which "sanitised" the titles by replacing
 * the separators with commas and LOST THE DATA. Now a title such as
 * "Java: the language, the machine and the ecosystem" is exported and
 * imported back identical.
 *
 * Persistence on NIO.2 (07-06), with atomic writing.
 */
public class CsvCatalogExporter {

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

    private static final java.nio.charset.Charset CHARSET = StandardCharsets.UTF_8;

    /** Comma and decimal dot: the standard. For a European Excel, ';' (section 7). */
    private static final char SEPARATOR = ',';

    private static final String[] CATALOG_HEADER =
            { "type", "reference", "title", "author", "year", "available" };

    private static final String[] LOANS_HEADER =
            { "reference", "material", "employee", "start_day",
              "return_day", "fine" };

    private final Path directory;

    public CsvCatalogExporter(Path directory) throws IOException {
        this.directory = Objects.requireNonNull(directory).toAbsolutePath().normalize();
        Files.createDirectories(this.directory);
    }

    // ---------------------- EXPORTING ----------------------

    /**
     * Exports the catalogue to CSV, atomically (07-06).
     *
     * @return number of materials exported
     */
    public int exportCatalog(Catalog catalog) throws IOException {
        Objects.requireNonNull(catalog, "The catalogue cannot be null");

        List<Material> materials = catalog.list();
        Path target = directory.resolve("catalog.csv");
        Path temp = target.resolveSibling(target.getFileName() + ".tmp");

        boolean completed = false;
        try {
            try (BufferedWriter output = Files.newBufferedWriter(temp, CHARSET,
                         StandardOpenOption.CREATE,
                         StandardOpenOption.TRUNCATE_EXISTING,
                         StandardOpenOption.WRITE);
                 CsvWriter csv = new CsvWriter(output, SEPARATOR, "\n")) {

                csv.writeHeader(CATALOG_HEADER);

                for (Material m : materials) {
                    csv.writeRecord(toRecord(m));
                }
            }

            Files.move(temp, target,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            completed = true;

            LOG.info(() -> String.format("Catalogue exported: %d materials to %s",
                    materials.size(), target));

        } catch (AtomicMoveNotSupportedException e) {
            LOG.warning(() -> "No ATOMIC_MOVE; non-atomic replacement");
            Files.move(temp, target, StandardCopyOption.REPLACE_EXISTING);
            completed = true;

        } finally {
            if (!completed) {
                Files.deleteIfExists(temp);               // compensation (06-05)
            }
        }
        return materials.size();
    }

    /**
     * Converts a material into a CSV record.
     *
     * NO sanitising: the writer quotes whatever is needed. The title travels
     * INTACT, with its commas, its quotes and its colons.
     */
    private List<String> toRecord(Material m) {
        List<String> fields = new ArrayList<>(6);

        if (m instanceof Book book) {                      // 03-06
            fields.add("BOOK");
            fields.add(book.getIsbn());
            fields.add(book.getTitle());
            fields.add(book.getAuthor());
            fields.add(String.valueOf(book.getPublicationYear()));
        } else {
            fields.add(m.getType().toUpperCase(Locale.ROOT));
            fields.add(m.getReference());
            fields.add(m.getTitle());
            fields.add("");
            fields.add("");
        }
        fields.add(String.valueOf(m.isAvailable()));
        return fields;
    }

    // ---------------------- IMPORTING ----------------------

    /** Result of an import (06-07, 07-04). */
    public record ImportResult(int read, int imported, int discarded,
                               List<String> errors) {

        public String summary() {
            StringBuilder sb = new StringBuilder();
            sb.append(String.format(
                    "CSV import: %d records read, %d imported, %d discarded%n",
                    read, imported, discarded));
            int n = Math.min(10, errors.size());
            for (int i = 0; i < n; i++) {
                sb.append("    ").append(errors.get(i)).append('\n');
            }
            if (errors.size() > n) {
                sb.append(String.format("    ... and %d more%n", errors.size() - n));
            }
            return sb.toString();
        }
    }

    /**
     * Imports the catalogue from CSV.
     *
     * The policy of 06-07 and 07-04: a bad line is discarded and counted;
     * a missing file degrades to an empty result with no exception.
     */
    public ImportResult importCatalog(Catalog catalog) throws IOException {
        Objects.requireNonNull(catalog, "The catalogue cannot be null");

        Path source = directory.resolve("catalog.csv");
        List<String> errors = new ArrayList<>();
        int read = 0, imported = 0;

        if (Files.notExists(source)) {
            LOG.warning(() -> "There is no CSV catalogue at " + source
                    + "; starting with an empty catalogue");
            return new ImportResult(0, 0, 0, errors);
        }

        try (BufferedReader reader = Files.newBufferedReader(source, CHARSET);
             CsvReader csv = new CsvReader(reader, SEPARATOR)) {

            List<String> header = csv.next();
            if (header == null) {
                LOG.warning(() -> "The file " + source + " is empty");
                return new ImportResult(0, 0, 0, errors);
            }
            checkHeader(header, errors);

            List<String> record;
            while ((record = csv.next()) != null) {
                read++;
                int number = csv.getRecordNumber();

                try {
                    Material material = toMaterial(record, number);
                    if (material != null) {
                        catalog.register(material);
                        imported++;
                    }
                } catch (IllegalArgumentException e) {
                    errors.add(e.getMessage());
                } catch (DuplicateReferenceException e) {
                    errors.add("Record " + number + ": " + e.getMessage());
                }
            }
        }

        int discarded = read - imported;
        LOG.info(() -> String.format("Catalogue imported: %d of %d records",
                imported, read));

        return new ImportResult(read, imported, discarded, errors);
    }

    /** A change of columns is a warning, not a fatal failure. */
    private void checkHeader(List<String> header, List<String> errors) {
        if (header.size() != CATALOG_HEADER.length) {
            errors.add(String.format(
                    "Header with %d columns; %d were expected (%s). "
                            + "The import is attempted anyway.",
                    header.size(), CATALOG_HEADER.length,
                    String.join(", ", CATALOG_HEADER)));
        }
    }

    /** Builds the material validating each field. Throws if the record is invalid. */
    private Material toMaterial(List<String> fields, int number) {
        if (fields.size() < 5) {
            throw new IllegalArgumentException(String.format(
                    "Record %d: %d fields, at least 5 were expected", number, fields.size()));
        }

        String type = fields.get(0).trim().toUpperCase(Locale.ROOT);
        if (!"BOOK".equals(type)) {
            throw new IllegalArgumentException(
                    "Record " + number + ": unsupported type '" + type + "'");
        }

        String isbn   = fields.get(1).trim();
        String title  = fields.get(2).trim();
        String author = fields.get(3).trim();

        if (isbn.isEmpty() || title.isEmpty()) {
            throw new IllegalArgumentException(
                    "Record " + number + ": ISBN or title empty");
        }

        int year;
        try {
            year = Integer.parseInt(fields.get(4).trim());
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException(String.format(
                    "Record %d: the year '%s' is not a number",
                    number, fields.get(4)), e);          // with the cause (06-03)
        }

        boolean available = fields.size() < 6
                || !"false".equalsIgnoreCase(fields.get(5).trim());

        return new Book(title, author.isEmpty() ? "Unknown" : author,
                isbn, year, available);
    }

    // ---------------------- LOANS ----------------------

    /** Exports the loan register, with the decimals in Locale.ROOT. */
    public int exportLoans(List<Loan> loans) throws IOException {
        Path target = directory.resolve("loans.csv");

        try (BufferedWriter output = Files.newBufferedWriter(target, CHARSET,
                     StandardOpenOption.CREATE,
                     StandardOpenOption.TRUNCATE_EXISTING,
                     StandardOpenOption.WRITE);
             CsvWriter csv = new CsvWriter(output, SEPARATOR, "\n")) {

            csv.writeHeader(LOANS_HEADER);

            for (Loan l : loans) {
                csv.writeRecord(
                        l.getReference(),
                        l.getMaterial().getReference(),
                        l.getBorrower().getIdentifier(),
                        String.valueOf(l.getStartDay()),
                        String.valueOf(l.isReturned() ? l.getReturnDay() : -1),
                        // Locale.ROOT: decimal DOT ALWAYS, so it can be reread
                        String.format(Locale.ROOT, "%.2f", l.calculateFine(l.getStartDay())));
            }
        }
        LOG.info(() -> "Loans exported: " + loans.size() + " to " + target);
        return loans.size();
    }
}

type,reference,title,author,year,available
BOOK,978-0000000001,Effective Java,Joshua Bloch,2018,true
BOOK,978-0000000002,Design Patterns,Erich Gamma,1994,false
BOOK,978-0000000003,Refactoring,Martin Fowler,1999,true
BOOK,978-0000000004,"Java: the language, the machine and the ecosystem",Bloch,2024,true

# BiblioTech configuration - Nexus Software
# This file is loaded at start-up and does NOT require recompiling the application

# --- Loan rules ---
bibliotech.loan.days = 15
bibliotech.max.loans = 3

# --- Fines ---
bibliotech.daily.rate = 0.25
bibliotech.max.fine = 20.0
bibliotech.minor.threshold = 7

# --- Paths ---
bibliotech.data.directory = data
bibliotech.data.catalog = catalog.csv

# --- Logging ---
bibliotech.log.level = INFO

# WRONG: \d is interpreted as an escape
path = C:\data\catalog.csv

# RIGHT: doubled backslash
path = C:\\data\\catalog.csv

# BETTER: ordinary slashes, which Java accepts on Windows (07-01)
path = C:/data/catalog.csv

import java.util.Properties;

Properties props = new Properties();

props.setProperty("bibliotech.loan.days", "15");

String days = props.getProperty("bibliotech.loan.days");               // "15"
String missing = props.getProperty("does.not.exist");                  // null
String withDefault = props.getProperty("does.not.exist", "a default"); // the default

props.containsKey("bibliotech.loan.days");       // true
props.stringPropertyNames();                     // Set<String> with all the keys
props.size();

# Before Java 9, the only way to write "cafe" with an acute accent:
message.welcome = Welcome to the BiblioTech caf\u00e9

import java.io.BufferedReader;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Properties;

public class LoadProperties {

    /** Loads with an EXPLICIT charset. The correct form, with no ambiguity. */
    public static Properties load(Path file) throws IOException {
        Properties props = new Properties();

        try (BufferedReader reader = Files.newBufferedReader(
                file, StandardCharsets.UTF_8)) {        // 07-06

            props.load(reader);          // load(Reader): the Reader decides the charset
        }
        return props;
    }

    /** Saves with an explicit charset. */
    public static void save(Properties props, Path file, String comment)
            throws IOException {

        try (java.io.BufferedWriter output = Files.newBufferedWriter(
                file, StandardCharsets.UTF_8,
                java.nio.file.StandardOpenOption.CREATE,
                java.nio.file.StandardOpenOption.TRUNCATE_EXISTING,
                java.nio.file.StandardOpenOption.WRITE)) {

            props.store(output, comment);
        }
    }
}

#Configuration generated by BiblioTech
#Wed Aug 05 09:14:22 CEST 2026
bibliotech.daily.rate=0.25
bibliotech.loan.days=15
bibliotech.data.directory=data

/** Loads from the classpath: the file goes inside the jar and cannot be lost. */
public static Properties loadFromClasspath(String resource) throws IOException {
    Properties props = new Properties();

    try (java.io.InputStream input =
                 Configuration.class.getResourceAsStream(resource)) {

        if (input == null) {
            throw new java.io.FileNotFoundException(
                    "The resource '" + resource + "' was not found on the classpath");
        }
        try (java.io.Reader reader = new java.io.InputStreamReader(
                input, StandardCharsets.UTF_8)) {       // the BRIDGE from 07-03
            props.load(reader);
        }
    }
    return props;
}

// Level 1: default values, in the code
Properties defaults = new Properties();
defaults.setProperty("bibliotech.loan.days", "15");
defaults.setProperty("bibliotech.daily.rate", "0.25");
defaults.setProperty("bibliotech.max.fine", "20.0");

// Level 2: the file, WITH the defaults as a fallback
Properties configuration = new Properties(defaults);
configuration.load(reader);        // the file only brings 'days'

configuration.getProperty("bibliotech.loan.days");        // from the file
configuration.getProperty("bibliotech.daily.rate");       // "0.25", from the default
configuration.getProperty("bibliotech.max.fine");         // "20.0", from the default

configuration.size();                        // 1: only what came from the file
configuration.stringPropertyNames().size();  // 3: it includes the defaults

package com.nexussoftware.bibliotech.infrastructure;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Locale;
import java.util.Objects;
import java.util.Properties;
import java.util.TreeMap;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * BiblioTech configuration with a hierarchy of sources.
 *
 * Precedence, from lowest to highest:
 *   1. code default values
 *   2. bibliotech-default.properties from the classpath
 *   3. external file bibliotech.properties
 *   4. environment variables (BIBLIOTECH_XXX_YYY)
 *   5. system properties (-Dbibliotech.xxx.yyy)
 *
 * GRACEFUL DEGRADATION (06-07): if there is no file at all, the application
 * starts with the default values and logs it. Configuring badly must not
 * prevent start-up; what MUST prevent it is an INVALID value, because
 * computing fines with an unknown rate would produce incorrect charges.
 */
public final class Configuration {

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

    private static final String DEFAULT_RESOURCE = "/bibliotech-default.properties";
    private static final String EXTERNAL_FILE = "bibliotech.properties";
    private static final String PREFIX = "bibliotech.";

    // ---------- Keys ----------
    public static final String LOAN_DAYS       = "bibliotech.loan.days";
    public static final String MAX_LOANS       = "bibliotech.max.loans";
    public static final String DAILY_RATE      = "bibliotech.daily.rate";
    public static final String MAX_FINE        = "bibliotech.max.fine";
    public static final String MINOR_THRESHOLD = "bibliotech.minor.threshold";
    public static final String DATA_DIRECTORY  = "bibliotech.data.directory";
    public static final String DATA_CATALOG    = "bibliotech.data.catalog";
    public static final String CSV_SEPARATOR   = "bibliotech.csv.separator";

    /** The properties already resolved by the hierarchy. */
    private final Properties resolved = new Properties();

    /** Where each value came from. Useful for diagnosis. */
    private final TreeMap<String, String> source = new TreeMap<>();

    private static Configuration instance;

    private Configuration() { }

    /**
     * Loads the configuration. Idempotent.
     *
     * @param filePath external file, or null for the default name
     */
    public static synchronized Configuration load(Path filePath) {
        if (instance != null) {
            return instance;
        }
        Configuration c = new Configuration();

        c.applyCodeDefaults();
        c.applyClasspathResource();
        c.applyExternalFile(filePath);
        c.applyEnvironmentVariables();
        c.applySystemProperties();
        c.validate();

        instance = c;
        LOG.info(() -> "Configuration loaded: " + c.resolved.size() + " properties");
        return instance;
    }

    public static synchronized Configuration get() {
        if (instance == null) {
            return load(null);
        }
        return instance;
    }

    /** For tests only: allows reloading between cases. */
    static synchronized void reset() { instance = null; }

    // ---------------------- THE FIVE LEVELS ----------------------

    /**
     * LEVEL 1: the code defaults.
     *
     * These are the values that have been hard-coded for seven modules. Now
     * they are in one place and are only the LAST resort, not the only option.
     */
    private void applyCodeDefaults() {
        put(LOAN_DAYS,       "15",          "code default");
        put(MAX_LOANS,       "3",           "code default");
        put(DAILY_RATE,      "0.25",        "code default");
        put(MAX_FINE,        "20.0",        "code default");
        put(MINOR_THRESHOLD, "7",           "code default");
        put(DATA_DIRECTORY,  "data",        "code default");
        put(DATA_CATALOG,    "catalog.csv", "code default");
        put(CSV_SEPARATOR,   ",",           "code default");
    }

    /** LEVEL 2: the factory file, inside the jar. */
    private void applyClasspathResource() {
        try (InputStream input = Configuration.class.getResourceAsStream(DEFAULT_RESOURCE)) {
            if (input == null) {
                LOG.fine(() -> "No " + DEFAULT_RESOURCE + " resource on the classpath");
                return;
            }
            // The BRIDGE from 07-03 with an explicit charset
            try (Reader reader = new InputStreamReader(input, StandardCharsets.UTF_8)) {
                merge(read(reader), "classpath " + DEFAULT_RESOURCE);
            }
        } catch (IOException e) {
            LOG.log(Level.WARNING, "Could not read " + DEFAULT_RESOURCE, e);
        }
    }

    /**
     * LEVEL 3: the external file.
     *
     * Its absence is NOT an error: the first run does not have it.
     * Graceful degradation (06-07, 07-01).
     */
    private void applyExternalFile(Path path) {
        Path file = (path != null) ? path : Path.of(EXTERNAL_FILE);

        if (Files.notExists(file)) {
            LOG.info(() -> "There is no configuration file at "
                    + file.toAbsolutePath()
                    + "; the default values are used");
            return;
        }

        try (BufferedReader reader = Files.newBufferedReader(
                file, StandardCharsets.UTF_8)) {             // 07-06

            merge(read(reader), "file " + file.toAbsolutePath());
            LOG.info(() -> "Configuration read from " + file.toAbsolutePath());

        } catch (IOException e) {
            // An UNREADABLE file IS a serious warning: somebody put it there
            // expecting it to be applied, and it is not being applied.
            LOG.log(Level.SEVERE, "Could not read " + file.toAbsolutePath()
                    + "; carrying on with the previous values", e);
        }
    }

    /**
     * LEVEL 4: environment variables.
     *
     * BIBLIOTECH_LOAN_DAYS -> bibliotech.loan.days
     */
    private void applyEnvironmentVariables() {
        for (var entry : System.getenv().entrySet()) {
            String variable = entry.getKey();
            if (!variable.startsWith("BIBLIOTECH_")) {
                continue;
            }
            String key = variable.toLowerCase(Locale.ROOT).replace('_', '.');
            put(key, entry.getValue(), "environment variable " + variable);
        }
    }

    /**
     * LEVEL 5: system properties (-D). The highest priority.
     */
    private void applySystemProperties() {
        Properties system = System.getProperties();
        for (String key : system.stringPropertyNames()) {
            if (key.startsWith(PREFIX)) {
                put(key, system.getProperty(key), "-D" + key);
            }
        }
    }

    private Properties read(Reader reader) throws IOException {
        Properties p = new Properties();
        p.load(reader);
        return p;
    }

    private void merge(Properties sourceProps, String description) {
        // stringPropertyNames, NOT keySet: it includes the defaults (section 12)
        for (String key : sourceProps.stringPropertyNames()) {
            put(key, sourceProps.getProperty(key), description);
        }
    }

    private void put(String key, String value, String sourceDescription) {
        if (value == null) {
            return;
        }
        // trim: trailing spaces in the value ARE preserved in .properties
        resolved.setProperty(key, value.trim());
        source.put(key, sourceDescription);
    }

    // ---------------------- VALIDATION ----------------------

    /**
     * Checks that the values are coherent.
     *
     * The distinction from 06-07: a MISSING file degrades (the defaults are
     * used); an INVALID value ABORTS, because computing fines with an unknown
     * rate would produce incorrect charges, and that is worse than not starting.
     */
    private void validate() {
        int days = getInt(LOAN_DAYS, 15);
        if (days < 1 || days > 365) {
            throw new InvalidConfigurationException(LOAN_DAYS,
                    String.valueOf(days), "it must be between 1 and 365");
        }

        int maximum = getInt(MAX_LOANS, 3);
        if (maximum < 1 || maximum > 50) {
            throw new InvalidConfigurationException(MAX_LOANS,
                    String.valueOf(maximum), "it must be between 1 and 50");
        }

        double rate = getDouble(DAILY_RATE, 0.25);
        if (rate < 0 || rate > 100) {
            throw new InvalidConfigurationException(DAILY_RATE,
                    String.valueOf(rate), "it must be between 0 and 100 EUR/day");
        }

        double cap = getDouble(MAX_FINE, 20.0);
        if (cap < 0) {
            throw new InvalidConfigurationException(MAX_FINE,
                    String.valueOf(cap), "it cannot be negative");
        }
        if (cap < rate) {
            throw new InvalidConfigurationException(MAX_FINE,
                    String.valueOf(cap),
                    "it cannot be lower than the daily rate (" + rate + ")");
        }

        int threshold = getInt(MINOR_THRESHOLD, 7);
        if (threshold < 0 || threshold > days) {
            throw new InvalidConfigurationException(MINOR_THRESHOLD,
                    String.valueOf(threshold),
                    "it must be between 0 and the loan term (" + days + ")");
        }
    }

    // ---------------------- TYPED ACCESS ----------------------

    public String getText(String key, String defaultValue) {
        return resolved.getProperty(key, defaultValue);
    }

    /**
     * An integer with a default value.
     *
     * A non-numeric value does NOT blow up the application: a warning is
     * issued and the default is used. The later validation checks the range.
     */
    public int getInt(String key, int defaultValue) {
        String value = resolved.getProperty(key);
        if (value == null || value.isBlank()) {
            return defaultValue;
        }
        try {
            return Integer.parseInt(value.trim());
        } catch (NumberFormatException e) {
            LOG.warning(() -> String.format(
                    "The property %s has the non-numeric value '%s' (source: %s); "
                            + "%d is used", key, value, source.get(key), defaultValue));
            return defaultValue;
        }
    }

    /** A decimal. It accepts a comma or a dot when reading, always writes a dot (section 7). */
    public double getDouble(String key, double defaultValue) {
        String value = resolved.getProperty(key);
        if (value == null || value.isBlank()) {
            return defaultValue;
        }
        try {
            return Double.parseDouble(value.trim().replace(',', '.'));
        } catch (NumberFormatException e) {
            LOG.warning(() -> String.format(
                    "The property %s has the non-numeric value '%s' (source: %s); "
                            + "%s is used", key, value, source.get(key), defaultValue));
            return defaultValue;
        }
    }

    public boolean getBoolean(String key, boolean defaultValue) {
        String value = resolved.getProperty(key);
        if (value == null || value.isBlank()) {
            return defaultValue;
        }
        String clean = value.trim().toLowerCase(Locale.ROOT);
        return switch (clean) {                     // switch expression (02-03)
            case "true", "yes", "y", "1", "on"   -> true;
            case "false", "no", "n", "0", "off"  -> false;
            default -> {
                LOG.warning(() -> "Unrecognised boolean value in " + key
                        + ": '" + value + "'; " + defaultValue + " is used");
                yield defaultValue;
            }
        };
    }

    public char getChar(String key, char defaultValue) {
        String value = resolved.getProperty(key);
        return (value == null || value.isEmpty()) ? defaultValue : value.charAt(0);
    }

    public Path getPath(String key, String defaultValue) {
        return Path.of(getText(key, defaultValue));
    }

    /**
     * Diagnostic dump: each property with its value and its SOURCE.
     *
     * Knowing WHERE each value comes from is what lets you resolve in a
     * minute the classic "I changed the file and it takes no notice": there
     * is nearly always an environment variable or a -D overriding it.
     */
    public String dump() {
        StringBuilder sb = new StringBuilder();
        sb.append("=== EFFECTIVE CONFIGURATION ===\n");

        for (String key : new TreeMap<>(source).keySet()) {
            sb.append(String.format("  %-42s = %-16s [%s]%n",
                    key, resolved.getProperty(key), source.get(key)));
        }
        return sb.toString();
    }

    /** Invalid configuration: the application must NOT start like this. */
    public static class InvalidConfigurationException extends RuntimeException {

        private static final long serialVersionUID = 1L;      // 07-05

        private final String key;
        private final String value;

        public InvalidConfigurationException(String key, String value, String reason) {
            super(String.format(
                    "Invalid configuration: %s = '%s'. %s. "
                            + "Correct the configuration file and start again.",
                    key, value, reason));
            this.key = key;
            this.value = value;
        }

        public String getKey()   { return key; }
        public String getValue() { return value; }
    }
}

// BEFORE: hard-coded, scattered across three classes

public class Loan {
    public static final int LOAN_DAYS = 15;              // 06-03
}

public abstract class Material {
    public static final double MAX_FINE        = 20.0;   // 04-02
    public static final int    MINOR_THRESHOLD = 7;      // 04-02
}

public class Book extends Material {
    public static final double BOOK_DAILY_RATE = 0.25;       // 04-02
}

public class Employee {
    public static final int MAX_CONCURRENT_LOANS = 3;        // 03-03
}

package com.nexussoftware.bibliotech.domain;

import com.nexussoftware.bibliotech.infrastructure.Configuration;

/**
 * BiblioTech business rules, read from the configuration.
 *
 * It replaces the constants scattered across the domain since module 3.
 * The values are read ONCE at start-up and stay fixed for the run:
 * changing them halfway would mean two loans on the same day being
 * computed with different rules, which is unacceptable in a system that
 * charges money.
 *
 * To reload the configuration the application must be restarted. It is a
 * DELIBERATE decision, not a limitation.
 */
public final class BusinessRules {

    private static final Configuration CONFIG = Configuration.get();

    /** Loan term in days. Before: Loan.LOAN_DAYS = 15 */
    public static final int LOAN_DAYS =
            CONFIG.getInt(Configuration.LOAN_DAYS, 15);

    /** Concurrent loans per employee. Before: Employee.MAX_CONCURRENT_LOANS = 3 */
    public static final int MAX_CONCURRENT_LOANS =
            CONFIG.getInt(Configuration.MAX_LOANS, 3);

    /** EUR per day late. Before: Book.BOOK_DAILY_RATE = 0.25 */
    public static final double DAILY_RATE =
            CONFIG.getDouble(Configuration.DAILY_RATE, 0.25);

    /** Fine cap. Before: Material.MAX_FINE = 20.0 */
    public static final double MAX_FINE =
            CONFIG.getDouble(Configuration.MAX_FINE, 20.0);

    /** Days until lateness stops being minor. Before: Material.MINOR_THRESHOLD = 7 */
    public static final int MINOR_THRESHOLD =
            CONFIG.getInt(Configuration.MINOR_THRESHOLD, 7);

    private BusinessRules() { }

    /** A summary for start-up, so there is a record of which rules are in force. */
    public static String summary() {
        return String.format(
                "Rules: %d loan days, maximum %d concurrent, "
                        + "%.2f EUR/day, cap %.2f EUR, minor threshold %d days",
                LOAN_DAYS, MAX_CONCURRENT_LOANS,
                DAILY_RATE, MAX_FINE, MINOR_THRESHOLD);
    }
}

public abstract class Material implements Lendable, Notifiable {

    // Before: literal constants. Now: read from the configuration.
    // The Template Method of 04-02 does not change one line: only where
    // the numbers come from changes.

    public final double calculateFine(int elapsedDays) {
        int    daysLate = calculateDaysLate(elapsedDays);
        double gross    = daysLate * getDailyRate();
        return Math.min(gross, BusinessRules.MAX_FINE);
    }

    public final Severity classifySeverity(int elapsedDays) {
        int daysLate = calculateDaysLate(elapsedDays);
        if (daysLate == 0)                              { return Severity.ON_TIME; }
        if (daysLate <= BusinessRules.MINOR_THRESHOLD)  { return Severity.MINOR; }
        return Severity.SEVERE;
    }
}

package com.nexussoftware.bibliotech.presentation;

import java.io.IOException;
import java.nio.file.Path;
import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.domain.BusinessRules;
import com.nexussoftware.bibliotech.infrastructure.LogConfiguration;
import com.nexussoftware.bibliotech.infrastructure.Configuration;
import com.nexussoftware.bibliotech.service.Catalog;
import com.nexussoftware.bibliotech.service.CsvCatalogExporter;

public class BiblioTechApp {

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

    public static void main(String[] args) {
        LogConfiguration.initialise();                       // 06-07

        Configuration config;
        try {
            Path path = (args.length > 0) ? Path.of(args[0]) : null;
            config = Configuration.load(path);

        } catch (Configuration.InvalidConfigurationException e) {
            // The main error boundary (06-07). An invalid value ABORTS:
            // starting with an absurd rate would produce incorrect charges.
            System.err.println("CONFIGURATION ERROR");
            System.err.println("  " + e.getMessage());
            LOG.log(Level.SEVERE, "Start-up aborted by invalid configuration", e);
            System.exit(2);
            return;
        }

        LOG.config(config::dump);

        System.out.println("BiblioTech - Nexus Software");
        System.out.println(BusinessRules.summary());

        try {
            Path directory = config.getPath(Configuration.DATA_DIRECTORY, "data");
            CsvCatalogExporter persistence = new CsvCatalogExporter(directory);

            Catalog catalog = new Catalog();
            var result = persistence.importCatalog(catalog);
            System.out.print(result.summary());

            // Save on exit (07-02)
            Runtime.getRuntime().addShutdownHook(new Thread(() -> {
                try {
                    int n = persistence.exportCatalog(catalog);
                    LOG.info("Catalogue saved on exit: " + n + " materials");
                } catch (IOException e) {
                    LOG.log(Level.SEVERE, "COULD NOT SAVE THE CATALOGUE", e);
                }
            }, "final-save"));

            new BiblioTechMenu(catalog, persistence).start();

        } catch (IOException e) {
            System.err.println("Could not access the data store: " + e.getMessage());
            LOG.log(Level.SEVERE, "I/O failure at start-up", e);
            System.exit(3);
        }
    }
}

# 1. No configuration file: default values
$ java -cp bibliotech.jar com.nexussoftware.bibliotech.presentation.BiblioTechApp
BiblioTech - Nexus Software
Rules: 15 loan days, maximum 3 concurrent, 0.25 EUR/day, cap 20.00 EUR, minor threshold 7 days

# 2. With a configuration file
$ cat bibliotech.properties
bibliotech.loan.days = 21
bibliotech.daily.rate = 0.50

$ java -cp bibliotech.jar com.nexussoftware.bibliotech.presentation.BiblioTechApp
BiblioTech - Nexus Software
Rules: 21 loan days, maximum 3 concurrent, 0.50 EUR/day, cap 20.00 EUR, minor threshold 7 days

# 3. Environment variable: it overrides the file
$ BIBLIOTECH_MAX_FINE=50.0 java -cp bibliotech.jar ...
Rules: 21 loan days, maximum 3 concurrent, 0.50 EUR/day, cap 50.00 EUR, minor threshold 7 days

# 4. -D: it overrides everything
$ java -Dbibliotech.loan.days=7 -cp bibliotech.jar ...
Rules: 7 loan days, maximum 3 concurrent, 0.50 EUR/day, cap 50.00 EUR, minor threshold 7 days

# 5. An invalid value: the application does NOT start
$ java -Dbibliotech.max.fine=-5 -cp bibliotech.jar ...
CONFIGURATION ERROR
  Invalid configuration: bibliotech.max.fine = '-5.0'. it cannot be negative.
  Correct the configuration file and start again.
$ echo $?
2

=== EFFECTIVE CONFIGURATION ===
  bibliotech.csv.separator                   = ,                [code default]
  bibliotech.daily.rate                      = 0.50             [file /home/marta/bibliotech.properties]
  bibliotech.data.catalog                    = catalog.csv      [code default]
  bibliotech.data.directory                  = data             [file /home/marta/bibliotech.properties]
  bibliotech.loan.days                       = 7                [-Dbibliotech.loan.days]
  bibliotech.max.fine                        = 50.0             [environment variable BIBLIOTECH_MAX_FINE]
  bibliotech.max.loans                       = 3                [code default]
  bibliotech.minor.threshold                 = 7                [code default]

# bibliotech.properties: this DOES go in the repository.
# Functional configuration, with no secrets whatsoever.

bibliotech.loan.days = 15
bibliotech.daily.rate = 0.25

# Secrets do NOT go here. They are read from environment variables:
#   BIBLIOTECH_DB_USER
#   BIBLIOTECH_DB_PASSWORD
# In development, put them in bibliotech-local.properties, which is in .gitignore.

/**
 * Reads a secret. NEVER from the repository file, and NEVER with a default
 * value: a missing secret must fail, not work halfway.
 */
public String getSecret(String environmentVariable) {
    String value = System.getenv(environmentVariable);

    if (value == null || value.isBlank()) {
        throw new IllegalStateException(String.format(
                "The environment variable %s is missing. Secrets are not read "
                        + "from the configuration file. See the deployment "
                        + "documentation.", environmentVariable));
    }
    // And NEVER log it (06-07): not the value, not part of it, not its length.
    LOG.config(() -> "Secret " + environmentVariable + " loaded correctly");
    return value;
}

package com.nexussoftware.bibliotech.tests;

import java.io.IOException;
import java.io.StringReader;
import java.io.StringWriter;
import java.util.List;

import com.nexussoftware.bibliotech.infrastructure.CsvWriter;
import com.nexussoftware.bibliotech.infrastructure.CsvReader;

/**
 * CSV round-trip test battery.
 *
 * The round-trip test —write, read and compare with the original— is the
 * only serious way of validating a format: if something comes back
 * different, there is data loss.
 *
 * It works IN MEMORY with StringWriter and StringReader (07-03): no files,
 * no clean-up, no dependency on the environment.
 */
public class FullCsvTest {

    private static int passed = 0;
    private static int failed = 0;

    public static void main(String[] args) throws IOException {

        System.out.println("=== ROUND TRIP WITH SEPARATOR ',' ===");
        char sep = ',';

        check(sep, "1. Normal field",             "Effective Java", "Bloch", "2018");
        check(sep, "2. With a separator inside",  "Java: the language, the machine", "Bloch", "2018");
        check(sep, "3. With quotes",              "The book \"Refactoring\"", "Fowler", "1999");
        check(sep, "4. With a line break",        "Title with\na line break", "Author", "2020");
        check(sep, "5. Empty field in the middle", "Title", "", "2021");
        check(sep, "6. Empty field at the end",   "Title", "Author", "");
        check(sep, "7. All empty",                "", "", "");
        check(sep, "8. Only spaces",              "   ", "Author", "2022");
        check(sep, "9. Spaces at the ends",       "  with spaces  ", "Author", "2022");
        check(sep, "10. Accents and diacritics",  "Naïve Set Theory", "Zoë Blackwood", "1994");
        check(sep, "11. Semicolon inside",        "field;with;semicolons", "Author", "2023");
        check(sep, "12. Quotes in the middle",    "The \"best\" Java book", "Author", "2024");
        check(sep, "13. A single quote",          "Loose quote \" here", "Author", "2024");
        check(sep, "14. Very long field",         "x".repeat(5000), "Author", "2024");
        check(sep, "15. Separator and quotes",    "a,b\"c,d", "Author", "2024");

        System.out.println();
        System.out.println("=== ROUND TRIP WITH SEPARATOR ';' ===");
        char sep2 = ';';
        check(sep2, "16. Comma inside with sep ;", "Java: the language, the machine", "Bloch", "2018");
        check(sep2, "17. Semicolon inside",        "field;with;semicolons", "Author", "2023");

        // ---- Controlled failure: unclosed quote ----
        System.out.println();
        System.out.println("=== CONTROLLED FAILURES ===");
        checkUnclosedQuotes();

        // ---- BOM ----
        System.out.println();
        System.out.println("=== BOM MARK ===");
        checkBom();

        System.out.println();
        System.out.printf("=== RESULT: %d passed, %d failed ===%n",
                passed, failed);

        if (failed > 0) {
            System.out.println("THERE IS DATA LOSS. Review the escaping.");
        }
    }

    /** Writes the fields, reads them back and compares with the original. */
    private static void check(char separator, String name, String... fields)
            throws IOException {

        List<String> originals = List.of(fields);

        StringWriter memory = new StringWriter();
        try (CsvWriter writer = new CsvWriter(memory, separator, "\n")) {
            writer.writeRecord(originals);
        }

        String generated = memory.toString();

        List<String> read;
        try (CsvReader reader = new CsvReader(new StringReader(generated), separator)) {
            read = reader.next();
        }

        boolean ok = originals.equals(read);
        if (ok) { passed++; } else { failed++; }

        System.out.printf("  %-30s %s%n", name, ok ? "OK" : "FAIL");

        if (!ok) {
            System.out.println("      original: " + originals);
            System.out.println("      read    : " + read);
            System.out.println("      csv     : " + generated.replace("\n", "\\n"));
        }
    }

    /** A file with an unclosed quote must fail, indicating the line. */
    private static void checkUnclosedQuotes() {
        String bad = "title,author\n\"Unclosed,Bloch";

        try (CsvReader reader = new CsvReader(new StringReader(bad))) {
            reader.next();            // the header, correct
            reader.next();            // this one must fail
            System.out.println("  Unclosed quote               FAIL (it should throw)");
            failed++;

        } catch (CsvReader.CsvFormatException e) {
            System.out.println("  Unclosed quote               OK");
            System.out.println("      " + e.getMessage());
            passed++;

        } catch (IOException e) {
            System.out.println("  Unclosed quote               FAIL (unexpected exception)");
            failed++;
        }
    }

    /**
     * The BOM mark Excel writes at the start of UTF-8 files.
     *
     * Without handling it, the first column reads as "\uFEFFtype" and does NOT
     * match "type", even though the file looks perfect in any editor.
     */
    private static void checkBom() throws IOException {
        String withBom = "\uFEFFtype,reference,title\nBOOK,978-0000000001,Effective Java";

        try (CsvReader reader = new CsvReader(new StringReader(withBom))) {
            List<String> header = reader.next();

            boolean ok = "type".equals(header.get(0));
            if (ok) { passed++; } else { failed++; }

            System.out.printf("  BOM removed                  %s%n", ok ? "OK" : "FAIL");
            System.out.println("      first column: '" + header.get(0)
                    + "' (length " + header.get(0).length() + ")");

            if (!ok) {
                System.out.println("      The BOM is still there: the comparison with 'type' fails");
            }
        }
    }
}

=== ROUND TRIP WITH SEPARATOR ',' ===
  1. Normal field                OK
  2. With a separator inside     OK
  3. With quotes                 OK
  4. With a line break           OK
  5. Empty field in the middle   OK
  6. Empty field at the end      OK
  7. All empty                   OK
  8. Only spaces                 OK
  9. Spaces at the ends          OK
  10. Accents and diacritics     OK
  11. Semicolon inside           OK
  12. Quotes in the middle       OK
  13. A single quote             OK
  14. Very long field            OK
  15. Separator and quotes       OK

=== ROUND TRIP WITH SEPARATOR ';' ===
  16. Comma inside with sep ;    OK
  17. Semicolon inside           OK

=== CONTROLLED FAILURES ===
  Unclosed quote               OK
      Line 2: The file ends with an unclosed quote

=== BOM MARK ===
  BOM removed                  OK
      first column: 'type' (length 4)

=== RESULT: 19 passed, 0 failed ===

package com.nexussoftware.bibliotech.util;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;
import java.util.TreeSet;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.infrastructure.CsvWriter;
import com.nexussoftware.bibliotech.infrastructure.CsvReader;

/**
 * Conversions between CSV and Properties, and between CSV dialects.
 *
 * All the writes are ATOMIC (07-06): if the conversion fails halfway, the
 * previous target file is left untouched.
 */
public class FormatConverter {

    private static final Logger LOG = Logger.getLogger(FormatConverter.class.getName());
    private static final java.nio.charset.Charset CHARSET = StandardCharsets.UTF_8;

    // ---------------------- CSV -> PROPERTIES ----------------------

    /**
     * Converts a two-column 'key,value' CSV into a .properties.
     *
     * NOTE: Properties escapes the special characters on its own, so a value
     * with '=' or ':' is stored escaped and comes back correct.
     */
    public int csvToProperties(Path csv, Path target, char separator) throws IOException {
        Properties props = new Properties();
        int converted = 0;

        try (BufferedReader reader = Files.newBufferedReader(csv, CHARSET);
             CsvReader input = new CsvReader(reader, separator)) {

            List<String> record = input.next();               // the header
            if (record == null) {
                throw new IOException("The file " + csv + " is empty");
            }

            while ((record = input.next()) != null) {
                if (record.size() < 2) {
                    LOG.warning(() -> "Record with fewer than 2 fields; ignored");
                    continue;
                }
                String key = record.get(0).trim();
                if (key.isEmpty()) {
                    continue;
                }
                props.setProperty(key, record.get(1));
                converted++;
            }
        }

        writePropertiesAtomically(props, target,
                "Generated from " + csv.getFileName());

        final int total = converted;
        LOG.info(() -> String.format("CSV -> Properties: %d keys in %s",
                total, target));
        return converted;
    }

    // ---------------------- PROPERTIES -> CSV ----------------------

    /** Converts a .properties into CSV, with the keys sorted. */
    public int propertiesToCsv(Path properties, Path target, char separator)
            throws IOException {

        Properties props = new Properties();
        try (BufferedReader reader = Files.newBufferedReader(properties, CHARSET)) {
            props.load(reader);
        }

        // stringPropertyNames, not keySet (section 12). TreeSet to sort.
        TreeSet<String> keys = new TreeSet<>(props.stringPropertyNames());

        writeAtomically(target, output -> {
            try (CsvWriter csv = new CsvWriter(output, separator, "\n")) {
                csv.writeHeader("key", "value");
                for (String key : keys) {
                    csv.writeRecord(key, props.getProperty(key));
                }
            }
        });

        LOG.info(() -> String.format("Properties -> CSV: %d keys in %s",
                keys.size(), target));
        return keys.size();
    }

    // ---------------------- CSV -> CSV ----------------------

    /**
     * Changes the separator of a CSV respecting the escaping.
     *
     * It is NOT a text substitution: a field that contained the NEW separator
     * and not the old one now needs quotes, and vice versa. It can only be
     * done properly by parsing and rewriting.
     */
    public int csvToCsv(Path source, Path target, char sourceSep, char targetSep)
            throws IOException {

        List<List<String>> records = new ArrayList<>();

        try (BufferedReader reader = Files.newBufferedReader(source, CHARSET);
             CsvReader input = new CsvReader(reader, sourceSep)) {

            List<String> record;
            while ((record = input.next()) != null) {
                records.add(record);
            }
        }

        writeAtomically(target, output -> {
            try (CsvWriter csv = new CsvWriter(output, targetSep, "\n")) {
                for (List<String> r : records) {
                    csv.writeRecord(r);
                }
            }
        });

        LOG.info(() -> String.format("CSV '%c' -> CSV '%c': %d records in %s",
                sourceSep, targetSep, records.size(), target));
        return records.size();
    }

    // ---------------------- ATOMIC WRITING ----------------------

    @FunctionalInterface
    private interface Writing {
        void writeTo(BufferedWriter output) throws IOException;
    }

    private void writeAtomically(Path target, Writing content) throws IOException {
        Files.createDirectories(target.toAbsolutePath().getParent());
        Path temp = target.resolveSibling(target.getFileName() + ".tmp");

        boolean completed = false;
        try {
            try (BufferedWriter output = Files.newBufferedWriter(temp, CHARSET,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE)) {

                content.writeTo(output);
            }
            Files.move(temp, target,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            completed = true;

        } catch (AtomicMoveNotSupportedException e) {
            Files.move(temp, target, StandardCopyOption.REPLACE_EXISTING);
            completed = true;

        } finally {
            if (!completed) {
                Files.deleteIfExists(temp);              // compensation (06-05)
            }
        }
    }

    private void writePropertiesAtomically(Properties props, Path target, String comment)
            throws IOException {

        writeAtomically(target, output -> props.store(output, comment));
    }

    // ---------------------- DEMONSTRATION ----------------------

    public static void main(String[] args) throws IOException {
        Path dir = Path.of("data/conversions");
        Files.createDirectories(dir);

        FormatConverter converter = new FormatConverter();

        // 1. Starting CSV with the difficult cases
        Path originalCsv = dir.resolve("configuration.csv");
        Files.writeString(originalCsv, String.join("\n",
                "key,value",
                "bibliotech.loan.days,15",
                "bibliotech.daily.rate,0.25",
                "bibliotech.message.welcome,\"Welcome to BiblioTech, from Nexus Software\"",
                "bibliotech.separators,\"semi;colon;list\"",
                "bibliotech.quote,\"The book \"\"Refactoring\"\" by Fowler\"",
                ""), CHARSET);

        System.out.println("=== ORIGINAL CSV ===");
        System.out.println(Files.readString(originalCsv, CHARSET));

        // 2. CSV -> Properties
        Path props = dir.resolve("configuration.properties");
        int n1 = converter.csvToProperties(originalCsv, props, ',');
        System.out.println("=== PROPERTIES GENERATED (" + n1 + " keys) ===");
        System.out.println(Files.readString(props, CHARSET));

        // 3. Properties -> CSV, with separator ';' for a European Excel
        Path excelCsv = dir.resolve("configuration-excel.csv");
        int n2 = converter.propertiesToCsv(props, excelCsv, ';');
        System.out.println("=== CSV FOR EUROPEAN EXCEL (" + n2 + " keys) ===");
        System.out.println(Files.readString(excelCsv, CHARSET));

        // 4. CSV ',' -> CSV ';' directly
        Path semicolonCsv = dir.resolve("configuration-semicolon.csv");
        int n3 = converter.csvToCsv(originalCsv, semicolonCsv, ',', ';');
        System.out.println("=== CSV WITH SEPARATOR ';' (" + n3 + " records) ===");
        System.out.println(Files.readString(semicolonCsv, CHARSET));

        // 5. Check: complete round trip
        Path back = dir.resolve("roundtrip.csv");
        converter.csvToCsv(semicolonCsv, back, ';', ',');

        boolean identical = Files.readString(originalCsv, CHARSET).trim()
                .equals(Files.readString(back, CHARSET).trim());

        System.out.println("=== ROUND TRIP ',' -> ';' -> ',' ===");
        System.out.println("  Identical to the original? " + identical);
    }
}

=== CSV WITH SEPARATOR ';' (6 records) ===
key;value
bibliotech.loan.days;15
bibliotech.daily.rate;0.25
bibliotech.message.welcome;Welcome to BiblioTech, from Nexus Software
bibliotech.separators;"semi;colon;list"
bibliotech.quote;"The book ""Refactoring"" by Fowler"

=== ROUND TRIP ',' -> ';' -> ',' ===
  Identical to the original? true

package com.nexussoftware.bibliotech.infrastructure;

import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Properties;
import java.util.Set;
import java.util.TreeMap;
import java.util.logging.Logger;

/**
 * BiblioTech configuration with reloading, change notification and
 * generation of a commented template.
 *
 * It extends the class of section 14 with what is needed to operate the
 * system without stopping it completely.
 */
public class ReloadableConfiguration {

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

    private static final java.nio.charset.Charset CHARSET = StandardCharsets.UTF_8;

    /**
     * Description of a known property.
     *
     * 'reloadable' tells what can be changed hot from what demands a restart.
     * The BUSINESS RULES are not reloadable: changing the rate halfway
     * through a run would mean two loans on the same day being computed
     * with different rules.
     */
    public record PropertyDescription(String key, String defaultValue,
                                      String description, boolean reloadable) { }

    private static final List<PropertyDescription> KNOWN = List.of(
            new PropertyDescription("bibliotech.loan.days", "15",
                    "Loan term in days", false),
            new PropertyDescription("bibliotech.max.loans", "3",
                    "Concurrent loans per employee", false),
            new PropertyDescription("bibliotech.daily.rate", "0.25",
                    "EUR per day late", false),
            new PropertyDescription("bibliotech.max.fine", "20.0",
                    "Fine cap per loan, in EUR", false),
            new PropertyDescription("bibliotech.minor.threshold", "7",
                    "Days until lateness stops being minor", false),
            new PropertyDescription("bibliotech.data.directory", "data",
                    "Data directory", true),
            new PropertyDescription("bibliotech.data.catalog", "catalog.csv",
                    "Name of the catalogue file", true),
            new PropertyDescription("bibliotech.csv.separator", ",",
                    "CSV field separator: ',' or ';' for a European Excel", true),
            new PropertyDescription("bibliotech.log.level", "INFO",
                    "Logging level: SEVERE, WARNING, INFO, CONFIG, FINE", true));

    /** Configuration change listener (functional interface, 04-06). */
    @FunctionalInterface
    public interface ConfigurationListener {
        void changed(String key, String previous, String current);
    }

    /** A change detected on reloading. */
    public record Change(String key, String previous, String current, boolean reloadable) {

        public String line() {
            return String.format("%-42s %-14s -> %-14s %s",
                    key, previous == null ? "(no value)" : previous, current,
                    reloadable ? "" : "  [REQUIRES RESTART]");
        }
    }

    private final Path externalFile;
    private final Map<String, String> values = new TreeMap<>();
    private final Map<String, String> source = new TreeMap<>();
    private final List<ConfigurationListener> listeners = new ArrayList<>();

    public ReloadableConfiguration(Path externalFile) {
        this.externalFile = Objects.requireNonNull(externalFile);
        loadAll();
    }

    public void addListener(ConfigurationListener listener) {
        listeners.add(Objects.requireNonNull(listener, "The listener cannot be null"));
    }

    // ---------------------- LOADING ----------------------

    private void loadAll() {
        values.clear();
        source.clear();

        // 1. Code defaults
        for (PropertyDescription d : KNOWN) {
            values.put(d.key(), d.defaultValue());
            source.put(d.key(), "code default");
        }

        // 2. External file
        if (Files.exists(externalFile)) {
            Properties props = new Properties();
            try (var reader = Files.newBufferedReader(externalFile, CHARSET)) {
                props.load(reader);
                for (String key : props.stringPropertyNames()) {       // not keySet
                    values.put(key, props.getProperty(key).trim());
                    source.put(key, "file " + externalFile.getFileName());
                }
            } catch (IOException e) {
                LOG.warning(() -> "Could not read " + externalFile + ": " + e.getMessage());
            }
        }

        // 3. Environment variables
        for (var e : System.getenv().entrySet()) {
            if (e.getKey().startsWith("BIBLIOTECH_")) {
                String key = e.getKey().toLowerCase(java.util.Locale.ROOT).replace('_', '.');
                values.put(key, e.getValue().trim());
                source.put(key, "environment " + e.getKey());
            }
        }

        // 4. System properties
        for (String key : System.getProperties().stringPropertyNames()) {
            if (key.startsWith("bibliotech.")) {
                values.put(key, System.getProperty(key).trim());
                source.put(key, "-D" + key);
            }
        }
    }

    // ---------------------- RELOADING ----------------------

    /**
     * Re-reads all the sources and returns the changes detected.
     *
     * It notifies the listeners of each change, and WARNS about the ones
     * needing a restart to take effect.
     */
    public List<Change> reload() {
        Map<String, String> previous = new LinkedHashMap<>(values);

        loadAll();

        List<Change> changes = new ArrayList<>();
        Set<String> all = new java.util.TreeSet<>(previous.keySet());
        all.addAll(values.keySet());

        for (String key : all) {
            String before = previous.get(key);
            String now = values.get(key);

            if (Objects.equals(before, now)) {
                continue;
            }
            boolean reloadable = isReloadable(key);
            changes.add(new Change(key, before, now, reloadable));

            // Notify. A listener that fails must NOT break the reload.
            for (ConfigurationListener listener : listeners) {
                try {
                    listener.changed(key, before, now);
                } catch (RuntimeException e) {
                    LOG.warning(() -> "A listener failed while notifying " + key
                            + ": " + e.getMessage());
                }
            }

            if (!reloadable) {
                LOG.warning(() -> String.format(
                        "The property %s has changed from '%s' to '%s', but it is NOT "
                                + "applied hot: the application must be restarted.",
                        key, before, now));
            }
        }

        LOG.info(() -> "Reload: " + changes.size() + " properties changed");
        return changes;
    }

    private boolean isReloadable(String key) {
        for (PropertyDescription d : KNOWN) {
            if (d.key().equals(key)) {
                return d.reloadable();
            }
        }
        return true;      // unknown: assumed reloadable
    }

    // ---------------------- TEMPLATE ----------------------

    /**
     * Generates a commented .properties with all the known keys.
     *
     * It is written by hand rather than with Properties.store because store
     * preserves neither the order nor the comments (section 11), and a
     * template with no comments and no order is of no use at all.
     */
    public void exportTemplate(Path target) throws IOException {
        Files.createDirectories(target.toAbsolutePath().getParent());
        Path temp = target.resolveSibling(target.getFileName() + ".tmp");

        boolean completed = false;
        try {
            try (BufferedWriter output = Files.newBufferedWriter(temp, CHARSET,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE)) {

                output.write("# ============================================================");
                output.newLine();
                output.write("# BiblioTech configuration - Nexus Software");
                output.newLine();
                output.write("# Template generated automatically.");
                output.newLine();
                output.write("#");
                output.newLine();
                output.write("# Precedence, from lowest to highest:");
                output.newLine();
                output.write("#   1. code defaults");
                output.newLine();
                output.write("#   2. this file");
                output.newLine();
                output.write("#   3. environment variables (BIBLIOTECH_XXX_YYY)");
                output.newLine();
                output.write("#   4. system properties (-Dbibliotech.xxx.yyy)");
                output.newLine();
                output.write("#");
                output.newLine();
                output.write("# WARNING: do NOT put passwords or keys in this file");
                output.newLine();
                output.write("# if it goes into version control. Use environment variables.");
                output.newLine();
                output.write("# ============================================================");
                output.newLine();
                output.newLine();

                for (PropertyDescription d : KNOWN) {
                    String current = values.getOrDefault(d.key(), d.defaultValue());
                    String from = source.getOrDefault(d.key(), "code default");

                    output.write("# " + d.description());
                    output.newLine();
                    output.write("#   default      : " + d.defaultValue());
                    output.newLine();
                    output.write("#   current value: " + current + "  (source: " + from + ")");
                    output.newLine();
                    output.write("#   hot reload: " + (d.reloadable()
                            ? "YES" : "NO, requires a restart"));
                    output.newLine();
                    output.write(d.key() + " = " + current);
                    output.newLine();
                    output.newLine();
                }
            }

            Files.move(temp, target,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            completed = true;

            LOG.info(() -> "Configuration template generated in " + target);

        } catch (AtomicMoveNotSupportedException e) {
            Files.move(temp, target, StandardCopyOption.REPLACE_EXISTING);
            completed = true;

        } finally {
            if (!completed) {
                Files.deleteIfExists(temp);
            }
        }
    }

    // ---------------------- ACCESS ----------------------

    public String getText(String key, String defaultValue) {
        return values.getOrDefault(key, defaultValue);
    }

    public String dump() {
        StringBuilder sb = new StringBuilder("=== EFFECTIVE CONFIGURATION ===\n");
        for (var e : values.entrySet()) {
            sb.append(String.format("  %-42s = %-16s [%s]%n",
                    e.getKey(), e.getValue(), source.get(e.getKey())));
        }
        return sb.toString();
    }

    // ---------------------- DEMONSTRATION ----------------------

    public static void main(String[] args) throws IOException {
        Path file = Path.of("data/bibliotech.properties");
        Files.createDirectories(file.getParent());

        Files.writeString(file,
                "bibliotech.loan.days = 15\n"
                        + "bibliotech.csv.separator = ,\n", CHARSET);

        ReloadableConfiguration config = new ReloadableConfiguration(file);

        // A listener reacting to the changes
        config.addListener((key, before, now) ->
                System.out.printf("  [LISTENER] %s: '%s' -> '%s'%n", key, before, now));

        System.out.println(config.dump());

        // A commented template for the administrator
        Path template = Path.of("data/bibliotech-template.properties");
        config.exportTemplate(template);
        System.out.println("=== TEMPLATE (first lines) ===");
        try (var lines = Files.lines(template, CHARSET)) {     // close the stream (07-06)
            int[] n = { 0 };
            lines.forEach(l -> {
                if (n[0]++ < 20) {
                    System.out.println("  " + l);
                }
            });
        }

        // Change the file and reload
        System.out.println();
        System.out.println("=== MODIFYING THE FILE AND RELOADING ===");
        Files.writeString(file,
                "bibliotech.loan.days = 21\n"
                        + "bibliotech.csv.separator = ;\n"
                        + "bibliotech.log.level = FINE\n", CHARSET);

        List<Change> changes = config.reload();

        System.out.println();
        System.out.println("=== CHANGES DETECTED ===");
        for (Change c : changes) {
            System.out.println("  " + c.line());
        }
    }
}

=== MODIFYING THE FILE AND RELOADING ===
  [LISTENER] bibliotech.csv.separator: ',' -> ';'
  [LISTENER] bibliotech.loan.days: '15' -> '21'
  [LISTENER] bibliotech.log.level: 'INFO' -> 'FINE'

=== CHANGES DETECTED ===
  bibliotech.csv.separator                   ,              -> ;
  bibliotech.loan.days                       15             -> 21               [REQUIRES RESTART]
  bibliotech.log.level                       INFO           -> FINE