public void example() {
    int counter = 42;                               // the VALUE is on the stack
    Book book = new Book("978-0000000001", "Effective Java");
    //   ^ the REFERENCE is on the stack        ^ the OBJECT is on the heap
}

public class AvailableMemory {

    public static void main(String[] args) {
        Runtime rt = Runtime.getRuntime();

        System.out.printf("Maximum (-Xmx):  %,d MB%n", rt.maxMemory()   / 1024 / 1024);
        System.out.printf("Total reserved:  %,d MB%n", rt.totalMemory() / 1024 / 1024);
        System.out.printf("Free overall:    %,d MB%n", rt.freeMemory()  / 1024 / 1024);
        System.out.printf("In use:          %,d MB%n",
                (rt.totalMemory() - rt.freeMemory()) / 1024 / 1024);
        System.out.printf("Processors:      %d%n", rt.availableProcessors());
    }
}

Maximum (-Xmx):  4,096 MB
Total reserved:  258 MB
Free overall:    196 MB
In use:          62 MB
Processors:      8

public class Frames {

    public static void main(String[] args) {    // frame 1
        int a = 10;
        first(a);
    }

    static void first(int x) {                  // frame 2
        String text = "BiblioTech";
        second(x * 2, text);
    }

    static void second(int y, String t) {       // frame 3
        System.out.println(y + " " + t);
    }                                            // frame 3 is discarded
}

public class StackOverflow {

    private static int depth = 0;

    static void infiniteRecursion() {
        depth++;
        infiniteRecursion();                    // no base case
    }

    public static void main(String[] args) {
        try {
            infiniteRecursion();
        } catch (StackOverflowError e) {
            System.out.println("StackOverflowError at " + depth + " frames");
        }
    }
}

StackOverflowError at 21847 frames

java -Xss1m MyProgram       # 1 MB per thread (typical default on 64-bit)
java -Xss16m MyProgram      # for legitimate deep recursion
java -Xss256k MyProgram     # to have MANY threads

Book book = new Book("978-0000000001", "Effective Java", "Joshua Bloch", 412, 4.85);

java -XX:+PrintFlagsFinal -version | grep -i UseCompressedOops

bool UseCompressedOops = true    {lp64_product} {default}

java -XX:MaxMetaspaceSize=256m MyProgram

Java HotSpot(TM) 64-Bit Server VM warning: CodeCache is full.
    Compiler has been disabled.

java -XX:ReservedCodeCacheSize=512m MyProgram

// DIRECT buffer: the memory is NOT on the heap
ByteBuffer direct = ByteBuffer.allocateDirect(64 * 1024 * 1024);    // 64 MB native

// Ordinary buffer: it IS on the heap
ByteBuffer onHeap = ByteBuffer.allocate(64 * 1024 * 1024);

java -XX:MaxDirectMemorySize=512m MyProgram

Total memory ≈ Heap (-Xmx)
              + Metaspace
              + Code cache
              + (Number of threads × -Xss)
              + Direct buffers
              + JVM internal structures (~100-300 MB)

java -XX:MaxRAMPercentage=70 -jar bibliotech.jar

package com.nexussoftware.bibliotech.diagnostics;

import java.util.ArrayList;
import java.util.List;

public class TriggerOutOfMemory {

    /** Run with: java -Xmx64m -XX:+HeapDumpOnOutOfMemoryError */
    public static void main(String[] args) {

        List<byte[]> retained = new ArrayList<>();
        int blocks = 0;

        try {
            while (true) {
                retained.add(new byte[1024 * 1024]);       // 1 MB each time
                blocks++;
            }
        } catch (OutOfMemoryError e) {
            // Catch OOM only to DIAGNOSE and exit. Never to carry on.
            System.err.println("OutOfMemoryError after " + blocks + " MB");
            System.err.println("Message: " + e.getMessage());
            retained.clear();                               // free up so we can print
            System.exit(1);
        }
    }
}

OutOfMemoryError after 61 MB
Message: Java heap space

java -XX:+HeapDumpOnOutOfMemoryError \
     -XX:HeapDumpPath=/var/log/bibliotech/heapdumps/ \
     -XX:+ExitOnOutOfMemoryError \
     -jar bibliotech.jar

java -Xlog:gc -Xmx256m -jar bibliotech.jar

[0.412s][info][gc] GC(0) Pause Young (Normal) (G1 Evacuation Pause) 51M->8M(256M) 6.412ms
[1.238s][info][gc] GC(1) Pause Young (Normal) (G1 Evacuation Pause) 59M->12M(256M) 5.891ms
[2.104s][info][gc] GC(2) Pause Young (Normal) (G1 Evacuation Pause) 63M->14M(256M) 7.203ms
[8.771s][info][gc] GC(9) Pause Full (System.gc()) 198M->31M(256M) 187.442ms

java -XX:+DisableExplicitGC -jar bibliotech.jar

java -Xlog:safepoint -jar bibliotech.jar

[3.201s][info][safepoint] Safepoint "G1CollectForAllocation", Time since last: 812 ms,
    Reaching safepoint: 47 ms, At safepoint: 8 ms, Total: 55 ms

java -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -Xmx8g -jar bibliotech.jar

java -XX:+UseZGC -XX:+ZGenerational -Xmx16g -jar bibliotech.jar

java -XX:+UnlockExperimentalVMOptions -XX:+UseEpsilonGC -Xmx1g AllocationTest

java -XX:+PrintFlagsFinal -version | wc -l

1247

java -Xmx4g -jar bibliotech.jar

java -XX:MaxRAMPercentage=70 -jar bibliotech.jar

java -Xms4g -Xmx4g -jar bibliotech.jar

java -XX:+UseG1GC -XX:MaxGCPauseMillis=200 ...

java -Xms2g -Xmx2g \
     -XX:+UseG1GC \
     -XX:MaxGCPauseMillis=200 \
     -XX:+HeapDumpOnOutOfMemoryError \
     -XX:HeapDumpPath=/var/log/bibliotech/ \
     -XX:+ExitOnOutOfMemoryError \
     -Xlog:gc*:file=/var/log/bibliotech/gc.log:time,uptime:filecount=5,filesize=10M \
     -jar bibliotech.jar

[3600.1s] GC(1201) Pause Young 892M->741M(1024M) 41.2ms
[3612.4s] GC(1202) Pause Young 901M->768M(1024M) 44.8ms
[3625.9s] GC(1203) Pause Young 918M->794M(1024M) 48.1ms
[3641.2s] GC(1204) Pause Full  1010M->961M(1024M) 892.3ms
[3644.7s] GC(1205) Pause Full  1014M->978M(1024M) 941.7ms
[3648.1s] GC(1206) Pause Full  1020M->1009M(1024M) 1102.4ms
java.lang.OutOfMemoryError: GC overhead limit exceeded

package com.nexussoftware.bibliotech.service;

import java.util.*;

/**
 * LEAK: the cache grows without limit.
 */
public class LeakyCache {

    // static: this is a GC ROOT. Everything hanging off it lives
    // as long as the class lives, that is, forever.
    private static final Map<String, Card> CACHE = new HashMap<>();

    public Card get(String isbn) {
        return CACHE.computeIfAbsent(isbn, this::buildCard);
    }
    // Nothing is ever removed. With a million distinct ISBNs,
    // a million cards retained forever.
}

/** CORRECT: a BOUNDED cache with LRU eviction (10-01). */
public class BoundedCache {

    private static final int CAPACITY = 10_000;

    private final Map<String, Card> cache =
            Collections.synchronizedMap(new LinkedHashMap<>(CAPACITY, 0.75f, true) {
                @Override
                protected boolean removeEldestEntry(Map.Entry<String, Card> eldest) {
                    return size() > CAPACITY;
                }
            });

    public Card get(String isbn) {
        return cache.computeIfAbsent(isbn, this::buildCard);
    }
}

package com.nexussoftware.bibliotech.presentation;

import java.util.ArrayList;
import java.util.List;
import java.util.function.Consumer;

public class EventManager {

    private static final List<Consumer<String>> SUBSCRIBERS = new ArrayList<>();

    public static void subscribe(Consumer<String> subscriber) {
        SUBSCRIBERS.add(subscriber);
    }

    public static void publish(String event) {
        SUBSCRIBERS.forEach(s -> s.accept(event));
    }
}

/** LEAK: it subscribes and never unsubscribes. */
public class LoanWindow {

    private final List<Loan> loans = new ArrayList<>(10_000);           // heavy object

