List<Customer> customers = new ArrayList<>();

You know what ArrayList does.

You know it is backed by an array. You know get() is fast.

You know inserting near the front is not.

You know it grows.

Then one day you open ArrayList.java.

And there it is.

Not the tiny collection class you imagined.

A real piece of production machinery.

Growth policies. Range checks. Bulk operations. Iterator bookkeeping. Compatibility constraints. Serialization support. Specialised fast paths. System.arraycopy. JVM-aware method sizing.

The current OpenJDK implementation is more than 1,600 lines of source, even though the fundamental data structure can be described in a sentence: a resizable array.

And that was the interesting part for me.

I did not come away thinking:

“I should never write an ArrayList.”

I came away thinking:

“This is what a mature API looks like after millions of programmers have depended on it.”

The source code taught me that API design is less about inventing clever abstractions and more about making a small set of promises, preserving them for years, and hiding the ugly machinery required to keep those promises.

Start with the public promise

The public API of ArrayList is wonderfully boring:

List<String> names = new ArrayList<>();
names.add("Ada");
names.add("Grace");
String first = names.get(0);

Nobody writing this code needs to know about:

Object[] elementData;
int size;
int modCount;
ArraysSupport.newLength(...);
System.arraycopy(...);

That is the first API-design lesson:

A good abstraction lets users depend on behaviour without depending on implementation.

The current JDK documentation promises constant-time size, isEmpty, get, set, iterator-related operations and amortized constant-time append. It deliberately does not promise a particular growth factor

That distinction is incredibly important.

The implementation has freedom.

The caller has a contract.

Those are not the same thing.

The first surprise: the growth policy is deliberately not your business

Every Java developer eventually learns the story:

“An ArrayList grows by 50%.”

That is a useful implementation detail.

It is not the API contract.

The current source delegates growth to:

ArraysSupport.newLength(
        oldCapacity,
        minCapacity - oldCapacity,
        oldCapacity >> 1
);

The implementation uses the old capacity as the preferred growth basis while preserving the API’s broader amortized-performance guarantee.

That taught me something subtle.

If the JDK had documented:

capacity always grows by exactly 50%

then an implementation optimisation could become a compatibility problem.

Instead, the API says, roughly:

adding elements is amortized O(1)

and keeps the exact strategy private.

That gives future JDK maintainers room to change the machinery.

This is a huge API-design principle:

Promise the property users need, not the implementation detail you happen to have today.

Good APIs leave room for better implementations

Imagine an API like this:

interface FastList<E> {
    /**
     * Capacity grows by exactly 1.5x.
     */
    void add(E element);
}

Congratulations.

You just documented your implementation.

Now someone discovers a better growth strategy.

You cannot change it without worrying about somebody depending on the behaviour they found in your documentation.

ArrayList avoids this trap.

The caller needs:

append is efficient

not:

the internal array grows from 1000 to 1500

This sounds obvious.

Thousands of APIs still get this wrong.

get() is almost comically simple

The current source contains a method with the essential shape:

public E get(int index) {
    Objects.checkIndex(index, size);
    return elementData(index);
}

and the helper eventually reads:

return (E) elementData[index];

That’s it.

There is no linked-list traversal.

No iterator.

No search.

Just:

check
index
read

This is the payoff for choosing the underlying representation correctly.

The public contract says random access is efficient.

The implementation delivers by making the representation match the access pattern.

ArrayList also implements:

RandomAccess

which communicates that positional access is efficient and lets library code make informed choices about iteration strategies.

That’s another API lesson:

Interfaces can communicate performance characteristics without exposing the implementation.

set() shows another good design choice

The current implementation is roughly:

public E set(int index, E element) {
    Objects.checkIndex(index, size);
    E oldValue = elementData(index);
    elementData[index] = element;
    return oldValue;
}

Notice what the API tells you.

set() returns the old value.

That is useful because it makes replacement a single operation:

String previous = names.set(0, "Katherine");

Instead of requiring:

String previous = names.get(0);
names.set(0, "Katherine");

The API captures an operation that callers genuinely care about.

That is a design habit worth stealing:

Design methods around useful state transitions, not merely around the fields inside your implementation.

Then add() gets interesting

Appending looks trivial:

public boolean add(E e) {
    modCount++;
    add(e, elementData, size);
    return true;
}

The actual insertion is pushed into a helper:

private void add(E e, Object[] elementData, int s) {
    if (s == elementData.length)
        elementData = grow();
   
    elementData[s] = e;
    size = s + 1;
}

That helper contains an especially revealing comment: it is split out to keep the bytecode for add(E) small enough to help C1 inlining

That is the kind of detail you don’t put into your public API.

But it is exactly the kind of detail a production implementation may need.

The user sees:

list.add(value);

The implementation worries about:

array capacity
copying
size
modification counts
JIT compilation

This is abstraction working properly.

A public method can be tiny while the implementation is sophisticated

This is one of my favourite lessons from the source.

Good API:

boolean add(E e)

Underlying machinery:

validate
check capacity
possibly allocate
copy
insert
update size
update modification count
return

