Java Intermediate¶

The missing middle: from writing Java to writing good Java. Design judgment, concurrency, performance awareness. Bridges From Scratch to Mastery.

Java Intermediate - From Writing Java to Writing Good Java¶

From "I can write a class and a for loop" to "I write concurrent, performance-aware, idiomatic Java that a senior reviewer would approve."

This is the missing middle. Java From Scratch takes you from never-coded to your first pull request. Java Mastery is the senior reference - JVM internals, JIT, GC, bytecode. Between them is a wide gap: you can write working Java, but you don't yet know which collection to reach for, how to make code thread-safe, why your program allocates so much, or how to design with interfaces instead of inheritance. This path closes that gap.

Who this is for¶

• You finished Java From Scratch (or you can already write classes, methods, collections, generics, and exceptions without looking up syntax).
• You can read most of a small Java program but couldn't yet explain why it's written the way it is.
• You've never written multithreaded code, or you have and it scared you.

If you're still learning what a class is, start with Java From Scratch first. If you're comfortable reading hotspot/share/gc/ source, you're past this - go to Java Mastery.

What you'll need¶

• A working JDK 21+ (Java From Scratch's setup chapter covers this).
• IntelliJ IDEA Community Edition or VS Code with the Java extensions.
• About 5 hours per week. Sized for 3-4 months.

How this path differs from From Scratch¶

Same teaching voice - concrete, you-directed, runnable examples, a "Try it" on every concept, a "What you might wonder" Q&A. But pitched higher: we assume you know the syntax, so we spend the time on judgment. When does composition beat inheritance? Which Map implementation? Why is this code not thread-safe? When does an allocation actually matter?

Every chapter still ends with code you run yourself. Reading without doing won't stick - that's even more true here than in the beginner path.

The pages¶

Start with What "intermediate" means.

00 - What "intermediate" means¶

What this session is¶

Ten minutes. The map for this path: what changes between beginner and intermediate, what we'll cover, and how to get the most out of it.

The shift¶

Beginner Java is about syntax and "does it run." You learned what a class is, how a loop works, how to catch an exception. The question was always: how do I make the compiler accept this and produce the right output?

Intermediate Java is about judgment and "is this good." The syntax is settled. Now the questions are different:

• There are five ways to do this. Which is right, and why?
• This works on my machine with one user. Does it still work with a thousand users hitting it at once?
• This is correct. Is it fast enough, and if not, where's the cost?
• This class works. Will the next person who reads it understand it, or curse my name?

Nobody writes good Java by accident. Every senior engineer you admire learned the judgment in this path the hard way - by shipping something, watching it break or slow down or confuse a teammate, and learning the rule behind the mistake. This path gives you the rules without requiring the full set of scars.

The three things that separate intermediate from beginner¶

1. Design judgment¶

A beginner makes a class because they need to group some data. An intermediate engineer asks: should this be a class or a record? Should it use inheritance or composition? Should this method take a concrete type or an interface? These choices compound. Get them right and your code stays flexible for years; get them wrong and every change fights you.

Chapters 01–07 are about design judgment.

2. Concurrency¶

This is the big one, and it's almost entirely absent from beginner Java. The moment your code runs on a server handling many requests at once - which is most real Java - you're writing concurrent code, whether you meant to or not. Concurrency bugs are the worst kind: they appear randomly, vanish when you look closely, and pass every test until production. You can't be a competent Java engineer without understanding threads, shared state, and the tools for managing them.

Chapters 09–11 are about concurrency. They're the heart of this path.

3. Performance awareness¶

Not premature optimization - awareness. Knowing that a String concatenation in a loop allocates a new object every iteration. Knowing that autoboxing an int into an Integer a million times has a cost. Knowing how to find the actual hot spot with a profiler instead of guessing. You won't optimize most code - but you'll recognize the 5% that matters and you'll have the tools to fix it.

Chapters 08, 12, and 13 are about performance awareness.

What this path is not¶

• Not JVM internals. We'll talk about the garbage collector enough to write GC-friendly code, but we won't dissect G1's remembered sets or ZGC's colored pointers. That's Java Mastery.
• Not a framework course. No Spring, no Hibernate as protagonists. We use the standard library so the concepts transfer. Frameworks are easier once the fundamentals are solid.
• Not exhaustive. Java is vast. This path covers the intermediate concepts you'll use weekly, not every corner of the language.

How to use this path¶

1. Do the exercises. Even more than in the beginner path. Concurrency especially cannot be learned by reading - you have to run code, see it race, and fix it.
2. Use the race detector mindset. From chapter 09 on, get in the habit of asking "what if two threads ran this at the same time?" of every piece of shared state.
3. Read real code alongside. Pick a small, well-regarded Java library (we'll suggest some). When a chapter teaches a concept, find it in the wild.
4. Don't rush the concurrency chapters. 09–11 are worth a week each. They're the difference between "writes Java" and "writes Java that survives production."

A note on Java versions¶

This path targets Java 21+ (the current LTS as you read this is 21 or 25). Where a feature is newer - virtual threads (21), structured concurrency, scoped values - it's flagged. If you're on an older JDK at work (Java 8 and 11 are still everywhere), the design and concurrency concepts all transfer; only some syntax and a few APIs differ. We note the important gaps.

What you might wonder¶

"I haven't finished From Scratch. Can I start here?" If you can write a class with fields and methods, use a List and a Map, write a try/catch, and define a generic method - yes. If any of those made you pause, do the relevant From Scratch chapters first. This path moves fast through anything From Scratch covered.

"Is concurrency really that important?" Yes. Almost every Java job involves servers handling concurrent requests. The frameworks hide some of it, but the moment you have shared mutable state - a cache, a counter, a connection pool - you're responsible for thread safety. It's the single most common source of "senior" Java interview questions and production incidents.

"Will this make me job-ready?" This plus From Scratch gets you to "competent mid-level Java engineer who can be trusted with real features." Mastery is for the senior/staff tier. Most working Java engineers operate at the level this path teaches.

Done¶

• You know the beginner → intermediate shift: from syntax to judgment.
• You know the three pillars: design, concurrency, performance.
• You know how to use the path: do the exercises, especially the concurrency ones.

Next: OOP done right →

01 - OOP done right¶

What this session is¶

About an hour. In From Scratch you learned how to write a class and how to extend one with extends. This session is about when to do which - the single most consequential design judgment in object-oriented Java. By the end you'll know why experienced engineers reach for composition far more than inheritance, and when inheritance is still the right call.

The trap beginners fall into¶

Inheritance is the first "real OOP" tool you learn, so it's the one you reach for. You have a Vehicle, so you make Car extends Vehicle and Truck extends Vehicle. It feels powerful. Code reuse! Polymorphism! The textbook examples all use it.

Then real requirements arrive, and inheritance starts to hurt. Let's watch it happen.

Inheritance, and where it breaks¶

Say you're modeling employees. You start clean:

class Employee {
    String name;
    double baseSalary;

    double monthlyPay() {
        return baseSalary / 12;
    }
}

class Manager extends Employee {
    double bonus;

    @Override
    double monthlyPay() {
        return (baseSalary + bonus) / 12;
    }
}

Fine so far. Now the requirements grow:

• Some employees are contractors (paid hourly, no annual salary).
• Some managers are also engineers (they still code).
• Some contractors become managers.
• An employee can be a part-time intern who is also a contractor.

Try to model this with inheritance and you hit a wall. Manager extends Employee - but what about a contractor who manages? ContractorManager extends Manager? But contractors aren't salaried, and Manager assumed a baseSalary. Now you're overriding methods to undo behavior you inherited. You add EngineerManager, ContractorEngineer, PartTimeContractorIntern... the class count explodes combinatorially, and each new trait doubles it.

This is the core problem with inheritance: it forces a single, rigid "is-a" hierarchy onto things that have many independent traits. A person isn't one thing on a tree. They're a bundle of capabilities - paid this way, has these roles, works this schedule - and those vary independently.

Three specific pains you'll feel:

1. The fragile base class. When Manager extends Employee, Manager depends on Employee's internals. Change Employee.monthlyPay() and you might silently break Manager - or every subclass. The base class can't evolve safely because subclasses reach into its behavior.

2. You inherit everything, wanted or not. extends is all-or-nothing. You get every field and method of the parent, even the ones that don't make sense for you. A Stack extends Vector (a real, regretted decision in Java's own standard library) means a Stack exposes Vector's add(index, element) - letting you insert into the middle of a stack, which is nonsense.

3. Single inheritance is a hard limit. A class can extend exactly one class. The moment something needs traits from two places, inheritance can't express it.

Composition: have-a instead of is-a¶

Composition flips the model. Instead of a class being a kind of another class, it has the pieces it needs as fields.

Here's the employee model rebuilt with composition:

// Each capability is its own small, focused type.
interface PayStrategy {
    double monthlyPay();
}

record Salaried(double annual, double bonus) implements PayStrategy {
    public double monthlyPay() { return (annual + bonus) / 12; }
}

record Hourly(double rate, double hoursPerMonth) implements PayStrategy {
    public double monthlyPay() { return rate * hoursPerMonth; }
}

// A person HAS a pay strategy and HAS a set of roles - they don't inherit them.
class Person {
    String name;
    PayStrategy pay;
    Set<String> roles;          // "manager", "engineer", "intern" - combine freely

    Person(String name, PayStrategy pay, Set<String> roles) {
        this.name = name;
        this.pay = pay;
        this.roles = roles;
    }

    double monthlyPay() {
        return pay.monthlyPay();
    }

    boolean isManager() {
        return roles.contains("manager");
    }
}

Now the combinatorial explosion is gone:

var alice = new Person("Alice",
        new Salaried(180_000, 30_000),
        Set.of("manager", "engineer"));

var bob = new Person("Bob",
        new Hourly(95, 160),
        Set.of("contractor", "manager"));     // a contractor who manages - no problem

A contractor-manager-engineer is just a Person with an Hourly pay strategy and three roles. No new class. Each trait varies independently because each is a separate field, not a fixed position on a tree.

This is the principle, and it's old enough to be a proverb:

Favor composition over inheritance.

It's the first design rule from the "Gang of Four" Design Patterns book and the most-cited piece of OOP advice for a reason. Composition gives you flexibility (mix traits freely), safety (each piece is independent - changing Hourly can't break Salaried), and testability (you can test Salaried.monthlyPay() in isolation).