    public LoanWindow() {
        // The LAMBDA implicitly captures 'this' by using a field.
        // EventManager.SUBSCRIBERS (static) retains the lambda,
        // the lambda retains this LoanWindow,
        // and this window retains its 10,000 loans. FOREVER.
        EventManager.subscribe(event -> refresh(event));
    }

    private void refresh(String event) { /* uses loans */ }

    public void close() {
        // There is no way to unsubscribe: we did not keep the reference
    }
}

/** CORRECT: keep the reference and unsubscribe. */
public class CorrectLoanWindow implements AutoCloseable {

    private final List<Loan> loans = new ArrayList<>(10_000);
    private final Consumer<String> subscriber;

    public CorrectLoanWindow() {
        this.subscriber = this::refresh;          // we keep the reference
        EventManager.subscribe(subscriber);
    }

    private void refresh(String event) { }

    @Override
    public void close() {
        EventManager.unsubscribe(subscriber);      // symmetry: subscribe/unsubscribe
    }
}

package com.nexussoftware.bibliotech.service;

/**
 * LEAK: the pool thread does NOT die, so neither does its ThreadLocal.
 */
public class LeakyContext {

    private static final ThreadLocal<RequestContext> CONTEXT = new ThreadLocal<>();

    public static void process(String employee, Runnable task) {
        CONTEXT.set(new RequestContext(employee));        // it is stored...
        task.run();
        // ...and NEVER cleared.
    }
}

/** CORRECT: clean-up guaranteed with finally. */
public class CorrectContext {

    private static final ThreadLocal<RequestContext> CONTEXT = new ThreadLocal<>();

    public static void process(String employee, Runnable task) {
        CONTEXT.set(new RequestContext(employee));
        try {
            task.run();
        } finally {
            CONTEXT.remove();           // MANDATORY, and in finally
        }
    }
}

package com.nexussoftware.bibliotech.service;

import java.util.ArrayList;
import java.util.List;

public class HeavyCatalog {

    private final List<Material> materials = new ArrayList<>(100_000);   // ~50 MB

    /**
     * NOT static: it implicitly retains HeavyCatalog.
     */
    public class SimpleCounter {
        private int count;
        public void increment() { count++; }
        public int getCount()   { return count; }
        // It does not use 'materials' at all, and yet it retains it
    }

    public SimpleCounter createCounter() {
        return new SimpleCounter();
    }
}

// The 50 MB catalogue is created, a 16-byte counter is taken out
// and the catalogue is discarded... but the counter retains it.
SimpleCounter counter;
{
    HeavyCatalog catalog = new HeavyCatalog();
    counter = catalog.createCounter();
}
// 'catalog' is no longer reachable... EXCEPT through counter.this$0
// The 50 MB are still there.

/** CORRECT: static, with no reference to the outer instance. */
public static class SimpleCounter {
    private int count;
    public void increment() { count++; }
    public int getCount()   { return count; }
}

package com.nexussoftware.bibliotech.diagnostics;

import java.lang.ref.*;

public class ReferenceStrengths {

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

        // --- STRONG: the GC does not touch it ---
        Book strong = new Book("978-0000000001", "Effective Java");
        System.gc();
        Thread.sleep(100);
        System.out.println("Strong after GC: " + (strong != null));      // true

        // --- WEAK: it disappears at the next GC ---
        WeakReference<Book> weak = new WeakReference<>(
                new Book("978-0000000002", "Design Patterns"));
        System.out.println("Weak before:     " + (weak.get() != null));  // true
        System.gc();
        Thread.sleep(100);
        System.out.println("Weak after GC:   " + (weak.get() != null));  // false

        // --- SOFT: it survives while there is memory ---
        SoftReference<Book> soft = new SoftReference<>(
                new Book("978-0000000003", "Refactoring"));
        System.gc();
        Thread.sleep(100);
        System.out.println("Soft after GC:   " + (soft.get() != null));  // true

        // --- PHANTOM: get() ALWAYS returns null ---
        ReferenceQueue<Book> queue = new ReferenceQueue<>();
        PhantomReference<Book> phantom = new PhantomReference<>(
                new Book("978-0000000004", "Clean Code"), queue);
        System.out.println("Phantom.get():   " + phantom.get());         // always null

        System.gc();
        Thread.sleep(100);
        Reference<?> enqueued = queue.poll();
        System.out.println("Notified?        " + (enqueued != null));    // true
    }
}

Strong after GC: true
Weak before:     true
Weak after GC:   false
Soft after GC:   true
Phantom.get():   null
Notified?        true

package com.nexussoftware.bibliotech.diagnostics;

import java.util.*;

public class MapComparison {

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

        Map<Book, String> ordinary = new HashMap<>();
        Map<Book, String> weak = new WeakHashMap<>();

        Book retained  = new Book("978-0000000001", "Effective Java");
        Book temporary = new Book("978-0000000002", "Design Patterns");

        ordinary.put(retained, "shelf A-1");
        ordinary.put(temporary, "shelf A-2");
        weak.put(retained, "shelf A-1");
        weak.put(temporary, "shelf A-2");

        System.out.println("Before -> HashMap: " + ordinary.size()
                         + ", WeakHashMap: " + weak.size());

        temporary = null;         // the last STRONG reference is lost
        System.gc();
        Thread.sleep(200);

        System.out.println("After  -> HashMap: " + ordinary.size()
                         + ", WeakHashMap: " + weak.size());
    }
}

Before -> HashMap: 2, WeakHashMap: 2
After  -> HashMap: 2, WeakHashMap: 1

package com.nexussoftware.bibliotech.service;

import com.nexussoftware.bibliotech.domain.*;

import java.time.Instant;
import java.util.*;

/**
 * BiblioTech card cache with two levels.
 *
 * Level 1 (WeakHashMap): cards associated with LIVE materials.
 *   If the material disappears from the catalogue, its card is freed on its own.
 *
 * Level 2 (LRU LinkedHashMap): cards by ISBN, bounded.
 *   It survives the material's disappearance, but with a cap.
 */
public class CardCache {

    private static final int LRU_CAPACITY = 5_000;

    /**
     * Key: the Material object. WEAK reference.
     * If nobody else references the material, the entry goes on its own.
     */
    private final Map<Material, Card> byMaterial =
            Collections.synchronizedMap(new WeakHashMap<>());

    /**
     * Key: the ISBN (a String, a strong reference).
     * Here an explicit eviction policy IS needed.
     */
    private final Map<String, Card> byIsbn =
            Collections.synchronizedMap(new LinkedHashMap<>(LRU_CAPACITY, 0.75f, true) {
                @Override
                protected boolean removeEldestEntry(Map.Entry<String, Card> eldest) {
                    return size() > LRU_CAPACITY;
                }
            });

    private long weakHits = 0;
    private long lruHits = 0;
    private long misses = 0;

    public Card get(Material material) {
        Card byObject = byMaterial.get(material);
        if (byObject != null) {
            weakHits++;
            return byObject;
        }

        Card byKey = byIsbn.get(material.getIsbn());
        if (byKey != null) {
            lruHits++;
            byMaterial.put(material, byKey);          // repopulate level 1
            return byKey;
        }

        misses++;
        Card fresh = compute(material);
        byMaterial.put(material, fresh);
        byIsbn.put(material.getIsbn(), fresh);
        return fresh;
    }

    private Card compute(Material material) {
        // Expensive computation: queries, aggregates, formatting
        return new Card(material.getIsbn(), material.getTitle(), true);
    }

    public String statistics() {
        long total = weakHits + lruHits + misses;
        return """
                CardCache
                  Level 1 (WeakHashMap): %d live entries, %d hits
                  Level 2 (LRU %d):      %d entries, %d hits
                  Misses:                %d
                  Hit rate:              %.1f %%"""
                .formatted(byMaterial.size(), weakHits,
                           LRU_CAPACITY, byIsbn.size(), lruHits,
                           misses, total == 0 ? 0.0
                                   : (weakHits + lruHits) * 100.0 / total);
    }
}

// LEAK: the value points at the key, which therefore never becomes unreachable
WeakHashMap<Book, Loan> map = new WeakHashMap<>();
map.put(book, new Loan(..., book));             // Loan holds the Book

// NEVER DO THIS
@Override
protected void finalize() throws Throwable {
    if (file != null) {
        file.close();
    }
}

package com.nexussoftware.bibliotech.persistence;

import java.lang.ref.Cleaner;
import java.nio.channels.FileChannel;
import java.nio.file.*;

/**
 * A resource with deterministic closing (AutoCloseable) PLUS a safety
 * net with Cleaner in case somebody forgets to close it.
 */