You do not make users manage that sequence.

They call one method.

That’s not “hiding complexity” in the bad sense.

It is encapsulating complexity.

The distinction matters.

Bad abstraction hides information the caller needs.

Good abstraction hides machinery the caller should never have needed.

add(index, element) shows the real cost model

Insert at the end:

list.add(element);

is usually cheap.

Insert in the middle:

list.add(10, element);

requires the array contents after that position to move.

The current source uses:

System.arraycopy(
        elementData,
        index,
        elementData,
        index + 1,
        s - index
);

before storing the new element.

That is why the API documentation carefully distinguishes operation costs instead of pretending every list operation is O(1). The JDK explicitly describes the random-access operations as constant time, append as amortized constant time, and other operations as generally linear.

There is an API lesson here too:

Good abstractions don’t hide performance reality; they describe it at the right level.

List gives you the abstraction.

ArrayList gives you a documented performance profile.

You choose the implementation based on the workload.

The List interface is doing more work than most developers realise

When you write:

List<Order> orders = new ArrayList<>();

you are making two design choices:

I want List semantics.
I want ArrayList performance characteristics.

The variable is typed to the abstraction.

The object provides the implementation.

That makes replacement possible:

List<Order> orders = new LinkedList<>();

or another implementation when appropriate.

The beauty is that the caller depends primarily on:

List contract

not:

Object[] layout

This is a classic example of programming to an interface.

But reading the source makes the reason more concrete.

The interface is the promise.

The class is the machinery.

remove() is where the implementation gets very practical

The source’s removal logic essentially does:

int newSize = size - 1;
if (newSize > index)
    System.arraycopy(
            elementData,
            index + 1,
            elementData,
            index,
            newSize - index
    );
elementData[size = newSize] = null;

That final:

= null

looks almost insignificant.

It isn’t.

It clears the obsolete reference so the removed object is no longer kept alive by the backing array.

This is a wonderful example of implementation detail serving an externally invisible property:

removed objects should become eligible for garbage collection

The API user does not know or care about the backing-array slot.

The implementation absolutely has to care.

clear() tells the same story

The current implementation resets the size and clears the old element references:

modCount++;

final Object[] es = elementData;
for (int to = size, i = size = 0; i < to; i++)
    es[i] = null;

Again:

logical size

and:

physical storage

are separate concepts.

The list can be logically empty while still retaining its capacity.

That is why clear() and trimToSize() are different operations.

clear() changes the contents.

trimToSize() changes the storage footprint.

The distinction is excellent API design.

Different operations answer different user needs.

ensureCapacity() is a beautiful example of exposing a useful knob

Suppose you know:

var orders = new ArrayList<Order>();

will receive 100,000 elements.

You can say:

orders.ensureCapacity(100_000);

The current implementation can expand the backing storage ahead of time, reducing incremental reallocations when a large number of elements is about to be added. The JDK documents exactly this use case.

Notice what the API exposes:

ensureCapacity(...)

It does not expose:

getInternalArray()
setCapacity(...)

The user gets a useful performance control.

The internal representation remains private.

That’s a very strong pattern:

Expose tuning controls at the level of user intent, not at the level of implementation state.

The source is full of defensive boundaries

Good library code assumes callers can be wrong.

For example:

Objects.checkIndex(index, size);

is central to positional access.

It is tempting to think:

“Why not just let the array throw?”

Because the collection’s API should control its own contract.

The implementation wants errors that mean :

index is invalid for this List

rather than allowing the underlying storage mechanism to define the entire user experience.

This pattern appears everywhere in good APIs:

validate
establish invariant
perform operation

The abstraction owns its boundary conditions.

Fail-fast is a debugging feature, not a synchronization mechanism

This distinction gets misunderstood constantly.

People see:

ConcurrentModificationException

and imagine:

ArrayList detected concurrency and stopped it.

No.

ArrayList itself is not synchronized.

The JDK documentation says that if multiple threads access an ArrayList and at least one structurally modifies it, external synchronization is required. It also explicitly warns that fail-fast behaviour is best effort.

That is a useful API-design pattern:

detect misuse

is not the same as:

guarantee safety

Libraries should make that distinction painfully clear.

What source code reveals that documentation cannot

Documentation tells you:

what the API promises.

Source code tells you:

how seriously those promises are engineered.

Reading ArrayList shows you a class that is constantly balancing:

correctness
performance
memory use
backward compatibility
JVM behaviour
API semantics

For example:

Objects.checkIndex(...)

exists for clean boundary checking.

System.arraycopy(...)

exists for efficient movement.

elementData[...] = null

exists to release obsolete references.

modCount

supports fail-fast diagnostics.

ArraysSupport.newLength(...)

handles growth safely.

These details are not random implementation trivia.

They are evidence of the contract being defended from multiple directions.

What I would steal for my own APIs

After reading ArrayList, my API checklist became much simpler.

Promise behaviour, not internals

Prefer:

amortized constant-time append

over:

we grow by 50%

Name user intent

Prefer:

ensureCapacity(...)

over:

resizeInternalArray(...)

