retainAll() in Java

Syntax of retainAll() in Java

The method signature for retainAll() is:

And the method syntax for retainAll() is:

Parameters of retainAll() in Java

The method takes a single parameter - collection. Collection C contains the elements that should be retained in the ArrayList.

Return values of retainAll() in Java

Return Type: boolean

The method returns a boolean value "true" if the elements of the collection "C" have been successfully retained in the list; otherwise, it will throw exceptions.

Exceptions of retainAll() in Java

The exceptions thrown by retainAll() method are:

1. java.lang.ClassCastException The retainAll() method throws ClassCastException if the class of elements in ArrayList is incompatible with the class of elements in the collection.
2. java.lang.NullPointerException The retainAll() method throws NullPointerException if the ArrayList contains a null element and the collection does not permit null elements or if the collection is null.

Example for retainAll() in Java

Let's see a simple example:

Output :

In the above example, there are two lists. num has an integer $[1]$ and num1 has $[1,2,3,4]$ integers. After using the retainAll() method, common integers are retained in the num1 ArrayList. num1 ArrayList has only one element that is 1 after using the reatinAll() method.

What is retainAll() in Java?

The retainAll() method of the ArrayList class keeps only those elements in the ArrayList which are present in the collection passed as an argument to the method. ArrayList class is part of the collection framework in Java.

In simple words, the reatainAll() method takes a collection as an argument; it compares the elements of the ArrayList with elements of the collection. It keeps only those common elements in both ArrayList and collection and removes all other elements. The method returns true if the elements were retained successfully. The elements are retained in the original ArrayList only.

Let's briefly discuss the collection and ArrayList in Java.

Collection in Java

Java's Collection framework provides classes and interfaces for storing multiple objects as a single entity. Using java Collections, we can treat these objects as a single data structure and perform various operations like insertion, deletion, manipulation, searching, sorting, etc.

The interface Collection can be found in the java.util package. The collection framework includes multiple classes, such as Collection, Set, Queue, SortedSet, Dequeue, ArrayList, LinkedList, etc. The following is a diagram showing the hierarchy of Java's Collection framework.

ArrayList in Java

ArrayList is a class in the java.util package. It extends AbstractList and implements Collection and List interfaces, which means the ArrayList class is a subclass of the AbstractList class. It implements methods of the interfaces Collection and List. The hierarchy of the ArrayList class is shown in the below image.

ArrayList is an array that can be resized dynamically. Elements can be added and removed from ArrayList without declaring the size explicitly, as with built-in arrays.

Syntax: Let's create an ArrayList object as cars.

Operations can be performed on ArrayList class objects using its methods like add(), remove(), size(), retainAll(), etc. ArrayList has O(n) time complexity for add/remove operations but O(1) for the operation at the end of the list. We will understand it with the help of examples in the next section of this article.

More Examples

With the help of programming, let us see some more scenarios of the retainAll() method in Java.

Example 1: Java ArrayList retainAll()

Let's take two ArrayList, which contain natural numbers and even numbers.

numbers = $[1,2,3,4,5,6,7,8,9,10]$
even_no = $[2,4,6,8,10,12,14]$

And we need only even numbers in the numbers ArrayList.

Output:

As we can see, only even numbers in the numbers list are retained.

Example 2: Passing ArrayList collection as a parameter to the method

ArrayList's retainAll() method supports different collections as parameters. ArrayList itself can also be passed as a parameter to the retainAll() method.

Output:

In the above example, bag and box are two ArrayLists with some elements within them. box.retainAll(bag); retains only those elements in the boxes list present in bags ArrayList. All other elements are removed.

Example 3: Passing collection different than ArrayList as a parameter to the method.

Until now, we have passed ArrayList collection as a parameter to the retain () method in Java. Now, let's pass another parameter, such as HashSet, to the retain () method.

Output:

In the above example, there is an ArrayList num and a HashSet primeNum. The statement num.retainAll(primeNum); retains only those elements in ArrayList num present in HashSet primeNum. Hence, only 2, 3, and 5 are retained in the ArrayList num.

Example 4: Illustrating the error thrown by the retainAll() method

The retainAll() method throws NullPointerException if the ArrayList contains a null element and the collection does not permit null elements or if the collection is null. Let's see the error thrown by the retainAll() method in java.

Output:

In the above example, list1 contains null. When list2.retainAll(list1); is executed, it throws a runtime error, as shown in the output. It's because the retainAll() method cannot handle nulls in the collection and throws java.lang.NullPointerException.