public class LoanStore implements AutoCloseable {

    /** ONE per application: it creates a thread. */
    private static final Cleaner CLEANER = Cleaner.create();

    /**
     * STATIC and with no reference to the outer object.
     * If it held a reference to LoanStore, that would never be
     * unreachable and the Cleaner would NEVER fire.
     * It is leak 4 from section 12, applied here.
     */
    private static class StateToClean implements Runnable {

        private final FileChannel channel;
        private final Path path;

        StateToClean(FileChannel channel, Path path) {
            this.channel = channel;
            this.path = path;
        }

        @Override
        public void run() {
            try {
                if (channel.isOpen()) {
                    System.err.println("WARNING: LoanStore(" + path
                            + ") was not closed; the Cleaner is closing it");
                    channel.close();
                }
            } catch (Exception e) {
                // The Cleaner swallows exceptions: there is nobody to propagate to
            }
        }
    }

    private final StateToClean state;
    private final Cleaner.Cleanable cleanable;

    public LoanStore(Path path) throws java.io.IOException {
        FileChannel channel = FileChannel.open(path,
                StandardOpenOption.CREATE, StandardOpenOption.WRITE);
        this.state = new StateToClean(channel, path);
        this.cleanable = CLEANER.register(this, state);
    }

    public void save(String line) { /* ... */ }

    @Override
    public void close() {
        cleanable.clean();     // DETERMINISTIC and idempotent closing
    }
}

// NORMAL USE: try-with-resources, guaranteed and deterministic closing
try (var store = new LoanStore(Path.of("loans.dat"))) {
    store.save("LN-2026-0041;978-0000000001;Marta Ruiz");
}

speedup = 1 / ((1 - p) + p/s)

jps -lvm

14237 com.nexussoftware.bibliotech.BiblioTechApp -Xms2g -Xmx2g -XX:+UseG1GC
14891 jdk.jcmd/sun.tools.jps.Jps -Dapplication.home=/usr/lib/jvm/jdk-21

# GC statistics every second, 10 times
jstat -gcutil 14237 1000 10

  S0     S1     E      O      M     CCS    YGC   YGCT    FGC   FGCT    GCT
  0.00  62.31  41.20  18.44  96.12 92.03    142   1.204     2  0.381   1.585
  0.00  62.31  78.90  18.44  96.12 92.03    142   1.204     2  0.381   1.585
 58.44   0.00  12.03  18.51  96.12 92.03    143   1.213     2  0.381   1.594

# Histogram of live objects, sorted by size
jmap -histo:live 14237 | head -20

 num     #instances         #bytes  class name
----------------------------------------------
   1:        847291       40669968  [B                        (byte[])
   2:        847012       20328288  java.lang.String
   3:        412008       19776384  com.nexussoftware.bibliotech.domain.Loan
   4:        198432        9524736  java.util.HashMap$Node
   5:        412008        6592128  java.time.LocalDate
   6:         98211        4713-28  java.util.ArrayList

# FULL heap dump for analysis with graphical tools
jmap -dump:live,format=b,file=/tmp/bibliotech.hprof 14237

jcmd 14237 help

GC.class_histogram
GC.heap_dump
GC.heap_info
GC.run
JFR.start
JFR.dump
Thread.print
VM.flags
VM.native_memory
VM.system_properties
VM.uptime

jcmd 14237 GC.heap_info
jcmd 14237 Thread.print              # thread dump: deadlocks (08-04)
jcmd 14237 VM.flags                  # effective JVM options
jcmd 14237 GC.class_histogram
jcmd 14237 VM.native_memory summary  # requires -XX:NativeMemoryTracking=summary

Found one Java-level deadlock:
=============================
"client-42":
  waiting to lock monitor 0x00007f... (object 0x000000071ab2, a java.lang.Object),
  which is held by "client-17"
"client-17":
  waiting to lock monitor 0x00007f... (object 0x000000071ab3, a java.lang.Object),
  which is held by "client-42"

jconsole 14237

# At start-up
java -XX:StartFlightRecording=duration=120s,filename=/tmp/bibliotech.jfr \
     -jar bibliotech.jar

# On a running process
jcmd 14237 JFR.start name=diagnostics settings=profile duration=120s \
     filename=/tmp/bibliotech.jfr

jcmd 14237 JFR.check
jcmd 14237 JFR.dump name=diagnostics filename=/tmp/snapshot.jfr
jcmd 14237 JFR.stop name=diagnostics

jfr summary /tmp/bibliotech.jfr

 Event Type                        Count    Size (bytes)
=========================================================
 jdk.ObjectAllocationSample        18421         589472
 jdk.ExecutionSample                9204         294528
 jdk.GCPhasePause                    412          13184
 jdk.JavaMonitorEnter                287          14924
 jdk.SocketRead                      194           9312
 jdk.ThreadPark                      142           5680

# Specific events
jfr print --events GCPhasePause /tmp/bibliotech.jfr | head -30
jfr print --events ObjectAllocationSample /tmp/bibliotech.jfr | head -40
jfr print --events JavaMonitorEnter /tmp/bibliotech.jfr

java -XX:StartFlightRecording=disk=true,maxsize=512m,maxage=12h,\
settings=default,filename=/var/log/bibliotech/recording.jfr \
     -XX:FlightRecorderOptions=repository=/var/log/bibliotech/jfr \
     -jar bibliotech.jar

package com.nexussoftware.bibliotech.diagnostics;

public class MisleadingBenchmark {

    public static void main(String[] args) {

        long start = System.nanoTime();

        for (int i = 0; i < 100_000_000; i++) {
            Math.sqrt(i);                          // we "measure" sqrt
        }

        long ns = System.nanoTime() - start;
        System.out.printf("100 million sqrt in %.2f ms%n", ns / 1_000_000.0);
    }
}

100 million sqrt in 3.41 ms

// The JIT can replace this with  int r = 5050;
int sum = 0;
for (int i = 1; i <= 100; i++) sum += i;

public class LessBadBenchmark {

    /** volatile: stops the JIT removing the computation */
    private static volatile double sink;

    public static void main(String[] args) {
        // 1. WARM-UP
        for (int r = 0; r < 10; r++) {
            measure();
        }
        // 2. Several repetitions, and the MEDIAN (less sensitive to spikes than the mean)
        long[] times = new long[11];
        for (int r = 0; r < times.length; r++) {
            times[r] = measure();
        }
        java.util.Arrays.sort(times);
        System.out.printf("Median: %.2f ms%n", times[times.length / 2] / 1_000_000.0);
    }

    private static long measure() {
        long start = System.nanoTime();
        double accumulated = 0;
        for (int i = 0; i < 100_000_000; i++) {
            accumulated += Math.sqrt(i);
        }
        sink = accumulated;          // consume the result
        return System.nanoTime() - start;
    }
}

Median: 312.47 ms

package com.nexussoftware.bibliotech.benchmark;

import org.openjdk.jmh.annotations.*;
import org.openjdk.jmh.infra.Blackhole;

import java.util.*;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;
import java.util.stream.IntStream;

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MICROSECONDS)
@State(Scope.Benchmark)
@Warmup(iterations = 5, time = 1)
@Measurement(iterations = 10, time = 1)
@Fork(2)
public class BiblioTechBenchmark {

    @Param({"100", "10000", "1000000"})
    private int size;

    private List<Book> catalog;

    @Setup
    public void prepare() {
        catalog = IntStream.range(0, size)
                .mapToObj(i -> new Book(String.format("978-%010d", i),
                                        "Title " + i, "Author " + (i % 100),
                                        200 + (i % 400), 3.0 + (i % 20) / 10.0))
                .collect(Collectors.toCollection(ArrayList::new));
    }

    @Benchmark
    public long withLoop() {
        long total = 0;
        for (Book b : catalog) {
            if (b.getPages() > 400) {
                total += b.getPages();
            }
        }
        return total;
    }

    @Benchmark
    public long withStream() {
        return catalog.stream()
                .filter(b -> b.getPages() > 400)
                .mapToLong(Book::getPages)
                .sum();
    }

    @Benchmark
    public long withParallelStream() {
        return catalog.parallelStream()
                .filter(b -> b.getPages() > 400)
                .mapToLong(Book::getPages)
                .sum();
    }

    /** Blackhole: consumes the value so the JIT cannot remove it. */
    @Benchmark
    public void grouping(Blackhole bh) {
        bh.consume(catalog.stream()
                .collect(Collectors.groupingBy(Book::getAuthor, Collectors.counting())));
    }
}

mvn clean package
java -jar target/benchmarks.jar BiblioTechBenchmark -prof gc