Document performance where it matters

Users need to know that:

get()

is cheap while middle insertion is not.

Protect ownership boundaries

Copies and views are different contracts.

Say which one you return.

Make failure semantics explicit

Don’t rely on accidental exceptions from implementation details.

Treat compatibility as a requirement

Your API will outlive your current implementation.

Optimise behind the abstraction

Special-case common paths internally.

Don’t force every caller to learn the tricks.

Keep escape hatches narrow

A tuning hook can be valuable.

An API that exposes the entire implementation usually becomes unchangeable.

The final lesson

I opened ArrayList.java expecting to learn more about arrays.

I learned more about APIs.

The array is the easy part.

The hard part is everything around it:

How do you grow without making append expensive?
How do you remove without retaining dead references?
How do you report invalid indexes?
How do you detect accidental structural modification?
How do you preserve decades of behaviour?
How do you expose useful performance controls without exposing representation?
How do you optimise common cases without changing the contract?
How do you leave enough implementation freedom for the next ten years?

That is what mature library code looks like.

The public surface stays boring:

add()
get()
set()
remove()
size()

The implementation underneath is allowed to be absolutely feral.

And that may be the best API-design lesson of all:

Make the public API simple enough that users don’t need to care how clever you had to be underneath it.

ArrayList is a resizable array.

That’s the concept.

The source code is everything it takes to make that concept remain trustworthy after billions of calls, thousands of JDK releases, and an entire ecosystem of developers who have never once thought about elementData.

That’s not accidental simplicity.

That’s engineered simplicity.

And after reading the source, I think that’s what good API design actually is

What reading the ArrayList source code taught me about API Design was originally published in Heap & Wire on Medium, where people are continuing the conversation by highlighting and responding to this story.

You have a database table:

select id, name, email
from customer;

You want three values.So somebody builds:

@Entity
public class Customer {
    @Id
    private Long id;

    private String name;
    private String email;
    // getters
    // setters
    // constructors
    // equals
    // hashCode
    // maybe lazy-loading surprises
}

Then a repository. Then a mapper. Then a DTO.

Then a service.

Then perhaps another DTO because the endpoint does not actually need the database entity.

Then a query projection because loading the whole entity was wasteful.

Then a framework-generated proxy because apparently we were not suffering enough.

And eventually someone asks the dangerous question:

“Why do I need all of this just to get three fields?”

That question leads somewhere interesting.

Java is nominally typed. A type is primarily identified by a declared type name and its relationships, not simply by the shape of the values it contains.

A language with structural types can often say something closer to:

“I need any value that has an id, a name, and an email.”

Java generally says:

“I need a Customer.”

That difference looks small.

It is not.

It shapes how we build DTOs, projections, mappers, repositories, serializers, adapters, and eventually ORMs.

Now, to be precise, ORMs did not appear only because Java lacks structural types. ORMs are primarily a response to the object-relational impedance mismatch: objects, classes, identity, inheritance, references, and collections do not map neatly onto tables, rows, foreign keys, and joins.

But Java’s nominal, class-centric model makes one part of that mismatch particularly expensive:

the shape of the data is rarely enough. The type name has to line up too.

And that is where this gets fun.

The tiny problem hiding inside a giant ORM stack

Suppose the database contains:

customer
--------------------------------
id | name | email | status | address_id | created_at | ...

But your screen only needs:

id
name
email

In a structurally typed language, you might imagine working with a shape:

{
    id: Long,
    name: String,
    email: String
}

You do not necessarily care what the original domain class is called.

In Java, the natural representation is a named type:

record CustomerSummary(
        long id,
        String name,
        String email
) {}

That is perfectly reasonable.

But now we have introduced a new nominal type just to represent a particular shape.

Then we need to construct it.

Then we need to map to it.

Then the query needs to know how to populate it.

That is the tiny seam where frameworks start multiplying.

Java asks “what type?” before “what shape?”

Consider this method:

void sendEmail(EmailContact contact) {
    ...
}

The compiler expects:

EmailContact

It does not care that another record has exactly the same members:

record CustomerContact(
        String name,
        String email
) {}

These two shapes may be identical, but they are different types.

You cannot casually substitute one for the other.

That is a feature, not a bug.

Nominal typing gives you identity, clear contracts, refactoring support, and a useful way to prevent accidental interchangeability.

But it also means that when the real problem is simply:

I need these fields

you often end up inventing another named type.

And large enterprise systems contain a lot of “I need these fields” problems.

This is why DTOs multiply

Imagine an endpoint returning:

{
  "id": 42,
  "name": "Ada"
}

The database entity has:

@Entity
class Customer {
    Long id;
    String name;
    String email;
    String status;
    Address address;
    Instant createdAt;
    Instant updatedAt;
    // ...
}

You probably do not want to expose the whole entity.

So you create:

record CustomerResponse(
        Long id,
        String name
) {}

Then somewhere:

new CustomerResponse(
        customer.getId(),
        customer.getName()
);

Now imagine twenty endpoints.

The business logic is not necessarily complicated.

The mapping is.