When inheritance is right¶

This isn't "never use inheritance." It's "use it deliberately, for the cases it fits." Inheritance is the right tool when:

1. There's a genuine, stable "is-a" relationship that won't grow new dimensions. A SavingsAccount truly is an Account. A Circle truly is a Shape. If the hierarchy is shallow and the "is-a" is real and unlikely to need cross-cutting traits, inheritance is clean.

2. You're implementing a framework's extension point. When you write class MyServlet extends HttpServlet or class MyTest extends TestCase, you're plugging into a contract the framework defined. That's inheritance used as intended.

3. You want to share a partial implementation via an abstract base. An AbstractList provides the plumbing so concrete lists only implement a few methods. (We'll cover abstract classes in chapter 02.)

The test: if you're overriding methods to remove or undo inherited behavior, inheritance is the wrong tool. That's the code telling you the "is-a" relationship is a lie.

The third tool: program to interfaces¶

Composition pairs with a second habit: depend on interfaces, not concrete classes. Notice that Person holds a PayStrategy (an interface), not a Salaried or Hourly (concrete types). That one choice means:

• Person doesn't know or care how pay is calculated. New pay schemes (Commission, Equity) drop in without touching Person.
• You can test Person with a fake PayStrategy that returns a fixed number.
• The dependency points at a stable contract, not a volatile implementation.

You met interfaces in From Scratch as "a contract any type can satisfy." The intermediate habit is to reach for them by default when one object needs to use another. We'll go deep on interface design in chapter 02.

Try it¶

1. Feel the explosion. Sketch (on paper or in code) a Notification system using inheritance: EmailNotification, SmsNotification, then add "urgent" and "scheduled" as variations. Watch the class count: UrgentEmailNotification, ScheduledSmsNotification... Count how many classes you need for 3 channels × 2 urgencies × 2 timings.

2. Refactor to composition. Rebuild it: a Notification that has a Channel (interface: Email, Sms, Push), a Priority field, and a Schedule field. How many types now? How do you add a new channel?

3. Spot the lie. Find this in the wild or write it: a subclass that overrides a method to throw UnsupportedOperationException ("this operation doesn't apply to me"). That's the canonical sign of inheritance abuse - the subclass is rejecting part of what it inherited. Rewrite it with composition so the unsupported operation simply isn't there.

4. Read Java's own mistake. Look up java.util.Stack (it extends Vector). Notice it inherits get(int), add(int, E), remove(int) - operations that violate stack semantics. Then look at ArrayDeque, the modern recommended stack, which uses composition-friendly design. This is the standard library admitting the lesson.

What you might wonder¶

"So inheritance is bad?" No - overused inheritance is bad. It's a precise tool for genuine, stable is-a relationships and framework extension points. The problem is reaching for it as the default reuse mechanism. Default to composition; use inheritance when the is-a is real.

"Isn't composition more boilerplate?" Sometimes slightly more upfront - you write a field and delegate a method instead of getting it free from extends. But it pays back fast: independent pieces, no fragile base class, easy testing, free mixing of traits. Records and modern Java keep the boilerplate small. The tradeoff is almost always worth it.

"What about default methods on interfaces - isn't that inheritance?" Interfaces can provide default method implementations (since Java 8), which is a limited form of shared behavior. It's safer than class inheritance - interfaces have no fields, so there's no fragile-base-class state problem - and a class can implement many interfaces. We'll cover this in chapter 02.

"How does this relate to 'SOLID'?" "Favor composition over inheritance" supports several SOLID principles at once - especially the Open/Closed Principle (extend behavior by adding new strategy implementations, not by editing existing classes) and Dependency Inversion (depend on the PayStrategy abstraction, not concrete pay types). You don't need to memorize SOLID as an acronym; you need the habits, and this is the central one.

Done¶

• You know why inheritance breaks down: rigid single hierarchy, fragile base class, all-or-nothing reuse.
• You know composition: model traits as fields (often interface-typed) that vary independently.
• You know the rule - favor composition over inheritance - and the cases where inheritance still wins.
• You know the tell: overriding to undo inherited behavior means you picked the wrong tool.

This is the foundation for everything in the design half of this path. Next we go deep on the contracts themselves: interfaces and abstract classes.

Next: Interfaces and abstract classes in depth →

02 - Interfaces and abstract classes in depth¶

What this session is¶

About ninety minutes. Chapter 01 told you to "program to interfaces." This session is the deep version: what interfaces really are, every feature they've grown (default methods, static methods, private methods, constants), what abstract classes add, exactly when to choose one over the other, and the design habits that make interfaces powerful instead of noise. By the end this is your reference for every "should this be an interface or a class?" decision you'll make.

The mental model: an interface is a promise¶

A class says what something is and how it works. An interface says what something can do - nothing about how. It's a promise: "any type that implements me guarantees these methods exist."

interface Switch {
    void turnOn();
    void turnOff();
    boolean isOn();
}

That's a promise with three clauses. A LightBulb, a Server, a Valve - completely unrelated things - can all make this promise. Code that depends on Switch works with all of them and never needs to know which it's holding:

void cycle(Switch s) {
    s.turnOn();
    System.out.println("on? " + s.isOn());
    s.turnOff();
}

cycle works on anything switchable, forever, including types that don't exist yet. That decoupling - the caller depends on the promise, not the implementation - is the entire point.

Implementing an interface¶

A class promises to fulfill an interface with implements, then provides every method:

class LightBulb implements Switch {
    private boolean on = false;

    public void turnOn()    { on = true; }
    public void turnOff()   { on = false; }
    public boolean isOn()   { return on; }
}

Two rules that bite beginners:

1. Interface methods are implicitly public. When you implement them, you must write public explicitly - leaving it off narrows the visibility, which the compiler rejects.
2. You must implement every method (unless your class is abstract - see below). Miss one and the class won't compile.

A class can implement many interfaces - this is the superpower inheritance lacks:

class SmartBulb implements Switch, Dimmable, NetworkConnected {
    // must fulfill all three promises
}

A SmartBulb is switchable and dimmable and network-connected - three independent capabilities, combined freely. Try that with single inheritance and you can't.

Default methods: behavior on an interface¶

Since Java 8, an interface can provide a method body with the default keyword. Implementing classes inherit it for free but may override it.

interface Switch {
    void turnOn();
    void turnOff();
    boolean isOn();

    // A default method built from the abstract ones.
    default void toggle() {
        if (isOn()) turnOff();
        else turnOn();
    }
}

Every Switch now has toggle() without writing it. LightBulb, Server, all of them - they get toggle() for free, defined once.

Why default methods exist: they let an interface grow without breaking every existing implementation. Before Java 8, adding a method to an interface broke every class that implemented it (suddenly missing a method). default methods were added specifically so the JDK could add methods like List.sort() and Collection.stream() to interfaces that millions of classes already implemented. The new method has a default body, so old implementations keep compiling.

Use them for: convenience methods derived from the core (abstract) ones, like toggle() above, or Comparator's reversed() and thenComparing(). Don't use them to smuggle in lots of stateful behavior - interfaces have no fields, so default methods can only work through the other methods. That limit is a feature; it keeps interfaces honest.

Static methods on interfaces¶

Interfaces can also hold static methods - usually factories or helpers related to the type:

interface Switch {
    void turnOn();
    void turnOff();
    boolean isOn();

    // Static factory: makes a Switch that does nothing. Useful for tests/defaults.
    static Switch noop() {
        return new Switch() {
            public void turnOn() {}
            public void turnOff() {}
            public boolean isOn() { return false; }
        };
    }
}

// Call it on the interface itself:
Switch s = Switch.noop();

You've used these without noticing: List.of(...), Map.of(...), Comparator.comparing(...), Path.of(...) are all static methods on interfaces. They're the modern idiom for "give me a ready-made instance of this type."

Private methods on interfaces¶

Since Java 9, interfaces can have private methods - used only to share code between default methods, hidden from implementers:

interface Logger {
    void write(String line);

    default void info(String msg)  { write(format("INFO", msg)); }
    default void warn(String msg)  { write(format("WARN", msg)); }
    default void error(String msg) { write(format("ERROR", msg)); }

    // Private helper - not part of the public promise, just shared plumbing.
    private String format(String level, String msg) {
        return "[" + level + "] " + msg;
    }
}

format isn't part of the contract - implementers never see it. It just removes duplication among the three default methods. Reach for private interface methods only when two or more default methods share logic.

Constants on interfaces (and why to be wary)¶

Fields in an interface are implicitly public static final - constants:

interface Physics {
    double SPEED_OF_LIGHT = 299_792_458;   // public static final, automatically
}

This works, but avoid the "constant interface" antipattern - making an interface whose only purpose is to hold constants, then implementing it to "get" them. It pollutes your type's public API with constants and abuses implements (which should mean "I fulfill this contract," not "I want these numbers"). Put constants in a final class with a private constructor, or an enum, instead. Constants directly relevant to an interface's methods are fine; a bag of unrelated constants is not.

Abstract classes: a partial implementation¶

An abstract class sits between an interface (pure promise) and a concrete class (full implementation). It can have everything a class has - fields, constructors, concrete methods - plus abstract methods with no body that subclasses must fill in. You can't instantiate it directly.

abstract class AbstractSwitch implements Switch {
    private boolean on = false;          // an interface can't have this field

    // Concrete: shared state management, written once.
    public boolean isOn()  { return on; }
    public void turnOn()   { on = true;  onChanged(); }
    public void turnOff()  { on = false; onChanged(); }

    // Abstract: each subclass provides the device-specific reaction.
    protected abstract void onChanged();
}

class Relay extends AbstractSwitch {
    protected void onChanged() {
        System.out.println("relay clicked, now " + (isOn() ? "closed" : "open"));
    }
}

AbstractSwitch handles the on field and the bookkeeping; subclasses only supply onChanged(). This is the template method pattern: the base class defines the skeleton of an operation and defers specific steps to subclasses. The JDK uses it everywhere - AbstractList, AbstractMap, InputStream all provide most methods and leave a few abstract.

What an abstract class can do that an interface cannot:

• Hold instance fields (mutable state like on above).
• Have constructors (to initialize that state).
• Have non-public members (protected, package-private).

What an interface can do that an abstract class cannot:

• Be implemented by a class that already extends something else (a class extends one class but implements many interfaces).

The decision: interface or abstract class?¶

Here's the rule that resolves almost every case:

Default to an interface. Reach for an abstract class only when you need to share mutable state or constructor logic across implementations - and even then, consider composition first.

The longer reasoning:

A powerful middle path the JDK uses: ship both. Define the interface (List), and provide an abstract skeleton (AbstractList) that implementers may extend for convenience but aren't forced to. Implementers who already extend something else implement List directly; everyone else extends AbstractList and saves work. You get the flexibility of an interface and the convenience of shared code.

A worked example: a plugin system¶

Let's design a small plugin system to see every tool in play.

// The contract every plugin promises.
interface Plugin {
    String name();
    void execute(Context ctx);

    // Default: most plugins don't need setup, so give a no-op default.
    default void init(Context ctx) {}

    // Default: derived convenience.
    default String describe() {
        return name() + " plugin";
    }

    // Static factory for a trivial plugin from a lambda.
    static Plugin of(String name, java.util.function.Consumer<Context> action) {
        return new Plugin() {
            public String name() { return name; }
            public void execute(Context ctx) { action.accept(ctx); }
        };
    }
}

A simple plugin implements directly:

class GreetPlugin implements Plugin {
    public String name() { return "greet"; }
    public void execute(Context ctx) {
        System.out.println("Hello from " + ctx.user());
    }
}

A family of plugins that share setup uses an abstract base:

// Shared plumbing: every DB plugin needs a connection, opened once.
abstract class DatabasePlugin implements Plugin {
    protected Connection conn;            // shared mutable state - needs a class

    public void init(Context ctx) {
        this.conn = ctx.openConnection(); // constructor-like setup, written once
    }

    // Subclasses implement the actual query work; conn is ready for them.
    public abstract void execute(Context ctx);
}

class BackupPlugin extends DatabasePlugin {
    public String name() { return "backup"; }
    public void execute(Context ctx) {
        conn.run("BACKUP DATABASE");       // conn was opened by init()
    }
}

And a throwaway plugin from the static factory:

Plugin ping = Plugin.of("ping", ctx -> System.out.println("pong"));

Three styles, one contract. The host code only ever sees Plugin:

void runAll(List<Plugin> plugins, Context ctx) {
    for (Plugin p : plugins) {
        p.init(ctx);
        System.out.println("running " + p.describe());
        p.execute(ctx);
    }
}

This is the shape of real plugin systems, servlet containers, build-tool task systems, and test frameworks. The interface is the contract; abstract classes provide optional shared scaffolding; static factories and lambdas make trivial cases cheap.

Try it¶

1. Build the Switch hierarchy. Write the Switch interface with the toggle() default. Implement LightBulb and a Fan (where turnOn prints "spinning"). Call toggle() on each twice. Confirm the default works for both without either class defining it.

2. Add a capability. Add a Dimmable interface (void setBrightness(int pct), int brightness()). Make a SmartBulb implements Switch, Dimmable. Write a method dimAll(List<Dimmable> ds) and a method cycleAll(List<Switch> ss). Pass your SmartBulb to both. One object, two contracts.

3. Template method. Write the AbstractSwitch with the onChanged() hook. Make two subclasses that react differently. Notice you wrote the on-field logic exactly once.

4. Spot the constant-interface antipattern. Find or write an interface that's only constants. Refactor it into a final class with a private constructor (private Physics() {}) holding public static final fields. Access via Physics.SPEED_OF_LIGHT. Discuss why this is cleaner than implements Physics.

5. Ship both. Take your Plugin interface and write an AbstractPlugin that provides a default describe() using a protected String category field. Make one plugin extend it and one implement Plugin directly. Both work through runAll.

What you might wonder¶

"If interfaces can have method bodies now, why have abstract classes at all?" State and constructors. Default methods can't touch instance fields (interfaces have none) and interfaces have no constructors. The moment your shared behavior needs to remember something between calls (the on field, the conn), you need an abstract class. Also: a class can only extend one abstract class, so abstract classes impose a hierarchy that interfaces don't.

"Can an interface extend another interface?" Yes - interface ColorSwitch extends Switch adds methods to the Switch promise. An interface can extend many interfaces: interface SmartDevice extends Switch, Dimmable, NetworkConnected. This is interface composition, and it's how you build up rich contracts from small ones.

"What's the diamond problem with default methods?" If a class implements two interfaces that both have a default method with the same signature, the compiler forces you to resolve the ambiguity by overriding it (you can call a specific one with InterfaceName.super.method()). Java makes the conflict a compile error rather than silently picking one - safer than C++'s implicit resolution.

"Should I make an interface for everything, just in case?" No. An interface with exactly one implementation that will never have another is usually premature - it adds indirection without flexibility. Introduce the interface when you have (or clearly foresee) a second implementation, a need to mock for tests, or a public API boundary. "Accept interfaces, return structs" (chapter 01) is the guide: interfaces earn their place at boundaries.

"sealed interfaces - what are those?" A sealed interface restricts which types may implement it (sealed interface Shape permits Circle, Square). It's the opposite of an open contract - used when you want an exhaustive, known set of implementations the compiler can check (great with pattern-matching switch). You met sealed types in From Scratch chapter 08; we'll use them again in chapter 07.

Done¶

• You know an interface is a promise - a contract decoupled from implementation.
• You know every interface feature: abstract methods, default, static, private, constants (and the constant-interface antipattern to avoid).
• You know abstract classes add state + constructors + the template-method pattern, at the cost of single inheritance.
• You can decide between them: default to interface, reach for abstract class when you need shared mutable state or constructor logic - and consider "ship both."

Next we make these contracts airtight: the equals, hashCode, and compareTo contracts that every Java object lives by.

Next: Equality, hashing, immutability →

03 - Equality, hashing, immutability¶

What this session is¶

About ninety minutes. Three contracts that every Java object silently participates in, and that - when you get them wrong - produce some of the most baffling bugs in the language: objects that vanish from a HashSet, map lookups that fail for keys you just put in, sort orders that throw exceptions. By the end you'll understand equals, hashCode, and compareTo deeply enough to implement them correctly by hand and to know when records do it for you.

Why this matters more than it looks¶

Here's a bug that has cost real engineers real hours:

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}

