# Java From Zero
> Learn Java from nothing to genuinely advanced: install the JDK and the basics - types, classes, objects, collections - then the deep half: generics, lambdas and streams, modern records and pattern matching, concurrency, the JVM and its garbage collector, testing, and performance. Mental-model-first, with clear explanations.
---
# Java From Zero
Java has been quietly running the world for thirty years. It's behind Android apps, the backends of
most large banks and enterprises, Minecraft, and an enormous share of the systems that move money and
data around the planet. That longevity comes from a deliberate bet: write once, run anywhere - your code
compiles to bytecode that runs on the **JVM** (Java Virtual Machine), the same on a laptop, a server, or
a phone. Java values stability, readability, and tooling over cleverness, which is exactly why teams keep
choosing it for software that has to keep working for a decade.
This guide takes you the whole way: from "I've never run `javac`" to understanding what Java and its
runtime are *actually doing* underneath your code. We go mental-model-first the whole way: before any
command, you'll understand what the thing actually *is* and why Java made the choice it did.
> π This guide teaches the **language**. If you've never programmed at all, start with
> [Programming From Zero](/guides/programming-from-zero) first - it covers the universal ideas (what a
> program is, variables, loops) every language shares. Then come back here.
It's one zero-to-hero journey in two halves. **Phases 1β9 are the basics** - enough to write real,
well-organized object-oriented programs. **Phases 10β17 are the deep half** - generics, lambdas and
streams, modern Java (records, sealed types, pattern matching), concurrency, the JVM and garbage
collector, testing, and performance, the stuff that separates "writes Java" from "understands Java."
Each phase carries a difficulty badge so you can see the climb.
## How to read this
- **Brand new to Java?** Read 1β9 in order, top to bottom - each builds on the last. Type the examples
yourself; doing beats reading. Come back for 10+ when the basics feel comfortable.
- **Already know another language?** Skim phases 1β4 for Java's spelling of ideas you have, then slow
down at [Phase 5: Classes & Objects](05-classes-and-objects.md) - object-orientation is Java's whole
worldview, and everything after it assumes you think in objects.
- **Past the basics already?** Jump to the deep half - [Phase 10: Generics, Deep](10-generics-deep.md)
onward is where Java stops being "a verbose OOP language" and becomes one you can reason about down to
the garbage collector.
## The phases
**Part 1 - The basics (π’ Basic β π‘ Intermediate)**
1. **[Install & Your First Program](01-install-and-first-program.md)** π’ - the JDK, `javac`/`java`, the JVM, a real `Hello`.
2. **[Syntax, Values & Types](02-syntax-values-and-types.md)** π’ - primitives vs objects, `var`, static typing, strings.
3. **[Collections](03-collections.md)** π’ - arrays, `List`/`ArrayList`, `Map`/`HashMap`, `Set`, and generics for collections.
4. **[Control Flow & Methods](04-control-flow-and-methods.md)** π’ - `if`/`switch`/loops, methods, and overloading.
5. **[Classes & Objects](05-classes-and-objects.md)** π‘ - **Java's whole worldview:** classes, fields, constructors, `this`, encapsulation.
6. **[Inheritance & Interfaces](06-inheritance-and-interfaces.md)** π‘ - `extends`, interfaces, polymorphism, and `abstract`.
7. **[Errors & I/O](07-errors-and-io.md)** π‘ - checked vs unchecked exceptions, `try`/`catch`/`finally`, try-with-resources, files.
8. **[Packages, Build & Tooling](08-packages-and-tooling.md)** π‘ - packages, the classpath, Maven/Gradle, JARs, the ecosystem.
9. **[Idioms & Gotchas](09-idioms-and-gotchas.md)** π‘ - the Java way, and the traps (`null`, `==` vs `equals`, autoboxing) that bite everyone once.
**Part 2 - Beyond the basics (π΄ Advanced)**
10. **[Generics, Deep](10-generics-deep.md)** π΄ - bounded types, wildcards (`? extends`/`super`), and type erasure.
11. **[Lambdas & Functional Interfaces](11-lambdas-and-functional-interfaces.md)** π‘ - lambdas, method references, and the functional-interface system.
12. **[The Streams API](12-streams-api.md)** π‘ - declarative pipelines: `map`/`filter`/`collect`, laziness, and parallel streams.
13. **[Records, Sealed Types & Modern Java](13-records-and-modern-java.md)** π‘ - records, sealed classes, switch expressions, pattern matching, `Optional`.
14. **[Concurrency & Threads](14-concurrency-and-threads.md)** π΄ - threads, `synchronized`, the memory model, `ExecutorService`, `CompletableFuture`, virtual threads.
15. **[The JVM: Memory, GC & JIT](15-the-jvm-memory-and-gc.md)** π΄ - heap vs stack, the garbage collector, JIT compilation, and class loading.
16. **[Testing, Build & Profiling](16-testing-and-profiling.md)** π‘ - JUnit, table-driven tests, Maven/Gradle deeper, and profiling with JFR.
17. **[Performance & the Ecosystem](17-performance-and-ecosystem.md)** π΄ - cutting allocation/GC pressure, measuring first, and the Java ecosystem.
**Finale**
18. **[Where to Go Next](18-where-to-go-next.md)** π’ - Spring Boot, Android, big data, and what to build.
> Frameworks (Spring Boot, Android, Jakarta EE) are their own world - this guide makes the *language and
> the JVM* make sense, top to bottom.
---
# Install & Your First Program - The JDK, javac & the JVM
Every language asks two things before anything fun happens: get the tools onto your machine, and prove
they work by running one tiny program. Java has a twist in that first program - it doesn't run the way
many languages do, and understanding that twist now saves a hundred moments of confusion later.
## The big idea: Java compiles to bytecode that runs on the JVM
When you "run" a Java program, two separate things happen, potentially on *different machines at different
times*:
1. **Compile.** A tool called `javac` reads your human-written `.java` file and translates it into
**bytecode** - a compact, portable instruction set - saved as a `.class` file. Bytecode is *not*
machine code for your CPU; it's instructions for an imaginary computer.
2. **Run.** A program called the **JVM** (Java Virtual Machine) loads that `.class` file and *executes*
the bytecode, translating it into real instructions for whatever CPU it happens to be sitting on.
That imaginary computer is the key trick: code compiled once into bytecode runs on *any* machine with a
JVM - Windows, macOS, Linux, your phone, a bank mainframe. This is the famous Java promise: **write once,
run anywhere**. You compile for the JVM, and the JVM is the part that's been ported everywhere.
```mermaid
flowchart LR
A[Hello.java source code] -->|javac| B[Hello.class bytecode]
B -->|java| C[JVM]
C --> D[runs on any OS / CPU]
```
*What just happened:* The diagram traces the whole pipeline: `.java` source, `javac` to portable `.class`
bytecode, `java` hands that to the JVM, which runs it on the actual hardware. The `.class` file is the
portable artifact - the same one runs on every JVM.
Three acronyms get mixed up constantly. Pin them down once:
π **JVM** (Java Virtual Machine) - the engine that *executes* bytecode. It's the "imaginary computer"
your code targets. **JRE** (Java Runtime Environment) - the JVM *plus* the standard libraries your code
needs to run; everything required to *run* a Java program, nothing to *build* one. **JDK** (Java
Development Kit) - the JRE *plus* the developer tools: the `javac` compiler, the `java` launcher, a
debugger, and more. Everything required to *build and run*.
π‘ **Key point.** You want the **JDK** - the superset, JVM and libraries included, so it gives you the
compiler *and* the runtime in one go. "Installing just a JRE" only makes sense for shipping software to end
users who run it but don't build it; as a learner, the JDK is your one download.
## Install a JDK
Java is open source; several distributions ship essentially the same thing. The two names you'll see most:
- **OpenJDK** - the open-source reference implementation. Most distributions are builds of this.
- **Oracle JDK** - Oracle's own build. Functionally near-identical for learning, but shifting licensing
terms are why most people reach for a free OpenJDK build instead.
A friendly, free, no-licensing-drama OpenJDK build is **Eclipse Temurin** from
[adoptium.net](https://adoptium.net): grab the installer for your OS (Windows `.msi`, macOS `.pkg`, or a
Linux package) and choose a **LTS** (Long-Term Support) version like 25 (the newest LTS). Accept the installer's defaults;
on Windows, let it add Java to your `PATH` when offered.
Confirm both halves of the JDK are present - the runtime *and* the compiler:
```bash
java -version
javac -version
```
```console
$ java -version
openjdk version "25.0.1" 2025-10-21
OpenJDK Runtime Environment Temurin-25.0.1+9 (build 25.0.1+9)
OpenJDK 64-Bit Server VM Temurin-25.0.1+9 (build 25.0.1+9, mixed mode)
$ javac -version
javac 25.0.1
```
*What just happened:* `java -version` reports the **runtime**; `javac -version` reports the **compiler**.
If *both* answer with a version, you have a complete JDK. The exact numbers will differ over time -
anything Java 17 or newer works for this guide.
β οΈ **Gotcha.** If `java -version` works but `javac -version` says "command not found" / "is not
recognized," you've installed a *JRE only* - you can run Java but not compile it. Reinstall the **JDK**
from Adoptium. If a terminal already open before you installed says `java` isn't found, open a fresh one -
old terminals don't know about the new `PATH`.
## Your first program
Make a file called `Hello.java` - the capital `H` matters, as you'll see shortly - in any folder, with
exactly this:
```java
public class Hello {
public static void main(String[] args) {
System.out.println("Hello, Java!");
}
}
```
*What just happened:* That's a complete Java program - a lot of words for one line of output, but Java is
wordy by design. Naming each piece:
- `public class Hello` - Java organizes all code into **classes** (named bundles of code and data). Every
program needs at least one; `public` means "visible from everywhere." Think of the class as the
container your code lives inside.
- `public static void main(String[] args)` - defines a **method** (a named block of code) called `main`.
This exact signature is the **entry point**, the one method the JVM looks for and runs when your program
starts.
- `System.out.println("Hello, Java!")` - calls `println` ("print line") to write text to the screen,
followed by a newline. `System.out` is the standard output stream that ships with Java.
That `main` signature trips everyone up at first, so briefly, *why* it reads this way: the JVM needs one
agreed-upon "start here" method. `public` so the JVM can reach it from outside the class; `static` so it
can be called *without first creating an object* (more in [Phase 5](05-classes-and-objects.md)); `void`
because it returns nothing; `String[] args` to receive command-line arguments. You'll type this line so
often it becomes muscle memory - just know every part has a job.
Now compile it. From the folder containing `Hello.java`:
```bash
javac Hello.java
```
```console
$ javac Hello.java
$ ls
Hello.class Hello.java
```
*What just happened:* `javac` read your source and, on success, said *nothing* - silence is good news in
the Unix tradition. It produced `Hello.class` next to your source: portable bytecode for the JVM, not for
your CPU. (Not human-readable - open it and you'll see gibberish.)
Then run it - and note you pass `Hello`, the class name, **not** `Hello.class` or `Hello.java`:
```bash
java Hello
```
```console
$ java Hello
Hello, Java!
```
*What just happened:* `java` launched a JVM, loaded the `Hello` class, found `main`, and ran it top to
bottom, printing your line. You give it the *class* name because the JVM thinks in classes, not files; it
finds `Hello.class` on its own. That two-step rhythm - `javac` to build, `java` to run - is the bedrock
workflow under every Java tool you'll ever use.
## The "everything lives in a class" rule
Notice there's no loose code floating at the top of the file - no statement outside a class. That's not a
style choice; it's a rule. In classic Java, *every* line of code lives inside a class - no free-floating
functions or top-level statements like Python or JavaScript allow.
β οΈ **Gotcha - the filename must match the public class.** A file containing `public class Hello` *must*
be named `Hello.java` - same name, same capitalization. Name it `hello.java` or `Main.java` and `javac`
refuses to compile it, with an error like `class Hello is public, should be declared in a file named
Hello.java`. This catches everyone once. The rule exists so the compiler can find any public class by
predicting its filename - but the takeaway is simpler: **public class name = filename**, capital letter
and all.
A note on the future: recent Java *loosens* this, letting you write a stripped-down program
with just a `main` method and no visible class wrapper, to ease beginners in. It was a preview feature in
Java 21-24 and became standard in Java 25 (JEP 512). Even so, essentially all existing Java code uses the
classic `public class { ... }` form, which is what this guide uses and what "Java" means in practice today.
## A smoother workflow
The `javac` β `java` two-step is the real foundation, worth doing by hand once so the pipeline isn't
magic. Day to day, you'll lean on shortcuts:
- **Single-file run (Java 11+).** For a one-file program, you can skip the separate compile step entirely:
```bash
java Hello.java
```
```console
$ java Hello.java
Hello, Java!
```
*What just happened:* Handed a `.java` file directly, `java` compiled it *in memory* and ran it
immediately - no `.class` file left on disk. Fastest way to try a quick idea; under the hood it's still
compile-then-run, you just skipped typing both commands.
- **Real projects use a build tool.** Once a project grows past a file or two - multiple classes, outside
libraries, tests - a **build tool** like **Maven** or **Gradle** manages compiling, dependencies, and
packaging instead of you calling `javac` by hand. Covered in [Phase 8](08-packages-and-tooling.md); for
now plain `javac`/`java` keeps the focus on the language.
- **And an IDE.** Almost everyone writes Java in an IDE - **IntelliJ IDEA** (community edition is free) or
**VS Code** with Java extensions are the popular picks. They compile as you type, underline mistakes
before you run, and turn build-and-run into one button. Pick either.
## Recap
1. Java **compiles to bytecode that runs on the JVM** - `javac` turns `.java` into a portable `.class`,
and the JVM runs that bytecode anywhere, which is what "write once, run anywhere" means.
2. **JDK vs JRE vs JVM:** the JVM *executes* bytecode, the JRE is the JVM plus standard libraries (enough
to *run*), and the JDK is the JRE plus dev tools like `javac` (enough to *build*). Install the **JDK**.
3. Confirm your install with **`java -version`** (runtime) and **`javac -version`** (compiler) - you need
*both* to answer.
4. A program needs a **class** and the special **`public static void main(String[] args)`** entry point;
build with **`javac Hello.java`**, then run with **`java Hello`** (the class name, not the filename).
5. β οΈ **Everything lives in a class**, and the **public class name must match the filename** exactly -
`public class Hello` belongs in `Hello.java`.
6. Shortcuts for later: **`java Hello.java`** runs a single file directly (Java 11+), and real projects
use a **build tool** (Maven/Gradle) plus an **IDE** (IntelliJ/VS Code).
Next: variables, the values they hold, and Java's type system - the rules that decide what fits in what.
## Quick check
Test yourself on the one idea that makes Java *Java* - compile to bytecode, run on the JVM:
```quiz
[
{
"q": "What does `javac` produce, and what runs it?",
"choices": [
"It produces a `.class` bytecode file, which the JVM (via the `java` command) executes",
"It produces a native CPU executable that the OS runs directly",
"It runs the program immediately and produces no file",
"It produces another `.java` file optimized for speed"
],
"answer": 0,
"explain": "`javac` compiles your `.java` source into portable `.class` bytecode. That bytecode isn't machine code - the JVM, launched by the `java` command, loads and executes it on whatever hardware it's running on. That's the compile-then-run, write-once-run-anywhere model."
},
{
"q": "You have a JDK installed. Which is true about JDK, JRE, and JVM?",
"choices": [
"The JDK includes a JRE (and thus a JVM) plus developer tools like `javac`",
"The JRE includes the JDK, so installing a JRE gives you the compiler",
"The JVM is the largest package and contains both the JDK and JRE",
"They are three unrelated downloads you must install separately"
],
"answer": 0,
"explain": "They nest: the JVM executes bytecode; the JRE is the JVM plus standard libraries (enough to run); the JDK is the JRE plus build tools like `javac` (enough to build and run). Installing the JDK gives you everything."
},
{
"q": "Your file contains `public class Hello`. What must the file be named?",
"choices": [
"`Hello.java` - the filename must match the public class name exactly, capitalization included",
"`hello.java` - Java filenames are always lowercase",
"`Main.java` - the file holding `main` must be called Main",
"Anything ending in `.java` - the name doesn't matter"
],
"answer": 0,
"explain": "A public class must live in a file whose name matches it exactly, including the capital letter - `public class Hello` requires `Hello.java`. Mismatch it and `javac` refuses to compile, telling you the file should be named after the class."
}
]
```
---
# Syntax, Values & Types - Primitives, Objects & Static Typing
A program that only prints a fixed greeting is a dead end. Real programs hold values - a name, a count, a
price. In Java, every value has a **type**, enforced strictly enough to feel like paperwork at first - but
it becomes a safety net fast.
The idea that organizes this phase: Java draws a hard line between **primitives** (a small set of types
holding a raw number or true/false directly) and **objects** (everything else, reached through a
reference). Almost every surprise here traces back to which side of that line you're standing on.
## What "statically typed" actually means
**What it is.** Java is **statically typed**: every variable has a fixed type that's written down and
checked when your code is *compiled*, before it ever runs. A variable declared to hold a whole number can
never later hold a piece of text. The compiler refuses to build a program where the types don't line up.
**Why people get this wrong.** Coming from Python or JavaScript, you might expect a variable to be a box
you can drop anything into. In Java it's a box with a *declared shape* - number-shaped, text-shaped - and
the compiler checks everything fits. A whole category of bugs ("I thought this held a number but it held
`"42"`") can't survive to runtime; they're caught while you build.
π **Static typing** - the type of every variable is known and checked at *compile time*, not while the
program runs. "Static" is the opposite of "dynamic," where types are checked as code executes. Java checks
early, so a running program never wonders what type something is.
You declare a variable by writing its type, then its name, then optionally an initial value:
```java
int count = 0;
count = count + 5; // fine: an int going into an int box
count = "hello"; // compile error: incompatible types
```
*What just happened:* `int count = 0;` declares `count` as type `int`, starting at `0`. The second line is
fine - a number into a number box. The third never compiles: the compiler sees text going into a
whole-number box and stops you cold with `incompatible types: String cannot be converted to int`. The
safety net doing its job at build time instead of letting a confused value blow up later.
## Primitives vs objects - the split that explains everything
This is the most important distinction in the phase.
π **Primitive** - a value that holds its data *directly*: the actual number or true/false sits right in
the variable. **Object** (also called a *reference type*) - a value that lives elsewhere in memory; the
variable holds a *reference* (a pointer-like handle) to it, not the thing itself.
Java has exactly **eight** primitive types, the only types that work this way. The ones you'll actually
reach for:
- **`int`** - a whole number (`-3`, `0`, `42`). Default for counting.
- **`double`** - a number with a decimal point (`3.14`, `-0.5`). Default for fractional numbers.
- **`boolean`** - a truth value, `true` or `false`. Named after George Boole.
- **`char`** - a single character, written in *single* quotes (`'A'`, `'7'`).
- **`long`** - a whole number with extra room, for values too big for `int` (literal suffix `L`:
`9_000_000_000L`).
(The other three - `byte`, `short`, `float` - exist for specific low-level needs; ignore them while
learning.)
**Everything that isn't one of those eight is an object.** `String`, arrays, `Scanner`, and every class you
write are reference types, holding a reference to data that lives elsewhere.
**Why this distinction earns its keep.** Two reasons:
1. **Performance.** A primitive is tiny and lives right where it's declared - no indirection, no extra
allocation. Objects carry more overhead.
2. **`null`.** A reference can point at *nothing* - the special value `null`. A primitive *cannot*; an
`int` is always some number, never "missing." That's the root of Java's most famous crash, the
`NullPointerException`, properly met in [Phase 9](09-idioms-and-gotchas.md). For now: primitives can't
be `null`; objects can.
π‘ **Mental model.** A primitive variable *is* the value. An object variable is a *label on a box stored
elsewhere*, and that label can point at nothing. When Java surprises you, ask "primitive or object?" first.
## Wrapper types & autoboxing - the object versions of primitives
Sometimes a primitive needs to behave like an object - most commonly because a collection (a list, a map)
can only hold objects, never raw primitives. For that, every primitive has an **object twin** called a
**wrapper type**: `int` β `Integer`, `double` β `Double`, `boolean` β `Boolean`, `char` β `Character`.
π **Wrapper type** - an object holding a single primitive value. `Integer` wraps an `int`; `Double` wraps
a `double`. Being an object, a wrapper can be stored where only objects are allowed - and, unlike its
primitive, it can be `null`.
The convenient part is **autoboxing**: Java converts between a primitive and its wrapper automatically, so
you rarely write the conversion yourself.
```java
Integer boxed = 42; // autoboxing: int 42 wrapped into an Integer
int unboxed = boxed; // auto-unboxing: Integer back to int
```
*What just happened:* `Integer boxed = 42;` assigns an `int` to an `Integer` - Java silently *boxed* the
primitive `42` into an object. The reverse line *unboxed* it back to a raw `int`; the compiler inserts the
conversion for you. That convenience hides two traps.
β οΈ **A wrapper can be `null`, so unboxing can crash.** Because `Integer` is an object, it can be `null` -
and auto-unboxing a `null` wrapper doesn't give you `0`, it throws a `NullPointerException`.
```java
Integer maybe = null; // perfectly legal - it's an object
int n = maybe; // NullPointerException at runtime when unboxing null
```
*What just happened:* `maybe` is an `Integer`, so `null` is valid for it. The next line unboxes it into a
plain `int` with no number to hand over - Java throws a `NullPointerException`. A plain `int` could never
have gotten you here; it's the `null` risk from the previous section, made concrete.
β οΈ **`==` on wrappers compares references, not values.** This bites everyone exactly once. On primitives,
`==` compares the actual numbers; on *objects* (wrappers included), it asks "are these the same object in
memory?" - a different question, often with a surprising answer.
```java
Integer a = 1000;
Integer b = 1000;
boolean sameValue = (a == b); // false! comparing two distinct objects
boolean reallySame = a.equals(b); // true - equals() compares the values
```
*What just happened:* `a` and `b` both wrap `1000` but are two *separate* `Integer` objects, so `a == b`
asks "same object?" and gets `false`. `.equals()` checks the numbers inside instead. (Java caches small
`Integer`s from -128 to 127, so the same test with `127` would confusingly print `true` - why you should
never rely on `==` for wrappers.) More in [Phase 9](09-idioms-and-gotchas.md); rule for now: **use
`.equals()` to compare objects, save `==` for primitives.**
## `var` - let the compiler infer the type
Writing the type twice - `ArrayList names = new ArrayList();` - gets tedious when it's
already obvious from the right side. Modern Java (10+) lets you write **`var`** instead; the compiler
*infers* the type from the assigned value.
```java
var name = "Ada"; // compiler infers: String
var count = 0; // compiler infers: int
var price = 9.99; // compiler infers: double
```
*What just happened:* `var name = "Ada";` declares `name` and lets the compiler see `"Ada"` is text and
decide `name` is a `String`. The variable is *exactly* as statically typed as if you'd written `String
name` - `var` is shorthand, not a change in how typing works. Try `name = 5;` afterward and you still get a
compile error, because `name`'s type locked to `String` the moment it was inferred.
π‘ **When to reach for `var`.** Use it when the type is plainly visible on the right side, especially to
avoid repeating a long type. Two limits: it only works for **local variables** inside methods (not fields or
parameters), and it needs an initial value to infer *from* - `var x;` alone won't compile. When the right
side is vague (`var result = compute();`), spell the type out for readability.
## Strings - objects, immutable, and never compared with `==`
You've used `String` since Phase 1, but a few facts about it will save you real grief.
**A `String` is an object, not a primitive.** Despite friendly syntax (double quotes, `+`), `String` is a
reference type - everything from the objects section applies to it.
**A `String` is immutable.** Once created, its characters never change - operations that look like they
modify a string actually build and return a *new* one, leaving the original untouched. Concatenate with
`+`:
```java
String first = "Ada";
String full = first + " " + "Lovelace"; // builds a brand-new String
System.out.println(full);
System.out.println(first); // unchanged
```
```console
$ java Strings.java
Ada Lovelace
Ada
```
*What just happened:* `first + " " + "Lovelace"` didn't alter `first`; it assembled a *new* `String` and
stored it in `full`. `first` is still just `"Ada"` - strings can't be mutated in place. Every "string
change" in Java is really "make a new string."
β οΈ **Never compare strings with `==`.** Since `String` is an object, `==` compares *references*, not text.
Two strings with identical characters can live at different memory addresses, so `==` may say `false` even
when they read the same. Always use `.equals()` for *contents*:
```java
String a = "hello";
String b = new String("hello"); // forces a distinct object
System.out.println(a == b); // false - different objects
System.out.println(a.equals(b)); // true - same characters
```
```console
$ java Compare.java
false
true
```
*What just happened:* `a` and `b` hold the same text but are two separate objects (`new String(...)`
guarantees a fresh one). `a == b` compares identity, `false`; `a.equals(b)` compares characters, `true`.
The single most common beginner trap in Java: **`.equals()` for "same thing?", never `==`.** Same rule as
wrappers, same cause - both are objects.
**Text blocks for multi-line strings.** For a string spanning several lines, the triple-quote **text
block** (Java 15+) saves you from a mess of `\n` escapes:
```java
String message = """
Dear Ada,
Welcome to Java.
""";
System.out.print(message);
```
```console
$ java Block.java
Dear Ada,
Welcome to Java.
```
*What just happened:* The `"""..."""` block let you write the message exactly as it should appear, no `\n`
escapes needed. Java strips the common leading indentation (measured from the closing `"""`), so text lines
up cleanly in source *and* output. Same immutable `String` type - just a more readable way to write a long
one.
## Recap
1. Java is **statically typed**: every variable has a declared type the compiler checks at build time, so
type mistakes are caught before the program runs.
2. The big split is **primitives vs objects**. The eight primitives (`int`, `double`, `boolean`, `char`,
`long`, β¦) hold their value directly and are cheap; everything else is an **object** reached by
reference - and only objects can be `null`.
3. **Wrapper types** (`Integer`, `Double`, β¦) are the object twins of primitives; **autoboxing** converts
between them automatically. β οΈ A wrapper can be `null` (unboxing it crashes), and `==` on wrappers
compares references, not values - use `.equals()`.
4. **`var`** lets the compiler infer a local variable's type from its initializer. It's still fully static
- just less typing - and works only for locals with an initial value.
5. **`String` is an immutable object.** Concatenate with `+` (it builds a new string); write multi-line
text with `"""` text blocks.
6. β οΈ **Never compare strings (or any objects) with `==`** - that checks identity. Use `.equals()` to
compare contents.
Next: *collections* of values - arrays, the `List` and `Map` you'll reach for daily, and how generics keep
them type-safe.
## Quick check
Test yourself on the idea driving this phase - which side of the primitive/object line you're on:
```quiz
[
{
"q": "What's the key difference between a primitive like `int` and an object like `Integer`?",
"choices": [
"An `int` holds its value directly and can never be null; an `Integer` is an object reference that can be null",
"There is no difference - `int` and `Integer` are two names for the same thing",
"An `Integer` is faster because it's stored directly in the variable",
"A primitive can be null but an object cannot"
],
"answer": 0,
"explain": "A primitive holds its data directly and is always some value - an `int` is never \"missing.\" `Integer` is a wrapper object reached by reference, so it can be `null`, which is exactly why unboxing a null `Integer` throws a NullPointerException."
},
{
"q": "You have two `String` variables holding the same text. How should you check whether their contents match?",
"choices": [
"Use `a.equals(b)`, because `==` compares object references, not the characters",
"Use `a == b`, which always compares the text of two strings",
"Either works - `==` and `.equals()` do the same thing for strings",
"Convert both to `int` first, then compare with `==`"
],
"answer": 0,
"explain": "`String` is an object, so `==` asks \"is this the same object in memory?\" - which can be false even when the text is identical. `.equals()` compares the actual characters, which is what you almost always want."
},
{
"q": "What does `var name = \"Ada\";` do?",
"choices": [
"Declares a local variable whose type the compiler infers as `String` - still fully static, just less typing",
"Declares a variable with no type, so it can later hold any kind of value",
"Makes `name` dynamically typed, like a Python variable",
"Only works for fields, not for local variables inside methods"
],
"answer": 0,
"explain": "`var` infers the type from the initializer - here `String` - and locks it in. It's pure shorthand: the variable is exactly as statically typed as if you'd written `String name`, and it works only for local variables that have an initial value."
}
]
```
---
# Collections - Arrays, Lists, Maps & Sets
Up to now you've held one value at a time. Real programs deal in *many*: a roster of users, a table of
prices, the unique tags on a post. Java gives you two layers for this - the old, low-level **array**, and
the rich **Collections Framework** on top of it. Newcomers waste energy fighting arrays when they should
reach for a `List`. We'll meet the array, see when it earns its keep, then spend the rest of the phase on
the collections you'll actually use daily.
The mental model: an **array** is a fixed slab of memory you size once and live with. A **collection** is a
smart, growable object that manages that slab for you, letting you ask by *behavior* ("ordered list," "fast
lookup by key") instead of wrestling the memory yourself.
## Arrays - the fixed-size foundation
**What it actually is.** An **array** is a fixed-length sequence of values, all the same type, laid out
back-to-back in memory. You choose the length at creation; it never changes. `int[]` reads as "an array of
ints."
```java
int[] nums = {1, 2, 3};
System.out.println(nums[0]); // first element
System.out.println(nums[2]); // third element
System.out.println(nums.length); // how many slots
```
```console
1
3
3
```
*What just happened:* `{1, 2, 3}` created an array with three slots, already filled. `nums[0]` reads the
**first** element (Java counts from zero), `nums[2]` the third. `nums.length` tells you the size - a
**field, no parentheses**. Reaching past the end (`nums[3]`) throws an `ArrayIndexOutOfBoundsException` -
there's no fourth slot.
The catch is right there in "fixed-length": no `add`. Need more room? Allocate a bigger array and copy
everything by hand - exactly the chore the Collections Framework does for you.
π‘ **When you'd reach for an array.** When the size is known and fixed (the 12 months, an RGB triple), when
you want the leanest memory for primitives, or when an API hands you one. For nearly everything else - it
grows, shrinks, or you're unsure of the size - reach for a `List`, next up and where most of your
collection work lives.
## The Collections Framework - the mental model
The idea that unlocks the rest of Java's collections: the framework splits into two halves.
π **Interfaces vs. implementations.** An **interface** describes *behavior* - what a collection can do,
not how. `List`, `Map`, and `Set` are interfaces. A **concrete class** provides the how; `ArrayList`,
`HashMap`, and `HashSet` are the workhorses. The interface is the *contract*; the class is the *machine*
that fulfills it.
Three interfaces cover almost everything you'll need:
- **`List`** - an *ordered* sequence accessed by position. Duplicates allowed. (Think: a numbered to-do list.)
- **`Map`** - a table of **key β value** pairs looked up by key. (Think: a phone book.)
- **`Set`** - an *unordered* bag of **unique** elements. (Think: the distinct words in a document.)
π‘ **Program to the interface.** Strong Java convention: *type your variable as the interface* but *create
the concrete class*:
```java
List names = new ArrayList<>();
```
The variable is a `List`; the object is an `ArrayList` doing the work. The rest of your code only depends on
"it's a list," so the day a `LinkedList` suits better, you change one line - the `new` - and nothing else
breaks. Coding against the *promise*, not the *machinery*.
The `` part is **generics**: it tells Java "this list holds `String`s and nothing else" - the
feature that makes collections type-safe.
## `List` and `ArrayList` - the growable sequence
**What it actually is.** A `List` is an ordered, indexed sequence - like an array, but growing and shrinking
on demand. `ArrayList` is the implementation you'll use 95% of the time; under the hood it manages a real
array, invisibly reallocating and copying when it fills up.
```java
import java.util.ArrayList;
import java.util.List;
public class Main {
public static void main(String[] args) {
List names = new ArrayList<>();
names.add("Ada");
names.add("Alan");
names.add("Grace");
System.out.println(names.get(0)); // read by index
System.out.println(names.size()); // how many
for (String name : names) { // the for-each loop
System.out.println(name);
}
}
}
```
```console
Ada
3
Ada
Alan
Grace
```
*What just happened:* We declared `names` as a `List` but built an `ArrayList<>()` - programming to
the interface, exactly as above. (The empty `<>` is the "diamond"; Java infers `String` from the left side.)
`add` appended each name to the end. `get(0)` read the first element by index; `size()` reported the count
*with* parentheses, unlike an array's `length` field. The **for-each** loop (`for (String name : names)`)
visited every element in order, no index needed - the cleanest way to walk a collection.
The generics payoff shows up the moment you slip: because `names` is a `List`, this won't compile:
```java
names.add(42); // compile error: int is not a String
```
*What just happened:* The `` is a promise the **compiler enforces**. Adding an `int` is caught
before the program ever runs, not as a surprise crash later - type mistakes become compile-time errors
instead of `ClassCastException`s in production.
## `Map` and `HashMap` - lookup by key
A `List` suits *order* and *position*. But often you want to look something up by *name* - a user's score
by username, a setting's value by its key. That's a `Map`.
**What it actually is.** A `Map` stores **key β value** pairs and fetches a value instantly by key.
`HashMap` is the standard implementation. `Map` reads as "a map from `String` keys to
`Integer` values." (Other languages call this a dictionary, hash, or associative array.)
```java
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) {
Map ages = new HashMap<>();
ages.put("Ada", 36);
ages.put("Alan", 41);
System.out.println(ages.get("Ada")); // look up by key
System.out.println(ages.getOrDefault("Nobody", 0)); // safe default
for (Map.Entry entry : ages.entrySet()) {
System.out.println(entry.getKey() + " -> " + entry.getValue());
}
}
}
```
```console
36
0
Alan -> 41
Ada -> 36
```
*What just happened:* `put` stored two keyβvalue pairs. `get("Ada")` returned `36`. The interesting one is
`getOrDefault("Nobody", 0)`: plain `get` on a missing key returns `null` (often a `NullPointerException` two
lines later), so `getOrDefault` says "give me the value, or this fallback" - here, `0`. To visit every pair,
we looped over `entrySet()`, which hands back each pair as a `Map.Entry` with `getKey()`/`getValue()` - the
standard way to iterate a map.
β οΈ **Gotcha - `get` returns `null` for a missing key.** It does *not* throw. Use the result blindly and a
missing key turns into a `NullPointerException` downstream, far from the real cause. Reach for
`getOrDefault` (or check `containsKey` first) whenever a key might be absent.
## `Set` and `HashSet` - uniqueness, fast
**What it actually is.** A `Set` holds **unique** elements - add the same value twice and the second add is
silently ignored. `HashSet` is the standard implementation, answering "is this in here?" almost instantly.
```java
import java.util.HashSet;
import java.util.Set;
public class Main {
public static void main(String[] args) {
Set tags = new HashSet<>();
tags.add("java");
tags.add("beginner");
tags.add("java"); // duplicate - ignored
System.out.println(tags.size()); // 2, not 3
System.out.println(tags.contains("java")); // fast membership test
}
}
```
```console
2
true
```
*What just happened:* We added `"java"` twice, but the set kept only one copy, so `size()` is `2`.
`contains` checked membership and returned `true` immediately - `HashSet` is built for exactly that "have I
seen this before?" question. Use a `Set` whenever uniqueness is the point: de-duplicating a list, tracking
processed items, testing membership in a hot loop.
π‘ **Picking the right one.** Let the question pick the collection. **Order and position** (or duplicates)?
β `List`. **Lookup by key**? β `Map`. **Uniqueness or fast membership**? β `Set`.
β οΈ **Gotcha - `HashMap` and `HashSet` have no order.** They're optimized for speed, not for preserving
insertion order - iterate one and the order can look scrambled, with no tie to how you inserted. If you need order,
the framework has drop-in replacements: **`LinkedHashMap`/`LinkedHashSet`** preserve *insertion* order, and
**`TreeMap`/`TreeSet`** keep keys *sorted*. Same interfaces, so swapping one in is a one-line change.
## Recap
1. An **array** (`int[]`) is fixed-size and lean - great when the count never changes, awkward when it does.
`.length` is a field, not a method.
2. The **Collections Framework** splits into **interfaces** (`List`, `Map`, `Set` - behavior) and **concrete
classes** (`ArrayList`, `HashMap`, `HashSet` - implementation).
3. **Program to the interface:** `List names = new ArrayList<>();`. Your code depends on the
contract, so swapping implementations costs one line.
4. **`List`/`ArrayList`** is the growable ordered sequence: `add`, `get`, `size`, and the **for-each** loop.
**Generics** (``) make it type-safe at compile time.
5. **`Map`/`HashMap`** does keyβvalue lookup: `put`, `get`, `getOrDefault`, and `entrySet()` to iterate -
but `get` returns `null` for a missing key.
6. **`Set`/`HashSet`** holds unique elements with fast `contains`. β οΈ `HashMap`/`HashSet` are **unordered**;
use `LinkedHashMap`/`TreeMap` (and the `Set` equivalents) when order matters.
Next: making programs *decide* and *organize logic* - `if`/`switch`, loops, and the methods that give Java
code its shape.
## Quick check
Test yourself on the habit that makes Java collections click - choosing by behavior and coding to the
interface:
```quiz
[
{
"q": "Why is `List names = new ArrayList<>();` preferred over `ArrayList names = new ArrayList<>();`?",
"choices": [
"The variable is typed to the List interface, so your code depends on behavior and you can swap the implementation with a one-line change",
"It runs faster because List is a smaller type than ArrayList",
"ArrayList cannot be assigned to a variable at all",
"It automatically makes the list unmodifiable"
],
"answer": 0,
"explain": "Programming to the interface means the rest of your code only knows it has a `List`. The concrete class lives in one place - the `new` - so switching to, say, a `LinkedList` changes that single line and nothing else."
},
{
"q": "You call `ages.get(\"Nobody\")` on a `HashMap` that has no \"Nobody\" key. What happens?",
"choices": [
"It returns `null` (which can cause a NullPointerException downstream) - use `getOrDefault` to avoid this",
"It throws a KeyNotFoundException immediately",
"It returns 0 because the value type is Integer",
"It adds the key with a null value and returns it"
],
"answer": 0,
"explain": "`get` returns `null` for a missing key rather than throwing. That null often blows up later, far from the cause. `getOrDefault(\"Nobody\", 0)` hands back a safe fallback instead."
},
{
"q": "You need to store the distinct tags on a post and quickly check whether a given tag is already present. Which collection fits best?",
"choices": [
"A Set (HashSet) - it keeps elements unique and answers `contains` fast",
"A List (ArrayList) - it preserves insertion order",
"A Map (HashMap) - it stores keyβvalue pairs",
"An array - it has a fixed size"
],
"answer": 0,
"explain": "Uniqueness plus fast membership is exactly what a `Set` is for. A `HashSet` ignores duplicate adds and answers `contains` almost instantly - the right tool when 'is this already in here?' is the core question."
}
]
```
---
# Control Flow & Methods - Decisions, Loops & Reusable Logic
So far your programs have run in a straight line: top to bottom, every statement once. Real programs make
decisions ("if logged in, show the dashboard"), repeat work ("for every order, send a receipt"), and bundle
logic into named pieces you can call again and again. Branching, looping, and methods are the joints that
let a program bend.
The mental model for this phase: **control flow is about choosing which statements run and how often, and
methods are about naming a chunk of statements so you can reuse it.** Everything below is a variation on
those two themes.
## `if` / `else` - making a decision
The most basic branch: give Java a **boolean expression** - something evaluating to `true` or `false` - and
it picks a path.
```java
int temperature = 30;
if (temperature > 25) {
System.out.println("Warm");
} else if (temperature > 10) {
System.out.println("Mild");
} else {
System.out.println("Cold");
}
```
```console
Warm
```
*What just happened:* Java checked the conditions top to bottom and ran the **first** block whose
condition was `true`. `temperature > 25` is `30 > 25`, `true`, so it printed `Warm` and skipped the rest
entirely - once a branch wins, the others aren't even evaluated. Parentheses around the condition are
required in Java (unlike Python), and braces `{ }` group each branch's statements.
Conditions are boolean expressions, built with comparison operators (`>`, `<`, `>=`, `<=`, `==`, `!=`) and
combined with `&&` (and), `||` (or), and `!` (not):
```java
boolean loggedIn = true;
int age = 20;
if (loggedIn && age >= 18) {
System.out.println("Access granted");
}
```
```console
Access granted
```
*What just happened:* `loggedIn && age >= 18` is `true && (20 >= 18)`, i.e. `true && true`, so the block
ran. `&&` is **short-circuiting**: if the left side were `false`, Java wouldn't check the right side at all,
since the whole thing can't be `true` anymore. That's not just a speed trick - it lets you write guards like
`if (user != null && user.isActive())` where the second check is only safe *because* the first passed.
π‘ **Key point.** Keep conditions explicit and readable. `if (count > 0)` says exactly what it means.
Resist nested ternaries or stacked negations - code is read far more than it's written, and a clear `if` is
a gift to whoever debugs this at 2 a.m.
## `switch` - one value, many cases
When checking a *single* value against many possible matches, a tall stack of `else if` gets noisy.
`switch` is built for that. Java has two forms, and the difference matters.
### The classic `switch` statement
The old form has a sharp edge worth knowing. Here it is, done correctly:
```java
int day = 3;
String name;
switch (day) {
case 1:
name = "Monday";
break;
case 2:
name = "Tuesday";
break;
case 3:
name = "Wednesday";
break;
default:
name = "Unknown";
}
System.out.println(name);
```
```console
Wednesday
```
*What just happened:* `switch (day)` jumped to the `case` matching `day` (`3`), set `name` to `"Wednesday"`,
and `break` stopped it. `default` is the catch-all when nothing matches. Burn that `break` into memory.
β οΈ **Gotcha - fall-through.** In the classic `switch`, execution does **not** stop at the end of a `case`.
It runs straight into the next `case` until it hits a `break` (or the end of the switch). Forget a `break`
and you get a bug that's hard to spot:
```java
int day = 1;
switch (day) {
case 1:
System.out.println("Monday");
// no break - execution falls through!
case 2:
System.out.println("Tuesday");
break;
}
```
```console
Monday
Tuesday
```
*What just happened:* `day` was `1`, so it matched `case 1` and printed `"Monday"`. No `break`, so
execution **fell through** into `case 2` and printed `"Tuesday"` too - even though `day` isn't `2`. The
single most common `switch` mistake, and exactly why the modern form exists. (Fall-through is occasionally
useful when several cases *should* share code, but that's a deliberate, documented choice - never an
accident.)
### The modern `switch` expression
Newer Java (14+) gives you a `switch` *expression* with arrow syntax: it returns a value, never falls
through, and reads cleanly.
```java
int day = 3;
String name = switch (day) {
case 1 -> "Monday";
case 2 -> "Tuesday";
case 3 -> "Wednesday";
default -> "Unknown";
};
System.out.println(name);
```
```console
Wednesday
```
*What just happened:* The whole `switch (...) { ... }` *evaluated to a value* assigned straight into `name`
- notice the `=` before it and `;` after the closing brace. Each `case ... ->` runs only its own branch
with no fall-through, so there's no `break` to forget. You can list several values in one case
(`case 1, 2, 3 -> ...`), and the compiler can even warn you if you miss a possible value. Same idea as the
classic form, minus the footgun.
π‘ **Key point.** Reach for the **switch expression** (`->`) by default in modern Java: safer (no
fall-through), more concise, and it produces a value you can assign or return directly. Keep the classic
form only for older code or genuine fall-through needs.
## Loops - repeating work
Three loop shapes cover almost everything, differing in *when* you know how many times to repeat.
**`for`** - when you're counting, or you know the iteration count up front:
```java
for (int i = 0; i < 3; i++) {
System.out.println("Pass " + i);
}
```
```console
Pass 0
Pass 1
Pass 2
```
*What just happened:* The `for` header has three parts: **init** (`int i = 0`, runs once), **condition**
(`i < 3`, checked before every pass), and **update** (`i++`, adds one to `i` after each pass). `i` walked
through `0`, `1`, `2`, and the loop stopped the moment `i` reached `3`.
**`while`** - when you repeat until some condition flips, and you don't know the count ahead of time:
```java
int countdown = 3;
while (countdown > 0) {
System.out.println(countdown);
countdown--;
}
```
```console
3
2
1
```
*What just happened:* `while (countdown > 0)` checked the condition before each pass and ran the body as
long as it held. Each pass printed `countdown`, then `countdown--` subtracted one. When `countdown` hit `0`,
the condition became `false` and the loop ended. β οΈ Forget the `countdown--` and the condition never
changes - an **infinite loop**, the classic "why is my program frozen?" bug.
**Enhanced `for` (for-each)** - to visit every element of a collection or array without caring about index
numbers:
```java
List names = List.of("Ada", "Linus", "Grace");
for (String name : names) {
System.out.println(name);
}
```
```console
Ada
Linus
Grace
```
*What just happened:* `for (String name : names)` reads as "for each `name` in `names`." Each pass binds
`name` to the next element, in order, until the list runs out - no index, no `i++`, no off-by-one risk.
Prefer it whenever you don't need the index. (`List.of(...)` came from [Phase 3](03-collections.md).)
π‘ **Key point.** Pick the loop that says what you mean: **for-each** to walk a collection, **`for`** to
count or need the index, **`while`** to loop until a condition changes.
## Methods - naming reusable logic
Once you've written the same handful of statements twice, it's time for a method.
π **Method** - a named, reusable block of logic with a **return type** (what it hands back, or `void` for
nothing), a **name**, a list of **parameters** (its inputs), and a body. An **access modifier** like
`public` or `private` controls who's allowed to call it. You "call" a method by its name to run its body.
```java
public class Calculator {
// a method: returns an int, named add, takes two int parameters
public static int add(int a, int b) {
return a + b;
}
public static void main(String[] args) {
int sum = add(3, 4);
System.out.println(sum);
}
}
```
```console
7
```
*What just happened:* `public static int add(int a, int b)` declares a method named `add` taking two `int`
parameters and **returning** an `int`. Inside `main`, `add(3, 4)` called it with `3` and `4`, which became
`a` and `b`; `return a + b` handed back `7`, stored in `sum`. The return type comes *first* in Java
(`int add(...)`), unlike Go where it comes last.
You've been staring at one keyword on every method so far: **`static`**. Just enough to read it.
π **`static` vs instance.** A `static` method belongs to the **class itself** - call it without creating an
object (`Calculator.add(3, 4)`). A non-static (**instance**) method belongs to an individual **object**. We
lean on `static` heavily now since we haven't built objects yet - that's all of
[Phase 5](05-classes-and-objects.md). For now, `static` is why `main` can run before any object exists.
π‘ **Key point.** A good method does **one thing** and has a name that says what that thing is. Struggling
to name it often signals it's doing too much - split it.
## Method overloading - same name, different parameters
Sometimes you want one logical operation that works on different inputs. Java lets you give several methods
the **same name** as long as their **parameter lists differ** - different types, or a different count. This
is **overloading**.
π **Overloading** - defining multiple methods with the same name but distinct parameter lists. The
compiler decides which one to call by looking at the *types and number of arguments* at the call site.
```java
public class Printer {
public static void show(int x) {
System.out.println("int: " + x);
}
public static void show(String x) {
System.out.println("String: " + x);
}
public static void show(int x, int y) {
System.out.println("two ints: " + x + ", " + y);
}
public static void main(String[] args) {
show(42);
show("hello");
show(1, 2);
}
}
```
```console
int: 42
String: hello
two ints: 1, 2
```
*What just happened:* All three methods are named `show`, but each takes a different parameter list.
`show(42)` matched `show(int x)`; `show("hello")` matched the `String` version; `show(1, 2)` matched the
two-parameter one. One name, three behaviors, chosen by what you pass in - no need for `showInt`,
`showString`, `showTwoInts`.
π‘ **Resolved at compile time.** The compiler picks the overload by inspecting argument types *while it
compiles*, baked in before your code runs - a real distinction from the next concept.
β οΈ **Don't confuse overloading with overriding.** They sound alike but are opposites. **Overloading** is
*same name, different parameters, picked at compile time*. **Overriding** is when a subclass *replaces* an
inherited method (same name, same parameters), decided *at runtime* by the actual object - needs
inheritance, met in [Phase 6](06-inheritance-and-interfaces.md).
## Recap
1. **`if` / `else`** branches on a **boolean expression** and runs the first matching block; build
conditions with `>`, `==`, `&&`, `||`, `!`, and lean on short-circuiting for safe guards.
2. **`switch`** matches one value against many cases. β οΈ The classic statement **falls through** without
`break`; prefer the modern **switch expression** (`->`), which returns a value and never falls through.
3. **Loops** come in three shapes: **`for`** for counting, **`while`** for looping until a condition flips,
and the **enhanced for-each** for walking a collection without an index.
4. A **method** packages reusable logic with a **return type**, a name, **parameters**, and an access
modifier; **`static`** methods belong to the class (no object needed), which is why `main` is static.
5. **Overloading** gives one name several parameter lists, and the **compiler** picks the right one by
argument types - distinct from **overriding** (a runtime, inheritance concept coming in Phase 6).
Next: we stop writing everything as `static` helpers and build the real thing Java is named for -
**classes and objects**, your own types with their own data and behavior.
## Quick check
Test yourself on the ideas most likely to bite - fall-through, loop choice, and overloading:
```quiz
[
{
"q": "In a classic `switch` statement, what happens if a matching `case` has no `break`?",
"choices": [
"Execution falls through and runs the following case(s) until it hits a break or the end",
"Java throws a compile error demanding a break",
"Only that case runs, then the switch ends automatically",
"The default case runs instead"
],
"answer": 0,
"explain": "Without `break`, execution falls through into the next case and keeps going. This is the most common switch bug, and exactly why the modern switch expression (with `->` arrows) never falls through."
},
{
"q": "You want to visit every element of a `List` and don't need the index. Which loop fits best?",
"choices": [
"The enhanced for-each: `for (String s : list)`",
"A `while` loop with a manual counter",
"A classic `for` loop with `i++`",
"A `switch` statement"
],
"answer": 0,
"explain": "The for-each loop binds each element in turn with no index, no `i++`, and no off-by-one risk. Use a classic `for` only when you actually need the index."
},
{
"q": "Given `show(int x)` and `show(String x)`, how does Java decide which `show` runs when you call `show(42)`?",
"choices": [
"The compiler picks the `int` version based on the argument type, at compile time",
"The JVM picks one at random at runtime",
"It always calls the first method declared",
"It calls both versions in order"
],
"answer": 0,
"explain": "This is overloading: the compiler resolves which overload to call by inspecting the argument types while it compiles. `42` is an int, so `show(int x)` is chosen - the decision is made before the program runs."
}
]
```
---
# Classes & Objects - Java's Whole Worldview
Up to now you've written methods, loops, and `if` statements inside something called `class Main` that you
mostly ignored. This phase is where `class` stops being scenery and becomes the point. In Java, the class
isn't *a* feature - it's *the* feature. Almost everything you build is a class, and almost every value you
touch is an object made from one.
That worldview runs deeper than in most languages. Python lets you write a loose function in a file; Go
has standalone functions everywhere. Java does not - no code lives outside a class. This phase shows you
how to think *in* classes: bundle data with its behavior, hand out copies of that bundle, protect it from
the rest of your program.
## The mental model: blueprint and instance
**What it actually is.** A **class** is a blueprint - a description that says "things of this kind hold
*this* data and can do *these* things." An **object** (also called an **instance**) is one concrete thing
built from it with the `new` keyword. The class is the architect's drawing; objects are the actual houses
built from it - one drawing, as many houses as you like, each with its own address and furniture.
π **Class** - the template/blueprint, written once. **Object / instance** - one real thing made from it,
created with `new`. The class `Account` is the idea of a bank account; `new Account(...)` is *your*
account, separate from everyone else's.
**Why this is the whole worldview.** In many languages, classes are one tool among several. In Java, every
program is a set of classes, every value with behavior is an object, and even `main` sits inside one. Stop
asking "where do I put this loose code?" and start asking "what *kind of thing* is this?"
> π‘ **Key point.** Everything below is one sentence repeated in different clothes: *the data and the
> behavior that belongs with it live together inside an object.* When a detail feels arbitrary, return to
> that line.
## Fields, constructors, and `this`
Let's build a real blueprint. An `Account` holds data (an owner's name, a balance) and offers behavior
(deposit, check balance). Data lives in **fields**; setup happens in a **constructor**; `this` is how a
method points at *its own* object.
**What it actually is.** A **field** is a variable belonging to each object - its own slice of data. A
**constructor** is a special method, named exactly like the class, that runs once when you write `new`, to
fill in the object's starting fields. **`this`** refers to "the object this method is running on" - reach
for it when a parameter name collides with a field name.
```java
public class Account {
private String owner; // a field - each Account gets its own
private double balance; // another field
public Account(String owner, double balance) { // constructor: same name as the class
this.owner = owner; // this.owner = the field; owner = the parameter
this.balance = balance;
}
public void deposit(double amount) {
this.balance += amount; // 'this.' is optional here - no name clash
}
public double getBalance() {
return balance; // reading the field directly
}
}
```
```java
public class Main {
public static void main(String[] args) {
Account ada = new Account("Ada", 100.0); // build one instance
Account bob = new Account("Bob", 50.0); // build another, totally separate
ada.deposit(25.0);
System.out.println(ada.getBalance());
System.out.println(bob.getBalance());
}
}
```
```console
$ java Main.java
125.0
50.0
```
*What just happened:* `new Account("Ada", 100.0)` allocated a fresh object and ran the constructor, copying
the parameters into that object's own `owner` and `balance` fields. `ada` and `bob` are independent
objects: depositing into `ada` changed `ada`'s balance and left `bob`'s untouched, since each carries its
own copy of the data - that separateness is the entire reason objects exist.
π **`this`** - a reference to the current object. Inside the constructor, `owner` (parameter) and
`this.owner` (field) share a name; `this.owner = owner` means "store the parameter into my field." Without
`this.`, you'd assign the parameter to itself and the field stays empty. β οΈ A classic silent bug - write
`owner = owner` and your account starts up with a blank name and no error to explain why.
## Instance vs static: the object vs the class itself
Some things belong to *each object*; some belong to *the class as a whole*. Java draws that line with the
keyword `static`, explaining a mystery from Phase 1: why `main` is `static`.
**What it actually is.** An **instance member** (no `static`) belongs to each object - every `Account` has
its own `balance`. A **static member** (`static`) belongs to the *class itself* - exactly one copy, shared
by everyone, existing even if you never create a single object.
```java
public class Account {
private static int accountCount = 0; // ONE counter, shared by the whole class
private String owner; // each object's own field
public Account(String owner) {
this.owner = owner;
accountCount++; // bump the shared counter on every new Account
}
public static int getAccountCount() { // a static method - call it on the class
return accountCount;
}
}
```
```java
public class Main {
public static void main(String[] args) {
new Account("Ada");
new Account("Bob");
new Account("Cy");
// Called on the CLASS, not on an object:
System.out.println(Account.getAccountCount());
}
}
```
```console
$ java Main.java
3
```
*What just happened:* `accountCount` is `static`, so it isn't stored inside any one `Account` - it lives on
the class, and all three constructors incremented the *same* counter. We read it with
`Account.getAccountCount()` (on the class), not `ada.getAccountCount()` (on an object), since it was never
about any single account. Instance data answers "what's true of *this* object?"; static data answers
"what's true of *all of them at once*?"
π‘ **Why `main` is `static`.** When a program runs, no objects exist yet - the JVM hasn't created anything,
so the entry point can't be an instance method. `static` means "this belongs to the class and can run with
zero objects in existence" - exactly what a starting point needs.
## Encapsulation: expose behavior, not raw data
Every field above was marked `private`. That's not decoration - it's the single most important habit in
object-oriented Java.
π **Encapsulation** - keeping an object's data (`private` fields) hidden from the outside world, letting
other code interact with it *only* through the object's methods. Nobody reaches in and changes a field
directly.
**Why hiding state prevents whole classes of bugs.** If `balance` were `public`, *any* code could write
`ada.balance = -9999` and your account would silently go invalid - and finding that negative balance later,
you'd have no idea which of a hundred lines did it. Make the field `private` and force all changes through
one method, and that method becomes the *one* checkpoint every change must pass.
Here's a setter that refuses to let the balance go negative:
```java
public class Account {
private double balance;
public Account(double balance) {
this.balance = balance;
}
public void withdraw(double amount) {
if (amount > balance) { // the guard lives in ONE place
System.out.println("Denied: insufficient funds");
return; // reject the bad change, leave balance untouched
}
balance -= amount;
}
public double getBalance() {
return balance; // a getter: read access, no write access
}
}
```
```java
public class Main {
public static void main(String[] args) {
Account ada = new Account(100.0);
ada.withdraw(30.0); // fine
ada.withdraw(500.0); // rejected by the guard
System.out.println(ada.getBalance());
}
}
```
```console
$ java Main.java
Denied: insufficient funds
70.0
```
*What just happened:* `balance` is `private`, so the only way to change it from outside is `withdraw`,
which checks the amount before touching the field. The bad withdrawal was rejected and the balance held at
`70.0`. With `withdraw` the only door that subtracts from `balance`, you get a guarantee: *no withdrawal can
ever push the balance negative*.
π‘ **Expose behavior, not raw data.** Don't reflexively generate a getter and setter for every field - that
just makes the field public with extra steps. Ask what the object should let callers *do*: an account
should let you `deposit` and `withdraw`; whether it stores that as one `balance` field or a transaction
list is the object's private business.
## The trio: `toString`, `equals`, and `hashCode`
Two final pieces complete your mental model of a Java object - one is the single most common trap that
catches beginners. Both come down to: Java objects don't behave the way you'd hope until you *tell them
how*.
**Objects print as gibberish until you override `toString`.** Print an object you made and you'll get
something like `Account@1b6d3586` - class name and memory hash, useless to a human. Java calls `toString()`
whenever it needs a text version, and the default is that gibberish. Override it and printing makes sense:
```java
public class Account {
private String owner;
private double balance;
public Account(String owner, double balance) {
this.owner = owner;
this.balance = balance;
}
@Override
public String toString() {
return owner + " ($" + balance + ")";
}
}
```
```java
public class Main {
public static void main(String[] args) {
Account ada = new Account("Ada", 100.0);
System.out.println(ada); // println calls toString() for you
}
}
```
```console
$ java Main.java
Ada ($100.0)
```
*What just happened:* `System.out.println(ada)` needed text, so it called `ada.toString()`. We overrode
that method to return a readable description, so instead of `Account@1b6d3586` we got `Ada ($100.0)`.
`@Override` tells the compiler "I mean to replace an inherited method" - misspell the name and it catches
the mistake instead of silently creating a new, uncalled method.
β οΈ **The #1 Java beginner trap: `==` vs `.equals()`.** This bites *everyone*. For objects, `==` does **not**
compare contents - it asks "are these the same object in memory?" To compare *value*, use `.equals()`. The
default `.equals()` you inherit *also* just checks identity - so until overridden, two accounts with
identical data count as unequal.
```java
public class Account {
private String owner;
private double balance;
public Account(String owner, double balance) {
this.owner = owner;
this.balance = balance;
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof Account)) return false;
Account other = (Account) o;
return balance == other.balance && owner.equals(other.owner);
}
@Override
public int hashCode() {
return java.util.Objects.hash(owner, balance); // override TOGETHER with equals
}
}
```
```java
public class Main {
public static void main(String[] args) {
Account a = new Account("Ada", 100.0);
Account b = new Account("Ada", 100.0); // same data, different object
System.out.println(a == b); // same object in memory?
System.out.println(a.equals(b)); // same value?
}
}
```
```console
$ java Main.java
false
true
```
*What just happened:* `a` and `b` hold identical data but are two separate objects, so `a == b` is `false` -
`==` compares *identity*, not contents. Our overridden `.equals()` compares the actual fields, so
`a.equals(b)` is `true`. Rule to burn in: **use `.equals()` for value comparison, reserve `==` for "is it
literally the same object."** (Strings are the most common place this bites - Phase 9 has the full gotcha.)
β οΈ **Override `equals` and `hashCode` *together*, always.** Not optional politeness - it's a contract Java
relies on. Hash-based collections like `HashMap`/`HashSet` use `hashCode()` to find objects fast: *equal
objects must have equal hash codes.* Override `equals` but not `hashCode`, and two "equal" accounts can
land in different buckets - a `HashSet` stores both as distinct, a `HashMap` lookup fails to find a key
that's really there.
## Recap
1. A **class** is a blueprint; an **object / instance** is one thing built from it with **`new`**. In
Java, this is the whole worldview - almost everything you build is a class.
2. **Fields** hold each object's own data; a **constructor** (same name as the class) fills them in when
you call `new`; **`this`** points at the current object and disambiguates a field from a same-named
parameter.
3. **Instance** members belong to each object; **`static`** members belong to the class itself (one shared
copy) - which is exactly why `main` is `static`: it runs before any object exists.
4. **Encapsulation** means `private` fields plus methods as the only doors in. Putting the rules in one
guarded method (reject a negative balance) prevents whole classes of bugs. Expose behavior, not raw data.
5. Override **`toString`** so objects print readably instead of as `Account@1b6d3586`.
6. β οΈ `==` compares object *identity*; **`.equals()`** compares *value* - and you must override **`equals`
and `hashCode` together** or hash-based collections break.
You can now design a Java object: bundle the data, guard it, give it behavior, make it print and compare
sensibly. Next: connecting objects to each other - how one class builds on another, and how interfaces let
unrelated classes promise the same behavior.
## Quick check
Test yourself on the ideas most likely to bite you in real code:
```quiz
[
{
"q": "Inside a constructor, why write `this.owner = owner` instead of just `owner = owner`?",
"choices": [
"`this.owner` is the object's field while `owner` is the parameter - without `this.`, you'd just assign the parameter to itself and the field would stay empty",
"`this.` makes the assignment run faster",
"It's purely stylistic; both lines do exactly the same thing",
"`this.` is required in every assignment inside any method"
],
"answer": 0,
"explain": "When a parameter shares a name with a field, the unqualified name refers to the parameter. `this.owner` explicitly means the field. Writing `owner = owner` assigns the parameter to itself, leaving the field at its default - a silent bug with no error."
},
{
"q": "You create two `Account` objects with identical owner and balance. What do `a == b` and `a.equals(b)` return, assuming `equals` is properly overridden?",
"choices": [
"`a == b` is false (different objects in memory); `a.equals(b)` is true (same values)",
"Both are true - identical data means identical objects",
"Both are false - Java never considers separate objects equal",
"`a == b` is true and `a.equals(b)` is false"
],
"answer": 0,
"explain": "`==` compares object identity: two separate objects are never `==` even with identical data. A properly overridden `.equals()` compares the actual field values, so it returns true. This `==` vs `.equals()` split is the #1 Java beginner trap."
},
{
"q": "Why must you override `hashCode` whenever you override `equals`?",
"choices": [
"Hash-based collections (HashMap, HashSet) require equal objects to have equal hash codes - override only `equals` and lookups silently break",
"`hashCode` is what makes objects print readably",
"The compiler refuses to compile a class that overrides only one of them",
"`hashCode` controls how the constructor initializes fields"
],
"answer": 0,
"explain": "It's a contract: equal objects must return equal hash codes. HashMap/HashSet use hashCode to place objects in buckets, so if two 'equal' objects hash differently, a set stores both as distinct and a map lookup fails to find a key that's really there. Always change the pair together."
}
]
```
---
# Inheritance & Interfaces - Sharing Behavior
Phase 5 built one self-contained object: bundle the data, guard it, give it behavior. This phase is about
relationships *between* objects - how one class builds on another, and how unrelated classes can promise
the same capability. These are Java's two mechanisms for sharing behavior, and the valuable thing to take
away isn't the syntax - it's knowing *which one to reach for*, since that judgment call separates clean
Java from the tangled inheritance towers that give OOP a bad name.
The mental model: two ways to say "this thing is related to that thing." One is **"is a kind of"** - a
`Dog` *is a kind of* `Animal`, so it inherits what an animal does. The other is **"is capable of"** - a
`Dog` *is capable of* making a sound, and so is a car horn, sharing nothing else. Inheritance handles the
first; interfaces the second. Most beginners over-use the first and under-use the second.
## Inheritance: building on a class with `extends`
**What it actually is.** **Inheritance** lets one class - the **subclass** - take everything a
**superclass** has and add to or change it. Write `class Dog extends Animal`, and `Dog` automatically gets
`Animal`'s behavior without copying a line. `super` lets the subclass reach back to the superclass, most
often to call its constructor.
**When it's the right tool.** Inheritance models a genuine **"is-a"** relationship: a `Dog` *is an*
`Animal`, a `SavingsAccount` *is an* `Account`. Can't say "X is a kind of Y" with a straight face?
Inheritance is the wrong tool - a warning we'll return to, since it's the one that matters most.
```java
public class Animal {
protected String name; // protected = visible to subclasses
public Animal(String name) {
this.name = name;
}
public void describe() {
System.out.println(name + " is an animal.");
}
}
```
```java
public class Dog extends Animal { // Dog IS A kind of Animal
public Dog(String name) {
super(name); // call Animal's constructor to set up the inherited part
}
public void fetch() { // brand-new behavior, only Dogs have it
System.out.println(name + " fetches the ball.");
}
}
```
```java
public class Main {
public static void main(String[] args) {
Dog rex = new Dog("Rex");
rex.describe(); // inherited from Animal - never written in Dog
rex.fetch(); // added by Dog
}
}
```
```console
$ java Main.java
Rex is an animal.
Rex fetches the ball.
```
*What just happened:* `Dog extends Animal`, so `rex` got `describe()` for free - it lives in `Animal`, but
`rex` calls it as its own. `super(name)` handed the name up to `Animal`'s constructor. Then `Dog` added
`fetch()`, behavior no plain `Animal` has. That's inheritance: reuse what the superclass does, then extend
it.
π **`protected`** - a third visibility level alongside `public` and `private`, hidden from the outside
world but *visible to subclasses* - why `Dog`'s `fetch()` could read `name` directly. Use it sparingly;
`private` plus a getter is often still cleaner.
## Overriding: replacing an inherited method
Inheriting a method as-is is useful, but the real power is *changing* it: a subclass can **override** a
superclass method, providing its own version that runs instead.
**What it actually is.** **Overriding** means a subclass redefines an inherited method with the exact same
signature (name and parameters), giving it different behavior. Mark it with `@Override` so the compiler
verifies you matched an inherited method.
β οΈ **Don't confuse overriding with overloading (Phase 4).** They sound alike and mean opposite things.
**Overloading** is *several methods with the same name but different parameters* in one class
(`print(int)`, `print(String)`) - the compiler picks by the arguments. **Overriding** is *one signature,
redefined in a subclass* - Java picks at runtime by the object's actual type. Overloading is compile-time
convenience; overriding is the engine behind polymorphism.
```java
public class Animal {
protected String name;
public Animal(String name) { this.name = name; }
public String speak() { // the default sound
return name + " makes a sound.";
}
}
```
```java
public class Dog extends Animal {
public Dog(String name) { super(name); }
@Override
public String speak() { // replace Animal's version for Dogs
return name + " says: Woof!";
}
}
public class Cat extends Animal {
public Cat(String name) { super(name); }
@Override
public String speak() {
return name + " says: Meow!";
}
}
```
```java
public class Main {
public static void main(String[] args) {
Animal a = new Dog("Rex"); // declared Animal, but it's really a Dog
Animal b = new Cat("Mia");
System.out.println(a.speak()); // which speak() runs?
System.out.println(b.speak());
}
}
```
```console
$ java Main.java
Rex says: Woof!
Mia says: Meow!
```
*What just happened:* Both `a` and `b` are *declared* as `Animal`, yet `a.speak()` ran `Dog`'s version and
`b.speak()` ran `Cat`'s. Java looked at the object's **actual runtime type**, not the declared type. This is
**dynamic dispatch**: which method body runs is decided at runtime, based on what the object truly is -
the whole point of the next section.
π‘ **Why `@Override` earns its keep.** Optional, but always write it. Misspell the method name or get a
parameter wrong, and you've quietly created a *new* method while the inherited one still runs. `@Override`
makes the compiler catch that, turning a silent runtime bug into a compile error.
## Polymorphism: one type, many behaviors
This is the payoff - everything above was setup for this, the reason inheritance exists.
π **Polymorphism** - a variable of a *supertype* can hold an object of *any subtype*, and calling an
overridden method on it runs the version matching the object's **real** type. One line, `thing.speak()`,
does the right thing for a `Dog`, `Cat`, or any future animal, without ever knowing which it's dealing with.
("Polymorphism" is Greek for "many shapes": one variable, many concrete shapes underneath.)
**Why this is the whole point.** Without polymorphism, handling three animal types means three branches of
`if/else`. With it, you write the loop *once* against the supertype, and each object brings its own
behavior along. Add a `Cow` class next year and the loop doesn't change. You program against the general
idea; the specifics take care of themselves.
```java
import java.util.List;
public class Main {
public static void main(String[] args) {
// A list of Animal - but each element is really a different subtype
List zoo = List.of(
new Dog("Rex"),
new Cat("Mia"),
new Dog("Buddy")
);
for (Animal a : zoo) { // we only know they're Animals
System.out.println(a.speak()); // each runs ITS OWN speak()
}
}
}
```
```console
$ java Main.java
Rex says: Woof!
Mia says: Meow!
Buddy says: Woof!
```
*What just happened:* The loop variable `a` is typed `Animal`, so the loop has no idea whether it holds a
dog or a cat. Yet each `a.speak()` produced the correct sound, because dynamic dispatch resolved the call
against each object's real type at runtime. *This* is why we bothered with inheritance and overriding: one
loop against the supertype handles every subtype - including ones that don't exist yet.
## Interfaces: a contract any class can sign
Inheritance has a hard limit: a class can `extend` **exactly one** superclass. Java has no multiple
inheritance of classes - a deliberate choice avoiding a famous category of ambiguity bugs. But a class
often needs several roles. That's what interfaces are for.
π **Interface** - a *contract*: a named list of method signatures a class promises to provide. A class that
`implements` an interface must supply a body for each method, or it won't compile. Unlike `extends`, a
class can `implements` **many** interfaces at once. The interface says *what* must be possible; each class
decides *how*.
```java
public interface Drawable { // the contract: "anything drawable can draw itself"
void draw(); // no body - just the promise
}
```
```java
public class Circle implements Drawable {
@Override
public void draw() {
System.out.println("Drawing a circle β―");
}
}
public class Square implements Drawable {
@Override
public void draw() {
System.out.println("Drawing a square β’");
}
}
```
```java
import java.util.List;
public class Main {
public static void main(String[] args) {
List shapes = List.of(new Circle(), new Square());
for (Drawable d : shapes) {
d.draw(); // polymorphism again - via interface this time
}
}
}
```
```console
$ java Main.java
Drawing a circle β―
Drawing a square β’
```
*What just happened:* `Circle` and `Square` share no common parent - they're unrelated. But both *signed
the same contract* by implementing `Drawable`, so we treat them uniformly and loop over them with the same
polymorphism you just saw. The interface gave shared behavior *without* forcing an "is-a" family tree - its
superpower: grouping by *capability*, not ancestry.
π‘ **Default methods.** Since Java 8, an interface method can ship with a body using `default` - a fallback
implementation classes inherit unless they override it, mainly so library authors can add a method to an
existing interface without breaking every implementing class. You'll see it in the standard library
(`List.sort`); reach for it rarely yourself.
## Abstract classes - and the call between the two
There's a middle ground between a fully-built class and a pure interface: the **abstract class**.
**What it actually is.** An `abstract` class is one you *can't instantiate directly* - `new Animal(...)` is
a compile error if `Animal` is abstract. It exists only to be extended, mixing **shared state** (fields,
real constructors) and **shared code** (fully-written methods) with `abstract` methods that have no body
and *force* every subclass to supply one.
```java
public abstract class Shape {
private final String name; // shared STATE - interfaces can't hold this
public Shape(String name) { // shared constructor
this.name = name;
}
public abstract double area(); // no body - every subclass MUST implement this
public void describe() { // shared CODE, reused by all subclasses
System.out.println(name + " has area " + area());
}
}
```
```java
public class Rectangle extends Shape {
private final double w, h;
public Rectangle(double w, double h) {
super("Rectangle");
this.w = w;
this.h = h;
}
@Override
public double area() { // satisfy the abstract method
return w * h;
}
}
```
```java
public class Main {
public static void main(String[] args) {
// Shape s = new Shape("x"); // ERROR: can't instantiate an abstract class
Shape r = new Rectangle(3, 4);
r.describe(); // uses shared describe(), which calls our area()
}
}
```
```console
$ java Main.java
Rectangle has area 12.0
```
*What just happened:* `Shape` can't be built on its own - a half-finished blueprint. `Rectangle` finished
it by implementing `area()`, and inherited the ready-made `describe()` and `name` field in return.
`describe()` calls `area()` and gets `Rectangle`'s version via dynamic dispatch: the abstract class wrote
shared logic once, letting each subclass fill in the one differing piece.
π‘ **The plain guidance: interface or abstract class?**
- **Interface** for a *capability or contract* - "can be drawn," "can be compared," "can be saved." Lighter
and more flexible; a class can implement many, and modern default methods cover most cases interfaces
once couldn't. **When unsure, prefer an interface.**
- **Abstract class** only when subclasses genuinely need to *share state or substantial code* in a common
base - like `Shape`'s `name` field and `describe()` method. The one-superclass limit is the price you pay.
β οΈ **Favor composition and interfaces over deep inheritance.** The single most common OOP mistake is
building tall hierarchies - `A extends B extends C extends D` - to share code. They're rigid (one
superclass, forever), brittle (a tweak in `B` ripples everywhere), and force "is-a" relationships that
often aren't true. The modern habit: model *capabilities* with interfaces, and when one object needs
another's behavior, **hold it as a field** (composition) instead of inheriting from it.
## Recap
1. **Inheritance** (`class Dog extends Animal`) lets a subclass reuse and extend a superclass; `super(...)`
calls the superclass constructor. Use it only for a true **"is-a"** relationship.
2. **Overriding** redefines an inherited method (mark it `@Override`); it's resolved at runtime by the
object's real type - distinct from **overloading**, which is same-name methods chosen at compile time.
3. **Polymorphism** is the payoff: a supertype variable holds any subtype, and the right overridden method
runs automatically - so you write one loop that handles every subtype, present and future.
4. An **interface** is a contract of methods a class promises (`implements`); a class can implement **many**
interfaces, grouping unrelated classes by *capability* rather than ancestry. `default` methods add an
optional body.
5. An **abstract class** can't be instantiated and forces subclasses to implement its `abstract` methods,
but can also share state and code in a base.
6. π‘ Prefer an **interface** for a capability (and when in doubt); use an **abstract class** for shared
state/code. β οΈ Favor **composition + interfaces** over deep inheritance towers.
You can now make classes share behavior two ways - and, more importantly, choose between them with
judgment instead of habit. Next: what happens when things go wrong - errors, exceptions, reading and
writing data.
## Quick check
Test yourself on the distinctions most likely to trip you in real code:
```quiz
[
{
"q": "A variable is declared `Animal a` but actually holds a `Dog` object, and `Dog` overrides `speak()`. When you call `a.speak()`, which version runs?",
"choices": [
"Dog's version - Java dispatches on the object's real runtime type, not the declared type",
"Animal's version - the declared type decides which method runs",
"Neither; it's a compile error because the types don't match",
"Both, one after the other, starting with Animal's"
],
"answer": 0,
"explain": "This is dynamic dispatch, the engine behind polymorphism. Java looks at what the object actually is at runtime (a Dog), not how the variable is declared (Animal), so Dog's overridden speak() runs. That's exactly why one loop over a List can handle every subtype correctly."
},
{
"q": "What's the difference between overriding and overloading?",
"choices": [
"Overriding redefines an inherited method (same signature) in a subclass, resolved at runtime; overloading is several same-name methods with different parameters in one class, resolved at compile time",
"They're two words for the same thing",
"Overloading replaces a superclass method; overriding adds a new parameter list",
"Overriding works only on static methods; overloading only on instance methods"
],
"answer": 0,
"explain": "Overriding = one signature redefined in a subclass, picked at runtime by the object's real type (the basis of polymorphism). Overloading = same name, different parameter lists in one class, picked at compile time by the arguments. They sound alike but do opposite things."
},
{
"q": "You need several unrelated classes to share a capability, and a class already extends something else. Interface or abstract class?",
"choices": [
"Interface - a class can implement many interfaces, and they group classes by capability rather than ancestry",
"Abstract class - it's always the better choice for shared behavior",
"Neither works; you must copy the methods into each class",
"Abstract class, because a class can extend several of them at once"
],
"answer": 0,
"explain": "A class can extend only one class but implement many interfaces, so when classes are unrelated (or already extend something), an interface is the fit - it describes a capability without forcing an is-a family tree. Reach for an abstract class only when subclasses need to share actual state or code in a common base."
}
]
```
---
# Errors & I/O - Exceptions, Resources & Files
Every program eventually meets the moment something goes wrong: a file isn't there, a number won't parse, a network call times out. Languages disagree, sometimes fiercely, on what to *do* then. If you've seen the Go guide, you know one answer - [errors are values](/guides/go-from-zero) you return and check by hand. Java takes the other big path, worth stating up front since it shapes everything here:
> **In Java, an error is a thrown object that unwinds the stack until something catches it.**
When a method hits trouble, it doesn't return a special value - it *throws*. Normal execution stops dead, and the runtime walks back up the call chain, abandoning each method, looking for code that said "I'll handle this." Find a handler, control jumps there; find nobody, the program crashes and prints a stack trace. Once that picture is in your head, `try`/`catch`/`finally`, the checked/unchecked split, and `try`-with-resources stop being syntax to memorize and become obvious consequences of one idea.
## Exceptions - Java's error model
π **An exception** is an object (a subclass of `Throwable`) representing something going wrong. *Throwing* it stops normal flow and searches upward through the call stack for a *handler*. *Catching* it says "stop unwinding here, I've got this."
Contrast this with Go: a function that can fail hands back `(result, err)` and you check `if err != nil` right there - the error travels *with* the return value. In Java the failure travels *instead of* it: the method never returns normally, ripping through every intermediate method until it reaches a `catch`. The upside: let an error blow past five layers with nothing useful to say, and handle it once, where it matters. The cost: control flow becomes invisible - an innocent line might launch an exception three calls deep.
You contain that with three keywords:
- `try` - wrap the code that might throw.
- `catch` - handle a specific exception type if it's thrown.
- `finally` - run cleanup *no matter what* (threw or not, caught or not).
**A real example.**
```java
public class Divide {
public static void main(String[] args) {
try {
int[] nums = {10, 0};
System.out.println("result: " + (nums[0] / nums[1]));
} catch (ArithmeticException e) {
System.out.println("caught: " + e.getMessage());
} finally {
System.out.println("finally always runs");
}
System.out.println("program continues");
}
}
```
```console
$ java Divide.java
caught: / by zero
finally always runs
program continues
```
*What just happened:* `nums[0] / nums[1]` is `10 / 0`, throwing an `ArithmeticException`. The division never completed - control jumped straight to the matching `catch`, which printed `e.getMessage()`. Then `finally` ran (it always does), and since we *caught* the exception, the program continued. Remove the `try`/`catch` and it unwinds all the way out of `main`, crashing with a stack trace like this:
```console
$ java Divide.java
Exception in thread "main" java.lang.ArithmeticException: / by zero
at Divide.main(Divide.java:5)
```
*What just happened:* With no handler, the exception walked up past `main`, hit the top of the stack, and the JVM printed the exception type, message, and the exact line each frame was on. Your most useful debugging tool - read it top-down: the first line is *what* went wrong, the `at ...` lines trace *where*, most recent first.
## Checked vs unchecked - the split the compiler enforces
Here's the part that's genuinely Java's own, and the first thing that surprises newcomers. Java sorts exceptions into two camps, treated completely differently *at compile time*.
π **Checked exceptions** (subclasses of `Exception` but not `RuntimeException`, e.g. `IOException`) are ones the compiler forces you to deal with: any method that might throw one must either `catch` it or *declare* it with `throws` in its signature. Forget to, and your code won't compile. **Unchecked exceptions** (subclasses of `RuntimeException`, e.g. `NullPointerException`, `ArithmeticException`, `IllegalArgumentException`) carry no such obligation - you *may* catch them, but the compiler won't make you.
The intended dividing line: checked exceptions are for *recoverable, expected* conditions outside your control - a file might not exist - and a caller ought to have a plan. Unchecked exceptions are for *programming bugs* - a null you should have checked, an index past an array's end, an invalid argument. You can't "recover" from a bug; you fix it.
**A real example.** Watch the compiler refuse the checked one:
```java
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
public class Checked {
// This method does NOT compile - Files.readString can throw IOException,
// and we neither catch it nor declare it.
static String load() {
return Files.readString(Path.of("notes.txt"));
}
}
```
```console
$ java Checked.java
Checked.java:9: error: unreported exception IOException; must be caught or declared to be thrown
return Files.readString(Path.of("notes.txt"));
^
1 error
```
*What just happened:* `Files.readString` declares `throws IOException` - checked - so the compiler demanded we acknowledge it. We did neither, so compilation failed *before the program ran*. Fix it by adding `throws IOException` to our method or wrapping the call in `try`/`catch`. Compare to `10 / 0`: `ArithmeticException` is unchecked, so the compiler said nothing - it only blew up at runtime.
π‘ **Why checked exceptions are controversial.** The idea is sound: the compiler guarantees you can't *accidentally* ignore a failure mode the API author thought important. In practice, many find them noisy - they push `throws` up through every layer, and tired programmers "shut the compiler up" with an empty `catch {}` that swallows the very error checked exceptions existed to surface. That's why Kotlin and Scala dropped them entirely, and why much Java code wraps checked exceptions in unchecked ones. Know which camp an exception is in - the compiler will tell you.
## Throwing - and writing your own exceptions
You're not limited to catching exceptions the library throws; you throw your own with `throw`. The most common case is rejecting bad input *the moment you detect it*, rather than letting a garbage value slither deeper into your program where it causes a confusing failure far from the cause.
For built-in cases, reach for the standard unchecked types - `IllegalArgumentException` (a caller passed something invalid) and `IllegalStateException` (the object isn't in a state where this call makes sense) - covering a huge fraction of real code.
```java
public class Account {
static int withdraw(int balance, int amount) {
if (amount <= 0) {
throw new IllegalArgumentException("amount must be positive, got " + amount);
}
if (amount > balance) {
throw new IllegalArgumentException("insufficient funds");
}
return balance - amount;
}
public static void main(String[] args) {
System.out.println(withdraw(100, 30)); // fine
System.out.println(withdraw(100, -5)); // throws
}
}
```
```console
$ java Account.java
70
Exception in thread "main" java.lang.IllegalArgumentException: amount must be positive, got -5
at Account.withdraw(Account.java:4)
at Account.main(Account.java:14)
```
*What just happened:* The first `withdraw` returned `70` normally. The second hit `amount <= 0`, so `throw new IllegalArgumentException(...)` fired, constructing and launching an exception with our message. `withdraw` never returned a value - the throw replaced it - and since `main` didn't catch it, the program crashed with our message attached. The key habit: *fail fast and loud* - validate at the boundary so the stack trace points at the real culprit.
**Writing a custom exception** is just subclassing. Do it when no built-in type names your error well and callers might want to catch *this specific thing*:
```java
class InsufficientFundsException extends RuntimeException {
InsufficientFundsException(String message) {
super(message); // hand the message up to the base class
}
}
```
*What just happened:* We extended `RuntimeException`, making our exception *unchecked*. The one-line constructor passes a message up to the parent so `getMessage()` works. Now `throw new InsufficientFundsException("balance too low")` reads like a sentence, and a caller can write `catch (InsufficientFundsException e)` to handle exactly that case. (Extend `Exception` instead for *checked*.) β οΈ Don't manufacture custom exceptions for every error - a built-in type with a good message is usually clearer and less code.
## try-with-resources - cleanup that can't leak
Files, database connections, network sockets - anything you *open*, you must *close*, or you leak OS handles until your program (or the machine) runs out. The naive approach is a `finally` block calling `close()`, but that's verbose and easy to get subtly wrong (what if `close()` itself throws?). Java's purpose-built answer is **try-with-resources**.
π **try-with-resources** is a `try` with a parenthesized declaration: `try (var thing = open()) { ... }`. Any resource declared there is *automatically closed* when the block exits - normally or via exception - as long as it implements `AutoCloseable` (every file, stream, and connection in the standard library does). A structural guarantee you can't forget the close.
π‘ This is the Java answer to "always close what you open." Declare the resource in the `try` header and the compiler wires up cleanup, even on the exception path. If you remember one resource-handling pattern, make it this one.
```java
import java.io.BufferedReader;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
public class ReadLines {
public static void main(String[] args) throws IOException {
try (BufferedReader reader = Files.newBufferedReader(Path.of("notes.txt"))) {
String line;
while ((line = reader.readLine()) != null) {
System.out.println("line: " + line);
}
} // reader.close() happens here, automatically - even if readLine threw
}
}
```
```console
$ cat notes.txt
buy milk
call dentist
$ java ReadLines.java
line: buy milk
line: call dentist
```
*What just happened:* `Files.newBufferedReader` opened the file (a resource), and since we declared it inside `try (...)`, Java guaranteed `reader.close()` ran the instant the block ended - loop finished cleanly or `readLine` threw partway through. We never typed `close()` or wrote a `finally`. `throws IOException` on `main`: reading can fail with a checked exception, and here we chose to declare rather than catch it - fine for a small program. The leak-proof part is the parenthesized declaration; the rest is ordinary loop code.
## File I/O - the modern way with `java.nio.file.Files`
Older Java tutorials drown you in `FileReader`, `FileWriter`, `BufferedReader`, and streams wrapped in streams. For common cases, ignore all that: `java.nio.file.Files` gives clean, one-call methods built around `Path` objects. Reach for these first.
The three you'll use constantly:
- `Files.readString(path)` - read an entire (small) text file into one `String`.
- `Files.readAllLines(path)` - read a file into a `List`, one entry per line.
- `Files.writeString(path, text)` - write a `String` to a file, creating or overwriting it.
```java
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
public class FileDemo {
public static void main(String[] args) throws IOException {
Path path = Path.of("greeting.txt");
Files.writeString(path, "hello\nworld\n"); // create + write in one call
String whole = Files.readString(path); // entire file as one String
System.out.print("readString gives:\n" + whole);
List lines = Files.readAllLines(path); // one String per line
System.out.println("line count: " + lines.size());
System.out.println("first line: " + lines.get(0));
}
}
```
```console
$ java FileDemo.java
readString gives:
hello
world
line count: 2
first line: hello
```
*What just happened:* `Files.writeString` created `greeting.txt` and wrote both lines in a single call - no stream to open or close, since these methods manage the resource internally. `Files.readString` handed the whole file back as one `String` (newlines included); `Files.readAllLines` split it into a `List` so we could count lines and index into them. Each declares `throws IOException` - the file might not exist, the disk might be full - exactly why `main` declares it too. For genuinely large files you'd stream (`Files.lines(path)` returns a lazy `Stream`), but for config files and most everyday work, these three methods are all you need.
β οΈ **The one runtime exception you'll meet most.** `NullPointerException` - thrown the instant you call a method or read a field on a `null` reference. A `null` path, a map lookup returning nothing, a method returning `null` you forgot to check - all roads lead to the dreaded NPE, the most common exception in production Java. It's *unchecked*, so the compiler gives no warning; it just detonates at runtime. Taming `null` gets its own treatment in [Phase 9](09-idioms-and-gotchas.md).
## Recap
1. **Exceptions are Java's error model** - a thrown object unwinds the stack until a `catch` handles it, or the program crashes with a stack trace. Opposite of Go's "errors are values you check inline."
2. **`try` / `catch` / `finally`** - wrap risky code, handle specific types, and `finally` runs cleanup on every path. Read stack traces top-down: *what* first, then the *where* trail.
3. **Checked vs unchecked is the Java-specific split** - checked exceptions (`IOException`) *must* be caught or declared with `throws`, compiler-enforced; unchecked (`RuntimeException`, `NullPointerException`) needn't be. Checked exceptions are controversial since that obligation can become noise.
4. **Throw your own** with `throw new IllegalArgumentException(...)` to fail fast at the boundary; write a custom exception (subclass `RuntimeException` or `Exception`) only when no built-in type fits.
5. **try-with-resources** - `try (var r = open()) { ... }` auto-closes anything `AutoCloseable`, on every exit path - the leak-proof way to handle files and connections.
6. **`java.nio.file.Files`** - `readString`, `readAllLines`, `writeString` cover everyday file I/O in one call each. β οΈ Watch for `NullPointerException`, the most common runtime exception - more in Phase 9.
You now write code that fails clearly and cleans up after itself. Next: the *toolbox* around the language - how Java projects organize into packages and build with the tools the ecosystem actually uses.
## Quick check
Test yourself on the one idea that defines this phase - how Java handles failure:
```quiz
[
{
"q": "In Java, what happens when a method throws an exception that nothing catches?",
"choices": [
"The exception unwinds the entire call stack and the program crashes with a stack trace",
"The method returns the special value null instead",
"The exception is silently ignored and execution continues on the next line",
"The compiler refuses to build the program until you add a return value"
],
"answer": 0,
"explain": "An uncaught exception keeps unwinding upward through each calling method until it leaves main, at which point the JVM crashes the program and prints a stack trace (type, message, and the line of each frame). Catching it anywhere along the way stops the unwind."
},
{
"q": "What's the practical difference between a checked exception (like IOException) and an unchecked one (like NullPointerException)?",
"choices": [
"A checked exception must be caught or declared with throws, or the code won't compile; an unchecked one carries no such requirement",
"A checked exception is faster because the compiler optimizes it",
"An unchecked exception always crashes the program, while a checked one never does",
"There's no real difference - the terms are interchangeable"
],
"answer": 0,
"explain": "The compiler enforces checked exceptions: any method that might throw one must catch it or declare throws. Unchecked exceptions (subclasses of RuntimeException) carry no compile-time obligation - they only surface at runtime, which is exactly why a forgotten null check (NullPointerException) compiles fine but blows up later."
},
{
"q": "Why prefer try-with-resources - `try (var r = Files.newBufferedReader(path)) { ... }` - over opening a file and closing it yourself?",
"choices": [
"It automatically closes the resource on every exit path, including when an exception is thrown, so the file can't leak",
"It makes file reading run significantly faster",
"It converts checked exceptions into unchecked ones automatically",
"It lets you skip importing the java.nio.file package"
],
"answer": 0,
"explain": "Any resource declared in the try header (that implements AutoCloseable) is closed automatically when the block exits - normally or via exception - so you can never forget the close or leak a handle. You don't write close() at all; the structure guarantees it."
}
]
```
---
# Packages, Build & Tooling - From Files to a Real Project
Up to now your Java has lived in loose `.java` files, compiled with `javac` and run with `java`. That works for learning, but falls apart once a project grows past a dozen classes or needs a library someone else wrote - and *every* real project needs both.
This phase is about the gap between "I can write a class" and "I can work on an actual Java project." The mental model: a real Java project isn't a pile of files you compile by hand. It's a *named, organized structure* (packages) that a *build tool* (Maven or Gradle) compiles, tests, and bundles for you - pulling in other people's code (dependencies) automatically. Once you see how those pieces fit, an unfamiliar Java repo stops being intimidating.
## Packages - namespaces that keep classes from colliding
**What it actually is.** A **package** is a named group of related classes, declared as the very first line of a file: `package com.example.app;`. That name does two jobs at once - groups your classes logically, and maps directly to a folder on disk. A class in package `com.example.app` lives in `com/example/app/`.
π **Package** - a namespace for your classes, written as a dotted name like `com.example.billing`. It maps one-to-one to a directory path (`com/example/billing/`), groups related code, and prevents name clashes: your `User` and a library's `User` coexist because their *full* names differ (`com.example.User` vs `org.lib.User`).
**Why this exists.** Without packages, every class name would need to be globally unique - impossible once you pull in libraries, since two might both define a `Logger`. Packages also control visibility: a class or member with no access modifier (met in [Phase 5](05-classes-and-objects.md)) is *package-private* - visible only within the same package.
To use a class from another package, you `import` it:
```java
package com.example.app;
import java.util.ArrayList; // pull in one class from java.util
import com.example.model.User; // pull in your own class from another package
public class Main {
public static void main(String[] args) {
ArrayList users = new ArrayList<>();
users.add(new User("Ada"));
System.out.println("users: " + users.size());
}
}
```
*What just happened:* The `package` line says "this file belongs to `com.example.app`," so on disk it sits at `com/example/app/Main.java`. The two `import` lines bring `ArrayList` and `User` into scope by short name, so we write `ArrayList` instead of `java.util.ArrayList`. Imports don't *do* anything at runtime - a compiler convenience, telling it which full name a short name refers to. (One package is special: everything in `java.lang` - `String`, `System`, `Integer` - is imported automatically.)
π‘ **Key point.** The package name *is* the folder structure. A file saying `package com.example.app;` but sitting in the wrong directory fails to compile.
## The classpath - how the JVM finds your classes
You've written packages and imports. But when the program runs, how does the JVM locate `com.example.model.User` on disk, or a class buried inside some downloaded library? The answer: the **classpath**, explaining one of the most common beginner errors.
**What it actually is.** The **classpath** is the list of locations - folders and JAR files - where the JVM looks for compiled `.class` files, at compile time and run time. Referencing `com.example.model.User`, the JVM walks each classpath entry looking for `com/example/model/User.class`. Find it, great. Miss it, and you get the infamous `ClassNotFoundException` or `NoClassDefFoundError`.
π **Classpath** - the search path the JVM uses to find classes: a list of roots (directories and `.jar` files). The JVM resolves a class's full name into a relative path under each root until it finds the matching `.class`. Set it with `-cp` (or `-classpath`), or the `CLASSPATH` environment variable.
**A real example.** Say you compiled into a folder `out/` and depend on a library `gson.jar`. Running by hand looks like this:
```bash
java -cp "out:libs/gson.jar" com.example.app.Main
```
```console
users: 1
```
*What just happened:* The `-cp` flag listed two places to find classes: your compiled output (`out/`) and the Gson JAR. The JVM searched both roots to resolve every class the program touched. The final argument is the *full name* of the class with `main()`, not a file path. Miss one classpath entry and the program dies with `ClassNotFoundException`. (On Windows the separator is `;` instead of `:`.)
β οΈ **This is exactly why managing the classpath by hand doesn't scale.** A toy program has one or two entries; a real one has *dozens* of library JARs, each possibly needing *other* JARs, all at specific versions. Assembling and maintaining that string is miserable and error-prone - the entire reason build tools exist.
## Build tools: Maven & Gradle
A **build tool** does everything tedious about turning source into a runnable, shippable artifact - so you never touch `javac` or a raw classpath again.
**What it actually does.** Given a single config file, a build tool will: compile your code, **download and manage dependencies** (resolving the whole classpath, versions and all), run tests, and package the result into a JAR. One command does the lot. **Maven** and **Gradle** dominate Java.
π **Build tool** - automation that compiles, tests, packages, and (crucially) manages dependencies from a declarative config file. You describe *what* your project needs; the tool figures out *how* to assemble it, including the classpath.
**Maven** is the older, convention-heavy one. You describe your project in a `pom.xml` file (XML). Maven prizes "convention over configuration": follow its standard folder layout (`src/main/java`, `src/test/java`) and you barely configure anything. Here's the part of a `pom.xml` declaring a dependency:
```xml
com.google.code.gsongson2.13.1
```
*What just happened:* Those three coordinates - `groupId`, `artifactId`, `version` - uniquely identify Gson. Maven reads them, fetches from **Maven Central** (a huge public repository of open-source Java libraries), downloads that exact version, and adds it to your classpath automatically. No JAR file, no `-cp` flag - add five lines of XML and let Maven fetch. That single idea - "name a library by coordinates, the tool wires it up" - makes Java's ecosystem usable.
**Gradle** is the newer alternative. Instead of XML, you write the build in a DSL - Groovy or Kotlin - more programmable and flexible. The same dependency in Gradle's Kotlin DSL is one line:
```text
dependencies {
implementation("com.google.code.gson:gson:2.13.1")
}
```
*What just happened:* Same three coordinates (`group:artifact:version`), same result - Gradle resolves from Maven Central and builds the classpath. The difference is style: Gradle's build files are real code, expressing logic XML can't, at the cost of being less predictable than Maven's rigid conventions. Android standardized on Gradle; much server-side Java still runs on Maven. Both solve the same problem; the choice is mostly team preference.
π‘ **Key point.** In real projects you almost never call `javac` directly. Run `mvn package` or `./gradlew build`, and the tool compiles, resolves every dependency, runs your tests, and produces a JAR - all from one config file.
## JARs & dependencies - bundling code to share and ship
The build tool keeps producing something called a JAR - worth knowing exactly what that is.
**What it actually is.** A **JAR** (Java ARchive) is just a ZIP file with a `.jar` extension, holding compiled `.class` files plus a little metadata. It's how Java code is packaged for sharing - every library on Maven Central is a JAR, and your own built project becomes one too. Put a JAR on the classpath, and the JVM reads classes straight out of it.
π **JAR** - a zipped bundle of compiled `.class` files (and resources), the unit of distribution in Java: one file you can drop on a classpath, publish to a repository, or hand to someone else.
A normal library JAR contains only *that* library's classes. But to *run* an application you need it plus everything it depends on. That's where a **fat JAR** (*uber JAR*) comes in: a single JAR bundling your code *and* all its dependencies, running standalone with nothing else on the classpath:
```bash
java -jar myapp.jar
```
```console
Server started on port 8080
```
*What just happened:* `java -jar myapp.jar` ran the application from one self-contained file - no `-cp` listing a dozen library JARs, since they're all *inside* `myapp.jar`. Build tools produce these with a plugin (Maven's Shade, Gradle's Shadow). Simplest way to deploy a Java service: build one fat JAR, copy it to a server, run.
One more piece you get for free: **transitive dependencies**. Depend on library A, and if A depends on B and C, the build tool pulls those in automatically - you only declared A. The tool resolves the whole graph from Maven Central. (This has a dark side - version conflicts deep in the tree, "JAR hell" - but declaring one library quietly brings its friends along.)
## The wider toolchain
Beyond the language and the build tool, Java has a mature, batteries-included ecosystem. A quick orientation so the names aren't a mystery later:
- **IDEs.** Most Java is written in a full IDE rather than a plain editor, since the language's verbosity pays off when a tool understands it deeply. **IntelliJ IDEA** is the de facto standard (Eclipse and VS Code with Java extensions are common too). The IDE handles imports, refactoring, navigation, and runs your build tool for you.
- **Formatters & linters.** Tools like **Spotless** (formatting) and **Checkstyle** (style/lint rules) keep a codebase consistent and catch issues before review, wired into the build so rules are enforced, not argued about.
- **Testing & profiling.** The standard test framework is **JUnit**, and the JVM has excellent profiling tools for performance and memory problems - big enough topics for their own treatment in [Phase 16](16-testing-and-profiling.md).
π‘ **Key point.** Java's ecosystem is old, deep, and well-supported: for almost any problem - JSON, HTTP, databases, logging, testing - there's a mature library a single dependency line away.
## Recap
1. A **package** (`package com.example.app;`) is a namespace that groups classes, maps to a folder on disk, controls visibility (package-private), and prevents name clashes. `import` brings other packages' classes into scope by short name.
2. The **classpath** is where the JVM searches for `.class` files and libraries; an entry it can't find is the cause of `ClassNotFoundException`. Managing it by hand doesn't scale - which is why build tools exist.
3. A **build tool** compiles, tests, packages, and - most importantly - resolves dependencies for you. **Maven** uses `pom.xml` (XML, convention-heavy); **Gradle** uses a Groovy/Kotlin DSL (flexible). Both pull libraries from **Maven Central** by `group:artifact:version` coordinates.
4. You rarely call `javac` directly in real projects; you run `mvn package` or `./gradlew build` instead.
5. A **JAR** is a zipped bundle of compiled classes - the unit of distribution. A **fat/uber JAR** bundles your dependencies inside so it runs standalone. **Transitive dependencies** are pulled in automatically.
6. The wider toolchain - **IntelliJ IDEA**, formatters/linters like **Spotless**/**Checkstyle**, and **JUnit** (Phase 16) - is mature and batteries-rich.
You can now read the shape of a real Java repository: the package folders, the `pom.xml` or `build.gradle`, the dependency list. Next: closing the guide with the idioms and gotchas that separate Java that *compiles* from Java that *looks like Java*.
## Quick check
Test yourself on the ideas that make a Java project a project, not just a folder of files:
```quiz
[
{
"q": "What does the line `package com.example.billing;` at the top of a file determine?",
"choices": [
"The class's namespace and the folder it must live in (com/example/billing/)",
"Which build tool - Maven or Gradle - will compile the file",
"The version of Java the file requires to run",
"Which libraries the file is allowed to import"
],
"answer": 0,
"explain": "A package is a namespace that maps one-to-one to a directory path. The file must physically live at com/example/billing/, and the package name becomes part of every class's full name - which is how the JVM and tools locate it."
},
{
"q": "Why do Maven and Gradle exist instead of just running `javac` and `java -cp` by hand?",
"choices": [
"They automatically resolve and download dependencies and build the whole classpath, which is unmanageable by hand once a project has many library versions",
"They make Java code run faster than plain javac",
"They are required by the JVM to load any class at all",
"They replace the need to write packages and imports"
],
"answer": 0,
"explain": "A real project has dozens of library JARs at specific versions, plus their transitive dependencies. Assembling and maintaining that classpath manually is error-prone and miserable; the build tool resolves the whole dependency graph from Maven Central and wires it up for you."
},
{
"q": "What is a 'fat JAR' (uber JAR), and why is it useful?",
"choices": [
"A single JAR bundling your code plus all its dependencies, so it runs standalone with `java -jar`",
"A JAR that has been compressed twice to take less disk space",
"A JAR containing only documentation and source, not compiled classes",
"A JAR that automatically updates its dependencies at runtime"
],
"answer": 0,
"explain": "A normal library JAR holds only its own classes. A fat/uber JAR bundles your application together with every dependency inside one file, so you can deploy and run it with `java -jar myapp.jar` - no separate classpath of library JARs needed."
}
]
```
---
# Idioms & Common Gotchas - Write It Like a Java Dev, Dodge the Traps
You can write Java that compiles and runs. This phase closes the gap between *that* and code that looks like a seasoned Java developer wrote it - plus the short list of traps that have caught every Java programmer alive. (Genuinely - the `==` versus `.equals()` one alone has cost the industry more debugging hours than anyone wants to count. You're about to skip past it.)
Two halves. First the **idioms** - conventions that make Java code feel coherent instead of arbitrary. The mental model: *Java rewards small contracts and unchanging data*. Depend on interfaces, not concrete classes; make things final and immutable so they can't change behind your back; say "no value" out loud with `Optional` instead of the silent landmine that is `null`.
Then a scannable **gotcha cheat-card** - surprises named *before* they bite, so you recognize one instead of staring at a stack trace. The mental model: *Java does exactly what the rules say, not what you assumed.*
## Idioms - the way it's written today
### Program to interfaces, not implementations
**What it actually is.** When declaring a variable, parameter, or return type, name the *interface* (`List`, `Map`, `Collection`) rather than the concrete class (`ArrayList`, `HashMap`). You still *create* the concrete thing with `new` - just don't let the rest of your code depend on which one.
```java
// Idiomatic: the type is the contract, not the implementation.
List names = new ArrayList<>();
// Not idiomatic: now everything downstream is welded to ArrayList.
ArrayList names2 = new ArrayList<>();
```
*What just happened:* both lines create an `ArrayList`, but the first *types* the variable as `List`. A method taking `List` accepts an `ArrayList`, a `LinkedList`, or `List.of(...)` without changes, and you swap implementations later by editing one line. That's why you'll see `void process(List orders)` everywhere and almost never `void process(ArrayList orders)`.
π‘ **Key point.** Declare with the most general interface that does the job (`List`, `Map`, `Set`, `Collection`), construct with the concrete class. Flexible outside, specific inside.
### Prefer immutability
**What it actually is.** An *immutable* object's state can't change after it's built. Mark fields `final`, don't expose setters, assign everything in the constructor - once it exists, it's frozen.
```java
public final class Point {
private final int x;
private final int y;
public Point(int x, int y) {
this.x = x;
this.y = y;
}
public int x() { return x; }
public int y() { return y; }
// "Change" returns a NEW Point instead of mutating this one.
public Point withX(int newX) {
return new Point(newX, y);
}
}
```
*What just happened:* `Point` has no setters and every field is `final`, so once constructed it never changes. Need a different `x`? `withX` hands you a brand-new `Point`, leaving the original untouched. Sounds wasteful, but immutable objects are automatically thread-safe, safe to share and cache, and never in a half-updated state. When in doubt, make value objects immutable. (In [Phase 13](13-records-and-modern-java.md), `record` automates this pattern down to one line.)
β οΈ **Gotcha - `final` on a reference freezes the *reference*, not the object.** `final List items = new ArrayList<>();` stops you reassigning `items`, but `items.add(...)` still works all day. `final` means "this variable always points at the same object," not "that object can't change." True immutability needs the object itself unchangeable (`List.copyOf(items)`).
### Use `Optional` instead of returning `null`
**What it actually is.** `Optional` is a small box holding a value or explicitly empty. When a method might legitimately have "no answer" (no user found, no config set), returning `Optional` instead of `User` (which might secretly be `null`) makes the absence *visible in the type*.
```java
import java.util.Optional;
Optional findNickname(String user) {
if (user.equals("ada")) return Optional.of("Countess");
return Optional.empty(); // "no value" - said out loud
}
// Caller is forced to deal with the empty case:
String shown = findNickname("bob").orElse("(none)");
System.out.println(shown);
```
```console
(none)
```
*What just happened:* `findNickname` returns an `Optional`, so its signature *announces* "there might be nothing here." The caller used `.orElse("(none)")` for a fallback. Compare that to returning `null`: nothing warns you, and the day you forget a null check, you get a `NullPointerException` in production instead of a compiler nudge.
π‘ **Key point.** Use `Optional` for *return types* that may be absent. Skip it for fields or parameters (it adds ceremony without payoff there), and never call `.get()` without checking first - that just reinvents the NPE.
### Loop with the enhanced for and streams
**What it actually is.** The enhanced for-loop (`for (var x : items)`) iterates without a manual index. Streams go further: describe *what* to do to a collection - filter, map, collect - instead of spelling out *how* with a counter.
```java
import java.util.List;
List names = List.of("ada", "bob", "cleo");
// Enhanced for - no index to fat-finger.
for (var name : names) {
System.out.println(name.toUpperCase());
}
// Stream - describe the transformation as a pipeline.
List longOnes = names.stream()
.filter(n -> n.length() > 3)
.toList();
System.out.println(longOnes);
```
```console
ADA
BOB
CLEO
[cleo]
```
*What just happened:* the enhanced for-loop walked the list with no `int i` to manage and no off-by-one risk. The stream expressed "keep names longer than three characters" as a readable pipeline - `filter` describes *intent*, not mechanics. Streams shine when chaining transformations; for a simple walk, the enhanced for is perfectly idiomatic. (Streams and lambdas get their own treatment in [Phase 12](12-streams-api.md).)
### Write meaningful `equals`, `hashCode`, and `toString`
**What it actually is.** By default, `equals` checks *identity*, and `toString` prints something useless like `Point@1b6d3586`. If two objects with the same field values should count as "equal" - especially bound for a `HashMap` or `HashSet` - override `equals` and `hashCode` together.
```java
import java.util.Objects;
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof Point p)) return false;
return x == p.x && y == p.y;
}
@Override
public int hashCode() {
return Objects.hash(x, y); // must agree with equals
}
@Override
public String toString() {
return "Point(" + x + ", " + y + ")";
}
```
*What just happened:* `equals` now compares actual field values, so two `Point(1, 2)` objects are equal despite being separate objects in memory. `hashCode` uses the *same* fields - non-negotiable, since hash-based collections use `hashCode` to find the bucket and `equals` to confirm the match. Disagree, and your objects vanish into a `HashMap` unrecoverably. `toString` makes debugging humane. ([Records](13-records-and-modern-java.md) generate all three; until then, honor this contract.)
> π‘ The umbrella idiom: make intent explicit, illegal states impossible. Interfaces narrow the contract, immutability removes a whole class of "who changed this?" bugs, `Optional` makes absence visible, proper `equals`/`hashCode` makes equality mean what you mean. Favor composition over deep inheritance - clarity over cleverness.
## The gotcha cheat-card
> **Hit something baffling? Find the symptom here.** These trap *everyone* - recognizing them on sight is most of the battle.
| The trap | What bites you | The fix |
|---|---|---|
| `==` vs `.equals()` | `==` compares references, so equal-looking objects/strings can be "not equal" | Compare objects with `.equals()`; reserve `==` for primitives and identity |
| `null` / NPE | Calling a method on `null` throws `NullPointerException` at runtime | `Optional`, explicit null checks, `Objects.requireNonNull` on inputs |
| Autoboxing surprises | `Integer` caches β128..127, so `==` "works" then mysteriously breaks; unboxing a `null Integer` throws NPE | Use `.equals()` for `Integer`; keep arithmetic in primitives |
| Mutating a list while looping it | Removing during a for-each throws `ConcurrentModificationException` | Use `Iterator.remove()`, `removeIf(...)`, or collect-then-remove |
| Integer division | `5 / 2` is `2`, not `2.5` - the fraction is silently discarded | Cast one operand to `double`: `5 / 2.0` |
| Shared mutable state / arrays | Passing a list or array hands over a reference; the callee can mutate your data | Defensive copies (`List.copyOf`) or immutable objects |
| Catching `Exception` too broadly | A blanket `catch (Exception e) {}` swallows bugs and hides real failures | Catch specific types; never leave a catch block empty |
Now the *why* behind the sharpest three.
### `==` vs `.equals()`
The big one. `==` asks "are these the *same object* in memory?" `.equals()` asks "do these represent the *same value*?" For primitives `==` is correct and the only option. For *objects* - including `String` - `==` almost never means what you want.
```java
String a = new String("hello");
String b = new String("hello");
System.out.println(a == b); // false - two different objects
System.out.println(a.equals(b)); // true - same characters
```
```console
false
true
```
*What just happened:* `new String("hello")` built two separate `String` objects holding the same characters. `==` compared *references* - different objects, `false`. `.equals()` compared *contents* - same text, `true`. Dangerous because string *literals* (`"hello" == "hello"`) often return `true`, since Java pools identical literals, lulling beginners into thinking `==` works on strings. Then a string comes from user input, the pool doesn't apply, and `==` quietly returns `false`. **Always compare strings and objects with `.equals()`.**
### Autoboxing and the `Integer` cache
Java auto-converts between primitives (`int`) and object wrappers (`Integer`) - *autoboxing*. Convenient, and the source of two classic traps. First, `==` on two `Integer` objects compares references, not values - but the JVM *caches* small `Integer`s from β128 to 127, so `==` accidentally "works" in that range and breaks above it.
```java
Integer a = 100, b = 100;
System.out.println(a == b); // true - both from the cache (-128..127)
Integer c = 200, d = 200;
System.out.println(c == d); // false - outside cache, two real objects
System.out.println(c.equals(d)); // true - value comparison, correct
```
```console
true
false
true
```
*What just happened:* `100` falls inside the cached range, so `a` and `b` point at the *same* cached `Integer` and `==` is `true`. `200` is outside the cache, so `c` and `d` are *separate* objects and `==` is `false` - even though both hold 200. Vicious, since it passes every test with small numbers and fails in production on large ones. Use `.equals()` for wrappers. Second trap: unboxing a `null` `Integer` (`int x = someInteger;` when null) throws a `NullPointerException` from a line that never mentions null. Keep arithmetic in primitives and sidestep both.
### Integer division
Dividing two `int`s gives an `int` - Java discards the remainder instead of producing a fraction. Bites every beginner computing an average or a percentage.
```java
int total = 5, count = 2;
System.out.println(total / count); // 2 - fraction discarded!
System.out.println((double) total / count); // 2.5 - cast first
```
```console
2
2.5
```
*What just happened:* `5 / 2` is integer arithmetic, so the result is `2` with the `.5` silently dropped - no error, no warning, just a wrong number. Casting one operand to `double` forces *floating-point* division and gets `2.5`. The rule: for a fractional result, make at least one operand a `double` *before* the division happens. `(double)(total / count)` is too late - integer division already ran.
π **The other three, in one line each.** **`ConcurrentModificationException`** - removed from a list inside a for-each loop; use `list.removeIf(...)` or `Iterator.remove()`. **Shared mutable state** - handing out your internal list or array lets the receiver mutate it; return `List.copyOf(...)` instead. **Over-broad catch** - `catch (Exception e) {}` swallows the bug you need to see; catch the specific exception, never leave the block empty.
## Recap
1. **Program to interfaces** - declare `List`/`Map`, construct `ArrayList`/`HashMap`: narrow contracts, swappable implementations.
2. **Prefer immutability** - `final` fields, no setters, "change" returns a new object: thread-safe and bug-resistant by construction. (`final` on a reference freezes only the reference.)
3. **Return `Optional`, not `null`** - make "no value" visible in the type so callers can't forget it.
4. **Loop with enhanced for and streams**, and write real **`equals`/`hashCode`/`toString`** (matched pair for the first two) - records automate this later.
5. β οΈ **The cheat-card** - `==` compares references (use `.equals()` for objects/strings); NPEs come from `null`; `Integer` caching makes `==` lie outside β128..127; `5/2` is `2`; shared references let others mutate your data; don't swallow exceptions.
That's idiomatic Java. You can now read other people's Java and write code that looks like it belongs - and you've met the traps before they meet you. Next: deep on **generics** - how `List` really works, wildcards, and why the compiler sometimes argues about types.
## Quick check
Test yourself on the three traps that catch everyone:
```quiz
[
{
"q": "You have two String objects built with `new String(\"hi\")`. What do `a == b` and `a.equals(b)` return?",
"choices": [
"`a == b` is false (different objects), `a.equals(b)` is true (same characters)",
"Both are true - strings always compare by value",
"Both are false - the strings are stored separately",
"`a == b` is true, `a.equals(b)` is false"
],
"answer": 0,
"explain": "`==` compares references, and `new String(...)` makes two distinct objects, so `a == b` is false. `.equals()` compares contents, so it's true. Always use `.equals()` for strings and objects."
},
{
"q": "Why does `Integer a = 100, b = 100; a == b` print `true`, but `Integer c = 200, d = 200; c == d` print `false`?",
"choices": [
"Java caches Integer objects from β128 to 127, so 100 reuses one cached object while 200 creates two separate ones",
"200 is too large to fit in an int, so it overflows",
"`==` rounds large numbers differently",
"It's undefined behavior and the result is random"
],
"answer": 0,
"explain": "The JVM caches small Integer objects (β128..127), so `a` and `b` are the same cached object and `==` is true. 200 is outside the cache, so `c` and `d` are separate objects and `==` is false. Use `.equals()` for wrapper objects."
},
{
"q": "What does `5 / 2` evaluate to in Java, and how do you get `2.5`?",
"choices": [
"It's `2` (integer division discards the fraction); cast an operand to double, e.g. `5 / 2.0` or `(double) 5 / 2`",
"It's `2.5` already - Java promotes to double automatically",
"It's `3` - Java rounds to the nearest integer",
"It throws an ArithmeticException for non-divisible numbers"
],
"answer": 0,
"explain": "Dividing two ints gives an int, dropping the remainder, so `5 / 2` is `2`. Force floating-point division by making at least one operand a double before the division runs."
}
]
```
---
# Generics, Deep - Type Safety Without Duplication
Back in [Phase 3](03-collections.md) you wrote `List` and moved on - strings in, strings out, no casting. That `` was your first taste of generics.
The mental model for this phase: **generics let you write one piece of code that works for many types while the compiler still checks every type for you.** Before generics, you got reuse *or* safety, never both. Generics give you both, and pay for it with a single weird runtime tax called type erasure. Once you understand that trade, the confusing parts - wildcards, the compiler's errors - become consequences instead of arbitrary rules.
## Why generics exist - the pain they replaced
Before Java 5, collections held `Object` - the universal supertype every class extends. A list could hold anything, which sounds flexible until you try to *get something back out*.
```java
import java.util.ArrayList;
import java.util.List;
// Pre-generics style: a raw list holds Object.
List names = new ArrayList();
names.add("Ada");
names.add("Grace");
names.add(42); // oops - nothing stops this
// Getting a value back gives you an Object. You must cast.
String first = (String) names.get(0); // fine
String third = (String) names.get(2); // 42 is not a String...
```
```console
Exception in thread "main" java.lang.ClassCastException:
class java.lang.Integer cannot be cast to class java.lang.String
```
*What just happened:* the raw `List` accepted a `String`, a `String`, and an `Integer` without complaint - to it, they're all just `Object`. The trouble surfaced at `names.get(2)`: the cast promised a `String`, the promise was a lie, and the JVM threw `ClassCastException` **at runtime**, after the bug shipped.
Now the same idea with generics:
```java
import java.util.ArrayList;
import java.util.List;
List names = new ArrayList<>();
names.add("Ada");
names.add(42); // compile error - caught before you run
```
```console
error: incompatible types: int cannot be converted to String
names.add(42);
^
```
*What just happened:* `List` told the compiler "this list holds strings, full stop." The bad `add(42)` was rejected **at compile time** - the program never even built. And since the compiler knows the element type, `names.get(0)` hands you a `String` directly, no cast required. π‘ A compile error is a gift - it's a runtime crash caught early, when it's cheap to fix.
## Generic methods and classes - `` is a parameter for types
The `` you've been writing is *using* a generic type. Now you'll *write* one. A **type parameter** is a placeholder for a type, written in angle brackets, filled in at the call site - exactly like a regular parameter is a placeholder for a value.
π **Type parameter** - a stand-in name (conventionally a single uppercase letter: `T` for "type," `E` for "element," `K`/`V` for "key"/"value") for a type the caller will supply, letting one definition serve every type.
A **generic method** declares its type parameter before the return type:
```java
import java.util.List;
// says "this method introduces a type parameter named T."
// It works for a List of ANY type, returning that same type.
static T first(List list) {
return list.get(0);
}
public static void main(String[] args) {
List words = List.of("alpha", "beta");
List nums = List.of(10, 20, 30);
String w = first(words); // T inferred as String
int n = first(nums); // T inferred as Integer
System.out.println(w + " " + n);
}
```
```console
alpha 10
```
*What just happened:* `` introduced a type parameter; `T` stands for whatever type the list holds, and the return type `T` means "same type I received." You never wrote `` or `` at the call sites - the compiler performed **type inference** off the argument, so `first(words)` made `T` be `String` and `w` needs no cast.
A **generic class** puts the type parameter on the class itself, so every instance is bound to a chosen type:
```java
// Box: a container holding exactly one value of some type T.
class Box {
private final T value;
Box(T value) {
this.value = value;
}
T get() {
return value;
}
}
public static void main(String[] args) {
Box nameBox = new Box<>("Ada"); // T = String for this box
Box ageBox = new Box<>(36); // T = Integer for this box
String name = nameBox.get(); // no cast - compiler knows it's String
System.out.println(name + " is " + ageBox.get());
}
```
*What just happened:* `class Box` declared `T` once, and the whole class body - field, constructor, return type - could use it. `new Box<>("Ada")` (the `<>` "diamond") let the compiler infer `T` as `String`, so `nameBox.get()` returns a `String` directly; `ageBox` is a separate binding where `T` is `Integer`. `List`, `Optional`, and `Map` are built the same way.
## Bounded type parameters - "any type, *as long as*"
A bare `` means "literally any type" - too generous if your method needs to compare, add, or call a method on `T`, since not every type supports that. A **bounded type parameter** narrows the allowed types and unlocks the operations that bound guarantees.
π **Bound** - a constraint of the form `` meaning "`T` must be `SomeType` or a subtype of it." It restricts which types the caller may use *and* lets the method body rely on everything `SomeType` provides. (`extends` here means "is-a," covering both extending classes and implementing interfaces.)
The classic case: finding the maximum of a list. To compare two `T`s, each must know how to compare *itself* - exactly what `Comparable` promises:
```java
import java.util.List;
// T must implement Comparable - i.e. T values can be compared to each other.
static > T max(List list) {
T biggest = list.get(0);
for (T item : list) {
if (item.compareTo(biggest) > 0) { // legal ONLY because of the bound
biggest = item;
}
}
return biggest;
}
public static void main(String[] args) {
System.out.println(max(List.of(3, 9, 2, 7))); // Integer is Comparable
System.out.println(max(List.of("pear", "fig", "kiwi"))); // String is Comparable
}
```
```console
9
pear
```
*What just happened:* `>` reads "for any type `T` that can be compared to itself" - what makes `item.compareTo(biggest)` legal; without it, `T` might have no `compareTo`. `Integer` and `String` both implement `Comparable`, so both work. The bound does double duty: keeps out incomparable types, grants the method the right to compare.
A bound that isn't met stops the compiler cold:
```java
// A plain class that does NOT implement Comparable.
class Widget {}
static double sum(List list) {
double total = 0;
for (T item : list) {
total += item.doubleValue(); // doubleValue() comes from Number
}
return total;
}
public static void main(String[] args) {
sum(List.of(1, 2, 3)); // fine: Integer extends Number
sum(List.of(new Widget(), new Widget())); // bound violated
}
```
```console
error: method sum in class Demo cannot be applied to given types;
required: List
found: List
reason: inference variable T has incompatible bounds
upper bounds: Number
Widget is not within its upper bound
```
*What just happened:* `` only admits `Number` and its subtypes (`Integer`, `Double`, `Long`, ...), making `item.doubleValue()` safe. `Integer` satisfies the bound, so the first call compiles; `Widget` doesn't extend `Number`, so the second is rejected before the program runs - "Widget is not within its upper bound."
## Wildcards and PECS - the part everyone trips on
β οΈ This section trips people up - not because the rule is hard, but because the *reason* behind it is unintuitive. We'll build the intuition, not just hand you the mnemonic.
You'd think `List` is a kind of `List`, since an `Integer` *is* a `Number`. It is not:
```java
import java.util.List;
List ints = List.of(1, 2, 3);
List nums = ints; // does NOT compile
```
```console
error: incompatible types: List cannot be converted to List
```
*What just happened:* generics are **invariant** - `List` and `List` are unrelated types even though `Integer` extends `Number`. If it were allowed, `nums.add(3.14)` would look fine (a `Double` is a `Number`) but would stuff a `Double` into a list the rest of your code believes holds only `Integer`s. Invariance stops that.
But invariance is sometimes too strict - a method that sums a list of numbers should accept `List`, `List`, and `List` alike. **Wildcards** (`?`) restore that flexibility safely, in two mirror-image flavors.
π **Upper-bounded wildcard `? extends T`** - "some specific subtype of `T`, but I don't know which." You can *read* `T`s out of it. **Lower-bounded wildcard `? super T`** - "some specific supertype of `T`, but I don't know which." You can *write* `T`s into it.
`? extends T` makes a collection a **producer** - a source you read from:
```java
import java.util.List;
// Accepts a List of ANY subtype of Number - reads values out and sums them.
static double sumAll(List list) {
double total = 0;
for (Number n : list) { // reading as Number is always safe
total += n.doubleValue();
}
return total;
}
public static void main(String[] args) {
System.out.println(sumAll(List.of(1, 2, 3))); // List - OK!
System.out.println(sumAll(List.of(1.5, 2.5))); // List - OK!
}
```
*What just happened:* `List` means "a list of *some* unknown subtype of `Number`" - loose enough to accept both `List` and `List`. Reading is safe: whatever the real element type is, it's *some* kind of `Number`, so pulling items out as `Number` always works.
You cannot *add* to a `? extends` collection - the famous head-scratcher:
```java
static void brokenAdd(List list) {
list.add(42); // does NOT compile
}
```
```console
error: incompatible types: int cannot be converted to CAP#1
where CAP#1 is a fresh type-variable:
CAP#1 extends Number from capture of ? extends Number
```
*What just happened:* the compiler refuses `list.add(42)` because it doesn't know the *real* element type - `list` might be a `List`, and an `Integer` would corrupt it. With `? extends`, the unknown type sits on the *output* side: take `Number`s out, put nothing in (except `null`) - read-only from the caller's view.
The mirror image is `? super T`, which makes a collection a **consumer** - a sink you write into:
```java
import java.util.ArrayList;
import java.util.List;
// Accepts any list that can HOLD an Integer: List, List, List