This is the same underlying pressure that gives us:

entities
DTOs
view models
projection interfaces
mapper classes
record projections
serialization metadata

The more frequently your application asks for slightly different shapes, the more painful nominal typing can become.

ORMs are partially an answer to this pressure

Here is the classic ORM promise:

row ↔ object
foreign key ↔ reference
join table ↔ collection relationship
column ↔ field/property

The framework says:

“Don’t write all the boring translation code. Tell me your model and I will bridge the worlds.”

That is incredibly useful.

Hibernate and Jakarta Persistence let you define mappings declaratively:

@Entity
class Customer {

    @Id
    private Long id;
    private String name;
    private String email;
}

Then code can work in terms of:

Customer customer = entityManager.find(Customer.class, id);

instead of manually writing:

execute SQL
read ResultSet
construct object
convert types
manage identity
track relationships
handle lifecycle

The ORM absorbs a huge amount of object-relational plumbing.

That is the good part.

The cost is that the framework is now trying to reconcile two different type systems and two different notions of structure.

The database is already structurally flexible

This is the part that makes the comparison interesting.

A SQL query can return a shape without inventing a new nominal domain type.

For example:

select
    c.id,
    c.name,
    c.email
from customer c;

The result shape is effectively:

(Long, String, String)

or, conceptually:

{id: Long, name: String, email: String}

SQL is very comfortable with ad hoc result shapes.

You can join tables and create a new projection in one query:

select
    c.id,
    c.name,
    o.total
from customer c
join orders o on o.customer_id = c.id;

That shape did not exist before you wrote the query.

The database does not need a class called:

CustomerOrderSummary

before it can return the row.

Java generally does.

Or at least, Java wants some declared representation if the result is going to participate in a strongly typed API.

And now we have a very productive mismatch.

Java 16+ quietly improved this story with records

Records reduce the cost of creating named data shapes:

record CustomerName(long id, String name) {}

That is a big improvement over writing:

final class CustomerName {
    private final long id;
    private final String name;

    CustomerName(long id, String name) {
        this.id = id;
        this.name = name;
    }
    long id() { return id; }
    String name() { return name; }
    // equals
    // hashCode
    // toString
}

Records do not make Java structurally typed.

But they reduce the cost of saying:

“Here is another immutable data shape.”

That turns out to matter a lot for database projections, API models, and intermediate transformations.

Record construction still needs a bridge from SQL

Suppose:

record CustomerSummary(
        long id,
        String name,
        String email
) {}

You can write SQL that returns exactly those columns.

But something still needs to connect:

SQL result

to:

CustomerSummary

This is where ORMs, JDBC mappers, row mappers, annotation processors, reflection, and generated code all show up.

The shape exists in one world.

The nominal Java type exists in another.

The mapping layer is the translator.

A large part of modern Java persistence is essentially a sophisticated answer to:

“How do I turn this runtime shape into that compile-time named type?”

Projection APIs are basically controlled escape hatches

JPA-style projections make this relationship explicit.

For example, you might define:

public interface CustomerNameOnly {
    Long getId();
    String getName();
}

and ask the persistence framework for that projection.

Conceptually, you are saying:

“I don’t actually need a Customer. I need something with these accessors.”

That is much closer to a structural notion.

And notice what the framework is doing.

It is using runtime machinery to simulate flexibility that the static type system does not naturally provide.

The framework can look at:

getId()
getName()

and adapt a row-backed representation to an interface.

Java does not need structural typing in the language itself because the framework builds a runtime layer that approximates the useful part.

That’s a recurring pattern in the Java ecosystem.

Dynamic proxies are structural adapters in disguise

Suppose a framework sees:

interface NameView {
    String getName();
}

and wants to create an implementation without writing:

class NameViewImpl implements NameView {
    ...
}

It can generate a proxy.

Very roughly:

NameView view = (NameView) Proxy.newProxyInstance(
        NameView.class.getClassLoader(),
        new Class<?>[] { NameView.class },
        (proxy, method, args) -> {
            return row.get(method.getName());
        }
);

Real frameworks are much more sophisticated than this toy example.

But the idea is revealing.

You define a shape as an interface.

The framework supplies the runtime implementation.

That is very close to saying:

“I don’t care what the concrete object is. I care that it has these members.”

Again, structural typing is not actually happening.

Nominal typing is still in charge because the proxy must implement a named interface.

But the runtime framework is bending the system toward shape-based use.

This is where ORMs start doing too much

The original promise of an ORM is attractive:

Customer.class
    ↕
customer table

But real systems rarely stop there.

They have:

partial projections
joins
aggregates
nested objects
inheritance
lazy relationships
fetch plans
pagination
sorting
filters
custom SQL

At some point the ORM starts inventing ways to represent ad hoc shapes.

That is why we get things like:

projection interfaces
constructor expressions
criteria APIs
query DSLs
Tuple
Object[]
record projections
native queries

This looks like framework complexity.

And it is.

But it is also the framework acknowledging a reality:

relational queries produce arbitrary shapes.

A single entity class cannot represent every useful database result.

So the ORM grows a language for shapes.

A query is often a better data-shape language than a class hierarchy

This is one reason SQL is so powerful.

Consider:

select
    c.id,
    c.name,
    count(o.id) as order_count,
    coalesce(sum(o.total), 0) as total_spend
from customer c
left join orders o
    on o.customer_id = c.id
group by c.id, c.name;

The result has a shape:

id          : bigint
name        : text
order_count : bigint
total_spend : numeric

That shape may exist only for this report.

It does not deserve to become a giant entity hierarchy.

A small Java record is a good fit:

record CustomerSpend(
        long id,
        String name,
        long orderCount,
        BigDecimal totalSpend
) {}

The record is useful because the data is useful.

The mistake is assuming every query result must map back to an entity.

Once you stop doing that, the ORM becomes less magical and more practical.

Records let you use Java’s nominal typing without paying the old ceremony tax

This is one of the best modern Java improvements for database work.

You can happily define:

record CustomerSpend(
        long id,
        String name,
        long orderCount,
        BigDecimal totalSpend
) {}

and treat it as a value.

There is no need for:

setter explosion
mutable DTOs
boilerplate equals/hashCode

So although Java has not become structurally typed, the cost of saying:

“This query returns this shape.”

has dropped substantially.

That reduces one of the reasons developers used to reach for increasingly complicated ORM magic.

What structural typing would change

Imagine Java had a structural record type that let you write something conceptually like:

{ id: long, name: String }

and say:

load anything with this shape

Then a query result could potentially flow directly into that shape without defining:

CustomerName
CustomerNameProjection
CustomerNameDto

for every tiny variation.

That could simplify:

DTOs
projections
mappers
query results
adapter types
serialization views

But there would be a trade-off.

Nominal types communicate intent beyond shape.

For example:

record CustomerId(long value) {}
record OrderId(long value) {}

Both have:

long value

A structural type system might consider them interchangeable if their shapes matched.

That could be disastrous.

Sometimes identical shape does not mean identical meaning.

Nominal typing protects you from that class of mistake.

“Same shape” and “same concept” are different things

This is the strongest argument for Java’s model.

These two values are structurally identical:

record CustomerId(long value) {}
record OrderId(long value) {}

But:

CustomerId ≠ OrderId

And that is exactly what you want.

If a method accepts:

void loadCustomer(CustomerId id) { ... }

passing:

new OrderId(42)

should fail.

A structural type system can support stronger systems of wrappers or branded types, but nominal identity is a very direct tool for expressing domain meaning.

So “Java lacks structural types” is not a complaint that should end with:

“Therefore Java should have structural types everywhere.”

The real question is:

Where do we care about shape, and where do we care about identity?

Databases and query projections care heavily about shape.

Domain boundaries often care heavily about identity.

ORMs sit in the uncomfortable middle.

A better rule for ORM-heavy Java

I would use three questions.

Does this object have domain identity?

If yes, an entity or domain type may be appropriate.

Is this object primarily a query result or transport shape?

If yes, prefer a small immutable record.

Is this relationship really about shape rather than identity?

If yes, do not force it into the entity model just because an ORM makes that convenient.

That one distinction can prevent a surprising amount of ORM complexity.

The practical architecture

A healthy persistence boundary often looks like:

Database
                  |
                  v
             SQL / ORM
                  |
          +-------+-------+
          |               |
       Entity         Projection
          |               |
          v               v
     Domain model      Record/value
          |               |
          +-------+-------+
                  |
                  v
          Application logic
                  |
                  v
              API DTO

The important part is that the types are allowed to be different.

The database does not need to think in terms of your domain classes.

The API does not need to think in terms of your tables.

The domain does not need to expose your persistence structure.

And the mapper is not a sign that the architecture failed.

It is the explicit seam between models.

What ORMs really bought us

It is easy to tell a simplistic story:

“Java has no structural types, therefore we got ORMs.”

That is too neat.

The real history is messier.

We got ORMs because developers wanted to work with an object model while storing data in relational databases.

We got ORMs because SQL and objects optimise for different things.

We got ORMs because manually mapping rows, relationships, identity, and lifecycle is exhausting.

But Java’s nominal type system adds another layer of friction:

SQL can create a shape on demand.
Java wants a named type for that shape.

That pressure contributes to the huge ecosystem around:

DTOs
projections
mappers
reflection
code generation
query DSLs

The ORM is not only mapping objects to tables.

It is also negotiating between a shape-oriented data system and a name-oriented language.

That is the more interesting story.

And this is why records matter so much

Records do not eliminate the object-relational mismatch.

They do something more achievable and more useful.

They make tiny, explicit, immutable data shapes cheap.

That means instead of thinking:

“How do I contort the entity model to represent this query?”

you can think:

“What is the smallest value that represents this result?”

Then write:

record OrderSummary(
        long orderId,
        String customerName,
        BigDecimal total
) {}

That is a very good modern Java answer to a very old problem.

Not structural typing.

Just less ceremony around named data.

The final rule

The interesting lesson is not:

“ORMs are bad.”

They are incredibly useful.

Nor is it:

“Java should become structurally typed.”

That would solve some problems and create others.

The more useful lesson is this:

Use nominal types when identity and meaning matter. Use small data shapes when shape is the whole point. Do not force every database result through an entity just because the ORM can.

When the database gives you:

{id, name, email}

and the use case needs:

{id, name, email}

create the smallest Java value that says exactly that.

A record is often enough.

When the use case needs a long-lived thing with identity, invariants, and behaviour, model that explicitly.

And when an ORM starts growing another projection API, another mapper layer, another proxy, and another framework abstraction because the query returned five fields that don’t fit your entity…

stop for a second.

The framework may not be failing.

It may simply be paying the tax for a language that asks:

“What is the name of this type?”

when the database already knows the answer to a different question:

“What shape are you asking for?”

That gap is one of the most interesting fault lines in enterprise Java.

And once you see it, ORMs stop looking like giant magical machines that map objects to tables.

They start looking like what they really are:

a very elaborate negotiation between two worlds that agree on data, but disagree about what a type is.

ORMs Are a Response to Java Not Having Structural Types was originally published in Heap & Wire on Medium, where people are continuing the conversation by highlighting and responding to this story.

Java borrowed lambdas from functional programming.

Then streams. Then Optional. Then records.

Then sealed types and pattern matching.

We can spend days arguing about whether Java is becoming a functional language.

Meanwhile, one of the most valuable functional ideas was sitting quietly in Java code long before any of those features arrived:

Build a value once, then stop changing it.

No special syntax. No pure-language runtime. No effect system. Just ordinary Java classes, constructors, final fields, and a little discipline.

And when modern Java added records, immutable-style modelling became dramatically easier.

That matters because immutability solves a surprisingly large part of the problems people reach for functional programming to solve:

unexpected state changes
aliasing
race conditions
temporal coupling
hard-to-reproduce bugs
defensive copying
concurrency coordination

You mostly have to stop changing things.

Which sounds trivial.

Then someone hands you an object graph with 14 nested collections and asks you to update one postcode.

And suddenly we’re back in reality.

So this is not a story about “immutability is always easy.” It isn’t.

It is a story about why it pays off so much that Java developers have been using the idea long before Java acquired the vocabulary to talk about it.

The bug is usually not the line you are looking at

Consider:

class Order {
    private String status;
    private Customer customer;
    
    public void setStatus(String status) {
        this.status = status;
    }
    public void setCustomer(Customer customer) {
        this.customer = customer;
    }
}

Then somewhere:

Order order = repository.find(orderId);
emailService.send(order);
fraudService.inspect(order);
order.setStatus("PAID");
auditService.record(order);

Looks harmless.

Now imagine emailService keeps the reference:

class EmailService {
   private Order lastOrder;
    void send(Order order) {
        this.lastOrder = order;
    }
}

Later:

order.setStatus("CANCELLED");

Now lastOrder is also cancelled.

Nobody explicitly told EmailService to mutate. Nobody explicitly passed a new value. It just happened because both pieces of code held the same object.

Welcome to aliasing.

Mutable state makes references socially complicated.

Immutability changes the question

Instead of:

order.setStatus("PAID");

you write:

Order paidOrder = order.withStatus("PAID"); //create a new object with the status

Now:

order      -> status = PENDING
paidOrder  -> status = PAID

The original value remains unchanged.

There is no mystery. There is no “who changed this?” investigation. There is no temporal question about which version you were looking at.

There are simply two values.

That is the practical magic of immutability.

Immutability removes an entire category of questions

Mutable code forces you to reason about:

who owns this object?
who can change it?
when can they change it?
is someone else holding the same reference?
has another thread changed it?
do I need to copy it?

Once an object is truly immutable, you can pass it around, cache it, return it, share it between threads, use it in a lambda, and put it in a collection without worrying that some unrelated caller will silently rewrite its state.

The value you received remains the value you received.

That sounds boring.

Boring is an underrated concurrency primitive.

Java has always been pretty good at immutable values

Take:

String name = "Alice";

Operations such as:

name.toUpperCase();

return a new value rather than mutating the existing string.

The same basic idea appears in types such as:

String
BigInteger
BigDecimal
java.time types

These types became ubiquitous partly because immutable values are remarkably easy to compose.

If a value cannot change, you do not need an ownership meeting every time it crosses a method boundary.

Mutable objects create temporal coupling

Imagine:

Account account = new Account();
account.setCustomer(customer);
account.setCurrency("GBP");
account.setBalance(new BigDecimal("1000"));

The object exists in several intermediate states.

A method that receives it after the first setter but before the last setter may see something incomplete.

The object’s validity depends on history.

That is temporal coupling.

With immutable construction:

Account account = new Account(
        customer,
        "GBP",
        new BigDecimal("1000")
);

the value arrives complete.

You don’t need to remember the sequence of mutator calls that makes it valid.

The constructor establishes the state. After that, the state stays put.

Records made the good path ridiculously short

Before records, an immutable value often meant a lot of ceremony:

public final class Customer {
    private final String id;
    private final String name;
    private final Address address;

    public Customer(String id, String name, Address address) {
        this.id = id;
        this.name = name;
        this.address = address;
    }
    public String id() { return id; }
    public String name() { return name; }
    public Address address() { return address; }
}

A record collapses the representation:

public record Customer(
        String id,
        String name,
        Address address
) {}

Records did not invent immutability.

They made immutable data so cheap to write that more developers actually use it.

But a record is not deeply immutable

Be careful.

record Customer(
        String name,
        List<String> roles
) {}

The record component is final, but the referenced list can still be mutable.

You can do:

customer.roles().add("ADMIN");

if the supplied list is mutable.

A safer boundary is:

record Customer(
        String name,
        List<String> roles
) {
    public Customer {
        roles = List.copyOf(roles);
    }
}

Now the record stores an immutable snapshot of the collection.

The broader lesson is:

Immutability is a property of the reachable object graph, not just the top-level reference.

final is not the same thing as immutable

This:

final List<String> names = new ArrayList<>();

does not make the list immutable.

It means the variable cannot be pointed at another list.

This is still legal:

names.add("Ada");

Likewise:

final Customer customer = ...;

does not make Customer immutable.

final provides assignment guarantees. Immutability provides state guarantees.

The second is a larger promise.

Builders did not kill immutability

A builder can be mutable:

Customer customer = Customer.builder()
        .name("Ada")
        .address(address)
        .roles(List.of("USER"))
        .build();

That is perfectly fine.

The builder is a temporary construction object.

The useful boundary is:

mutable builder
      ↓
immutable value
      ↓
application

You do not need every object involved in construction to be immutable.

You need the published domain value to be immutable.

Mutation during construction is not the same thing as shared mutable state.

Immutability makes concurrency boring

Suppose twenty threads all read the same immutable Customer.

No synchronisation is required merely to protect its fields from mutation because there is no mutation.

With a mutable object, depending on the access pattern, you may need:

locks
volatile
atomic operations
copying
thread confinement

Immutability removes the shared-state mutation problem instead of making concurrent mutation less dangerous.

That is why it is such a powerful concurrency technique.

Functional pipelines get easier when values are stable

Consider:

var customers = orders.stream()
        .map(Order::customer)
        .distinct()
        .toList();

This is much easier to reason about when Order and Customer are values that do not change underneath the pipeline.

The functional model is naturally:

value → value → value

Shared mutable state changes that mental model into:

value → who knows what happened → value

That is where composition starts leaking.

Immutability and value semantics belong together

Consider:

record Money(
        BigDecimal amount,
        Currency currency
) {}

Then:

Money price = new Money(
        new BigDecimal("100"),
        Currency.getInstance("GBP")
);

Money discounted = new Money(
        price.amount().multiply(new BigDecimal("0.9")),
        price.currency()
);

You can reason about both values independently.

Modern records make this particularly pleasant because they provide value-oriented equals(), hashCode(), and toString() implementations.

A good value object does not require you to remember its history.

Immutable state reduces defensive copying

Mutable APIs often produce code like:

List<String> roles() {
    return new ArrayList<>(roles);
}

Why? Because returning the internal list would expose mutable state.

Then callers make more copies to protect themselves.

With an immutable representation, the API can safely return the same value:

List<String> roles() {
    return roles;
}

No ownership negotiation.

No documentation saying “please don’t modify this.”

The value itself enforces the contract.

Immutable values are excellent cache values and messages

Suppose:

Map<String, Customer> customerCache;

If Customer is immutable, cached instances can be shared safely from the perspective of their internal state.

The same principle fits:

cache values
configuration snapshots
event payloads
commands
DTOs
read models

An event such as:

record OrderPlaced(
        String orderId,
        String customerId,
        Instant occurredAt
) {}

is naturally a value representing what happened at a point in time.

History is a particularly bad place for setters.

Immutability makes tests easier

Mutable test fixtures tend to require a sequence of setup calls:

Customer customer = new Customer();
customer.setName("Ada");
customer.setCountry("UK");
customer.setActive(true);

Now test state depends on setup order.

Immutable construction makes the fixture explicit:

Customer customer =
        new Customer("Ada", "UK", true);

And variants become values:

Customer inactive =
        customer.withActive(false);

That is very close to the functional style of:

start with a value
derive another value

Immutability can expose missing domain operations

Suppose you have:

order.setStatus(PAID);
order.setApprovedBy(user);
order.setApprovedAt(now);
order.setApprovedReason(reason);

These are not necessarily four independent field updates.

They may represent one business operation:

Order approved =
        order.approve(user, now, reason);

The immutable design forces a useful question:

What does this state transition actually mean?

That often improves the domain model.

The awkward part: nested immutable updates

Now for the bit everybody eventually hits.

record Customer(
        String name,
        Address address
) {}

record Address(
        String city,
        Postcode postcode
) {}
record Postcode(
        String value
) {}

You want to change:

Customer → Address → Postcode → value

With mutation:

customer.getAddress()
        .getPostcode()
        .setValue("M1 1AA");

