Java Immutable Collections

An immutable collection cannot be modified after it is created. No element can be added, removed, or replaced. This single guarantee eliminates an entire class of bugs: shared state corrupted by unexpected mutation, concurrent modification exceptions, and defensive copy boilerplate scattered across every method boundary. Java 9 introduced clean factory methods — List.of(), Set.of(), Map.of() — that create truly immutable collections in one line.

What Are Java Immutable Collections?

An immutable collection is one where every mutating operation — add(), remove(), set(), put(), clear() — throws UnsupportedOperationException. The collection's contents are fixed at creation time and cannot change through any reference. Java provides three layers of immutability with increasing strength.

THREE LAYERS OF COLLECTION IMMUTABILITY IN JAVA:

LAYER 1 — UNMODIFIABLE WRAPPER (Java 1.2+):
  Collections.unmodifiableList(list)
  Collections.unmodifiableSet(set)
  Collections.unmodifiableMap(map)
  ─────────────────────────────────────
  Mutation attempts on the WRAPPER throw UnsupportedOperationException.
  BUT: the backing collection is still mutable.
  Changes to the backing collection ARE VISIBLE through the wrapper.
  This is a READ-ONLY VIEW, not true immutability.

LAYER 2 — TRULY IMMUTABLE FACTORY COLLECTIONS (Java 9+):
  List.of(e1, e2, e3)
  Set.of(e1, e2, e3)
  Map.of(k1, v1, k2, v2)
  Map.entry(key, value)
  Map.ofEntries(Map.entry(k1,v1), Map.entry(k2,v2))
  ─────────────────────────────────────────────────
  No backing mutable structure.
  The collection IS the data — no reference to a mutable original.
  Cannot be modified by ANY reference, not just the one you hold.
  NULL elements or keys/values throw NullPointerException.
  Set.of() and Map.of() reject duplicate keys/elements.
  Iteration ORDER IS NOT GUARANTEED (implementation may vary).

LAYER 3 — IMMUTABLE DEFENSIVE COPY (Java 10+):
  List.copyOf(existingCollection)
  Set.copyOf(existingCollection)
  Map.copyOf(existingMap)
  ─────────────────────────────────
  Creates a new immutable collection from any existing collection.
  If the input is already an immutable collection of the same type,
  no copy is made — the same instance may be returned.
  NULL elements throw NullPointerException.
  Changes to the original collection are NOT reflected.

Basic Overview — The Full Immutable API

LIST.OF() — IMMUTABLE LIST:
  List<E> List.of()                           ← empty
  List<E> List.of(e1)                         ← 1 element
  List<E> List.of(e1, e2, ..., e10)           ← up to 10 element overloads
  List<E> List.of(E... elements)              ← varargs for 11+
  Properties: null REJECTED, duplicates ALLOWED, order PRESERVED

SET.OF() — IMMUTABLE SET:
  Set<E> Set.of()                             ← empty
  Set<E> Set.of(e1, e2, ..., e10)             ← up to 10 element overloads
  Set<E> Set.of(E... elements)                ← varargs for 11+
  Properties: null REJECTED, duplicates REJECTED (IllegalArgumentException),
              iteration order NOT GUARANTEED

MAP.OF() — IMMUTABLE MAP (up to 10 entries):
  Map<K,V> Map.of()                           ← empty
  Map<K,V> Map.of(k1,v1, k2,v2, ..., k10,v10)← alternating key-value pairs
  Map<K,V> Map.ofEntries(Map.Entry<K,V>...)   ← for 11+ entries
  Map.Entry<K,V> Map.entry(key, value)        ← for ofEntries()
  Map<K,V> Map.copyOf(existingMap)            ← Java 10+
  Properties: null keys/values REJECTED, duplicate keys REJECTED,
              iteration order NOT GUARANTEED

LIST.COPYOF / SET.COPYOF / MAP.COPYOF (Java 10+):
  Creates an immutable collection from any Collection or Map.
  If input already is an appropriate immutable collection: MAY return same ref.
  NULL elements throw NullPointerException.
  Set.copyOf() and Map.copyOf() reject duplicates in the source.

COLLECTIONS.UNMODIFIABLE*() (Java 1.2+, legacy pattern):
  Returns a READ-ONLY VIEW of the backing collection.
  Changes to backing collection are visible through the wrapper.
  Use only when you need to expose a live mutable collection as read-only.
  For new code: prefer List.of(), Set.of(), Map.of() for truly immutable data.

When to Use Immutable Collections

USE immutable collections WHEN:

  1. A method returns a collection that callers must not modify
     — configuration data, lookup tables, allow-lists
     — returning a field from a service: callers get read-only access
     — before Java 9: Collections.unmodifiableList(internalList)
     — Java 9+: return List.copyOf(internalList) for true immutability

  2. Thread safety is needed without synchronisation overhead
     — immutable collections can be read by any number of threads safely
     — no lock, no volatile, no ConcurrentHashMap needed for reads
     — Java Memory Model: publication through final fields makes visible

  3. Map or Set constants in the codebase
     — static final Map<String, Integer> HTTP_STATUS = Map.of(...)
     — static final Set<String> ALLOWED_DOMAINS = Set.of(...)
     — impossible to accidentally mutate from test code or other classes

  4. Defensive programming in constructors of immutable classes
     — store List.copyOf(input) not input itself — decouples from caller's reference
     — caller cannot invalidate the stored collection by mutating their original

  5. API design: signalling intent
     — returning List.of() says "this result has no elements — do not add to it"
     — returning new ArrayList<>() accidentally implies callers may add to it

CHOOSE mutable collections WHEN:
  — Elements must be added, removed, or updated after creation
  — The collection is built incrementally and finalised later
  — Accumulated in a loop, then returned as immutable:
    List.Builder pattern or collect + copyOf

DO NOT USE immutable collections AS:
  — A thread-safe accumulator (use ConcurrentHashMap, synchronizedList)
  — A queue or work list (use ArrayDeque, LinkedBlockingQueue)
  — A cache that evicts entries (use LinkedHashMap with removeEldestEntry)

How Immutable Factory Collections Work Internally

List.of() IMPLEMENTATION:

  List.of() with 0-2 elements returns specialised ImmutableCollections.List0,
  ImmutableCollections.List1, or ImmutableCollections.List2.

  List.of() with 3-10 elements returns ImmutableCollections.ListN backed by
  a final Object[] array with the elements.

  All mutating methods (add, remove, set, clear, replaceAll, sort) call:
    throw new UnsupportedOperationException();

  SIZE, GET, CONTAINS, ITERATOR are supported.
  ITERATOR does NOT support iterator.remove() — throws UnsupportedOperationException.

Set.of() IMPLEMENTATION:
  NOT backed by a HashMap.
  Uses a custom hash table with open addressing (probe-based, compact).
  Iteration order is intentionally unspecified and may differ per JVM run.
  This prevents code from accidentally depending on order.

Map.of() IMPLEMENTATION:
  Uses a custom compact hash table — NOT a HashMap.
  Iteration order is intentionally unspecified.
  For Map.ofEntries() with many entries: also a compact implementation.

SHARED CHARACTERISTICS OF JAVA 9+ FACTORY COLLECTIONS:
  — All implement Serializable
  — All are value-based: equals() and hashCode() work correctly
  — No null keys, values, or elements (NPE thrown immediately)
  — Duplicate keys/set elements throw IllegalArgumentException at creation
  — Random iteration order for Set.of() and Map.of() prevents order dependence

Core Operations with Examples

List.of(), Set.of(), Map.of() — The Java 9+ API

Output:
=== List.of() ===
List     : [Spring, Quarkus, Micronaut, Vert.x]
get(1)   : Quarkus
contains : true
size     : 4
add() throws UnsupportedOperationException
set() throws UnsupportedOperationException

=== Set.of() ===
Set      : [ADMIN, ANALYST, DEVELOPER, VIEWER]
contains : true
Duplicate in Set.of() throws IllegalArgumentException
add() throws UnsupportedOperationException

=== Map.of() ===
Map size   : 6
get(OK)    : 200
get(Missing): null
put() throws UnsupportedOperationException

=== Null rejection ===
List.of(null) throws NPE
Set.of(null) throws NPE
Map.of(null value) throws NPE

copyOf() and Unmodifiable Wrappers — The Difference

Output:
=== unmodifiableList — VIEW of backing list ===
view before backing change: [Kafka, Redis, MySQL]
view AFTER backing change : [Kafka, Redis, MySQL, MongoDB]
view.add() blocked — but backing changes propagate

=== List.copyOf() — TRUE immutable snapshot ===
snapshot before change: [Kafka, Redis, MySQL]
snapshot AFTER change : [Kafka, Redis, MySQL]

=== Set.copyOf() — from mutable Set ===
immutableSet: [Go, Java, Python]
immutableSet unchanged: [Go, Java, Python]

=== Map.copyOf() — protect config ===
Config: {db.host=prod-db-01.internal, cache.ttl=300, db.port=5432}
Immutable config unchanged: prod-db-01.internal

=== Build-then-freeze pattern ===
Frozen pipeline: [Step 1: Validate, Step 2: Authenticate, Step 3: Process, Step 4: Respond]

Map.ofEntries() and Large Immutable Maps

Output:
=== HTTP status map (15 entries via ofEntries) ===
200 → OK
404 → Not Found
503 → Service Unavailable
Map size: 15

=== Allowed payment method check ===
  UPI              ALLOWED
  CRYPTO           REJECTED
  CREDIT_CARD      ALLOWED
  GIFT_CARD        REJECTED

=== Default feature flags ===
  ai_suggestions       ENABLED
  beta_checkout        DISABLED
  dark_mode            ENABLED
  express_delivery     ENABLED
  gamification         DISABLED

=== Merging and freezing with copyOf ===
  ai_suggestions       ENABLED
  beta_checkout        DISABLED
  dark_mode            DISABLED
  express_delivery     ENABLED
  gamification         ENABLED

Real-World Example — Swiggy Restaurant Configuration Service

A restaurant configuration service at Swiggy loads cuisine types, delivery zone constants, and platform fee rules at startup. These are immutable lookup tables — they never change during a service lifetime, are read by hundreds of threads per second, and must never be accidentally modified by any code path. Map.of(), Set.of(), and List.copyOf() make this contract explicit in the type system.

Output:
=== Platform fee by order amount ===
  Rs.   50 → Rs.5.0 platform fee
  Rs.  150 → Rs.10.0 platform fee
  Rs.  350 → Rs.15.0 platform fee
  Rs.  650 → Rs.20.0 platform fee
  Rs. 1200 → Rs.25.0 platform fee

=== Surge multipliers ===
  STANDARD       1.00x
  PEAK           1.50x
  HEAVY_RAIN     2.00x
  FESTIVAL       1.75x
  UNKNOWN        1.00x

=== Instamart zone availability ===
  Koramangala            AVAILABLE
  Sarjapur               NOT AVAILABLE
  Whitefield             AVAILABLE
  Electronic City        NOT AVAILABLE

=== Cuisine allergens ===
  Thai           [NUTS, SOY, SHELLFISH]
  Italian        [GLUTEN, DAIRY, EGGS]
  Japanese       []

=== Mutation attempts blocked ===
INSTAMART_ZONES.add() blocked
SURGE_MULTIPLIERS.put() blocked
FEE_SLABS.add() blocked

Performance Considerations

Set.of() and Map.of() use significantly less memory than HashSet and HashMap. The JDK implementation uses compact open-addressing hash tables with no wrapper Node objects — roughly 50% less memory per entry. For large static lookup tables, this difference is significant.

List.copyOf() may avoid copying. If the source collection is already an immutable List created by List.of() or List.copyOf(), the JDK may return the same instance without allocating a new array. This optimisation makes List.copyOf() safe to call defensively without worrying about unnecessary allocation.

Thread safety is free. Immutable collections need no synchronized wrappers, no ConcurrentHashMap, and no volatile fields. They can be read by any number of threads simultaneously with no overhead. Publishing through a final field or via safe publication makes them visible to all threads under the Java Memory Model.

Best Practices

Use List.of(), Set.of(), Map.of() for static constants instead of initialised mutable collections. private static final Map<String, Integer> CODES = new HashMap<>() followed by a static initialiser block has four problems: the map is mutable (any code path can corrupt it), the initialiser block is verbose, HashMap uses more memory than Map.of(), and thread safety requires extra care. private static final Map<String, Integer> CODES = Map.of("OK", 200, "Created", 201) is immutable, compact, and thread-safe by default.

Return List.copyOf(internalList) from service methods instead of the live list. When a service returns an internal ArrayList, callers could modify it — corrupting the service's state without any indication. return List.copyOf(this.items) creates a snapshot that callers can iterate safely. Unlike Collections.unmodifiableList(), which still exposes the backing list to mutation by the owner, List.copyOf() is a true disconnected snapshot.

Use the build-then-freeze pattern for incrementally constructed immutable collections. List.copyOf(buildBuffer) after the buffer is fully populated is cleaner than attempting to build immutably from the start. Accumulate into an ArrayList or HashMap in a loop, then freeze with List.copyOf() / Map.copyOf() before returning or storing. This gives full mutability during construction and full immutability afterwards.

Prefer Map.ofEntries(Map.entry(...), ...) for maps with more than 10 entries. Map.of() has overloads up to 10 key-value pairs. The 11th entry needs Map.ofEntries(). Map.entry(key, value) is the clean companion factory. Do not use new AbstractMap.SimpleImmutableEntry<>() — Map.entry() is the intended API.

Common Mistakes

Mistake 1 — Assuming unmodifiableList() Protects Against All Mutation

Mistake 2 — Putting Duplicate Elements in Set.of() or Duplicate Keys in Map.of()

Mistake 3 — Trying to Sort or Shuffle an Immutable List

Output:
Sorted: [Apple, Banana, Cherry]
Stream sorted: [Apple, Banana, Cherry]

Mistake 4 — Using an Array-Backed asList() When an Immutable List Is Needed

Interview Questions

Q1. What is the difference between Collections.unmodifiableList() and List.of() in Java?

Collections.unmodifiableList(list) creates a read-only wrapper around an existing mutable list. Mutation attempts on the wrapper throw UnsupportedOperationException. But the backing list is still mutable — the original owner can modify it, and those changes are visible through the wrapper. List.of() (Java 9+) creates a truly immutable list with no backing mutable structure. No reference can modify it. It also rejects null elements immediately. For static constants and defensive return values, List.of() and List.copyOf() are always preferable.

Q2. What happens when you pass null to List.of(), Set.of(), or Map.of()?

All three throw NullPointerException immediately at construction time — not when the null element is accessed. This is by design: null is explicitly prohibited in all Java 9+ immutable collection factory methods. Collections.unmodifiableList() allows nulls because it wraps an existing list that may already contain them. For collections that require null-tolerant immutability, the only option before Java 9 was Collections.unmodifiableList() wrapping a null-containing ArrayList.

Q3. Does Set.of() guarantee the same iteration order across runs?

No. The iteration order of Set.of() and Map.of() is intentionally unspecified and may vary between JVM runs, JDK versions, or even between calls in the same program. This is a deliberate design decision — it prevents code from accidentally depending on a specific order that is not part of the Set contract. LinkedHashSet preserves insertion order if ordered iteration matters. When the order of a Set.of() result is important for tests, sort it before asserting.

Q4. When should you use List.copyOf() over List.of()?

Use List.copyOf(existingCollection) when the source data already exists as a Collection and you want to snapshot it immutably. It copies all elements into a new immutable list. If the source collection is already an immutable List, the JDK may return the same instance without allocating. Use List.of(e1, e2, ...) when the elements are known at compile time or code-time — it is syntactically cleaner for static constants. Both produce equivalent immutable lists; the choice is about whether elements come from existing collections or are specified inline.

Q5. Are immutable collections thread-safe in Java?

Yes. Immutable collections created by List.of(), Set.of(), Map.of(), and copyOf() are fully thread-safe for concurrent reads without any synchronisation. Since no thread can mutate the collection, there is no risk of data races, ConcurrentModificationException, or visible inconsistency. Publishing an immutable collection through a final field or via safe publication makes it visible to all threads under the Java Memory Model. This is one of the primary reasons to prefer immutable collections in multi-threaded services.

Q6. What is the build-then-freeze pattern and when is it needed?

The build-then-freeze pattern accumulates elements into a mutable collection (like ArrayList or HashMap), then produces an immutable version with List.copyOf() or Map.copyOf() before returning or storing. It is needed when a collection cannot be fully specified at a single call site — for example, when elements are added conditionally inside a loop, read from a database, or assembled from multiple sources. The mutable collection serves as a builder; the copyOf() call freezes it into an immutable result that the caller can hold safely.

FAQs

What is the difference between immutable and unmodifiable in Java?

"Unmodifiable" means the collection cannot be modified through a specific reference — the wrapper view. But another reference (to the backing mutable collection) can still modify the underlying data. "Immutable" means no reference can modify the collection — the data is fixed permanently. Collections.unmodifiableList() is unmodifiable. List.of() is truly immutable. The distinction matters when the owner of the backing mutable collection might change it.

Can I add elements to a List.of() by creating a new list?

Not by mutating the existing list — that always throws. But you can create a new immutable list that includes the additional element. The pattern: List<String> extended = Stream.concat(existing.stream(), Stream.of("newElement")).toList(). This creates a new list from the existing elements plus the new one. The original List.of() result is unchanged.

Are Java 9 immutable collections serialisable?

Yes. List.of(), Set.of(), Map.of(), and copyOf() all implement Serializable. They use a serialisation proxy pattern to ensure deserialization produces a canonical immutable collection instance, not a raw internal implementation class. This makes them safe to use in distributed caches, JMS messages, and session replication.

What is Map.entry() and when do I use it?

Map.entry(key, value) creates an immutable Map.Entry<K, V> object. Its primary use is as an argument to Map.ofEntries(Map.entry(k1,v1), Map.entry(k2,v2), ...) for creating immutable maps with more than 10 entries. It can also be used independently wherever an immutable Map.Entry is needed. Unlike new AbstractMap.SimpleEntry<>(k, v), Map.entry() explicitly rejects null keys and values.

Does List.of() with one null throw immediately or when the null is accessed?

Immediately, at the call site. List.of("A", null, "C") throws NullPointerException before the method returns. This is faster feedback than a collection that accepts null but throws later during a sort or serialisation. It enforces the contract at the boundary where the violation occurs.

How do immutable collections interact with Java Streams?

Immutable collections are perfectly compatible as stream sources. list.stream(), set.stream(), map.entrySet().stream() all work on immutable collections. The terminal operation .toList() (Java 16+) also returns an unmodifiable list. Collectors.toUnmodifiableList(), Collectors.toUnmodifiableSet(), and Collectors.toUnmodifiableMap() produce immutable views. List.copyOf(stream.collect(Collectors.toList())) produces a fully immutable copy from any stream pipeline.

Summary

Java's immutable collections exist on a spectrum. Collections.unmodifiable*() (Java 1.2+) provides a read-only view that still exposes the backing collection to mutation by its owner — useful when the owner and consumer have different access rights. List.of(), Set.of(), Map.of() (Java 9+) are truly immutable — no reference can change them, nulls are rejected at construction, and they use compact memory layouts. List.copyOf(), Set.copyOf(), Map.copyOf() (Java 10+) create immutable snapshots from existing collections, decoupling from the source.

The practical rules: use List.of() and Map.of() for static constants and fixed lookup tables. Return List.copyOf() from service methods to prevent callers from seeing internal mutations. Use the build-then-freeze pattern when data must be assembled incrementally. Never assume unmodifiableList() fully protects against mutation — it only protects one side of the reference.

For interviews: explain the view-vs-copy distinction between unmodifiableList() and List.copyOf(), describe null rejection in factory methods, explain why Set.of() iteration order is unspecified, and describe the thread-safety guarantee of immutable collections without locks.

What to Read Next