Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Creating a Java Immutable Map

Learn how to create immutable maps in Java with Map.of, Map.copyOf, and Collections.unmodifiableMap. Compare behavior, null handling, and when to choose each approach.

~5 min readJava
#immutable collections#Map.of#unmodifiable map#Java collections
A Java immutable map concept showing a locked map with keys and values, representing unmodifiable collections.

When you need to pass a configuration map around an application without allowing it to be modified, the Java standard library offers several options. You can use Map.of for a small fixed map, Map.copyOf for an immutable copy of an existing map, or Collections.unmodifiableMap for a read-only view of a map you still own. The choice affects not only whether mutation is blocked, but also runtime behavior, null handling, ordering guarantees, and memory use.

The Problem with Mutable Maps

A regular HashMap is mutable by design. Every reference to the map can call put, remove, or clear, which makes it easy to introduce subtle bugs when the map is shared across components. For example, a service that reads a configuration map might accidentally modify it, breaking other parts of the application that rely on the original values.

java
Map<String, String> config = new HashMap<>(); config.put("timeout", "30"); // Later, another component can modify it: config.put("timeout", "60");

Once the map is passed to multiple methods, there is no way to enforce that it stays unchanged. The standard solution is to create an immutable view or a truly immutable map.

Creating an Immutable Map with Map.of

Java 9 introduced Map.of as a static factory method for creating small immutable maps. It accepts key-value pairs and returns a map that cannot be modified. Attempting to call put, remove, or replace throws an UnsupportedOperationException.

java
Map<String, Integer> scores = Map.of( "alice", 10, "bob", 20, "carol", 30 );

Map.of has overloads for up to 10 entries. If you need more, use Map.ofEntries, which takes a varargs array of Map.Entry objects.

java
Map<String, Integer> large = Map.ofEntries( Map.entry("alice", 10), Map.entry("bob", 20), // ... more entries );

Both Map.of and Map.ofEntries reject null keys and values. This is a deliberate design choice: the standard immutable map factories keep one uniform rule instead of inheriting the different null behavior of mutable maps such as HashMap and TreeMap.

Using Map.copyOf for Existing Maps

If you already have a map and want an immutable version, Map.copyOf (added in Java 10) returns an immutable map containing the same entries. It is not a view: if the original map is later modified through another reference, the returned map is not affected.

java
Map<String, String> original = new HashMap<>(); original.put("host", "localhost"); original.put("port", "8080"); Map<String, String> immutable = Map.copyOf(original); original.put("port", "9090"); // immutable still has port=8080

Like Map.of, Map.copyOf throws NullPointerException if the source map contains a null key or value. It also does not preserve the iteration order of the source map; the order is unspecified.

Wrapping with Collections.unmodifiableMap

Before Java 9, the standard way to create an unmodifiable map was Collections.unmodifiableMap. This method returns a view of the original map. The view does not allow direct modification, but the underlying map can still be changed through its original reference.

java
Map<String, String> mutable = new HashMap<>(); mutable.put("key", "value"); Map<String, String> unmodifiable = Collections.unmodifiableMap(mutable); // This throws UnsupportedOperationException unmodifiable.put("other", "value"); // But this is allowed: mutable.put("other", "value"); // Now unmodifiable sees the change

This is a view, not a copy. If the original map is modified after the wrapper is created, the unmodifiable view reflects those changes. This behavior is useful when you want to expose a read-only view of a map that is still owned by another component, but it is not a true immutable map.

Comparing the Three Approaches

The following table summarizes the key differences:

FeatureMap.of / Map.ofEntriesMap.copyOfCollections.unmodifiableMap
Introduced inJava 9Java 10Java 1.2
Null keys/valuesNot allowedNot allowedAllowed (if wrapped map supports them)
Independent copyYesYes (not a view)No, it is a view
Iteration orderUnspecifiedUnspecifiedDepends on underlying map
Best forSmall fixed mapsCopying an existing mapExposing a read-only view of a mutable map

Map.of and Map.copyOf produce immutable maps. Map.copyOf is not a view, so later changes to a mutable original do not appear in the returned map. Collections.unmodifiableMap only prevents direct modification through the wrapper; it does not protect against changes to the original map.

Performance and Memory Considerations

Immutable maps created by Map.of and Map.copyOf can be more memory-efficient than a HashMap because they do not need a resizable bucket array. Their internal representation is compact, and lookup still uses the key's hash code. This is especially true for small maps.

Immutable maps are also easy to share across threads. Because there is no mutable state to corrupt, they can be passed around without synchronization or defensive copies. This can reduce contention, though the primary benefit in concurrent code is correctness rather than speed.

However, immutable maps do not support updates in place. Every change requires creating a new map. If the map is updated frequently, an immutable map is probably not the right choice; the overhead of copying the map on each change outweighs the safety benefits.

Choosing the Right Approach for Your Use Case

Use Map.of when you need a small, fixed set of key-value pairs. It is concise and efficient for configuration constants, lookup tables, or default values.

Use Map.copyOf when you have an existing map that you want to protect from future changes. This is common when receiving a map from an external source, such as a method parameter or a deserialized object, and you want to ensure it cannot be modified later.

Use Collections.unmodifiableMap when you need to expose a read-only view of a map that is still owned by another object. For example, a class might keep a private mutable map and return an unmodifiable view to clients. This avoids copying the map while still preventing direct modification through the public API.

Common Pitfalls and Edge Cases

One subtle issue is that an immutable map only prevents structural modification; it does not make the values themselves immutable. If the map contains mutable objects, those objects can still be changed.

java
Map<String, List<String>> map = Map.of("key", new ArrayList<>()); map.get("key").add("value"); // This works

The map itself is unchanged, but the list it references is modified. To achieve deep immutability, you must also make the values immutable, such as using List.of instead of ArrayList.

Another edge case is iteration order. Map.of and Map.copyOf do not guarantee any specific order. If your code relies on entry order, use a LinkedHashMap and wrap it with Collections.unmodifiableMap for insertion order, or use a TreeMap for sorted order.

Finally, remember that Map.of and Map.copyOf reject null keys and values. If you need to allow null values, use Collections.unmodifiableMap with a map that permits them, such as a HashMap. This is a deliberate tradeoff: the standard immutable maps prioritize uniform behavior over flexibility.

When an Immutable Map Is Not the Answer

If you need to modify the map frequently, consider using a mutable map with proper encapsulation, or a concurrent map like ConcurrentHashMap for thread safety. Immutable maps are best for data that is set once and then read many times. They are not suitable for dynamic data that changes over time.

For very large maps, the memory savings of the standard immutable map factories may be less significant. Because there is no resize mechanism, the map cannot grow in place; adding an entry requires creating a new map.

In summary, the Java standard library provides a clear set of tools for creating immutable maps. Understanding the difference between a copy and a view, and knowing when to use each, helps you write safer and more maintainable code.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.