Benchmark                          (size)  Mode  Cnt      Score      Error  Units
BiblioTechBenchmark.withLoop          100  avgt   20      0.082 ±    0.003  us/op
BiblioTechBenchmark.withLoop        10000  avgt   20      8.914 ±    0.142  us/op
BiblioTechBenchmark.withLoop      1000000  avgt   20   1102.412 ±   28.331  us/op
BiblioTechBenchmark.withStream        100  avgt   20      0.341 ±    0.012  us/op
BiblioTechBenchmark.withStream      10000  avgt   20     11.208 ±    0.201  us/op
BiblioTechBenchmark.withStream    1000000  avgt   20   1284.904 ±   31.204  us/op
BiblioTechBenchmark.withParallelStream 100 avgt   20     12.041 ±    1.412  us/op
BiblioTechBenchmark.withParallelStream 10000 avgt 20     28.114 ±    2.031  us/op
BiblioTechBenchmark.withParallelStream 1000000 avgt 20  241.882 ±   18.442  us/op

Benchmark                          (size)  Mode  Cnt      Score  Units
withStream:gc.alloc.rate.norm       10000  avgt   20    128.004  B/op
withLoop:gc.alloc.rate.norm         10000  avgt   20      0.001  B/op

java -XX:+PrintCompilation -jar bibliotech.jar 2>&1 | head -20

    112    1       3       java.lang.String::hashCode (49 bytes)
    118    2       3       java.util.HashMap::hash (20 bytes)
    134    5       4       java.lang.String::equals (65 bytes)
    891   142       4       com...LoanManager::lend (218 bytes)
   1204   198       3       com...BiblioTechStatistics::countByType (94 bytes)
   2841   142       4       com...LoanManager::lend (218 bytes)   made not entrant

// You write
public int totalPages(List<Book> books) {
    int total = 0;
    for (Book b : books) {
        total += b.getPages();       // a call to a getter
    }
    return total;
}

// The JIT inlines getPages() and generates something equivalent to
for (Book b : books) {
    total += b.pages;                // direct field access
}

public double distance(int x1, int y1, int x2, int y2) {
    Point a = new Point(x1, y1);      // does not escape
    Point b = new Point(x2, y2);      // does not escape
    return Math.hypot(a.x() - b.x(), a.y() - b.y());
}
// The JIT may NOT CREATE the two objects: zero heap allocation

// O(n·m): for every material, walk ALL the loans
for (Material m : materials) {                        // n = 10,000
    for (Loan l : loans) {                            // m = 50,000
        if (l.getIsbn().equals(m.getIsbn())) { ... }
    }
}
// 500,000,000 comparisons

// O(n+m): index first
Map<String, Loan> byIsbn = loans.stream()
        .collect(Collectors.toMap(Loan::getIsbn, l -> l, (a, b) -> a));

for (Material m : materials) {
    Loan l = byIsbn.get(m.getIsbn());                 // O(1)
}
// 60,000 operations: 8,000 times fewer

// BAD: it compiles the regular expression on EVERY call
public boolean isValidIsbn(String isbn) {
    return isbn.matches("978-\\d{10}");     // an internal Pattern.compile each time
}

// GOOD: compiled once
private static final Pattern ISBN = Pattern.compile("978-\\d{10}");

public boolean isValidIsbn(String isbn) {
    return ISBN.matcher(isbn).matches();
}

// BAD: a query inside the loop
for (Loan l : loans) {
    Material m = catalog.queryDatabase(l.getIsbn());              // N queries
}

// GOOD: one batch query
Map<String, Material> materials = catalog.queryBatch(
        loans.stream().map(Loan::getIsbn).distinct().toList());

public class BiblioTechServices {

    // Immutable and thread-safe: ONE per application (10-05, 09-06)
    private static final DateTimeFormatter ISO = DateTimeFormatter.ISO_LOCAL_DATE;
    private static final Pattern ISBN = Pattern.compile("978-\\d{10}");
    private static final HttpClient HTTP = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5)).build();
}

// BAD: quadratic. Each + creates a new String, copying everything
String report = "";
for (Loan l : loans) {
    report += l.getId() + ";" + l.getEmployee() + "\n";
}

// GOOD: linear
StringBuilder sb = new StringBuilder(loans.size() * 48);
for (Loan l : loans) {
    sb.append(l.getId()).append(';').append(l.getEmployee()).append('\n');
}
String report = sb.toString();

// EVEN BETTER if it fits: streams (10-04)
String report = loans.stream()
        .map(l -> l.getId() + ";" + l.getEmployee())
        .collect(Collectors.joining("\n"));

// BAD: 10 million Long objects
Long sum = 0L;
for (int i = 0; i < 10_000_000; i++) {
    sum += i;                           // unbox, add, BOX
}

// GOOD: zero objects
long sum = 0L;
for (int i = 0; i < 10_000_000; i++) {
    sum += i;
}

// And in streams
int total = catalog.stream().mapToInt(Book::getPages).sum();       // IntStream

// Resizes ~14 times on the way to 10,000, copying each time
List<Loan> list = new ArrayList<>();

// A single allocation
List<Loan> list = new ArrayList<>(10_000);

// HashMap: capacity / load factor, so it does not rehash
Map<String, Loan> map = new HashMap<>((int) (10_000 / 0.75f) + 1);

public class StringPool {

    public static void main(String[] args) {

        String a = "Effective Java";                         // literal: to the POOL
        String b = "Effective Java";                         // the SAME pooled object
        String c = new String("Effective Java");             // a NEW object on the heap
        String d = c.intern();                               // looks it up in the pool

        System.out.println("a == b: " + (a == b));           // true
        System.out.println("a == c: " + (a == c));           // false
        System.out.println("a == d: " + (a == d));           // true
        System.out.println("a.equals(c): " + a.equals(c));   // true

        // COMPILE-TIME concatenation: it is a literal
        String e = "Effective " + "Java";
        System.out.println("a == e: " + (a == e));           // true

        // RUNTIME concatenation: a new object
        String part = "Effective ";
        String f = part + "Java";
        System.out.println("a == f: " + (a == f));           // false
    }
}

a == b: true
a == c: false
a == d: true
a.equals(c): true
a == e: true
a == f: false

package com.nexussoftware.bibliotech.benchmark;

import org.openjdk.jmh.annotations.*;
import java.util.concurrent.TimeUnit;

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MICROSECONDS)
@State(Scope.Benchmark)
@Warmup(iterations = 5) @Measurement(iterations = 10) @Fork(2)
public class StringBenchmark {

    @Param({"10", "100", "1000", "10000"})
    private int n;

    @Benchmark
    public String concatWithPlus() {
        String result = "";
        for (int i = 0; i < n; i++) {
            result += "LN-2026-" + i + ";";           // QUADRATIC
        }
        return result;
    }

    @Benchmark
    public String withStringBuilder() {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < n; i++) {
            sb.append("LN-2026-").append(i).append(';');
        }
        return sb.toString();
    }

    @Benchmark
    public String withSizedStringBuilder() {
        StringBuilder sb = new StringBuilder(n * 16);   // estimated capacity
        for (int i = 0; i < n; i++) {
            sb.append("LN-2026-").append(i).append(';');
        }
        return sb.toString();
    }
}

Benchmark                                   (n)  Mode  Cnt        Score      Error  Units
StringBenchmark.concatWithPlus               10  avgt   20        0.412 ±    0.011  us/op
StringBenchmark.concatWithPlus              100  avgt   20        8.204 ±    0.204  us/op
StringBenchmark.concatWithPlus             1000  avgt   20      512.891 ±   14.201  us/op
StringBenchmark.concatWithPlus            10000  avgt   20    48204.112 ± 1204.441  us/op
StringBenchmark.withStringBuilder            10  avgt   20        0.198 ±    0.008  us/op
StringBenchmark.withStringBuilder           100  avgt   20        1.412 ±    0.041  us/op
StringBenchmark.withStringBuilder          1000  avgt   20       14.208 ±    0.312  us/op
StringBenchmark.withStringBuilder         10000  avgt   20      148.904 ±    3.204  us/op
StringBenchmark.withSizedStringBuilder    10000  avgt   20      104.412 ±    2.118  us/op

StringBenchmark.concatWithPlus:gc.alloc.rate.norm     10000  avgt  20  512048912.0  B/op
StringBenchmark.withStringBuilder:gc.alloc.rate.norm  10000  avgt  20     524312.0  B/op

package com.nexussoftware.bibliotech.diagnostics;

import java.util.*;
import java.util.function.Consumer;

/**
 * Reproduces the four classic leak patterns and their fixes.
 * This is NOT production code: it is a teaching laboratory.
 */
public class LeakLab {

    // ==================================================================
    // LEAK 1: a collection that grows without limit
    // ==================================================================

    static class LeakyCache {
        // static + never cleared = a GC root that retains everything
        private static final Map<String, byte[]> CACHE = new HashMap<>();

        static void use(String key) {
            CACHE.computeIfAbsent(key, k -> new byte[10 * 1024]);      // 10 KB
        }
        static int size()  { return CACHE.size(); }
        static void clear() { CACHE.clear(); }
    }

    static class BoundedCache {
        private static final int CAPACITY = 500;

        private static final Map<String, byte[]> CACHE =
                new LinkedHashMap<>(CAPACITY, 0.75f, true) {
                    @Override
                    protected boolean removeEldestEntry(Map.Entry<String, byte[]> e) {
                        return size() > CAPACITY;
                    }
                };

        static void use(String key) {
            CACHE.computeIfAbsent(key, k -> new byte[10 * 1024]);
        }
        static int size()  { return CACHE.size(); }
        static void clear() { CACHE.clear(); }
    }

    // ==================================================================
    // LEAK 2: listeners that are never unsubscribed
    // ==================================================================

    static class EventManager {
        private static final List<Consumer<String>> SUBSCRIBERS = new ArrayList<>();

        static void subscribe(Consumer<String> s)   { SUBSCRIBERS.add(s); }
        static void unsubscribe(Consumer<String> s) { SUBSCRIBERS.remove(s); }
        static int howMany()                        { return SUBSCRIBERS.size(); }
        static void clear()                         { SUBSCRIBERS.clear(); }
    }

    /** LEAK: it subscribes with a lambda capturing this and never unsubscribes. */
    static class LeakyWindow {
        private final byte[] heavyData = new byte[100 * 1024];      // 100 KB

        LeakyWindow() {
            EventManager.subscribe(event -> handle(event));         // captures this
        }
        private void handle(String e) { /* uses heavyData */ }
    }

    /** CORRECT: it keeps the reference and offers close(). */
    static class CorrectWindow implements AutoCloseable {
        private final byte[] heavyData = new byte[100 * 1024];
        private final Consumer<String> subscriber;

        CorrectWindow() {
            this.subscriber = this::handle;
            EventManager.subscribe(subscriber);
        }
        private void handle(String e) { }

        @Override public void close() { EventManager.unsubscribe(subscriber); }
    }

    // ==================================================================
    // LEAK 3: ThreadLocal in a pool
    // ==================================================================

    static class LeakyContext {
        private static final ThreadLocal<byte[]> CONTEXT = new ThreadLocal<>();

        static void process() {
            CONTEXT.set(new byte[500 * 1024]);       // 500 KB
            // no remove(): the pool thread retains it forever
        }
    }

    static class CorrectContext {
        private static final ThreadLocal<byte[]> CONTEXT = new ThreadLocal<>();

        static void process() {
            CONTEXT.set(new byte[500 * 1024]);
            try {
                // real work
            } finally {
                CONTEXT.remove();                     // MANDATORY
            }
        }
    }

    // ==================================================================
    // LEAK 4: a non-static inner class
    // ==================================================================

    static class HeavyCatalog {
        private final byte[] materials = new byte[2 * 1024 * 1024];    // 2 MB

        /** NOT static: it retains HeavyCatalog.this */
        class LeakyCounter {
            private int count;
            void increment() { count++; }
        }

        /** static: it retains nothing from the outer class */
        static class CorrectCounter {
            private int count;
            void increment() { count++; }
        }

        LeakyCounter createLeaky()             { return new LeakyCounter(); }
        static CorrectCounter createCorrect()  { return new CorrectCounter(); }
    }

    // ==================================================================
    // MONITOR
    // ==================================================================

    /**
     * Measures RETAINED memory (after a GC), not used memory.
     *
     * Here System.gc() IS justified: this is a diagnostic tool,
     * not production code, and we need to know how much memory
     * survives a collection.
     */
    static class MemoryMonitor {

        private final List<Long> samples = new ArrayList<>();
        private final String name;

        MemoryMonitor(String name) { this.name = name; }

        long sample() {
            System.gc();
            try { Thread.sleep(120); } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
            Runtime rt = Runtime.getRuntime();
            long used = (rt.totalMemory() - rt.freeMemory()) / 1024 / 1024;
            samples.add(used);
            return used;
        }

        /** Monotonic growth in at least 80 % of the intervals = a leak. */
        boolean detectsLeak() {
            if (samples.size() < 4) {
                return false;
            }
            int growing = 0;
            for (int i = 1; i < samples.size(); i++) {
                if (samples.get(i) > samples.get(i - 1)) {
                    growing++;
                }
            }
            double ratio = (double) growing / (samples.size() - 1);
            long delta = samples.get(samples.size() - 1) - samples.get(0);
            return ratio >= 0.8 && delta > 5;          // a 5 MB threshold
        }

        String verdict() {
            long first = samples.get(0);
            long last = samples.get(samples.size() - 1);
            return String.format("%-26s %4d MB -> %4d MB  (Δ %+4d MB)  %s",
                    name, first, last, last - first,
                    detectsLeak() ? "*** LEAK DETECTED ***" : "stable");
        }
    }

    // ==================================================================

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

        System.out.println("Maximum heap: "
                + Runtime.getRuntime().maxMemory() / 1024 / 1024 + " MB");
        System.out.println("Run with: java -Xmx512m LeakLab");
        System.out.println("=".repeat(74));

        testLeak1();
        testLeak2();
        testLeak3();
        testLeak4();

        System.out.println("=".repeat(74));
        System.out.println("""

                DIAGNOSIS WITH REAL TOOLS
                ─────────────────────────
                1. Locate the process:
                     jps -lvm

                2. Check whether the old generation grows without falling (column O):
                     jstat -gcutil <PID> 1000 30

                3. Histogram of live objects, twice a few minutes apart:
                     jcmd <PID> GC.class_histogram | head -20
                   The class whose count keeps growing is the suspect.

                4. Full dump for analysis:
                     jcmd <PID> GC.heap_dump /tmp/bibliotech.hprof

                5. Open the .hprof with Eclipse MAT:
                     - "Leak Suspects Report" names the culprit in 80 % of cases
                     - Sort by "Retained Heap": how much each object would free
                     - "Path to GC Roots" on the suspect: WHO is retaining it
                       (excluding weak and soft references)
                """);
    }

    private static void testLeak1() {
        System.out.println("\n--- LEAK 1: an unbounded collection ---");

        var monitor = new MemoryMonitor("Unbounded HashMap");
        monitor.sample();
        for (int round = 0; round < 5; round++) {
            for (int i = 0; i < 2_000; i++) {
                LeakyCache.use("isbn-" + round + "-" + i);
            }
            monitor.sample();
        }
        System.out.println(monitor.verdict());
        System.out.println("  Retained entries: " + LeakyCache.size());
        LeakyCache.clear();

        var monitor2 = new MemoryMonitor("Bounded LinkedHashMap");
        monitor2.sample();
        for (int round = 0; round < 5; round++) {
            for (int i = 0; i < 2_000; i++) {
                BoundedCache.use("isbn-" + round + "-" + i);
            }
            monitor2.sample();
        }
        System.out.println(monitor2.verdict());
        System.out.println("  Retained entries: " + BoundedCache.size() + " (cap 500)");
        BoundedCache.clear();
    }

    private static void testLeak2() {
        System.out.println("\n--- LEAK 2: listeners ---");

        var monitor = new MemoryMonitor("Without unsubscribing");
        monitor.sample();
        for (int round = 0; round < 5; round++) {
            for (int i = 0; i < 500; i++) {
                new LeakyWindow();             // created, discarded... and retained
            }
            monitor.sample();
        }
        System.out.println(monitor.verdict());
        System.out.println("  Live subscribers: " + EventManager.howMany());
        EventManager.clear();

        var monitor2 = new MemoryMonitor("With try-with-resources");
        monitor2.sample();
        for (int round = 0; round < 5; round++) {
            for (int i = 0; i < 500; i++) {
                try (var w = new CorrectWindow()) {
                    // use it
                }
            }
            monitor2.sample();
        }
        System.out.println(monitor2.verdict());
        System.out.println("  Live subscribers: " + EventManager.howMany());
    }

    private static void testLeak3() throws Exception {
        System.out.println("\n--- LEAK 3: ThreadLocal in a pool ---");

        var pool = java.util.concurrent.Executors.newFixedThreadPool(50);

        var monitor = new MemoryMonitor("ThreadLocal without remove");
        monitor.sample();
        for (int round = 0; round < 4; round++) {
            var latch = new java.util.concurrent.CountDownLatch(200);
            for (int i = 0; i < 200; i++) {
                pool.submit(() -> { LeakyContext.process(); latch.countDown(); });
            }
            latch.await();
            monitor.sample();
        }
        System.out.println(monitor.verdict());
        System.out.println("  50 threads × 500 KB retained ≈ 25 MB that never get freed");

        var monitor2 = new MemoryMonitor("ThreadLocal with remove");
        monitor2.sample();
        for (int round = 0; round < 4; round++) {
            var latch = new java.util.concurrent.CountDownLatch(200);
            for (int i = 0; i < 200; i++) {
                pool.submit(() -> { CorrectContext.process(); latch.countDown(); });
            }
            latch.await();
            monitor2.sample();
        }
        System.out.println(monitor2.verdict());

        pool.shutdown();
    }

    private static void testLeak4() {
        System.out.println("\n--- LEAK 4: a non-static inner class ---");

        List<Object> counters = new ArrayList<>();

        var monitor = new MemoryMonitor("NON-static inner class");
        monitor.sample();
        for (int round = 0; round < 4; round++) {
            for (int i = 0; i < 20; i++) {
                HeavyCatalog catalog = new HeavyCatalog();          // 2 MB
                counters.add(catalog.createLeaky());                // retains the 2 MB
            }
            monitor.sample();
        }
        System.out.println(monitor.verdict());
        System.out.println("  " + counters.size()
                + " 16-byte counters retaining " + (counters.size() * 2) + " MB");
        counters.clear();

        var monitor2 = new MemoryMonitor("Static inner class");
        monitor2.sample();
        for (int round = 0; round < 4; round++) {
            for (int i = 0; i < 20; i++) {
                HeavyCatalog catalog = new HeavyCatalog();
                counters.add(HeavyCatalog.createCorrect());         // retains nothing
            }
            monitor2.sample();
        }
        System.out.println(monitor2.verdict());
        System.out.println("  " + counters.size()
                + " counters retaining no catalogue at all");
    }
}

Maximum heap: 512 MB
Run with: java -Xmx512m LeakLab
==========================================================================

--- LEAK 1: an unbounded collection ---
Unbounded HashMap            12 MB ->  116 MB  (Δ +104 MB)  *** LEAK DETECTED ***
  Retained entries: 10000
Bounded LinkedHashMap        14 MB ->   19 MB  (Δ   +5 MB)  stable
  Retained entries: 500 (cap 500)

--- LEAK 2: listeners ---
Without unsubscribing        14 MB ->  272 MB  (Δ +258 MB)  *** LEAK DETECTED ***
  Live subscribers: 2500
With try-with-resources      14 MB ->   15 MB  (Δ   +1 MB)  stable
  Live subscribers: 0

--- LEAK 3: ThreadLocal in a pool ---
ThreadLocal without remove   15 MB ->   40 MB  (Δ  +25 MB)  *** LEAK DETECTED ***
  50 threads × 500 KB retained ≈ 25 MB that never get freed
ThreadLocal with remove      15 MB ->   16 MB  (Δ   +1 MB)  stable

--- LEAK 4: a non-static inner class ---
NON-static inner class       16 MB ->  176 MB  (Δ +160 MB)  *** LEAK DETECTED ***
  80 16-byte counters retaining 160 MB
Static inner class           17 MB ->   18 MB  (Δ   +1 MB)  stable
  80 counters retaining no catalogue at all

package com.nexussoftware.bibliotech.diagnostics;

import com.nexussoftware.bibliotech.domain.Card;

import java.util.*;
import java.util.function.Function;

/**
 * Comparison of three cache strategies.
 *
 * WARNING: a HOMEMADE measurement. The timings are indicative.
 * See the closing note about JMH.
 */
public class CacheComparison {

    /** Common contract. */
    interface Cache {
        Card get(String isbn, Function<String, Card> computation);
        int size();
        long hits();
        long misses();
        String name();

        default double hitRate() {
            long total = hits() + misses();
            return total == 0 ? 0 : hits() * 100.0 / total;
        }
    }

    /** STRATEGY 1: unbounded. This is the leak from section 12. */
    static class UnboundedCache implements Cache {
        private final Map<String, Card> map = new HashMap<>();
        private long hits, misses;

        public Card get(String isbn, Function<String, Card> computation) {
            Card c = map.get(isbn);
            if (c != null) { hits++; return c; }
            misses++;
            c = computation.apply(isbn);
            map.put(isbn, c);
            return c;
        }
        public int size()     { return map.size(); }
        public long hits()    { return hits; }
        public long misses()  { return misses; }
        public String name()  { return "Unbounded HashMap"; }
    }

    /** STRATEGY 2: bounded LRU. */
    static class LruCache implements Cache {
        private final int capacity;
        private final LinkedHashMap<String, Card> map;
        private long hits, misses;

        LruCache(int capacity) {
            this.capacity = capacity;
            this.map = new LinkedHashMap<>(capacity, 0.75f, true) {
                @Override protected boolean removeEldestEntry(Map.Entry<String, Card> e) {
                    return size() > LruCache.this.capacity;
                }
            };
        }
        public Card get(String isbn, Function<String, Card> computation) {
            Card c = map.get(isbn);
            if (c != null) { hits++; return c; }
            misses++;
            c = computation.apply(isbn);
            map.put(isbn, c);
            return c;
        }
        public int size()     { return map.size(); }
        public long hits()    { return hits; }
        public long misses()  { return misses; }
        public String name()  { return "LRU (" + capacity + ")"; }
    }

    /**
     * STRATEGY 3: weak keys.
     *
     * CAREFUL: the keys are Strings. If they came from the interned
     * pool they would NEVER be collected. Here they are built
     * dynamically, so they are indeed eligible.
     */
    static class WeakCache implements Cache {
        private final Map<String, Card> map = new WeakHashMap<>();
        private long hits, misses;

        public Card get(String isbn, Function<String, Card> computation) {
            Card c = map.get(isbn);
            if (c != null) { hits++; return c; }
            misses++;
            c = computation.apply(isbn);
            map.put(isbn, c);
            return c;
        }
        public int size()     { return map.size(); }
        public long hits()    { return hits; }
        public long misses()  { return misses; }
        public String name()  { return "WeakHashMap"; }
    }

    // ------------------------------------------------------------------

    private static final int ACCESSES = 100_000;
    private static final int DISTINCT_ISBNS = 20_000;
    private static final int HOT = DISTINCT_ISBNS / 5;          // the 20 %

    /** Simulated expensive computation. */
    private static Card compute(String isbn) {
        double accumulated = 0;
        for (int i = 1; i <= 2_000; i++) {
            accumulated += Math.sqrt(i);
        }
        return new Card(isbn, "Card " + isbn + " (" + (long) accumulated + ")", true);
    }

    /** An 80/20 distribution: 80 % of the accesses over 20 % of the keys. */
    private static List<String> generateAccesses(Random random) {
        List<String> accesses = new ArrayList<>(ACCESSES);
        for (int i = 0; i < ACCESSES; i++) {
            int index = random.nextInt(100) < 80
                    ? random.nextInt(HOT)
                    : HOT + random.nextInt(DISTINCT_ISBNS - HOT);
            accesses.add(String.format("978-%010d", index));
        }
        return accesses;
    }

    record Result(String name, double hitRate, long memoryMb,
                  long ms, int entries, int survivors) { }

    private static Result measure(Cache cache, List<String> accesses) throws Exception {

        long memoryBefore = retainedMemory();
        long start = System.nanoTime();

        for (String isbn : accesses) {
            cache.get(isbn, CacheComparison::compute);
        }

        long ms = (System.nanoTime() - start) / 1_000_000;
        long memoryAfter = retainedMemory();
        int entries = cache.size();

        // Memory pressure: allocate and release to force aggressive collections
        try {
            List<byte[]> pressure = new ArrayList<>();
            for (int i = 0; i < 200; i++) {
                pressure.add(new byte[1024 * 1024]);
            }
            pressure.clear();
        } catch (OutOfMemoryError e) {
            // expected: it is what we are after
        }
        retainedMemory();
        int survivors = cache.size();

        return new Result(cache.name(), cache.hitRate(),
                Math.max(0, memoryAfter - memoryBefore), ms, entries, survivors);
    }

    private static long retainedMemory() throws InterruptedException {
        System.gc();
        Thread.sleep(150);
        Runtime rt = Runtime.getRuntime();
        return (rt.totalMemory() - rt.freeMemory()) / 1024 / 1024;
    }

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

        Random random = new Random(42);               // fixed seed: reproducible
        List<String> accesses = generateAccesses(random);

        System.out.printf("""
                Accesses: %,d over %,d distinct ISBNs (80/20 distribution)
                Maximum heap: %d MB
                """, ACCESSES, DISTINCT_ISBNS,
                Runtime.getRuntime().maxMemory() / 1024 / 1024);

        List<Result> results = new ArrayList<>();
        results.add(measure(new UnboundedCache(), accesses));
        results.add(measure(new LruCache(HOT), accesses));
        results.add(measure(new LruCache(1_000), accesses));
        results.add(measure(new WeakCache(), accesses));

        System.out.printf("%n%-22s %9s %9s %8s %10s %14s%n",
                "STRATEGY", "HITS", "MEMORY", "TIME", "ENTRIES", "AFTER PRESSURE");
        System.out.println("-".repeat(78));

        results.forEach(r -> System.out.printf("%-22s %8.1f%% %7d MB %6d ms %10d %14d%n",
                r.name(), r.hitRate(), r.memoryMb(), r.ms(),
                r.entries(), r.survivors()));

        System.out.println("""

                RECOMMENDATION
                ──────────────
                • Unbounded HashMap: the highest hit rate and the worst decision.
                  It retains EVERY entry indefinitely: it is leak 1 from
                  section 12. Only acceptable if the number of keys is bounded
                  by design (an enum, a fixed configuration list).

                • An LRU sized to the hot set: the best trade-off.
                  With an 80/20 distribution, an LRU the size of the hot 20 %
                  captures almost all the hits with a fraction of the memory.
                  IT IS THE DEFAULT CHOICE.

                • An undersized LRU: the hit rate collapses because the hot
                  entries evict one another (thrashing). Sizing a cache below
                  the working set is worse than not having one at all.

                • WeakHashMap: self-regulating memory, but UNPREDICTABLE
                  behaviour: entries vanish whenever the GC decides.
                  Its real use case is not "a bounded cache" but "metadata
                  associated with live objects I do not control" (section 14).

                ABOUT THIS MEASUREMENT
                ──────────────────────
                It is HOMEMADE and its numbers are indicative:
                  - There is not enough warm-up: the first strategies measured
                    pay for the JIT compilation of compute().
                  - System.gc() is a suggestion: the "retained" memory is
                    approximate.
                  - There are no repetitions and no confidence intervals.
                  - The order of execution matters (the first cache leaves the
                    heap in a different state for the next one).

                To measure properly: JMH with @State(Scope.Benchmark),
                @Setup(Level.Iteration) recreating the cache, @Fork(3) to isolate
                processes and -prof gc for allocation normalised per operation.
                """);
    }
}

Accesses: 100,000 over 20,000 distinct ISBNs (80/20 distribution)
Maximum heap: 512 MB

STRATEGY                    HITS    MEMORY     TIME    ENTRIES AFTER PRESSURE
------------------------------------------------------------------------------
Unbounded HashMap          80.0%      12 MB    412 ms      20000          20000
LRU (4000)                 79.4%       3 MB    438 ms       4000           4000
LRU (1000)                 61.2%       1 MB    891 ms       1000           1000
WeakHashMap                79.8%       9 MB    467 ms      19884              0

RECOMMENDATION
──────────────
• Unbounded HashMap: the highest hit rate and the worst decision.
  ...

package com.nexussoftware.bibliotech.diagnostics;

import java.lang.management.*;
import java.time.Duration;
import java.util.*;
import java.util.stream.Collectors;

/**
 * BiblioTech performance self-diagnosis.
 * It uses only the JDK management API: no external dependencies.
 */
public class PerformanceReport {

    // --- Report sections as a sealed type (10-06) ---

    public sealed interface Section {

        record Memory(long heapUsedMb, long heapMaxMb, long heapCommittedMb,
                      long nonHeapUsedMb, List<Pool> pools) implements Section { }

        record Pool(String name, String type, long usedMb, long maxMb) { }

        record Collection(List<GcStat> collectors, long totalTimeMs,
                          long uptimeMs) implements Section { }

        record GcStat(String name, long collections, long timeMs) { }

        record Threads(int live, int daemons, int peak, long totalStarted,
                       List<String> deadlocks) implements Section { }

        record Classes(long loaded, long totalLoaded, long unloaded) implements Section { }

        record Compilation(String compiler, long timeMs) implements Section { }
    }

    public enum Health { GREEN, AMBER, RED }

    // ------------------------------------------------------------------

    public Section.Memory collectMemory() {
        MemoryMXBean memory = ManagementFactory.getMemoryMXBean();
        MemoryUsage heap = memory.getHeapMemoryUsage();
        MemoryUsage nonHeap = memory.getNonHeapMemoryUsage();

        List<Section.Pool> pools = ManagementFactory.getMemoryPoolMXBeans().stream()
                .map(p -> new Section.Pool(
                        p.getName(),
                        p.getType().toString(),
                        p.getUsage().getUsed() / 1024 / 1024,
                        p.getUsage().getMax() < 0 ? -1 : p.getUsage().getMax() / 1024 / 1024))
                .toList();

        return new Section.Memory(
                heap.getUsed() / 1024 / 1024,
                heap.getMax() / 1024 / 1024,
                heap.getCommitted() / 1024 / 1024,
                nonHeap.getUsed() / 1024 / 1024,
                pools);
    }

    public Section.Collection collectGc() {
        List<Section.GcStat> collectors =
                ManagementFactory.getGarbageCollectorMXBeans().stream()
                        .map(gc -> new Section.GcStat(
                                gc.getName(), gc.getCollectionCount(), gc.getCollectionTime()))
                        .toList();

        long total = collectors.stream()
                .mapToLong(Section.GcStat::timeMs).sum();

        return new Section.Collection(collectors, total,
                ManagementFactory.getRuntimeMXBean().getUptime());
    }

    public Section.Threads collectThreads() {
        ThreadMXBean threads = ManagementFactory.getThreadMXBean();

        List<String> deadlocks = new ArrayList<>();
        long[] blocked = threads.findDeadlockedThreads();
        if (blocked != null) {
            for (ThreadInfo info : threads.getThreadInfo(blocked, true, true)) {
                deadlocks.add(String.format("%s (id %d) blocked on %s, held by %s",
                        info.getThreadName(), info.getThreadId(),
                        info.getLockName(), info.getLockOwnerName()));
            }
        }

        return new Section.Threads(
                threads.getThreadCount(), threads.getDaemonThreadCount(),
                threads.getPeakThreadCount(), threads.getTotalStartedThreadCount(),
                deadlocks);
    }

    public Section.Classes collectClasses() {
        ClassLoadingMXBean classes = ManagementFactory.getClassLoadingMXBean();
        return new Section.Classes(classes.getLoadedClassCount(),
                classes.getTotalLoadedClassCount(), classes.getUnloadedClassCount());
    }

    public Section.Compilation collectCompilation() {
        CompilationMXBean jit = ManagementFactory.getCompilationMXBean();
        if (jit == null) {
            return new Section.Compilation("(not available)", 0);
        }
        return new Section.Compilation(jit.getName(),
                jit.isCompilationTimeMonitoringSupported() ? jit.getTotalCompilationTime() : -1);
    }

    // ------------------------------------------------------------------

    /** Health indicator with justified rules, via an exhaustive switch. */
    public Health assess(Section section) {
        return switch (section) {

            // Rule: above 90 % of the heap after a GC, a real risk of OOM
            case Section.Memory(var used, var max, var committed, var nonHeap, var pools) -> {
                double usage = max <= 0 ? 0 : used * 100.0 / max;
                yield usage > 90 ? Health.RED : usage > 75 ? Health.AMBER : Health.GREEN;
            }

            // Rule: more than 10 % of uptime in GC indicates a serious problem
            case Section.Collection(var collectors, var totalMs, var uptimeMs) -> {
                double percentage = uptimeMs == 0 ? 0 : totalMs * 100.0 / uptimeMs;
                yield percentage > 10 ? Health.RED : percentage > 5 ? Health.AMBER : Health.GREEN;
            }

            // Rule: a deadlock is ALWAYS red
            case Section.Threads(var live, var daemons, var peak, var started, var locks) -> {
                if (!locks.isEmpty()) yield Health.RED;
                yield live > 1_000 ? Health.AMBER : Health.GREEN;
            }

            // Rule: many classes loaded and none unloaded suggests a metaspace leak
            case Section.Classes(var loaded, var total, var unloaded) ->
                    loaded > 50_000 ? Health.AMBER : Health.GREEN;

            // A high JIT time is only informational
            case Section.Compilation c -> Health.GREEN;
        };
    }

