Add One Element to an Immutable List in Java

1. Overview

In Java, immutable objects ensure thread safety and prevent unintended modifications, fostering robust and reliable code. However, sometimes, we want to add elements to an immutable list.

In this quick tutorial, we’ll explore how to achieve that in Java.

2. Introduction to the Problem

An Immutable list doesn’t allow us to add elements to it. But there are scenarios where we want to incorporate additional elements into an immutable list without compromising its immutability. In other words, we want an immutable list containing all elements in the given immutable list and the new elements.

Next, let’s create a method to do that. For simplicity, we’ll use unit test assertions to verify whether our solutions yield the expected result.

3. Leveraging a Mutable List

One idea to solve the problem is to leverage a mutable list, such as an ArrayList. Next, let’s elaborate the idea:

• Create an ArrayList to hold all elements in the original immutable list
• Add the new element to the ArrayList
• Make the ArrayList immutable

Now, let’s implement the logic in a method:

static <T> List<T> appendAnElement(List<T> immutableList, T element) {
    List<T> tmpList = new ArrayList<>(immutableList);
    tmpList.add(element);
    return Collections.unmodifiableList(tmpList);
}

As the code shows, appendAnElement() is a generic method. It first creates the ArrayList tmpList carrying the given immutableList‘s elements. Then, it adds element to tmpList. Finally, Collections.unmodifiableList(tmpList) is returned as the result. As the method name implies, Collections.unmodifiableList() returns an unmodifiable view of the specified list.

Next, let’s test the method. Since AssertJ can quickly examine if a collection is immutable, we’ll employ this library to verify whether our appendAnElement() method works as expected:

List<String> myList = List.of("A", "B", "C", "D", "E");
List<String> expected = List.of("A", "B", "C", "D", "E", "F");
List<String> result = appendAnElement(myList, "F");
assertThat(result).isEqualTo(expected)
  .isUnmodifiable();

Since the List.of() method returns an immutable list, we used this method to build up our input myList.

The test passes if we give it a run. So, the problem is solved. However, the method can only add one element to the list.

Next, let’s extend the method a bit to support multiple elements addition.

4. Adding Multiple Elements

Varargs (variable-length arguments) allows a method to accept an arbitrary number of parameters of the same type. Therefore, we can use this technique to make our method support multiple elements addition:

@SafeVarargs
static <T> List<T> appendElements(List<T> immutableList, T... elements) {
    List<T> tmpList = new ArrayList<>(immutableList);
    tmpList.addAll(Arrays.asList(elements));
    return Collections.unmodifiableList(tmpList);
}

As we can see in the above code, we annotate the method as @SafeVarargs to ensure our parameterized Varargs type is safe, and won’t cause Heap Pollution.

Using this method, we can conveniently add one single or multiple elements to an immutable list:

List<String> myList = List.of("A", "B", "C", "D", "E");
 
List<String> expected1 = List.of("A", "B", "C", "D", "E", "F");
List<String> result1 = appendElements(myList, "F");
assertThat(result1).isEqualTo(expected1)
  .isUnmodifiable();
 
List<String> expected2 = List.of("A", "B", "C", "D", "E", "F", "G", "H", "I");
List<String> result2 = appendElements(myList, "F", "G", "H", "I");
assertThat(result2).isEqualTo(expected2)
  .isUnmodifiable();

5. Conclusion

In this article, we explored how to add elements to an immutable list in Java and demonstrated how to use Varargs to make a method accept a variable number of arguments of the same type.

As always, the complete source code for the examples is available over on GitHub.