var seen = new HashSet<Point>();
seen.add(new Point(1, 2));
System.out.println(seen.contains(new Point(1, 2)));   // false (!!)

You added (1, 2). You asked if (1, 2) is there. It says no. The set appears broken. It isn't - you are, because Point never told Java what "equal" means. This session is about never writing that bug.

Reference equality vs logical equality¶

There are two completely different questions you can ask about two objects:

1. Are they the same object in memory? That's ==. It compares references - the addresses, essentially.
2. Do they represent the same value? That's .equals(). It compares meaning.

String a = new String("hi");
String b = new String("hi");

System.out.println(a == b);        // false - two different objects
System.out.println(a.equals(b));   // true  - same characters

The default equals() that every object inherits from Object just does ==:

// Object's default - only true for the literal same object
public boolean equals(Object obj) {
    return this == obj;
}

So unless you override equals(), "logical equality" is "same object" - which is why our Point lookup failed. The new Point(1,2) you searched for was a different object from the one you added, and the inherited equals only matches identical objects.

The rule: for any class whose instances represent a value (a point, a money amount, a date, a name) - where two instances with the same contents should be treated as equal - you must override equals(). For classes that represent a unique entity with identity (a database connection, a running thread, a service), the default reference equality is correct; leave it alone.

Implementing equals correctly¶