With immutable values:

var updated = new Customer(
        customer.name(),
        new Address(
                customer.address().city(),
                new Postcode("M1 1AA")
        )
);

Correct. Explicit. A little pyramid-shaped.

This is where developers begin missing setters.

And this is where builders, withX() methods, copy methods, persistent data structures, and lenses earn their keep.

Immutability solved the state problem. It did not promise to solve the syntax problem.

withX() methods are a practical middle ground

For small immutable types:

record Customer(String id,
        String name,
        Address address) {
    
    Customer withName(String name) {
        return new Customer(id, name, address);
    }

    Customer withAddress(Address address) {
        return new Customer(id, name, address);
    }
}

Then:

var updated = customer.withName("Grace");

This keeps the update readable without introducing a framework.

For deeper object graphs, though, nested reconstruction can become ugly. That is a real cost.

This is where lenses enter the conversation

A lens is a reusable description of how to focus on one part of an immutable structure.

Conceptually:

Lens<Customer, String> postcode =
        addressLens
                .andThen(postcodeLens)
                .andThen(valueLens);

Then:

Customer updated =
        postcode.set(customer, "M1 1AA");

The distinction is important:

immutability
    = design principle

lens
    = tool for convenient immutable updates

You do not need lenses to benefit from immutability.

You reach for them when structural updates become repetitive enough to hurt.

Not every object needs to be immutable

This is where dogma gets expensive.

Suppose you have a local accumulator:

var result = new ArrayList<Result>();

for (Input input : inputs) {
    if (!isValid(input)) {
        continue;
    }
    result.add(transform(input));
}

There is local mutation.

That is not automatically a design failure.

The useful distinction is:

shared mutable state

versus:

local mutation with clear ownership

A local variable that nobody else can see is often easy to reason about.

A mutable object shared between services and threads is much harder.

Ownership is a better rule than purity

A practical rule is:

The more widely an object is shared, the more valuable immutability becomes.

Think about the gradient:

local method variable
    ↓
usually easy to mutate

request-local state
    ↓
often safe with clear ownership

shared service state
    ↓
prefer immutable or thread-safe state

cache value
    ↓
immutability is very useful

event/message
    ↓
immutability is usually ideal

That is a much more useful rule than “never mutate anything.”

Immutability can cost you something

Let’s be honest.

Immutable updates may mean more object creation.

They may mean more construction code.

Nested records can be annoying to update.

Collection boundaries may need List.copyOf() or similar defensive copying.

Persistent data structures are not built into the standard Java collections in the same way they are central to some functional ecosystems.

And in a very hot loop, replacing one in-place mutation with several allocations can matter.

But there is an equally important correction:

“Immutable means slow” is just as simplistic as “allocation is free.”

Modern JVMs are very good at handling short-lived objects, and JIT optimisation can remove some allocations entirely. The right question is still the real workload: measure before changing a clear design for a theoretical performance problem.

The compiler gets more useful when state stops changing

With mutable code, a debugger often forces you to ask:

who last changed this field?
when did it change?
what thread changed it?
was the object shared?

With immutable values, inspection is much more local.

If:

Customer customer = ...;

is immutable, the debugger can show you the value and you can trust that value to remain stable while you inspect the surrounding code.

That is a surprisingly large productivity benefit.

Functional Java gets easier when the middle is made of values

The most useful modern-Java combination is often:

records
    ↓
immutable data
    ↓
small functions
    ↓
streams / pattern matching
    ↓
new immutable data

For example:

var result = orders.stream()
        .filter(Order::isPaid)
        .map(this::calculateDiscount)
        .map(this::createSummary)
        .toList();

That pipeline is easy to reason about because each stage can be thought of as a transformation.

The more those functions mutate shared state, the less that model helps.

Immutability is the FP idea Java adopted without needing to become FP

This is the part I find most interesting.

Java did not need a radical new syntax to get enormous value from immutability.

It needed a design decision:

construct once
keep state stable
return a new value when something changes

Then the language gradually made that design cheaper:

records
pattern matching
lambdas
streams
sealed types

These features did not make immutability valuable.

Immutability made many of those features easier to use safely.

The final idea

Functional programming is often introduced as a collection of exotic concepts.

Some of its most valuable ideas are almost aggressively ordinary.

Don’t mutate the value. Don’t share state unless you need to.

Pass values around. Create a new value when something changes.

Make invalid states harder to represent.

Keep mutation at the boundary where it is easiest to control.

That gets you surprisingly far. It just needed to stop asking every object to be a tiny database.

Because once a value can safely travel through:

threads
streams
caches
messages
tests
services

without changing underneath you, an enormous amount of code gets easier.

That is the part people sometimes miss when they talk about functional programming in Java.

The biggest win isn’t that the code looks functional.

It is that the state stops being surprising.

And after a few years of production debugging, you start to realise that “nothing changed” is one of the most beautiful properties an object can have.

Immutability Is the FP Idea That Paid Off Most in Java was originally published in Heap & Wire on Medium, where people are continuing the conversation by highlighting and responding to this story.