Immutable List in Java

This post will discuss various methods to create an immutable list in Java.

Unmodifiable lists are “read-only” wrappers over other collections. They do not support any modification operations such as add, remove, and clear, but their underlying collection can be changed. Lists that additionally guarantee that no change in the Collection object will ever be visible are referred to as immutable. When we don’t expect to modify a collection, it’s a good practice to defensively copy it into an immutable collection. Immutable lists have many advantages over their mutable siblings, like they are thread-safe, more memory-efficient, and can be passed to untrusted libraries without any side effects. Here are some of the methods that we can use to create immutable lists in Java:

1. Using Guava Library

Guava provides simple, easy-to-use immutable versions of each standard Collection type, including Guava’s own Collection variations. An instance of ImmutableList contains its own private data and will never change. An ImmutableList collection can be created using different ways. We can use the ImmutableList.copyOf() method to create an immutable copy of the mutable list. We need to pass the mutable list as an argument to the method. The method returns an instance of ImmutableList that contains the same elements as the original list, but cannot be modified. For example, we can write:

import com.google.common.collect.ImmutableList;

import java.util.ArrayList;

import java.util.Arrays;

import java.util.List;

class Main

{

public static void main(String[] args)

{

List<String> list = new ArrayList<>(Arrays.asList("C", "C++", "Java"));

// ImmutableList.copyOf() creates a copy of the mutable list

ImmutableList<String> immutableList = ImmutableList.copyOf(list);

try {

// any attempt to modify the list will result in `UnsupportedOperationException`

immutableList.add("C#");

}

catch (UnsupportedOperationException ex) {

System.out.println("java.lang.UnsupportedOperationException");

}

// any changes made to the original list will not be reflected in the immutable list

list.add("Go");

System.out.println(immutableList); // [C, C++, Java]

}

Download Code

Guava also provides a Builder for creating immutable list instances. The ImmutableList.builder() method returns a builder that can be used to add elements to the list and then build it. For example, we can create a list like this:

import com.google.common.collect.ImmutableList;

import java.util.ArrayList;

import java.util.Arrays;

import java.util.List;

class Main

{

public static void main(String[] args)

{

List<String> mutableList = new ArrayList<>(Arrays.asList("C", "C++"));

// get a builder for creating immutable list instances

ImmutableList.Builder<String> builder = ImmutableList.builder();

// or `new ImmutableList.Builder<>();`

// `addAll()` adds each element of mutable list to the `ImmutableList`

// `build()` returns a newly created `ImmutableList`

ImmutableList<String> immutableList = builder.addAll(mutableList)

.add("Java")

.build();

try {

// any attempt to modify the list will result in `UnsupportedOperationException`

immutableList.add("C#");

}

catch (UnsupportedOperationException ex) {

System.out.println("java.lang.UnsupportedOperationException");

}

// any changes made to the original list will not be reflected in the immutable list

mutableList.add("C#");

System.out.println(immutableList); // [C, C++, Java]

}

Download Code

The ImmutableList.of() method returns an immutable list containing the given elements in order. It has seven overloaded versions, the last one with var-args to handle any number of elements. For example, we can create an immutable list with ImmutableList.of() like this:

import com.google.common.collect.ImmutableList;

class Main

{

public static void main(String[] args)

{

// create an immutable list containing the given elements, in order

ImmutableList<String> immutableList = ImmutableList.of("C", "C++", "Java");

try {

// any attempt to modify the list will result in `UnsupportedOperationException`

immutableList.add("C#");

}

catch (UnsupportedOperationException ex) {

System.out.println("java.lang.UnsupportedOperationException");

}

System.out.println(immutableList); // [C, C++, Java]

}

Download Code

2. Using Collection factory methods

In Java 9, several collection factory methods have been added to List, Set, and Map interfaces that allows for easy initialization of immutable collections with specified elements. These collections are structurally immutable, i.e., we cannot add, remove, or replace elements. Any modification operation will throw an UnsupportedOperationException. However, if the contained elements are mutable, this may cause the collection’s contents to appear to change. For example, we can use the new factory method List.of() in the List interface to create immutable lists, like this:

import java.util.List;

class Main

{

public static void main(String[] args)

{

// create an immutable list using `List.of()` in Java 9

List<String> immutableList = List.of("C", "C++", "Java");

try {

// any attempt to modify the list will result in `UnsupportedOperationException`

immutableList.add("C#");

}

catch (UnsupportedOperationException ex) {

System.out.println("java.lang.UnsupportedOperationException");

}

System.out.println(immutableList); // [C, C++, Java]

}

Download Run Code

Note that the Java Collections framework also provides the unmodifiableList() method, but it is unsafe to use as the returned list is only truly immutable if nobody holds a reference to the original collection. The returned list is also inefficient as the data structures will still have all the overhead of mutable collections, including concurrent modification checks, extra space in hash tables, etc. Basically, it is a view of a separate collection that can still change.

That’s all about creating an immutable List in Java.

Reference: Guava’s Wiki – Immutable Collections Explained

1. Using Guava Library

2. Using Collection factory methods

Share this: