skip to content

What does Collections.unmodifiableList return, and how is it different from a collection built by List.of?

level: seniorimportance: should knowfreq 55%

answer

  1. unmodifiable = read-only VIEW, not a copy
  2. mutations to the backing list leak through
  3. List.of/copyOf = no backing list, reject nulls
  4. wraps with UnsupportedOperationException on mutators
  5. immutability is shallow — elements can still change

basics

~20 s

Collections.unmodifiableList returns a read-only view of an existing list: you cannot change it through the view, but the original can still change and those changes show up. List.of builds its own unmodifiable list, with no backing list to reach.

solid answer

~40 s

Collections.unmodifiableList wraps an existing list and returns a view that throws UnsupportedOperationException on any mutating method. Crucially it is a view, not a copy: if you still hold a reference to the backing list and modify it, those changes are visible through the wrapper. So it provides read-only access for the recipient, not immutability. List.of (Java 9+) and List.copyOf (Java 10+) return unmodifiable lists with no backing list to reach; their mutators throw too, they reject null elements, and they are often more memory-compact. A second subtlety: neither freezes the elements themselves, so the Javadoc's word for both is unmodifiable, and immutable holds only when the elements are. For a safe read-only handoff you either defensively copy first (unmodifiableList(new ArrayList<>(src))) or use List.copyOf.

code

java · 8 lines
java
List<String> src = new ArrayList<>(List.of("a"));
List<String> view = Collections.unmodifiableList(src);
src.add("b");                 // mutating the backing list...
System.out.println(view);     // [a, b] -- leaked through the view!

List<String> safe = List.copyOf(src); // immutable snapshot
src.add("c");
System.out.println(safe);     // [a, b] -- unaffected

go deeper

for a junior

Knows unmodifiableList prevents add/remove and throws if you try.

for a middle

Explains it is a view whose backing list can still change, and that List.of is a separate unmodifiable option with no backing list.

for a senior

Contrasts view-vs-copy, null handling, and gives the defensive-copy recipe for safe getters.

for a principal

Distinguishes shallow vs deep immutability, reasons about API contracts/encapsulation, and standardizes List.copyOf in code guidelines.

## The problem these wrappers solve When you return a collection from a method, the caller can normally mutate it — `add`, `remove`, `clear` — which may corrupt your object's internal state. You want to hand out **read-only** access. `Collections.unmodifiableList(list)` (and `unmodifiableSet`, `unmodifiableMap`, etc.) is one tool for that. ## What unmodifiableList actually returns: a VIEW It returns a thin **wrapper object** that delegates every read to the original list and **throws `UnsupportedOperationException`** on every mutator (`add`, `set`, `remove`, `clear`, the iterator's `remove`, etc.). The critical word is **view**: it does **not copy** the data. It still points at the original list. Therefore: ```java List<String> src = new ArrayList<>(List.of("a")); List<String> ro = Collections.unmodifiableList(src); // ro.add("b"); // would throw UnsupportedOperationException src.add("b"); // allowed! System.out.println(ro); // [a, b] — the change leaked through ``` So `unmodifiableList` makes the collection unmodifiable **through that reference**, but it does **not** make the underlying data immutable. If anyone keeps the original `src`, immutability is an illusion. The Javadoc names the safe cases: if the backing collection is itself effectively immutable, or the only reference to it is through the view, the view "can be considered effectively immutable". Two version notes. Since JDK 17 wrapping a view again costs nothing: `unmodifiableList` returns its argument when the argument is already such a view, which the Javadoc marks an implementation note. And JDK 21 added `unmodifiableSequencedCollection`, `unmodifiableSequencedSet` and `unmodifiableSequencedMap` to the family. ## Self-contained: List.of / List.copyOf - `List.of(...)` (Java 9) returns a collection with **no backing reference anyone can reach**. It does have mutator methods, because `List` declares them, and every one throws `UnsupportedOperationException`. - `List.copyOf(src)` (Java 10) snapshots the *current contents* of `src`; later changes to `src` are invisible. It is not always a new object: given a list that is already unmodifiable in this sense, such as a `List.of` result, it generally returns that same list, which is safe because nothing can change it. A `Collections.unmodifiableList` view does get copied. These factories differ from the `unmodifiableXxx` wrappers in three ways: 1. **No leak path** — there is no separate mutable backing list. 2. **They reject `null` elements** (throw `NullPointerException`); `unmodifiableList` permits nulls if the source had them. 3. They are typically **more compact** in memory (specialized internal layouts). ## What "immutable" does NOT cover: shallow vs deep The Javadoc calls all of these *unmodifiable* and keeps the stronger word apart: "An unmodifiable collection is not necessarily immutable." Neither approach makes the *elements* immutable. If a list holds mutable objects (e.g. `StringBuilder`, a mutable `User`), you can still mutate those objects — only the **structure** (which references the list holds) is frozen. This is **shallow** immutability. Deep immutability requires immutable element types too. ## The safe-handoff recipe To return a defensively safe read-only collection from a getter: - Modern code: `return List.copyOf(internalList);` — unmodifiable snapshot, nulls rejected. - Before Java 10, or when the list may hold nulls: `return Collections.unmodifiableList(new ArrayList<>(internalList));` — the `new ArrayList<>` copy severs the leak, and the wrapper blocks mutation. ## Key terms - **View:** an object that delegates to an underlying collection without copying; changes to the underlying data are visible. - **UnsupportedOperationException:** thrown when a method is structurally present (from the interface) but intentionally not supported. - **Shallow immutability:** the collection's structure is frozen, but the elements it references may still be mutable. - **Defensive copy:** copying input/output data so external code cannot mutate your internal state.

  • How do you make unmodifiableList truly safe to hand out?
    Wrap a fresh copy: Collections.unmodifiableList(new ArrayList<>(src)), so no one holds a mutable reference to the backing list — or just use List.copyOf.
  • What happens if you call add() on an unmodifiable list?
    It throws UnsupportedOperationException at runtime; the method exists on the List interface but the wrapper refuses to perform it.

  • Claiming unmodifiableList makes the data immutable
  • Forgetting that holding the original list defeats the wrapper
  • Thinking it deep-freezes the elements
  • Assuming List.of allows null elements
  • Saying List.of has no add method (it has one, and it throws)
  • Assuming List.copyOf always allocates a new list

Collections.unmodifiableList
Java 1.2
List.of
Java 9
List.copyOf
Java 10

Assumes JDK 27, the same at JDK 25. List.of arrived in Java 9 and List.copyOf in 10; since 17 the unmodifiable wrappers no longer re-wrap one of their own views, and 21 added the sequenced variants.

context