package java.io;

public interface Serializable {
    // No methods. None at all.
}

package com.nexussoftware.bibliotech.domain;

import java.io.Serializable;

public class Employee implements Serializable {

    private static final long serialVersionUID = 1L;      // section 6

    private final String name;
    private final String identifier;
    private int activeLoans;

    // ... the rest as always
}

package com.nexussoftware.bibliotech.demo;

import java.io.*;

public class BasicSerialisation {

    public static void save(Employee employee, String path) throws IOException {
        try (ObjectOutputStream output = new ObjectOutputStream(
                new BufferedOutputStream(new FileOutputStream(path)))) {

            output.writeObject(employee);        // writes the object and its whole graph
        }
    }

    public static Employee load(String path) throws IOException, ClassNotFoundException {
        try (ObjectInputStream input = new ObjectInputStream(
                new BufferedInputStream(new FileInputStream(path)))) {

            // readObject returns Object: a cast is needed
            return (Employee) input.readObject();
        }
    }

    public static void main(String[] args) throws Exception {
        Employee marta = new Employee("Marta Ruiz", "EMP-001");
        marta.registerLoan();
        marta.registerLoan();

        save(marta, "data/marta.ser");

        Employee restored = load("data/marta.ser");
        System.out.println(restored.getName());              // Marta Ruiz
        System.out.println(restored.getActiveLoans());       // 2

        // It is ANOTHER object, with the SAME state
        System.out.println(marta == restored);               // false
        System.out.println(marta.equals(restored));          // true, if equals is right (03-09)
    }
}

/** Several objects: they are written and read IN THE SAME ORDER. */
public static void saveAll(List<Employee> employees, String path) throws IOException {
    try (ObjectOutputStream output = new ObjectOutputStream(
            new BufferedOutputStream(new FileOutputStream(path)))) {

        output.writeInt(employees.size());          // first, how many there are
        for (Employee e : employees) {
            output.writeObject(e);
        }
    }
}

public static List<Employee> loadAll(String path)
        throws IOException, ClassNotFoundException {

    List<Employee> employees = new ArrayList<>();
    try (ObjectInputStream input = new ObjectInputStream(
            new BufferedInputStream(new FileInputStream(path)))) {

        int howMany = input.readInt();
        for (int i = 0; i < howMany; i++) {
            employees.add((Employee) input.readObject());
        }
    }
    return employees;
}

output.writeObject(new ArrayList<>(employees));      // a single writeObject
// ...
List<Employee> employees = (List<Employee>) input.readObject();

AC ED 00 05 73 72 00 2C 63 6F 6D 2E 6E 65 78 75  |....sr.,com.nexu|
73 73 6F 66 74 77 61 72 65 2E 62 69 62 6C 69 6F  |ssoftware.biblio|
74 65 63 68 2E 64 6F 6D 61 69 6E 2E 45 6D 70 6C  |tech.domain.Empl|
6F 79 65 65 00 00 00 00 00 00 00 01 02 00 03 78  |oyee...........x|

public class Loan implements Serializable {

    private static final long serialVersionUID = 1L;

    private final String reference;
    private final Material material;
    private final int startDay;
    private int returnDay = -1;

    // DERIVED: computed from the days and the material rate.
    // Saving it would duplicate information, and worse: if the rate changes,
    // the saved value would be stale and contradict the computed one.
    private transient double calculatedFine;
    private transient boolean fineCached = false;

    public double calculateFine(int currentDay) {
        if (!fineCached) {
            calculatedFine = material.calculateFine(currentDay - startDay);
            fineCached = true;
        }
        return calculatedFine;
    }
}

public class UserSession implements Serializable {

    private static final long serialVersionUID = 1L;

    private final String identifier;

    // NEVER on disk. Everything 06-07 said about what not to log applies
    // equally, or more, to what is persisted: the file stays.
    private transient char[] credential;
    private transient String sessionToken;
}

public class CardCache implements Serializable {

    private static final long serialVersionUID = 1L;

    // WRONG: on deserialising it will be null, not an empty HashMap.
    // The initialiser is NOT run.
    private transient Map<String, Card> cache = new HashMap<>();

    public void store(String key, Card c) {
        cache.put(key, c);          // NullPointerException after deserialising
    }
}

import java.io.Serializable;
import java.util.logging.Logger;

public class LoanManager implements Serializable {

    private static final long serialVersionUID = 1L;

    private final Catalog catalog;               // serialisable
    private final LoanRegistry registry;         // serialisable

    // PROBLEM: Logger is NOT Serializable.
    // This single field makes the WHOLE LoanManager fail.
    private final Logger log = Logger.getLogger(LoanManager.class.getName());
}

Exception in thread "main" java.io.NotSerializableException: java.util.logging.Logger
    at java.base/java.io.ObjectOutputStream.writeObject0(ObjectOutputStream.java:1197)
    at java.base/java.io.ObjectOutputStream.defaultWriteFields(...)
    at ...

public class LoanManager implements Serializable {

    private static final long serialVersionUID = 1L;

    private final Catalog catalog;
    private final LoanRegistry registry;

    // transient: it is not saved. And it does not need to be, because a
    // Logger is recovered with a static call at any moment.
    private transient Logger log = Logger.getLogger(LoanManager.class.getName());

    /**
     * Reinitialises the transient fields after deserialisation (section 9).
     * Without this, 'log' would be null and the first use would fail.
     */
    private void readObject(java.io.ObjectInputStream input)
            throws java.io.IOException, ClassNotFoundException {

        input.defaultReadObject();
        log = Logger.getLogger(LoanManager.class.getName());
    }
}

public class MaterialNotFoundException extends CatalogException {
    private static final long serialVersionUID = 1L;
    // ...
}

public class Employee implements Serializable {

    /**
     * Version of the serialised form.
     *
     * It is ONLY incremented when an INCOMPATIBLE change is made (section 8).
     * Compatible changes (adding fields, methods, changing code) keep the
     * same value.
     */
    private static final long serialVersionUID = 1L;

    // ...
}

private static final long serialVersionUID = 1L;

javac -Xlint:serial *.java

warning: [serial] serializable class Employee has no definition of serialVersionUID

// VERSION 1 - it is compiled, run, and a file is saved
public class Employee implements Serializable {
    // NO serialVersionUID declared: it is computed automatically
    private final String name;
    private final String identifier;
    private int activeLoans;

    public Employee(String name, String identifier) {
        this.name = name;
        this.identifier = identifier;
    }
    public String getName() { return name; }
}

Employee marta = new Employee("Marta Ruiz", "EMP-001");
save(marta, "data/marta.ser");             // OK

// VERSION 2 - only a method is added
public class Employee implements Serializable {
    private final String name;
    private final String identifier;
    private int activeLoans;

    public Employee(String name, String identifier) {
        this.name = name;
        this.identifier = identifier;
    }
    public String getName() { return name; }

    /** NEW method. It does not touch the state. */
    public String getInitials() {
        String[] parts = name.split(" ");
        return "" + parts[0].charAt(0) + parts[1].charAt(0);
    }
}

Exception in thread "main" java.io.InvalidClassException:
    com.nexussoftware.bibliotech.domain.Employee;
    local class incompatible:
    stream classdesc serialVersionUID = -4738291056473829104,
    local class serialVersionUID = 8273645019283746152

private void writeObject(ObjectOutputStream output) throws IOException;
private void readObject(ObjectInputStream input) throws IOException, ClassNotFoundException;

package com.nexussoftware.bibliotech.service;

import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.Serializable;
import java.util.HashMap;
import java.util.Map;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.domain.Card;

/**
 * Card cache with customised serialisation.
 *
 * The cache is NOT saved (it is derived), but it must be rebuilt empty on
 * loading: otherwise it would be null and the first use would fail.
 */
public class CardCache implements Serializable {

    private static final long serialVersionUID = 1L;

    /** static: not serialised. The correct convention for a Logger. */
    private static final Logger LOG = Logger.getLogger(CardCache.class.getName());

    private final String name;
    private int maxCapacity;

    /** transient: on deserialising it will be null if we do not fix it. */
    private transient Map<String, Card> cache = new HashMap<>();
    private transient int hits = 0;
    private transient int misses = 0;

    public CardCache(String name, int maxCapacity) {
        this.name = java.util.Objects.requireNonNull(name);
        if (maxCapacity < 1) {
            throw new IllegalArgumentException(
                    "The capacity must be at least 1, and it was: " + maxCapacity);
        }
        this.maxCapacity = maxCapacity;
    }

    /**
     * Customised serialisation.
     *
     * USE 1: log the operation.
     * USE 2: write extra data after the default fields.
     */
    private void writeObject(ObjectOutputStream output) throws IOException {
        LOG.fine(() -> "Serialising cache '" + name + "' with "
                + cache.size() + " entries (which are NOT saved)");

        output.defaultWriteObject();          // first, the normal fields

        // Extra data can be written. It will be read in the SAME order.
        output.writeInt(cache.size());        // informative only
    }

    /**
     * Customised deserialisation.
     *
     * USE 3: reinitialise the transient fields.
     * USE 4: VALIDATE the state read.
     */
    private void readObject(ObjectInputStream input)
            throws IOException, ClassNotFoundException {

        input.defaultReadObject();            // first, the normal fields

        int previousSize = input.readInt();   // the extra, in the same order

        // USE 3: reinitialise. Without this, cache would be null.
        this.cache = new HashMap<>();
        this.hits = 0;
        this.misses = 0;

        // USE 4: VALIDATE. Deserialisation does NOT call the constructor, so
        // its checks have not been run. A tampered file or one from an old
        // version can bring impossible values.
        if (maxCapacity < 1) {
            LOG.warning(() -> "Invalid capacity on deserialising ("
                    + maxCapacity + "); corrected to 100");
            this.maxCapacity = 100;
        }
        if (name == null) {
            throw new java.io.InvalidObjectException(
                    "Cache deserialised with no name: file corrupt or tampered with");
        }

        LOG.fine(() -> "Cache '" + name + "' restored empty (it had "
                + previousSize + " entries)");
    }

    public java.util.Optional<Card> find(String key) {
        Card c = cache.get(key);
        if (c != null) { hits++; } else { misses++; }
        return java.util.Optional.ofNullable(c);
    }

    public void store(String key, Card card) {
        if (cache.size() >= maxCapacity) {
            cache.clear();                    // a simple eviction policy
        }
        cache.put(key, card);
    }

    public int getHits()   { return hits; }
    public int getMisses() { return misses; }
}

/** Preserves the singleton pattern when deserialising. */
private Object readResolve() {
    return INSTANCE;       // the unique instance is returned, not the deserialised one
}

public interface Externalizable extends Serializable {
    void writeExternal(ObjectOutput output) throws IOException;
    void readExternal(ObjectInput input) throws IOException, ClassNotFoundException;
}

public class Location implements Externalizable {

    private String room;
    private int bookcase;
    private int shelf;

    /** MANDATORY and PUBLIC: Externalizable calls it when deserialising. */
    public Location() { }

    public Location(String room, int bookcase, int shelf) {
        this.room = room;
        this.bookcase = bookcase;
        this.shelf = shelf;
    }

    @Override
    public void writeExternal(ObjectOutput output) throws IOException {
        output.writeUTF(room);
        output.writeInt(bookcase);
        output.writeInt(shelf);
    }

    @Override
    public void readExternal(ObjectInput input) throws IOException {
        room = input.readUTF();            // the SAME order
        bookcase = input.readInt();
        shelf = input.readInt();
    }
}

/** NON-serialisable superclass. */
public abstract class InventoryItem {

