Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Collections

List.copyOf() and immutable collections

Reference for List.copyOf(), Set.copyOf(), Map.copyOf() and Collectors.toUnmodifiableList(): true immutable copies versus unmodifiable views.

List.copyOf(collection), Set.copyOf(collection) and Map.copyOf(map) (all Java 10) return an immutable snapshot of their argument. The result cannot be changed through any method, and later changes to the source do not show up in it. This is the usual way to protect a class's internal state: copy on the way in, expose the immutable copy on the way out.

Do not confuse that with Collections.unmodifiableList(list), which is only a read-only view: nobody can modify the collection through the wrapper, but anyone holding the original can, and the wrapper then shows the changes. copyOf() also returns the argument itself when it is already an immutable collection created by List.of()/copyOf(), avoiding a needless copy.

Java
List<String> snapshot = List.copyOf(names);   // independent, immutable
List<String> view = Collections.unmodifiableList(names);   // live, read-only

Try it

Java Copy versus view

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Null rules, duplicates and maps

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
static <E> List<E>       List.copyOf(Collection<? extends E> coll)
static <E> Set<E>        Set.copyOf(Collection<? extends E> coll)
static <K,V> Map<K,V>    Map.copyOf(Map<? extends K,? extends V> map)
Name Description
coll / map The source whose current contents are copied.

Returns: an unmodifiable List, Set or Map with the same elements or entries. Throws: NullPointerException if the argument is null or contains a null element, key or value.

Related factories: List.of(...), Set.of(...), Map.of(...), Map.ofEntries(...), Stream.toList() (Java 16, allows nulls), Collectors.toUnmodifiableList/Set/Map() (Java 10), Collections.unmodifiableXxx().

Usage notes

  • Copy vs view: copyOf is a snapshot; Collections.unmodifiableList is a live read-only window. Pick a copy when the source may keep changing.
  • Shallow immutability: the collection is fixed, but mutable elements (like StringBuilder or a Date) can still be changed through it. Store immutable elements, such as strings, numbers and records, for real immutability.
  • No nulls anywhere, and contains(null) on these collections throws NullPointerException instead of returning false.
  • Set.copyOf and Map.copyOf iteration order is unspecified and may differ between runs. Sort before printing or use a TreeSet/LinkedHashSet copy if order matters.
  • Duplicates: Set.copyOf silently removes them (unlike Set.of); Map.copyOf cannot see duplicate keys because its source is already a map.
  • Efficiency: copying an already-immutable collection is free, and the small List.of() implementations are compact.
  • Defensive copying in a constructor: this.items = List.copyOf(items); makes the class safe against later changes by the caller.
  • Stream.toList() returns an unmodifiable list but permits null; Collectors.toList() makes no promise about mutability.