equals has a precise contract from the Object Javadoc. It must be:

• Reflexive: x.equals(x) is always true.
• Symmetric: x.equals(y) is true if and only if y.equals(x) is true.
• Transitive: if x.equals(y) and y.equals(z), then x.equals(z).
• Consistent: repeated calls return the same result (as long as nothing changes).
• Non-null: x.equals(null) is always false.

Break any of these and the collections that rely on equals (HashSet, HashMap, List.contains, List.indexOf) misbehave in ways that are very hard to debug.

The canonical, contract-correct implementation:

@Override
public boolean equals(Object o) {
    if (this == o) return true;            // fast path: same object
    if (o == null || getClass() != o.getClass()) return false;  // null + type check
    Point other = (Point) o;               // safe cast now
    return x == other.x && y == other.y;   // field-by-field comparison
}

Walk every line, because each guards a clause of the contract:

• if (this == o) return true; - reflexive and a performance shortcut.
• if (o == null || getClass() != o.getClass()) return false; - handles the non-null rule and rejects different types. (Using getClass() keeps symmetry airtight; instanceof can break symmetry across subclasses - more in the Q&A.)
• Point other = (Point) o; - now safe because we verified the type.
• return x == other.x && y == other.y; - compare the fields that define value. For object fields, use Objects.equals(this.field, other.field) (it null-checks for you); for double/float, use Double.compare to handle NaN and -0.0 correctly.

The hashCode contract - and why it's coupled to equals¶

Now the part that bit our Point. Hash-based collections (HashMap, HashSet) don't compare every element with equals. That would be O(n) per lookup. Instead they:

1. Call hashCode() to get an int, and use it to pick a bucket (a slot).
2. Only compare with equals against the (few) items already in that bucket.

This is what makes HashMap O(1). But it means the system only works if equal objects land in the same bucket - which requires:

If a.equals(b) is true, then a.hashCode() == b.hashCode() must also be true.

This is the single most important coupling in Java. Our Point overrode neither, so two equal points got the default hashCode (based on object identity), landed in different buckets, and the set never even compared them with equals. The lookup failed before equality was ever checked.

The full hashCode contract:

• Consistent: same object returns the same hash across calls (while unchanged).
• Equal ⇒ same hash: equal objects must have equal hash codes. (The load-bearing rule.)
• Unequal may share a hash (a "collision") - allowed, just slower. Good hash codes spread values out to minimize collisions.

The correct Point.hashCode:

@Override
public int hashCode() {
    return Objects.hash(x, y);    // combines the same fields equals() uses
}

Objects.hash(...) takes the fields and combines them into a well-distributed int. Always hash exactly the fields you compare in equals - no more, no fewer. If equals uses x and y, hashCode uses x and y. Mismatch here is the bug.

Now the fix in full:

class Point {
    final int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }

    @Override public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Point p = (Point) o;
        return x == p.x && y == p.y;
    }

    @Override public int hashCode() {
        return Objects.hash(x, y);
    }
}

var seen = new HashSet<Point>();
seen.add(new Point(1, 2));
System.out.println(seen.contains(new Point(1, 2)));   // true - fixed

Iron law: override equals and hashCode together, always. Never one without the other. Every linter and IDE enforces this. The moment you write one, write the other from the same fields.

compareTo - ordering¶

equals answers "are these equal?" compareTo answers "which comes first?" A class implements Comparable<T> to define a natural order - used by Collections.sort, TreeSet, TreeMap, and list.sort(null).

class Version implements Comparable<Version> {
    final int major, minor, patch;
    Version(int major, int minor, int patch) {
        this.major = major; this.minor = minor; this.patch = patch;
    }

    @Override public int compareTo(Version o) {
        // Returns negative if this < o, 0 if equal, positive if this > o.
        return Comparator.comparingInt((Version v) -> v.major)
                .thenComparingInt(v -> v.minor)
                .thenComparingInt(v -> v.patch)
                .compare(this, o);
    }
}

var versions = new ArrayList<>(List.of(
    new Version(1, 2, 0), new Version(1, 0, 5), new Version(2, 0, 0)));
Collections.sort(versions);   // uses compareTo: 1.0.5, 1.2.0, 2.0.0

The contract: compareTo returns a negative int, zero, or a positive int for less-than, equal, greater-than. It must be a consistent total order (antisymmetric, transitive). And there's a strong recommendation: compareTo should be consistent with equals - x.compareTo(y) == 0 should usually mean x.equals(y). Violate this and TreeSet/TreeMap (which use compareTo, not equals, to decide membership) behave differently from HashSet/HashMap, which surprises everyone.

When you don't control the class or want a one-off order, use a Comparator instead of Comparable:

versions.sort(Comparator.comparingInt((Version v) -> v.patch));   // sort by patch only
versions.sort(Comparator.comparing((Version v) -> v.major).reversed());