    private final String internalCode;
    private int revisions;

    /**
     * MANDATORY for the serialisable subclasses to work.
     * Without it: InvalidClassException "no valid constructor".
     */
    protected InventoryItem() {
        this.internalCode = "NO-CODE";         // default value
        this.revisions = 0;
    }

    protected InventoryItem(String internalCode) {
        this.internalCode = internalCode;
        this.revisions = 0;
    }

    public String getInternalCode() { return internalCode; }
}

/** Serialisable subclass. */
public class Material extends InventoryItem implements Serializable {

    private static final long serialVersionUID = 1L;

    private final String title;
    private final String reference;
    private boolean available;

    // ...
}

java.io.InvalidClassException: com.nexussoftware.bibliotech.domain.Material;
    no valid constructor

// This code IS ALREADY VULNERABLE if 'input' comes from outside.
// The check arrives TOO LATE: the damage happened inside readObject().
Object o = input.readObject();
if (o instanceof Loan l) {              // <-- too late
    process(l);
}

package com.nexussoftware.bibliotech.infrastructure;

import java.io.ObjectInputFilter;
import java.io.ObjectInputStream;

/**
 * Deserialisation filters for BiblioTech.
 *
 * WARNING: a filter REDUCES the risk, it does not eliminate it. The only
 * complete defence is not deserialising untrusted data (section 12).
 */
public final class DeserialisationFilter {

    private DeserialisationFilter() { }

    /**
     * Allow-list filter: only BiblioTech classes and a minimal set from the
     * JDK are permitted. Everything else is REJECTED.
     *
     * The allow list is the only correct approach: a deny list always falls
     * short, because you cannot enumerate everything dangerous.
     */
    public static ObjectInputFilter forBiblioTech() {
        String pattern = String.join(";",
                "com.nexussoftware.bibliotech.**",   // our classes
                "java.util.ArrayList",
                "java.util.LinkedList",
                "java.util.HashMap",
                "java.util.HashSet",
                "java.lang.String",
                "java.lang.Number",
                "java.lang.Integer",
                "java.lang.Double",
                "java.lang.Boolean",
                "java.lang.Enum",
                "maxdepth=20",           // maximum graph depth
                "maxrefs=10000",         // maximum references
                "maxbytes=10485760",     // 10 MB
                "maxarray=100000",       // maximum elements in an array
                "!*");                   // REJECT EVERYTHING ELSE

        return ObjectInputFilter.Config.createFilter(pattern);
    }

    /** Applies the filter to a particular stream. */
    public static void applyTo(ObjectInputStream input) {
        input.setObjectInputFilter(forBiblioTech());
    }
}

try (ObjectInputStream input = new ObjectInputStream(
        new BufferedInputStream(new FileInputStream(path)))) {

    // BEFORE any readObject
    DeserialisationFilter.applyTo(input);

    LibrarySession session = (LibrarySession) input.readObject();
}

java.io.InvalidClassException: filter status: REJECTED

java -Djdk.serialFilter='com.nexussoftware.bibliotech.**;java.util.*;!*' BiblioTechApp

package com.nexussoftware.bibliotech.service;

import java.io.*;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.infrastructure.DeserialisationFilter;

/**
 * Saves and restores the state of a BiblioTech working session.
 *
 * WHY NATIVE SERIALISATION IS ACCEPTABLE HERE:
 *   - The file is written and read by the SAME application.
 *   - It lives in the local data directory; it does not travel nor get uploaded.
 *   - Its content can be REGENERATED: if it gets corrupted, it is deleted and a
 *     new session is started. It is not the source of truth; the CSV catalogue is.
 *
 * WHY THE CATALOGUE DOES NOT USE THIS: the catalogue is the valuable data, it
 * must be readable, versionable and importable from a spreadsheet. That is 07-07.
 *
 * Even so a deserialisation FILTER is applied: defence in depth.
 */
public class SessionManager {

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

    private static final String EXTENSION = ".session";

    private final File directory;

    public SessionManager(String dataDirectory) {
        this.directory = new File(
                Objects.requireNonNull(dataDirectory, "The directory cannot be null"));
        if (!directory.exists() && !directory.mkdirs()) {
            LOG.warning("Could not create " + directory.getAbsolutePath());
        }
    }

    // ------------------------- THE STATE -------------------------

    /**
     * Serialisable snapshot of the state of a session.
     *
     * It is a SEPARATE class from LibrarySession on purpose: the session
     * manages resources (locks, logger) that must not be serialised.
     * This class contains only DATA.
     */
    public static class SessionState implements Serializable {

        /**
         * DECLARED from day one. Without it, adding a private method in six
         * months' time would make every saved session unreadable
         * (section 7).
         */
        private static final long serialVersionUID = 1L;

        private final String employeeId;
        private final int openingDay;
        private final List<String> operations;
        private final int loansMade;
        private final int returnsMade;
        private final double finesCollected;

        /** Derived: it is recomputed. There is no point in saving it. */
        private transient String formattedSummary;

        public SessionState(String employeeId, int openingDay, List<String> operations,
                            int loansMade, int returnsMade,
                            double finesCollected) {

            this.employeeId = Objects.requireNonNull(employeeId, "The employee is mandatory");
            if (openingDay < 1) {
                throw new IllegalArgumentException("Invalid day: " + openingDay);
            }
            if (finesCollected < 0) {
                throw new IllegalArgumentException("Negative fines: " + finesCollected);
            }
            this.openingDay = openingDay;
            // Explicit ArrayList: it is serialisable and its form is stable
            this.operations = new ArrayList<>(operations);
            this.loansMade = loansMade;
            this.returnsMade = returnsMade;
            this.finesCollected = finesCollected;
        }