    private String icon(Health h) {
        return switch (h) {
            case GREEN -> "[ OK ]";
            case AMBER -> "[WARN]";
            case RED   -> "[FAIL]";
        };
    }

    // ------------------------------------------------------------------

    public String generate() {
        var memory = collectMemory();
        var gc = collectGc();
        var threads = collectThreads();
        var classes = collectClasses();
        var jit = collectCompilation();

        RuntimeMXBean runtime = ManagementFactory.getRuntimeMXBean();
        OperatingSystemMXBean os = ManagementFactory.getOperatingSystemMXBean();

        StringBuilder sb = new StringBuilder();

        sb.append("""
                ══════════════════════════════════════════════════════════
                  PERFORMANCE REPORT -- BiblioTech
                ══════════════════════════════════════════════════════════
                  JVM:        %s %s
                  Vendor:     %s
                  System:     %s %s (%d processors)
                  Uptime:     %s
                  PID:        %d
                """.formatted(
                        runtime.getVmName(), runtime.getVmVersion(), runtime.getVmVendor(),
                        os.getName(), os.getArch(), os.getAvailableProcessors(),
                        formatDuration(runtime.getUptime()),
                        ProcessHandle.current().pid()));

        // --- MEMORY ---
        sb.append("\n%s MEMORY%n".formatted(icon(assess(memory))));
        sb.append("  Heap:     %,d MB used / %,d MB committed / %,d MB maximum (%.1f %%)%n"
                .formatted(memory.heapUsedMb(), memory.heapCommittedMb(),
                           memory.heapMaxMb(),
                           memory.heapMaxMb() <= 0 ? 0
                                   : memory.heapUsedMb() * 100.0 / memory.heapMaxMb()));
        sb.append("  Non-heap: %,d MB (metaspace, code cache)%n"
                .formatted(memory.nonHeapUsedMb()));
        sb.append("  Regions:%n");
        memory.pools().forEach(p -> sb.append("    %-28s %6d MB%s%n".formatted(
                p.name(), p.usedMb(), p.maxMb() < 0 ? "" : " / " + p.maxMb() + " MB")));

        // --- GC ---
        double gcPercentage = gc.uptimeMs() == 0 ? 0
                : gc.totalTimeMs() * 100.0 / gc.uptimeMs();
        sb.append("\n%s GARBAGE COLLECTION%n".formatted(icon(assess(gc))));
        gc.collectors().forEach(c -> sb.append(
                "  %-28s %,8d collections  %,8d ms  (mean %.1f ms)%n".formatted(
                        c.name(), c.collections(), c.timeMs(),
                        c.collections() == 0 ? 0.0 : (double) c.timeMs() / c.collections())));
        sb.append("  Total in GC: %,d ms out of %,d ms of uptime (%.2f %%)%n"
                .formatted(gc.totalTimeMs(), gc.uptimeMs(), gcPercentage));

        // --- THREADS ---
        sb.append("\n%s THREADS%n".formatted(icon(assess(threads))));
        sb.append("  Live: %d (%d daemons)   Peak: %d   Total started: %,d%n"
                .formatted(threads.live(), threads.daemons(), threads.peak(), threads.totalStarted()));
        if (threads.deadlocks().isEmpty()) {
            sb.append("  No deadlocks detected%n".formatted());
        } else {
            sb.append("  *** DEADLOCK DETECTED ***%n".formatted());
            threads.deadlocks().forEach(d -> sb.append("    ").append(d).append('\n'));
        }

        // --- CLASSES AND JIT ---
        sb.append("\n%s CLASSES%n".formatted(icon(assess(classes))));
        sb.append("  Loaded now: %,d   Historical total: %,d   Unloaded: %,d%n"
                .formatted(classes.loaded(), classes.totalLoaded(), classes.unloaded()));

        sb.append("\n%s JIT COMPILATION%n".formatted(icon(assess(jit))));
        sb.append("  Compiler: %s   Total time: %,d ms%n"
                .formatted(jit.compiler(), jit.timeMs()));

        // --- OPTIONS ---
        sb.append("\n  JVM OPTIONS%n".formatted());
        runtime.getInputArguments().forEach(a -> sb.append("    ").append(a).append('\n'));

        sb.append("""

                ──────────────────────────────────────────────────────────
                  NEXT STEP IF ANYTHING IS ON WARN OR FAIL
                    jstat -gcutil %d 1000 30       (is column O growing?)
                    jcmd %d GC.class_histogram     (which class is growing?)
                    jcmd %d Thread.print           (deadlocks and stacks)
                    jcmd %d JFR.start settings=profile duration=120s \\
                         filename=/tmp/bibliotech.jfr
                ══════════════════════════════════════════════════════════
                """.formatted(ProcessHandle.current().pid(), ProcessHandle.current().pid(),
                              ProcessHandle.current().pid(), ProcessHandle.current().pid()));

        return sb.toString();
    }

    private String formatDuration(long ms) {
        Duration d = Duration.ofMillis(ms);
        return "%dd %02dh %02dm %02ds".formatted(
                d.toDays(), d.toHoursPart(), d.toMinutesPart(), d.toSecondsPart());
    }

    /** Starts a JFR recording on this very process. */
    public void recordJfr(String file, int seconds) throws Exception {
        long pid = ProcessHandle.current().pid();
        var process = new ProcessBuilder("jcmd", String.valueOf(pid),
                "JFR.start", "name=bibliotech", "settings=profile",
                "duration=" + seconds + "s", "filename=" + file)
                .inheritIO().start();
        process.waitFor();
        System.out.println("JFR recording started: " + file);
    }

    public static void main(String[] args) throws Exception {
        PerformanceReport report = new PerformanceReport();

        // Generate some load so the figures are not all zero
        List<byte[]> garbage = new ArrayList<>();
        for (int i = 0; i < 500; i++) {
            garbage.add(new byte[512 * 1024]);
            if (i % 50 == 0) garbage.clear();
        }
        garbage.clear();

        System.out.println(report.generate());
    }
}

══════════════════════════════════════════════════════════
  PERFORMANCE REPORT -- BiblioTech
══════════════════════════════════════════════════════════
  JVM:        OpenJDK 64-Bit Server VM 21.0.1+12
  Vendor:     Eclipse Adoptium
  System:     Linux amd64 (8 processors)
  Uptime:     0d 00h 00m 02s
  PID:        18492

[ OK ] MEMORY
  Heap:     41 MB used / 258 MB committed / 4,096 MB maximum (1.0 %)
  Non-heap: 22 MB (metaspace, code cache)
  Regions:
    CodeHeap 'non-nmethods'             1 MB / 5 MB
    Metaspace                          14 MB
    CodeHeap 'profiled nmethods'        3 MB / 117 MB
    Compressed Class Space              1 MB / 1024 MB
    G1 Eden Space                      28 MB
    G1 Old Gen                         12 MB / 4096 MB
    G1 Survivor Space                   1 MB
    CodeHeap 'non-profiled nmethods'    1 MB / 117 MB

[ OK ] GARBAGE COLLECTION
  G1 Young Generation                   12 collections        41 ms  (mean 3.4 ms)
  G1 Old Generation                      0 collections         0 ms  (mean 0.0 ms)
  Total in GC: 41 ms out of 2,104 ms of uptime (1.95 %)

[ OK ] THREADS
  Live: 11 (9 daemons)   Peak: 11   Total started: 12
  No deadlocks detected

[ OK ] CLASSES
  Loaded now: 1,284   Historical total: 1,284   Unloaded: 0

[ OK ] JIT COMPILATION
  Compiler: HotSpot 64-Bit Tiered Compilers   Total time: 412 ms

  JVM OPTIONS
    -Xms256m
    -Xmx4g
    -XX:+UseG1GC

──────────────────────────────────────────────────────────
  NEXT STEP IF ANYTHING IS ON WARN OR FAIL
    jstat -gcutil 18492 1000 30       (is column O growing?)
    jcmd 18492 GC.class_histogram     (which class is growing?)
    jcmd 18492 Thread.print           (deadlocks and stacks)
    jcmd 18492 JFR.start settings=profile duration=120s \
         filename=/tmp/bibliotech.jfr
══════════════════════════════════════════════════════════