Comparable is the one natural order baked into the type; Comparator is any number of external orders. Prefer Comparator for alternative sorts; reserve Comparable for the single most obvious "default" order (or omit it if there's no obvious default).

Immutability - the quiet superpower¶

Notice the fixed Point used final int x, y. That's deliberate. An immutable object can't change after construction. This matters enormously for the contracts above and for concurrency (chapters 09-11).

Why immutability is a default worth reaching for:

1. Hash keys must not change. If you put a mutable object in a HashSet, then mutate a field used by hashCode, the object is now in the wrong bucket - lost. Immutable keys can't have this bug.
2. Thread safety for free. An object that never changes can be shared across threads with zero synchronization. No races possible on data that doesn't mutate. (This is why chapters 09-11 keep coming back to immutability.)
3. Easier reasoning. You can pass an immutable object anywhere without fear someone will change it behind your back.

How to make a class immutable:

final class Money {                          // final: no subclass can add mutability
    private final long cents;                // final fields, set once
    private final String currency;

    Money(long cents, String currency) {
        this.cents = cents;
        this.currency = currency;
    }

    long cents()       { return cents; }     // getters only, no setters
    String currency()  { return currency; }

    // "Mutation" returns a NEW object instead of changing this one.
    Money plus(Money other) {
        if (!currency.equals(other.currency))
            throw new IllegalArgumentException("currency mismatch");
        return new Money(cents + other.cents, currency);
    }
}

The recipe: final class, all fields private final, no setters, and any "change" returns a new instance. String, Integer, LocalDate, and BigDecimal are all immutable this way - which is why String methods like toUpperCase() return a new string instead of changing the original.

The defensive-copy trap¶

Immutability has a hole: if a field is itself a mutable object (a List, an array, a Date), storing or returning it directly leaks mutability.

final class Team {
    private final List<String> members;

    // BROKEN: caller keeps a reference to the same list and can mutate it.
    Team(List<String> members) {
        this.members = members;
    }
    List<String> members() {
        return members;                       // caller can do members().add(...)!
    }
}

Fix with defensive copies on the way in and out (or unmodifiable wrappers):

final class Team {
    private final List<String> members;

    Team(List<String> members) {
        this.members = List.copyOf(members);  // copy in - our list is independent
    }
    List<String> members() {
        return members;                       // List.copyOf already made it unmodifiable
    }
}

List.copyOf creates an independent, unmodifiable list. Now neither the original caller's list nor anything they get back can corrupt the Team. The same applies to arrays (array.clone()), maps (Map.copyOf), and any mutable field.

Records: the contracts, for free¶

Here's the relief: for the common case of a value type, records implement all of this correctly for you. You met records in From Scratch chapter 08; now you can appreciate what they do.

record Point(int x, int y) {}

That one line generates:

• A constructor.
• x() and y() accessors.
• A correct equals comparing both fields.
• A correct hashCode from both fields (consistent with equals).
• A readable toString.

The Point bug we spent this chapter fixing simply cannot happen with a record - the generated equals/hashCode are correct and coupled by construction. Records are also implicitly final and their fields are final, so they're immutable (with the defensive-copy caveat for mutable components - a record holding a List field still needs care in its compact constructor):

record Team(List<String> members) {
    Team {                                    // compact constructor
        members = List.copyOf(members);       // defensive copy still needed
    }
}

The practical guidance: for value types, reach for a record first. You get the contracts right automatically. Write equals/hashCode by hand only when you can't use a record (you need mutability, or you extend a class, or you need custom equality semantics like case-insensitive comparison). Knowing how to do it by hand matters because you'll read and maintain pre-record code constantly - but for new value types, records are the answer.

Try it¶

1. Reproduce the bug. Write Point with no equals/hashCode. Add one to a HashSet, search for an equal one, watch contains return false. Then add correct equals/hashCode and watch it return true. Feel the cause.

2. Break the coupling on purpose. Override equals correctly but make hashCode return a constant return 1;. Does the HashSet work? (It does - but every element collides into one bucket, making it O(n). Correct but slow.) Now make hashCode return x only while equals uses x and y. Add (1,2) and (1,3), then search for (1,2). Reason about what happens.

3. The mutation-in-a-set disaster. Make Point mutable (non-final fields, a setter). Put one in a HashSet. Mutate its x. Now call contains with an equal point and also iterate the set looking for it. The object is "in" the set but unfindable - it's in the wrong bucket. This is the argument for immutable keys.

4. Order it. Implement Version implements Comparable<Version>. Sort a list. Then sort the same list by patch-number-descending using a Comparator. Notice Comparable is the one natural order; Comparator is for everything else.

5. Records vs hand-written. Write Money as a hand-written immutable class with equals/hashCode, then as a record. Put both in a HashMap as keys and look them up. Confirm both work. Count the lines you saved.

6. Defensive copy. Write the broken Team (stores the list directly). Construct one, then team.members().add("intruder") (or mutate the original list you passed in). Watch the "immutable" team change. Fix with List.copyOf. Confirm the mutation no longer leaks.

What you might wonder¶

"instanceof vs getClass() in equals - which?" getClass() requires both objects to be the exact same class, which keeps symmetry airtight even across subclasses. instanceof allows subclass instances to equal superclass instances, which can break symmetry (a ColorPoint might equal a Point but not vice versa). For most value types, getClass() is the safe default. Records use exact-class matching internally. There are advanced patterns using instanceof for class hierarchies, but they require care; default to getClass().

"Do I really need to memorize the equals contract?" You don't write equals by hand often once you have records. But you read hand-written ones constantly, and you need to recognize when one is broken. Know the five rules well enough to spot a violation in code review - that's the working level.

"Why is Objects.hash better than writing my own?" You can write int result = 31 * x + y; - the classic formula. Objects.hash does essentially that for any number of fields, correctly and readably, and handles nulls. For hot paths where the varargs array allocation of Objects.hash matters, hand-write the 31 * formula; otherwise Objects.hash is the clear, correct default.

"Is everything supposed to be immutable now?" Default to immutable; allow mutability when you have a reason (a builder accumulating state, a large object you mutate in place for performance, an entity whose identity persists while its fields change). The guidance is "immutable unless you need otherwise," not "immutable always." Records make immutable the path of least resistance, which is the point.

"What about compareTo returning this.x - other.x?" A classic bug. Subtraction can overflow (Integer.MIN_VALUE - 1 wraps to a positive number, inverting the order). Always use Integer.compare(a, b) or Comparator builders, never raw subtraction, for compareTo.

Done¶

• You know reference equality (==) vs logical equality (.equals()), and when each is correct.
• You can implement equals against its five-rule contract.
• You understand why hashCode is coupled to equals - and the bucket mechanism that makes the coupling load-bearing.
• You can implement compareTo/Comparator for ordering, and avoid the subtraction-overflow trap.
• You know why immutability protects the contracts and enables thread safety, how to build immutable classes, and the defensive-copy trap.
• You know records implement all of it correctly for free - reach for them first.

Next: generics in depth - bounded types, wildcards, and the truth about type erasure.

Next: Generics in depth →

04 - Generics in depth¶

What this session is¶

About ninety minutes. In From Scratch you used generics - List<String>, Map<String, Integer> - as type-safe containers. This session is about writing generic code: generic methods and classes, bounded type parameters, wildcards (the ? you've seen and maybe feared), the PECS rule that makes wildcards make sense, and the truth about type erasure - what generics actually compile to, and the surprising limits that follow. By the end you'll write generic APIs with confidence and read the gnarliest generic signatures in the JDK.

Why generics exist: the problem they solve¶

Before generics (Java 1.4 and earlier), containers held Object, and you cast on the way out:

List names = new ArrayList();        // a list of... something
names.add("Alice");
names.add(42);                       // oops, nobody stopped me
String first = (String) names.get(0);   // cast required
String second = (String) names.get(1);  // ClassCastException at runtime!

Two problems: no compiler help (you could put anything in), and casts everywhere (verbose and error-prone). Generics fix both:

List<String> names = new ArrayList<>();
names.add("Alice");
names.add(42);                       // COMPILE ERROR - caught immediately
String first = names.get(0);         // no cast - the compiler knows it's a String

The core idea: generics move type errors from runtime to compile time, and remove casts. A List<String> is a promise, checked by the compiler, that only strings go in and only strings come out.

Generic methods¶

You can make a single method generic by declaring a type parameter before the return type:

// <T> declares a type parameter. The method works for any T.
static <T> T firstOrNull(List<T> list) {
    return list.isEmpty() ? null : list.get(0);
}

String s = firstOrNull(List.of("a", "b"));   // T inferred as String
Integer n = firstOrNull(List.of(1, 2, 3));   // T inferred as Integer

The <T> before the return type says "this method introduces a type variable T." The caller never specifies it - the compiler infers T from the arguments. One method, type-safe for every type.

A two-parameter example:

// Swap returns a new pair with elements swapped.
static <A, B> Map.Entry<B, A> swap(Map.Entry<A, B> entry) {
    return Map.entry(entry.getValue(), entry.getKey());
}

Convention: type parameters are single uppercase letters - T (type), E (element), K/V (key/value), R (result), N (number). Multiple are comma-separated: <A, B>.

Generic classes¶

A class can be parameterized too - every instance fixes the type:

// A simple immutable box holding one value of type T.
final class Box<T> {
    private final T value;
    Box(T value)        { this.value = value; }
    T get()             { return value; }
    <R> Box<R> map(java.util.function.Function<T, R> f) {
        return new Box<>(f.apply(value));    // transform T into R
    }
}

Box<String> b = new Box<>("hello");
Box<Integer> len = b.map(String::length);    // Box<String> -> Box<Integer>
System.out.println(len.get());               // 5

Box<T> is type-safe: a Box<String> only ever holds a string. The map method even introduces its own type parameter R so it can transform the box's type. This is exactly how Optional<T> and Stream<T> are built.

Bounded type parameters: extends¶

Sometimes a generic method needs to do something with T, not just store it. To call methods on T, you must constrain it. <T extends SomeType> says "T can be any type that is a SomeType."

// To find the max, T must be Comparable - we need compareTo.
static <T extends Comparable<T>> T max(List<T> list) {
    T best = list.get(0);
    for (T item : list) {
        if (item.compareTo(best) > 0) best = item;   // compareTo available now
    }
    return best;
}

max(List.of(3, 1, 2));            // works - Integer is Comparable
max(List.of("c", "a", "b"));      // works - String is Comparable
// max(List.of(new Object()));    // COMPILE ERROR - Object isn't Comparable

Without the bound, item.compareTo(best) wouldn't compile - the compiler only knows the methods guaranteed by the bound. <T extends Comparable<T>> unlocks compareTo. Note extends here means "is a subtype of," and it works for both classes and interfaces (you always write extends, never implements, in a bound).

You can have multiple bounds with &:

// T must be both Comparable AND Serializable.
static <T extends Comparable<T> & java.io.Serializable> T pick(T a, T b) {
    return a.compareTo(b) >= 0 ? a : b;
}

Wildcards: ?¶

Here's where people get lost. Consider:

static double sumOfList(List<Number> list) {
    double sum = 0;
    for (Number n : list) sum += n.doubleValue();
    return sum;
}

List<Integer> ints = List.of(1, 2, 3);
sumOfList(ints);   // COMPILE ERROR (!)

Surprise: a List<Integer> is not a List<Number>, even though Integer is a Number. Generics are invariant - List<Integer> and List<Number> are unrelated types. (If they were related, you could add a Double to a List<Number> that's really a List<Integer>, breaking type safety. The invariance protects you.)

To accept "a list of Number or any subtype," use a wildcard:

static double sumOfList(List<? extends Number> list) {   // ? extends Number
    double sum = 0;
    for (Number n : list) sum += n.doubleValue();
    return sum;
}

sumOfList(List.of(1, 2, 3));          // List<Integer> - works
sumOfList(List.of(1.5, 2.5));         // List<Double>  - works
sumOfList(List.of(1, 2.5));           // List<Number>  - works

? extends Number means "some specific subtype of Number, I don't know which." That's enough to read Numbers out. But there's a catch that leads to the most important rule in generics.

PECS: Producer Extends, Consumer Super¶

There are two wildcard forms, and choosing between them confuses everyone until they learn the mnemonic.

? extends T - an upper-bounded wildcard. "Some subtype of T." You can read T from it (everything is at least a T), but you cannot write to it (you don't know the exact subtype, so no value is safe to add).

List<? extends Number> nums = List.of(1, 2, 3);
Number n = nums.get(0);    // OK to read - it's at least a Number
// nums.add(4);            // COMPILE ERROR - could be a List<Double>, can't add an Integer

? super T - a lower-bounded wildcard. "Some supertype of T." You can write a T to it (a T fits in any supertype container), but reading gives you only Object (you don't know which supertype).

List<? super Integer> sink = new ArrayList<Number>();
sink.add(42);              // OK to write - an Integer fits in a List of any Integer-supertype
// Integer x = sink.get(0);  // COMPILE ERROR - could be List<Object>, read gives Object
Object o = sink.get(0);    // only this works

The mnemonic, from Joshua Bloch's Effective Java:

PECS: Producer Extends, Consumer Super.

• If a parameter produces values for you (you read from it), use ? extends T.
• If a parameter consumes values you give it (you write to it), use ? super T.

The classic example is Collections.copy, which reads from a source (producer) and writes to a destination (consumer):

static <T> void copy(List<? super T> dest, List<? extends T> src) {
    //                      consumer (super)        producer (extends)
    for (int i = 0; i < src.size(); i++) {
        dest.set(i, src.get(i));   // read from src (T), write to dest (super T)
    }
}

src is a producer - we read Ts out, so extends. dest is a consumer - we write Ts in, so super. This signature lets you copy a List<Integer> into a List<Number>, which the rigid List<T>, List<T> version couldn't.

When do you use a plain ? (unbounded wildcard)? When you don't care about the type at all - you only use methods that don't depend on it:

static void printSize(List<?> list) {   // any list, of anything
    System.out.println("size: " + list.size());   // size() doesn't care about type
}

Type erasure: the truth about generics¶

Now the part that explains every weird limit of Java generics. Generics are a compile-time feature only. After the compiler checks your types and inserts casts, it erases the type parameters. At runtime, a List<String> and a List<Integer> are both just List. The <String> is gone.

List<String> a = new ArrayList<>();
List<Integer> b = new ArrayList<>();
System.out.println(a.getClass() == b.getClass());   // true - both are just ArrayList

Why did Java do this? Backward compatibility. Generics arrived in Java 5 (2004), and erasure let generic code interoperate with the mountain of pre-generics code. The cost is a set of limitations you have to know:

1. You can't check a generic type at runtime.

// if (list instanceof List<String>)   // COMPILE ERROR - type info is erased
if (list instanceof List<?>)           // OK - can only check the raw type

2. You can't create an array of a generic type.

// T[] arr = new T[10];        // COMPILE ERROR
// List<String>[] arr = ...    // COMPILE ERROR
T[] arr = (T[]) new Object[10]; // workaround: create Object[], cast (unchecked warning)

3. You can't use primitives as type arguments.

// List<int> nums;             // COMPILE ERROR
List<Integer> nums;            // must use the wrapper - and pay autoboxing (chapter 12)

4. Overloading on erased types collides.

// These two methods erase to the same signature - won't compile together:
// void process(List<String> s) {}
// void process(List<Integer> i) {}   // COMPILE ERROR - both erase to process(List)

5. A class can't have static state per type parameter - because there's only one class at runtime, shared across all T.

The mental model: the compiler uses the type parameters to check your code and insert casts, then throws them away. Everything generics can and can't do follows from this. When a generic limitation surprises you, ask "what's left after erasure?" and the answer usually explains it.

Reading scary JDK signatures¶

Armed with all this, you can decode signatures that look terrifying. Here's Stream.collect:

<R, A> R collect(Collector<? super T, A, R> collector)

Decoded: it introduces two type variables R (the result) and A (an internal accumulator). It takes a Collector that consumes the stream's elements (? super T - consumer, super) and produces an R. You don't need to memorize it - you can read it now.

And Comparator.comparing:

static <T, U extends Comparable<? super U>> Comparator<T> comparing(
        Function<? super T, ? extends U> keyExtractor)

Decoded: for a type T to compare and a key type U that is comparable (U extends Comparable<? super U> - U can be compared against itself or a supertype), take a function that consumes a T (? super T) and produces a comparable key (? extends U). PECS everywhere. Intimidating until you have the vocabulary; routine once you do.

Try it¶

1. Write a generic method. Implement static <T> List<T> repeat(T item, int n) that returns a list with item repeated n times. Call it with a String and an Integer; note the type is inferred.

2. Feel invariance. Write void addNumbers(List<Number> list). Try to pass a List<Integer>. Watch it fail to compile. Change the parameter to List<? super Integer> and add integers to it. Now it works - that's the consumer (super) case.

3. PECS in practice. Write static <T> void moveAll(List<? extends T> from, List<? super T> to) that adds every element of from to to. Test it copying a List<Integer> into a List<Number>. Try swapping extends and super and watch the compile errors - they teach you which side reads and which writes.

4. Hit erasure. Try to write static <T> T[] makeArray(int n) { return new T[n]; }. Read the compile error. Then try (T[]) new Object[n] and note the unchecked warning. Reason about why the JVM can't make a real T[].

5. Bounded type. Write static <T extends Comparable<T>> T min(T a, T b). Use it on Strings and Integers. Remove the bound and watch compareTo stop compiling - the bound is what unlocks the method.

6. Decode a signature. Open the JDK docs for Map.computeIfAbsent. Read its signature out loud, naming each type variable and wildcard. You should be able to explain every symbol now.

What you might wonder¶

"When do I write <T extends Comparable<T>> vs <T extends Comparable<? super T>>?" The ? super T version is more flexible - it allows T to be comparable against a supertype (e.g., a Timestamp that's Comparable<Date>). For your own code, <T extends Comparable<T>> is usually fine and simpler. The JDK uses the ? super T form for maximum flexibility in public APIs. Start simple; widen to ? super T if a real type forces you.

"Do I need wildcards in my own code, or just to read the JDK?" Both, but reading first. You'll use wildcard-typed APIs constantly (every stream collector). You'll write wildcards when you make utility methods that work across a type family - which is less often, but PECS is the rule when you do. If a method only reads a collection, take ? extends; if it only writes, take ? super; if both, take an exact <T>.

"Is erasure why I get 'unchecked cast' warnings?" Yes. When you cast to a generic type the runtime can't verify (like (T[]) new Object[n] or (List<String>) someRawList), the compiler warns it can't guarantee safety - because the type info is erased and it can't insert a real check. Suppress with @SuppressWarnings("unchecked") only when you've reasoned that it's actually safe.

"Why can other languages (C#, Rust) do things Java generics can't?" C# reifies generics - the type info survives to runtime, so new T[n] and typeof(List<int>) work. Rust monomorphizes - it generates a specialized copy per concrete type. Java chose erasure for backward compatibility in 2004. Each approach trades off differently; erasure's cost is the limitations above, its benefit was seamless interop with a decade of existing code. (This exact comparison is a cross-topic page on the site if you want the three-language view.)

"What's the diamond operator <> actually doing?" new ArrayList<>() lets the compiler infer the type argument from the left-hand side (List<String> x = new ArrayList<>() infers String). Before Java 7 you had to write new ArrayList<String>() redundantly. It's pure inference convenience - no runtime effect.

Done¶

• You know why generics exist: compile-time type safety, no casts.
• You can write generic methods and generic classes, including ones that transform their type.
• You can bound type parameters with extends (and &) to unlock methods on T.
• You understand invariance, both wildcard forms, and PECS - producer extends, consumer super.
• You understand type erasure and the five limitations that follow from it.
• You can read intimidating JDK generic signatures.

Next: collections deep - which one to reach for, the performance characteristics, and the families that matter.

Next: Collections deep →

05 - Collections deep¶

What this session is¶

About ninety minutes. In From Scratch you used List, Set, and Map. This session is about choosing the right one - because Java gives you a dozen implementations, each with different performance characteristics, and reaching for the wrong one is one of the most common quiet performance bugs. By the end you'll know which collection to use for any situation and why, with the Big-O costs in your head.

The map of the collections framework¶

Everything descends from a few interfaces. Hold this picture:

Iterable
  └─ Collection
       ├─ List      - ordered, indexed, allows duplicates
       ├─ Set       - no duplicates
       └─ Queue/Deque - ordered for adding/removing at ends

Map (separate hierarchy - not a Collection)
  └─ key -> value pairs, unique keys

You program to the interface (List, Set, Map) and choose the implementation (ArrayList, HashSet, HashMap) based on performance needs. This is "program to interfaces" (chapter 01) in daily practice:

List<String> names = new ArrayList<>();   // declare interface, pick implementation
Map<String, Integer> counts = new HashMap<>();

If you later need a different implementation, you change one word (new ArrayList<>() to new LinkedList<>()) and nothing else, because all callers depend on List.

Lists: ArrayList vs LinkedList¶

Both are Lists. They perform completely differently.

ArrayList is a growable array. Elements live in a contiguous block of memory.

LinkedList is a doubly-linked list. Each element is a separate node with pointers to its neighbors.

The practical verdict: use ArrayList by default. Always. Its O(1) random access and cache-friendly contiguous memory beat LinkedList for almost everything real code does, even insertion-heavy work, because CPU cache locality matters more than the Big-O suggests. LinkedList's only real edge is constant-time add/remove at both ends - and for that, ArrayDeque (below) is faster anyway.

In practice: reach for LinkedList almost never. The fact that beginner tutorials present them as equal alternatives is misleading. ArrayList is the answer ~95% of the time.

Sets: HashSet vs LinkedHashSet vs TreeSet¶

A Set holds unique elements. Three implementations, three tradeoffs:

HashSet - backed by a HashMap. O(1) add/contains/remove. No order - iteration order is unspecified and can change. Use when you just need uniqueness and fast membership tests.

Set<String> seen = new HashSet<>();
seen.add("a"); seen.add("b"); seen.add("a");
System.out.println(seen.size());          // 2 - duplicate ignored
System.out.println(seen.contains("a"));   // true, O(1)

LinkedHashSet - like HashSet but remembers insertion order. Slightly more memory (it maintains a linked list through the entries). Use when you need uniqueness and predictable iteration order.

Set<String> ordered = new LinkedHashSet<>();
ordered.add("c"); ordered.add("a"); ordered.add("b");
// iterates c, a, b - insertion order, every time

TreeSet - keeps elements sorted (by natural order or a Comparator). O(log n) add/contains/remove - slower than hash sets, but you get sorted iteration and range queries (first(), last(), headSet(), subSet()).

TreeSet<Integer> sorted = new TreeSet<>(List.of(5, 1, 3, 2, 4));
System.out.println(sorted);             // [1, 2, 3, 4, 5] - always sorted
System.out.println(sorted.first());     // 1
System.out.println(sorted.headSet(3));  // [1, 2] - everything below 3

The decision: HashSet for plain uniqueness (fastest). LinkedHashSet when iteration order must match insertion. TreeSet when you need sorted order or range queries (and can pay O(log n)).

Critical reminder from chapter 03: HashSet and LinkedHashSet depend on correct equals/hashCode. TreeSet depends on correct compareTo/Comparator. A broken contract silently breaks the set.

Maps: the workhorse family¶

Map is the most-used collection after List. Same three flavors as sets, for the same reasons (sets are literally implemented on maps):

HashMap - O(1) get/put/remove, no order. The default map. Use it unless you need order.

LinkedHashMap - insertion-order (or access-order) iteration. The access-order mode makes it a ready-made LRU cache:

// Access-order LinkedHashMap that evicts the least-recently-used entry past capacity.
var lru = new LinkedHashMap<String, String>(16, 0.75f, true) {
    protected boolean removeEldestEntry(Map.Entry<String, String> eldest) {
        return size() > 100;     // keep at most 100 entries
    }
};

TreeMap - sorted by key, O(log n). Gives you firstKey(), lastKey(), floorKey(), ceilingKey(), subMap() - range queries on keys.

TreeMap<Integer, String> byScore = new TreeMap<>();
byScore.put(90, "A"); byScore.put(70, "C"); byScore.put(80, "B");
System.out.println(byScore.firstKey());        // 70
System.out.println(byScore.ceilingKey(75));    // 80 - smallest key >= 75

The decision mirrors sets: HashMap by default; LinkedHashMap for ordered iteration or LRU; TreeMap for sorted keys / range queries.

The modern Map methods you should be using¶

Pre-Java-8 map code is full of get-check-put patterns. Modern methods replace them:

Map<String, Integer> counts = new HashMap<>();

// Counting - the classic. Old way: get, null-check, put.
for (String word : words) {
    counts.merge(word, 1, Integer::sum);   // add 1, or start at 1 if absent
}

// Grouping into lists without the null dance:
Map<String, List<String>> byFirstLetter = new HashMap<>();
for (String name : names) {
    String key = name.substring(0, 1);
    byFirstLetter.computeIfAbsent(key, k -> new ArrayList<>()).add(name);
}

// Default for missing keys:
int n = counts.getOrDefault("missing", 0);   // 0 instead of null

// Compute only if present:
counts.computeIfPresent("apple", (k, v) -> v * 2);

merge, computeIfAbsent, getOrDefault, putIfAbsent, computeIfPresent - learn these five. They turn five-line patterns into one line and avoid a whole class of null bugs.

Queues and Deques: ArrayDeque and PriorityQueue¶

ArrayDeque - a double-ended queue backed by a resizable array. Add/remove at both ends in O(1). This is your stack and your queue - faster than the legacy Stack (chapter 01's cautionary tale) and faster than LinkedList for the same job.

Deque<Integer> stack = new ArrayDeque<>();
stack.push(1); stack.push(2);
stack.pop();                 // 2 - LIFO, this is a stack

Deque<Integer> queue = new ArrayDeque<>();
queue.offer(1); queue.offer(2);
queue.poll();                // 1 - FIFO, this is a queue

Use ArrayDeque whenever you need a stack or a queue. Never use the legacy Stack class.

PriorityQueue - a heap. poll() always returns the smallest element (by natural order or Comparator), in O(log n). Use for "always process the most urgent next":

PriorityQueue<Integer> pq = new PriorityQueue<>();
pq.addAll(List.of(5, 1, 3, 2));
pq.poll();   // 1 - smallest first
pq.poll();   // 2

// Max-heap with a reversed comparator:
var maxHeap = new PriorityQueue<Integer>(Comparator.reverseOrder());

Iteration and the fail-fast trap¶

A bug everyone hits once: modifying a collection while iterating it.

List<String> list = new ArrayList<>(List.of("a", "b", "c"));
for (String s : list) {
    if (s.equals("b")) list.remove(s);   // ConcurrentModificationException!
}

The for-each loop uses an iterator, and most collections are fail-fast: they detect structural modification during iteration and throw ConcurrentModificationException rather than silently corrupting. (The name is misleading - it happens single-threaded too.) Three correct ways to remove during iteration:

// 1. Iterator.remove() - the explicit way
Iterator<String> it = list.iterator();
while (it.hasNext()) {
    if (it.next().equals("b")) it.remove();
}

// 2. removeIf - the modern one-liner
list.removeIf(s -> s.equals("b"));

// 3. Collect what to remove, remove after the loop

removeIf is almost always the right answer. Reach for it.

Immutable and unmodifiable collections¶

Three ways to get a read-only collection, with different guarantees:

// 1. List.of / Set.of / Map.of - truly immutable, can't be changed by anyone (Java 9+)
List<String> a = List.of("x", "y");        // a.add(...) throws UnsupportedOperationException

// 2. List.copyOf - immutable snapshot of an existing collection
List<String> b = List.copyOf(existing);    // independent, immutable

// 3. Collections.unmodifiableList - a read-only VIEW (the backing list can still change!)
List<String> c = Collections.unmodifiableList(backing);
// you can't change c directly, but if someone changes `backing`, c reflects it

The trap is #3: an unmodifiable view doesn't copy - it wraps. If the underlying collection changes, the view changes. For real immutability (chapter 03), use List.of or List.copyOf, which fully decouple. Return List.copyOf(...) from getters to protect your internal collections (the defensive-copy lesson from chapter 03).

Choosing: a decision table¶

Print this table mentally. "Which collection?" should take you two seconds.

Try it¶

1. Measure ArrayList vs LinkedList. Build both with 1,000,000 integers. Time get(500_000) a million times on each. The ArrayList will be dramatically faster (O(1) vs O(n)). Then time adding a million elements at the end of each. ArrayList still wins (cache locality). This kills the "LinkedList is for inserts" myth.

2. Word frequency three ways. Count word frequencies in a paragraph using (a) the old get-null-check-put pattern, (b) merge, (c) a stream groupingBy + counting (you'll meet streams next chapter). Compare line counts and readability.

3. Pick the right set. You need to dedupe a list of names but preserve the order they first appeared. Which set? Implement it. Then change the requirement to "deduped and alphabetical" - which set now?

4. Hit the fail-fast. Reproduce the ConcurrentModificationException with a for-each remove. Fix it three ways: Iterator.remove, removeIf, and collect-then-remove. Note which is cleanest.

5. Unmodifiable view trap. Create a backing ArrayList, wrap it with Collections.unmodifiableList. Confirm you can't add to the view. Then add to backing directly and print the view - watch it change. Now do the same with List.copyOf and confirm the copy is truly frozen.

6. TreeMap range query. Put exam scores (key) to names (value) in a TreeMap. Use subMap, ceilingKey, and headMap to answer "who scored between 70 and 90?" and "what's the lowest passing score >= 60?".

What you might wonder¶

"Is LinkedList ever the right choice?" Rarely. If you need a List and frequent O(1) add/remove at both ends and you specifically need List semantics (indexed-ish access via iterator), maybe. But ArrayDeque covers the both-ends case better, and ArrayList covers everything else. In years of Java you'll reach for LinkedList a handful of times, usually then reconsider.

"HashMap initial capacity - should I set it?" If you know roughly how many entries you'll add, yes: new HashMap<>(expectedSize / 0.75 + 1) avoids rehashing as it grows (same idea as pre-sizing an ArrayList). For small maps it doesn't matter. For large ones built in a hot path, it's a real win - same lesson as the Go pre-sizing chapter if you've seen it.

"What's the load factor (0.75)?" A HashMap resizes when it's 75% full, to keep collisions low. 0.75 is the default sweet spot between memory and speed. You almost never change it. It's the second constructor arg you saw in the LRU example.

"Are these collections thread-safe?" No - ArrayList, HashMap, etc. are not safe for concurrent modification. That's a chapter 10 topic (ConcurrentHashMap, CopyOnWriteArrayList, and friends). For now: a plain HashMap shared across threads without synchronization is a bug, even if it seems to work in testing.

"Vector and Hashtable - what about those?" Legacy, from Java 1.0. They're synchronized (slow) versions of ArrayList/HashMap. Don't use them in new code. If you need thread safety, use the java.util.concurrent collections (chapter 10), not these. They survive only for backward compatibility - the same "sediment" the Java Mastery path's legacy appendix covers.

"Should I always use List.of for constants?" Yes for fixed, never-changing collections - it's immutable, compact, and clear. Just remember List.of rejects nulls and is immutable, so don't use it where you need to mutate or store nulls.

Done¶

• You know the framework map: List, Set, Queue/Deque, Map.
• You know ArrayList is the default list and why LinkedList rarely wins.
• You can choose among HashSet/LinkedHashSet/TreeSet and the matching Map trio by their order and performance tradeoffs.
• You know ArrayDeque for stacks/queues and PriorityQueue for "most urgent first."
• You know the modern map methods (merge, computeIfAbsent, ...) and the fail-fast iteration trap.
• You know unmodifiable views vs truly immutable collections.
• You have the decision table in your head.

Next: exceptions done right - the strategy for checked vs unchecked, custom hierarchies, and clean error handling.

Next: Exceptions done right →

06 - Exceptions done right¶

What this session is¶

About ninety minutes. From Scratch taught you try/catch/finally - the mechanics. This session is about the strategy: checked vs unchecked (Java's most-debated design decision), designing exception types, try-with-resources properly, exception chaining, and the anti-patterns that turn error handling into a liability. By the end you'll handle errors like someone who's maintained a large codebase, not someone who wraps everything in try { } catch (Exception e) { }.

The exception hierarchy¶

Every error in Java is a Throwable. The tree matters because it drives the rules:

Throwable
  ├─ Error                  - JVM-level catastrophes. Don't catch these.
  │    └─ OutOfMemoryError, StackOverflowError, ...
  └─ Exception              - things programs can reasonably handle
       ├─ RuntimeException  - UNCHECKED. Programming errors, usually.
       │    └─ NullPointerException, IllegalArgumentException,
       │       IllegalStateException, IndexOutOfBoundsException, ...
       └─ (everything else) - CHECKED. The compiler forces you to handle these.
            └─ IOException, SQLException, ...

Two splits to internalize:

1. Error vs Exception. Error means the JVM is in trouble (out of memory, stack overflow). You generally cannot meaningfully recover, so you don't catch them. Exception is for conditions a program can handle.

2. Checked vs unchecked. This is the big one. RuntimeException and its subclasses are unchecked - the compiler doesn't force you to handle them. Everything else under Exception is checked - the compiler forces you to either catch it or declare throws it. This single distinction shapes how all Java error handling reads.

Checked vs unchecked: the strategy¶

// Checked: the compiler MAKES you deal with IOException.
void readFile(String path) throws IOException {   // declare it...
    Files.readString(Path.of(path));
}
// or catch it:
void readFileSafe(String path) {
    try {
        Files.readString(Path.of(path));
    } catch (IOException e) {
        // handle
    }
}

// Unchecked: no compiler obligation. You CAN catch it, but aren't forced to.
void parse(String s) {
    int n = Integer.parseInt(s);   // throws NumberFormatException (unchecked) - no try needed
}

The design intent:

• Checked exceptions = "recoverable conditions the caller should consciously handle." A file might not exist; a network call might fail. The compiler forces the caller to acknowledge the possibility.
• Unchecked exceptions = "programming errors that shouldn't happen if the code is correct." A null where one shouldn't be, an index out of range, an illegal argument. Forcing callers to catch these everywhere would drown the code.

In practice, the Java community has drifted toward using unchecked exceptions for most things. Checked exceptions sound good but have real costs: they leak through every layer (a low-level IOException forces throws clauses all the way up), they don't compose with lambdas/streams (a lambda can't throw a checked exception that the functional interface doesn't declare), and they tempt developers into the worst anti-pattern (catch-and-ignore) just to make the compiler stop complaining.

The pragmatic guidance most modern Java follows:

Use unchecked exceptions (extend RuntimeException) by default. Use checked exceptions only when the caller can realistically recover and you want to force them to think about it.

Many influential libraries (Spring, and most modern frameworks) use unchecked exceptions almost exclusively, often wrapping checked ones. You'll still handle checked exceptions constantly (the JDK is full of them - IOException, SQLException), but when designing your own exceptions, default to unchecked.

Choosing and throwing the right exception¶

The JDK provides standard unchecked exceptions - use them instead of inventing your own for common cases:

void setAge(int age) {
    if (age < 0)
        throw new IllegalArgumentException("age must be non-negative, got " + age);
    this.age = age;
}

void withdraw(double amount) {
    if (closed)
        throw new IllegalStateException("account is closed");   // wrong object state
    if (amount > balance)
        throw new IllegalArgumentException("insufficient funds");
}

String get(int index) {
    Objects.checkIndex(index, size);   // throws IndexOutOfBoundsException with a good message
    return data[index];
}

void process(Order order) {
    Objects.requireNonNull(order, "order must not be null");   // throws NPE with a message
    // ...
}

The standard ones and when to throw them:

• IllegalArgumentException - a method argument is invalid (negative age, empty string where one's required).
• IllegalStateException - the object is in the wrong state for this call (using a closed resource, calling next() past the end).
• NullPointerException - a required value was null. Use Objects.requireNonNull(x, "msg") to throw it early with a message rather than letting a confusing NPE surface deep in the call.
• IndexOutOfBoundsException - an index is out of range. Objects.checkIndex does this with a good message.
• UnsupportedOperationException - an operation isn't supported (the chapter 01 sign of inheritance abuse, but also legitimately used by immutable collections).

Always include a useful message. throw new IllegalArgumentException() tells the next debugger nothing. throw new IllegalArgumentException("age must be non-negative, got " + age) tells them exactly what went wrong and what the bad value was. The message is the gift you give your future self at 2 AM.

Designing custom exceptions¶

When the standard exceptions don't fit - when callers need to distinguish your error type to handle it specifically - design your own. Keep them unchecked unless you have a recovery reason.

// A focused, unchecked domain exception.
public class PaymentException extends RuntimeException {
    private final String orderId;

    public PaymentException(String orderId, String message, Throwable cause) {
        super(message, cause);     // pass message AND cause to super (chaining - see below)
        this.orderId = orderId;
    }

    public String orderId() { return orderId; }
}

For a family of related errors, use a small hierarchy so callers can catch broadly or narrowly:

public class PaymentException extends RuntimeException { /* ... */ }
public class CardDeclinedException extends PaymentException { /* ... */ }
public class InsufficientFundsException extends PaymentException { /* ... */ }

// Caller chooses granularity:
try {
    processPayment(order);
} catch (CardDeclinedException e) {
    promptForNewCard();                  // handle this specific case
} catch (PaymentException e) {
    abortCheckout(e.orderId());          // handle the whole family
}

Catch blocks are checked top to bottom, so order subclasses before superclasses - if PaymentException came first, CardDeclinedException would be unreachable (compile error, helpfully).

Design principles for custom exceptions:

• Carry structured data the handler needs (the orderId above), not just a string. This is the chapter 03 lesson - an exception is an object; put useful fields on it.
• Keep the hierarchy shallow and meaningful. Two or three levels max.
• Always provide a constructor that accepts a cause (Throwable) so chaining works.

Try-with-resources, properly¶

Anything that holds an external resource (a file, a socket, a database connection) must be closed, even if an exception is thrown mid-use. The old way - finally blocks - was verbose and error-prone:

// The old, painful way - don't write this anymore.
BufferedReader r = null;
try {
    r = new BufferedReader(new FileReader("data.txt"));
    return r.readLine();
} finally {
    if (r != null) r.close();   // and close() itself can throw, masking the real error...
}

Try-with-resources handles all of it. Any object implementing AutoCloseable declared in the try (...) header is automatically closed when the block exits - normally or via exception, in reverse order of declaration:

try (BufferedReader r = new BufferedReader(new FileReader("data.txt"))) {
    return r.readLine();
}   // r.close() called automatically, even if readLine() throws

Multiple resources, closed in reverse:

try (var in = new FileInputStream("src");
     var out = new FileOutputStream("dst")) {
    in.transferTo(out);
}   // out closed first, then in - reverse of declaration order