        /**
         * VALIDATION on deserialising.
         *
         * Essential: deserialisation does NOT call the constructor, so the
         * checks above have NOT been run. A corrupt or tampered file could
         * bring a negative day or impossible fines, and the rest of the
         * system would take them as good.
         */
        private void readObject(ObjectInputStream input)
                throws IOException, ClassNotFoundException {

            input.defaultReadObject();

            if (employeeId == null || employeeId.isBlank()) {
                throw new InvalidObjectException(
                        "Session with no employee: file corrupt or tampered with");
            }
            if (openingDay < 1) {
                throw new InvalidObjectException(
                        "Invalid opening day: " + openingDay);
            }
            if (finesCollected < 0) {
                throw new InvalidObjectException(
                        "Negative fines: " + finesCollected);
            }
            if (operations == null) {
                throw new InvalidObjectException("Null operations list");
            }
            // The transient field is recomputed on demand: nothing to do here
        }

        public String getEmployeeId()        { return employeeId; }
        public int getOpeningDay()           { return openingDay; }
        public List<String> getOperations()  { return List.copyOf(operations); }
        public int getLoansMade()            { return loansMade; }
        public int getReturnsMade()          { return returnsMade; }
        public double getFinesCollected()    { return finesCollected; }

        /** Derived field: computed the first time and cached. */
        public String getSummary() {
            if (formattedSummary == null) {
                formattedSummary = String.format(
                        "Session of %s (day %d): %d loans, %d returns, %.2f EUR",
                        employeeId, openingDay, loansMade,
                        returnsMade, finesCollected);
            }
            return formattedSummary;
        }
    }

    // ------------------------- SAVING -------------------------

    /**
     * Saves the state ATOMICALLY (07-02): temporary file and rename.
     *
     * A half-saved session would be worse than none: on restoring it would
     * give StreamCorruptedException or, worse, an incomplete object.
     */
    public void save(SessionState state) throws IOException {
        Objects.requireNonNull(state, "The state cannot be null");

        File target = new File(directory, state.getEmployeeId() + EXTENSION);
        File temp = new File(target.getAbsolutePath() + ".tmp");

        boolean completed = false;
        try {
            try (ObjectOutputStream output = new ObjectOutputStream(
                    new BufferedOutputStream(new FileOutputStream(temp)))) {

                output.writeObject(state);
            }   // close() -> flush guaranteed

            if (target.exists() && !target.delete()) {
                throw new IOException("Could not replace " + target.getName());
            }
            if (!temp.renameTo(target)) {
                throw new IOException("Could not rename " + temp.getName());
            }
            completed = true;

            LOG.info(() -> String.format("Session of %s saved to %s (%d bytes)",
                    state.getEmployeeId(), target.getName(), target.length()));

        } finally {
            if (!completed && temp.exists() && !temp.delete()) {
                LOG.warning(() -> "Temporary file left undeleted: " + temp.getAbsolutePath());
            }
        }
    }

    // ------------------------- RESTORING -------------------------

    /**
     * Restores an employee's session.
     *
     * GRACEFUL DEGRADATION (06-07): if there is no saved session, or it is
     * corrupt, or the class changed, an empty result is returned and we
     * start from scratch. Losing a session is not a serious failure: the
     * valuable data is in the catalogue.
     *
     * @return an empty Optional if it could not be restored
     */
    public java.util.Optional<SessionState> restore(String employeeId) {
        File file = new File(directory, employeeId + EXTENSION);

        if (!file.exists()) {
            LOG.fine(() -> "There is no saved session for " + employeeId);
            return java.util.Optional.empty();
        }

        try (ObjectInputStream input = new ObjectInputStream(
                new BufferedInputStream(new FileInputStream(file)))) {

            // FILTER before reading anything. Defence in depth (section 13).
            DeserialisationFilter.applyTo(input);

            SessionState state = (SessionState) input.readObject();

            LOG.info(() -> "Session restored: " + state.getSummary());
            return java.util.Optional.of(state);

        } catch (InvalidClassException e) {
            // The class changed incompatibly (section 8).
            LOG.log(Level.WARNING, "The session of " + employeeId
                    + " was saved with another version of the application and cannot be read", e);
            setAside(file);
            return java.util.Optional.empty();

        } catch (InvalidObjectException e) {
            // Our readObject rejected the content: corrupt or tampered with.
            LOG.log(Level.SEVERE, "Session of " + employeeId + " rejected by validation", e);
            setAside(file);
            return java.util.Optional.empty();

        } catch (StreamCorruptedException | EOFException e) {
            // Truncated file: a write was cut short. The atomic writing of
            // save() prevents that, but a disk failure does not.
            LOG.log(Level.WARNING, "Session of " + employeeId + " corrupt", e);
            setAside(file);
            return java.util.Optional.empty();

        } catch (ClassNotFoundException e) {
            // It does not extend IOException: it needs its own catch (section 3)
            LOG.log(Level.SEVERE, "Class not found while restoring the session of "
                    + employeeId, e);
            return java.util.Optional.empty();

        } catch (IOException e) {
            LOG.log(Level.SEVERE, "I/O failure restoring the session of " + employeeId, e);
            return java.util.Optional.empty();
        }
    }

    /** Sets an unreadable file aside instead of deleting it: it may be needed for diagnosis. */
    private void setAside(File file) {
        File aside = new File(file.getAbsolutePath() + ".invalid");
        if (aside.exists()) {
            aside.delete();
        }
        if (file.renameTo(aside)) {
            LOG.info(() -> "Unreadable session set aside as " + aside.getName());
        }
    }
}

public class SessionDemo {

    public static void main(String[] args) throws IOException {
        SessionManager manager = new SessionManager("data/sessions");

        // --- On start-up: try to restore ---
        manager.restore("EMP-001").ifPresentOrElse(
                state -> System.out.println("Continuing: " + state.getSummary()),
                ()    -> System.out.println("New session for EMP-001"));

        // --- The shift's work ---
        List<String> operations = new ArrayList<>();
        operations.add("LOAN LN-0001");
        operations.add("LOAN LN-0002");
        operations.add("RETURN LN-0001 (fine 1.75)");

        // --- On exit: save ---
        manager.save(new SessionManager.SessionState(
                "EMP-001", 15, operations, 2, 1, 1.75));

        System.out.println("Session saved. Run it again to see the restoration.");
    }
}

New session for EMP-001
Session saved. Run it again to see the restoration.

Continuing: Session of EMP-001 (day 15): 2 loans, 1 returns, 1.75 EUR
Session saved. Run it again to see the restoration.

package com.nexussoftware.bibliotech.demo;

import java.io.*;

/**
 * serialVersionUID laboratory.
 *
 * HOW TO REPRODUCE THE MAIN EXPERIMENT:
 *
 *   1. Compile and run with the getLabel() method COMMENTED OUT in DataV1.
 *      data/v1.ser is generated
 *
 *   2. UNCOMMENT getLabel() (a PRIVATE method, which does not touch the state).
 *
 *   3. Recompile and run again.
 *
 *   RESULT: reading data/v1.ser gives
 *
 *     java.io.InvalidClassException: ...DataV1; local class incompatible:
 *       stream classdesc serialVersionUID = -4738291056473829104,
 *       local class serialVersionUID = 8273645019283746152
 *
 *   The file is left UNREADABLE FOR EVER because a private method was added
 *   that does not affect the state in any way.
 */
public class CompatibilityLab {

    // ---------------- WITHOUT serialVersionUID: fragile ----------------

    static class DataV1 implements Serializable {
        // WITHOUT serialVersionUID: it is computed automatically from the
        // name, fields, METHODS (including private ones), constructors...
        private final String reference;
        private final String title;
        private final int year;

        DataV1(String reference, String title, int year) {
            this.reference = reference;
            this.title = title;
            this.year = year;
        }

        // STEP 2 OF THE EXPERIMENT: uncomment this and recompile.
        // private String getLabel() { return reference + " - " + title; }

        @Override
        public String toString() {
            return String.format("DataV1[%s, %s, %d]", reference, title, year);
        }
    }

    // ---------------- WITH serialVersionUID: stable ----------------

    /** Version B: three fields, UID declared. */
    static class DataV2 implements Serializable {
        private static final long serialVersionUID = 1L;

        private final String reference;
        private final String title;
        private final int year;

        // FIELD ADDED in version 2. Compatible: the files written without it
        // read just the same, and this field takes its default value.
        private final String author;

        DataV2(String reference, String title, int year, String author) {
            this.reference = reference;
            this.title = title;
            this.year = year;
            this.author = author;
        }

        @Override
        public String toString() {
            return String.format("DataV2[%s, %s, %d, author=%s]",
                    reference, title, year,
                    author == null ? "(null: old file)" : author);
        }
    }

    // ---------------- Utilities ----------------

    static void save(Object o, String path) throws IOException {
        try (ObjectOutputStream output = new ObjectOutputStream(
                new BufferedOutputStream(new FileOutputStream(path)))) {
            output.writeObject(o);
        }
    }

    static Object load(String path) throws IOException, ClassNotFoundException {
        try (ObjectInputStream input = new ObjectInputStream(
                new BufferedInputStream(new FileInputStream(path)))) {
            return input.readObject();
        }
    }

    /** Shows the UID the mechanism assigns to a class, declared or computed. */
    static long uidOf(Class<?> type) {
        ObjectStreamClass osc = ObjectStreamClass.lookup(type);
        return (osc == null) ? 0L : osc.getSerialVersionUID();
    }

    public static void main(String[] args) throws Exception {
        new File("data").mkdirs();

        System.out.println("=== UID OF EACH CLASS ===");
        System.out.printf("  DataV1 (not declared): %d%n", uidOf(DataV1.class));
        System.out.printf("  DataV2 (declared)    : %d%n", uidOf(DataV2.class));
        System.out.println("  The first changes when you touch the class; the second, never.");
        System.out.println();

        // --- Experiment 1: without a declared UID ---
        System.out.println("=== WITHOUT serialVersionUID ===");
        File v1 = new File("data/v1.ser");

        if (!v1.exists()) {
            save(new DataV1("978-0000000001", "Effective Java", 2018), v1.getPath());
            System.out.println("  File created. NOW: uncomment getLabel(),");
            System.out.println("  recompile and run again.");
        } else {
            try {
                System.out.println("  Read: " + load(v1.getPath()));
                System.out.println("  (the class has not changed since it was saved)");
            } catch (InvalidClassException e) {
                System.out.println("  INCOMPATIBLE, as expected:");
                System.out.println("  " + e.getMessage());
                System.out.println("  Cause: a method was added. The file is unreadable.");
            }
        }

        // --- Experiment 2: with a declared UID and an added field ---
        System.out.println();
        System.out.println("=== WITH serialVersionUID ===");

        File v2 = new File("data/v2.ser");
        save(new DataV2("978-0000000002", "Design Patterns", 1994, "Gamma"),
                v2.getPath());
        System.out.println("  Saved and read: " + load(v2.getPath()));

        System.out.println();
        System.out.println("=== COMPATIBLE CHANGES (with the UID declared) ===");
        System.out.println("  COMPATIBLE:");
        System.out.println("    - Adding a field         -> it is null / 0 / false");
        System.out.println("    - Removing a field       -> the value in the file is discarded");
        System.out.println("    - Adding or removing methods -> no effect");
        System.out.println("    - Changing a body        -> no effect");
        System.out.println("    - normal <-> transient   -> like adding or removing a field");
        System.out.println("  INCOMPATIBLE:");
        System.out.println("    - Changing the TYPE of a field -> InvalidClassException");
        System.out.println("    - RENAMING a field             -> the data is LOST, no error");
        System.out.println("    - Renaming or moving the class -> ClassNotFoundException");
        System.out.println("    - Changing the inheritance     -> InvalidClassException");
    }
}

package com.nexussoftware.bibliotech.util;

import java.io.*;
import java.util.ArrayList;
import java.util.List;

/**
 * Deep copy by means of in-memory serialisation.
 *
 * It serialises to an array of bytes and deserialises from it: the result is
 * a completely new graph, with no reference shared with the original.
 * Without touching the disk: ByteArrayOutputStream / ByteArrayInputStream
 * (07-03).
 *
 * THREE REAL LIMITATIONS:
 *
 *   1. THE WHOLE graph must be Serializable. A single non-serialisable field
 *      at any depth makes the entire copy fail (NotSerializableException).
 *
 *   2. IT IS SLOW. Serialising and deserialising involve reflection, metadata
 *      construction and byte copying. A hand-written copy method is between
 *      ten and a hundred times faster.
 *
 *   3. transient FIELDS ARE NOT COPIED. They are left null or 0 in the copy,
 *      which is correct for a cache but a silent bug if the field was marked
 *      transient for another reason.
 *
 *   And a fourth worth keeping in mind: if the object came from an untrusted
 *   source, this technique inherits ALL the risks of section 12. Use it only
 *   with objects you already have in memory and control.
 */
public final class DeepCopy {

    private DeepCopy() { }

    /**
     * Deep copy of a serialisable object.
     *
     * It returns Object: casting is the caller's business. (With generics it
     * would be nicer, but that is 10-01.)
     */
    public static Object copy(Serializable original) throws IOException {
        if (original == null) {
            return null;
        }

        ByteArrayOutputStream memory = new ByteArrayOutputStream();

        try (ObjectOutputStream output = new ObjectOutputStream(memory)) {
            output.writeObject(original);
        }
        // ByteArrayOutputStream does not need closing: its close() does nothing,
        // and closing it before toByteArray() would be a conceptual error (07-03).

        try (ObjectInputStream input = new ObjectInputStream(
                new ByteArrayInputStream(memory.toByteArray()))) {

            return input.readObject();

        } catch (ClassNotFoundException e) {
            // Impossible in practice: the class is loaded, we have just
            // serialised it. It is translated into an IOException so as not to
            // force the caller to catch something that cannot happen (06-03).
            throw new IOException("Impossible failure while copying: class not found", e);
        }
    }

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

    /** Test object with a mutable list inside. */
    static class LoanBasket implements Serializable {
        private static final long serialVersionUID = 1L;

        private final String employeeId;
        private final List<String> references;
        private double estimatedTotal;

        /** transient: it will NOT be copied. It is left null in the copy. */
        private transient String internalNote;

        LoanBasket(String employeeId) {
            this.employeeId = employeeId;
            this.references = new ArrayList<>();
            this.internalNote = "working note";
        }

        void add(String reference, double cost) {
            references.add(reference);
            estimatedTotal += cost;
        }

        List<String> getReferences() { return references; }     // mutable reference
        String getInternalNote()     { return internalNote; }

        @Override
        public String toString() {
            return String.format("Basket[%s, %s, %.2f, note=%s]",
                    employeeId, references, estimatedTotal,
                    internalNote == null ? "(null)" : internalNote);
        }
    }

    /** Hand-written copy, for a performance comparison. */
    static LoanBasket copyByHand(LoanBasket original) {
        LoanBasket copy = new LoanBasket(original.employeeId);
        copy.references.addAll(original.references);         // a new list
        copy.estimatedTotal = original.estimatedTotal;
        copy.internalNote = original.internalNote;           // this one IS copied
        return copy;
    }

    public static void main(String[] args) throws IOException {
        LoanBasket original = new LoanBasket("EMP-001");
        original.add("978-0000000001", 0.25);
        original.add("978-0000000002", 0.25);

        System.out.println("=== SHALLOW COPY (reference assignment) ===");
        LoanBasket shallow = original;
        shallow.getReferences().add("978-0000000003");
        System.out.println("  Original: " + original.getReferences());
        System.out.println("  'Copy'  : " + shallow.getReferences());
        System.out.println("  They are the SAME object: " + (original == shallow));

        System.out.println();
        System.out.println("=== DEEP COPY (serialisation) ===");
        LoanBasket deep = (LoanBasket) copy(original);
        deep.getReferences().add("978-0000000004");

        System.out.println("  Original: " + original.getReferences());
        System.out.println("  Copy    : " + deep.getReferences());
        System.out.println("  Different objects       : " + (original != deep));
        System.out.println("  Different lists         : "
                + (original.getReferences() != deep.getReferences()));
        System.out.println("  Note (transient) copied : " + deep.getInternalNote());

        System.out.println();
        System.out.println("=== PERFORMANCE (10,000 copies) ===");

        long start = System.nanoTime();
        for (int i = 0; i < 10_000; i++) {
            copy(original);
        }
        long msSerialisation = (System.nanoTime() - start) / 1_000_000;

        start = System.nanoTime();
        for (int i = 0; i < 10_000; i++) {
            copyByHand(original);
        }
        long msByHand = (System.nanoTime() - start) / 1_000_000;

        System.out.printf("  By serialisation : %5d ms%n", msSerialisation);
        System.out.printf("  By hand          : %5d ms%n", msByHand);
        System.out.printf("  Factor           : %.1fx slower%n",
                (double) msSerialisation / Math.max(1, msByHand));
    }
}

=== SHALLOW COPY (reference assignment) ===
  Original: [978-0000000001, 978-0000000002, 978-0000000003]
  'Copy'  : [978-0000000001, 978-0000000002, 978-0000000003]
  They are the SAME object: true

=== DEEP COPY (serialisation) ===
  Original: [978-0000000001, 978-0000000002, 978-0000000003]
  Copy    : [978-0000000001, 978-0000000002, 978-0000000003, 978-0000000004]
  Different objects       : true
  Different lists         : true
  Note (transient) copied : null

=== PERFORMANCE (10,000 copies) ===
  By serialisation :   412 ms
  By hand          :     4 ms
  Factor           : 103.0x slower

package com.nexussoftware.bibliotech.service;

import java.io.*;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.logging.Level;
import java.util.logging.Logger;

import com.nexussoftware.bibliotech.infrastructure.DeserialisationFilter;

/**
 * Session manager supporting TWO versions of the saved state.
 *
 * Version 2 adds the 'materialsViewed' field KEEPING the same
 * serialVersionUID, because adding a field is a COMPATIBLE change: the
 * version 1 files are still read and the new field arrives as 0.
 *
 * The trick is in readObject: telling "0 really were viewed" from "this file
 * is old and does not know" is impossible with the default value, so an
 * explicit SENTINEL is used.
 */
public class VersionedSessionManager {

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

    private static final String EXTENSION = ".session";
    private static final String INVALID_EXTENSION = ".session.invalid";

    private final File directory;

    public VersionedSessionManager(String dataDirectory) {
        this.directory = new File(Objects.requireNonNull(dataDirectory));
        if (!directory.exists() && !directory.mkdirs()) {
            LOG.warning("Could not create " + directory.getAbsolutePath());
        }
    }

    // ------------------------- THE STATE, VERSION 2 -------------------------

    public static class SessionState implements Serializable {

        /** SAME value as in version 1: the change is compatible. */
        private static final long serialVersionUID = 1L;

        /** "Not reported" marker, to tell it from a real 0. */
        private static final int NOT_REPORTED = -1;

        private final String employeeId;
        private final int openingDay;
        private final List<String> operations;
        private final int loansMade;
        private final int returnsMade;
        private final double finesCollected;

        /**
         * FIELD ADDED IN VERSION 2.
         *
         * It is not final: readObject needs to be able to correct it when the
         * file comes from version 1.
         */
        private int materialsViewed;

        /** Format version it was created with. transient: it is deduced. */
        private transient int detectedVersion = 2;

        public SessionState(String employeeId, int openingDay, List<String> operations,
                            int loansMade, int returnsMade,
                            double finesCollected, int materialsViewed) {

            this.employeeId = Objects.requireNonNull(employeeId, "The employee is mandatory");
            if (openingDay < 1) {
                throw new IllegalArgumentException("Invalid day: " + openingDay);
            }
            if (finesCollected < 0) {
                throw new IllegalArgumentException("Negative fines: " + finesCollected);
            }
            this.openingDay = openingDay;
            this.operations = new ArrayList<>(operations);
            this.loansMade = loansMade;
            this.returnsMade = returnsMade;
            this.finesCollected = finesCollected;
            this.materialsViewed = Math.max(0, materialsViewed);
        }

        /**
         * Migration and validation.
         *
         * A version 1 file does not contain 'materialsViewed', so it arrives
         * as 0. Since we cannot tell that 0 from a real 0, we apply a
         * reasonable HEURISTIC and LEAVE A RECORD in the log: whoever viewed
         * materials at least viewed the ones they lent.
         */
        private void readObject(ObjectInputStream input)
                throws IOException, ClassNotFoundException {

            input.defaultReadObject();

            // --- VALIDATION (the constructor has not been run) ---
            if (employeeId == null || employeeId.isBlank()) {
                throw new InvalidObjectException("Session with no employee: file corrupt");
            }
            if (openingDay < 1) {
                throw new InvalidObjectException("Invalid day: " + openingDay);
            }
            if (finesCollected < 0) {
                throw new InvalidObjectException("Negative fines: " + finesCollected);
            }
            if (operations == null) {
                throw new InvalidObjectException("Null operations list");
            }

            // --- VERSION MIGRATION ---
            if (materialsViewed == 0 && loansMade > 0) {
                detectedVersion = 1;
                materialsViewed = loansMade;

                LOG.info(() -> String.format(
                        "Session of %s saved with version 1 of the format: "
                                + "materialsViewed = %d is estimated from the loans",
                        employeeId, loansMade));
            } else {
                detectedVersion = 2;
            }

            if (materialsViewed < 0) {
                materialsViewed = 0;
            }
        }

        public String getEmployeeId()       { return employeeId; }
        public int getOpeningDay()          { return openingDay; }
        public List<String> getOperations() { return List.copyOf(operations); }
        public int getLoansMade()           { return loansMade; }
        public int getReturnsMade()         { return returnsMade; }
        public double getFinesCollected()   { return finesCollected; }
        public int getMaterialsViewed()     { return materialsViewed; }
        public int getDetectedVersion()     { return detectedVersion; }

        public String getSummary() {
            return String.format(
                    "Session of %s (day %d, format v%d): %d loans, %d returns, "
                            + "%d views, %.2f EUR",
                    employeeId, openingDay, detectedVersion, loansMade,
                    returnsMade, materialsViewed, finesCollected);
        }
    }

    // ------------------------- OPERATIONS -------------------------

    public void save(SessionState state) throws IOException {
        Objects.requireNonNull(state, "The state cannot be null");

        File target = new File(directory, state.getEmployeeId() + EXTENSION);
        File temp = new File(target.getAbsolutePath() + ".tmp");
        boolean completed = false;

        try {
            try (ObjectOutputStream output = new ObjectOutputStream(
                    new BufferedOutputStream(new FileOutputStream(temp)))) {
                output.writeObject(state);
            }
            if (target.exists() && !target.delete()) {
                throw new IOException("Could not replace " + target.getName());
            }
            if (!temp.renameTo(target)) {
                throw new IOException("Could not rename " + temp.getName());
            }
            completed = true;
            LOG.info(() -> "Session saved: " + target.getName());

        } finally {
            if (!completed && temp.exists() && !temp.delete()) {
                LOG.warning(() -> "Temporary file left undeleted: " + temp.getAbsolutePath());
            }
        }
    }

    public java.util.Optional<SessionState> restore(String employeeId) {
        File file = new File(directory, employeeId + EXTENSION);
        if (!file.exists()) {
            return java.util.Optional.empty();
        }
        try {
            return java.util.Optional.of(read(file));
        } catch (Exception e) {
            LOG.log(Level.WARNING, "Could not restore " + file.getName(), e);
            return java.util.Optional.empty();
        }
    }

    /** Reading with a filter. It throws so the caller can decide. */
    private SessionState read(File file) throws IOException, ClassNotFoundException {
        try (ObjectInputStream input = new ObjectInputStream(
                new BufferedInputStream(new FileInputStream(file)))) {

            DeserialisationFilter.applyTo(input);
            return (SessionState) input.readObject();
        }
    }

    // ------------------------- REPORT AND CLEAN-UP -------------------------

    /** State of a session file in the directory. */
    public record SessionInfo(String name, long size, boolean readable,
                              String detail) { }

    /**
     * Report of all the saved sessions.
     *
     * It tries to read each one and classifies the result. It does NOT
     * propagate: the report must be producible even when there are broken
     * files, which is precisely when it is most needed.
     */
    public List<SessionInfo> listSessions() {
        List<SessionInfo> report = new ArrayList<>();

        File[] files = directory.listFiles(
                (dir, name) -> name.endsWith(EXTENSION));

        if (files == null) {                           // it can be null (07-01)
            LOG.warning("Could not list " + directory.getAbsolutePath());
            return report;
        }

        Arrays.sort(files);                             // stable order (05-09)

        for (File f : files) {
            try {
                SessionState state = read(f);
                report.add(new SessionInfo(f.getName(), f.length(), true,
                        state.getSummary()));

            } catch (InvalidClassException e) {
                report.add(new SessionInfo(f.getName(), f.length(), false,
                        "Incompatible class version"));

            } catch (InvalidObjectException e) {
                report.add(new SessionInfo(f.getName(), f.length(), false,
                        "Rejected by validation: " + e.getMessage()));

            } catch (StreamCorruptedException | EOFException e) {
                report.add(new SessionInfo(f.getName(), f.length(), false,
                        "Corrupt or truncated file"));

            } catch (ClassNotFoundException e) {
                report.add(new SessionInfo(f.getName(), f.length(), false,
                        "Class not found: " + e.getMessage()));

            } catch (IOException e) {
                report.add(new SessionInfo(f.getName(), f.length(), false,
                        "I/O failure: " + e.getMessage()));
            }
        }
        return report;
    }

    /**
     * Sets the unreadable files aside by renaming them.
     *
     * It does NOT delete them: an unreadable file may be needed to diagnose
     * why it stopped being readable.
     *
     * @return how many were set aside
     */
    public int cleanInvalidSessions() {
        int setAside = 0;

        for (SessionInfo info : listSessions()) {
            if (info.readable()) {
                continue;
            }
            File source = new File(directory, info.name());
            File target = new File(directory,
                    info.name().replace(EXTENSION, INVALID_EXTENSION));

            if (target.exists()) {
                target.delete();
            }
            if (source.renameTo(target)) {
                setAside++;
                LOG.info(() -> "Unreadable session set aside: " + target.getName()
                        + " (" + info.detail() + ")");
            } else {
                LOG.warning(() -> "Could not set aside " + source.getName());
            }
        }
        return setAside;
    }

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

    public static void main(String[] args) throws IOException {
        VersionedSessionManager manager = new VersionedSessionManager("data/sessions");

        // 1. Save three sessions
        manager.save(new SessionState("EMP-001", 15,
                List.of("LOAN LN-0001", "RETURN LN-0001"), 1, 1, 1.75, 4));
        manager.save(new SessionState("EMP-002", 15,
                List.of("LOAN LN-0002"), 1, 0, 0.0, 2));
        manager.save(new SessionState("EMP-003", 16,
                List.of(), 0, 0, 0.0, 0));

        // 2. Create a corrupt file on purpose
        File corrupt = new File("data/sessions/EMP-999.session");
        try (FileOutputStream fos = new FileOutputStream(corrupt)) {
            fos.write("this is not an object stream".getBytes());
        }

        // 3. Report
        System.out.println("=== SAVED SESSIONS ===");
        for (SessionInfo info : manager.listSessions()) {
            System.out.printf("  %-18s %6d bytes  %-10s %s%n",
                    info.name(), info.size(),
                    info.readable() ? "[OK]" : "[ERROR]", info.detail());
        }

        // 4. A particular restoration
        System.out.println();
        System.out.println("=== RESTORATION ===");
        manager.restore("EMP-001").ifPresentOrElse(
                s -> System.out.println("  " + s.getSummary()),
                () -> System.out.println("  Could not restore EMP-001"));

        // 5. Clean-up
        System.out.println();
        System.out.printf("=== CLEAN-UP: %d files set aside ===%n",
                manager.cleanInvalidSessions());
    }
}

=== SAVED SESSIONS ===
  EMP-001.session       301 bytes  [OK]       Session of EMP-001 (day 15, format v2): 1 loans, 1 returns, 4 views, 1.75 EUR
  EMP-002.session       268 bytes  [OK]       Session of EMP-002 (day 15, format v2): 1 loans, 0 returns, 2 views, 0.00 EUR
  EMP-003.session       243 bytes  [OK]       Session of EMP-003 (day 16, format v2): 0 loans, 0 returns, 0 views, 0.00 EUR
  EMP-999.session         28 bytes  [ERROR]    Corrupt or truncated file

=== RESTORATION ===
  Session of EMP-001 (day 15, format v2): 1 loans, 1 returns, 4 views, 1.75 EUR

=== CLEAN-UP: 1 files set aside ===