AbstractCollection retainAll() Method in Java

The retainAll() method in AbstractCollection is used to retain only the elements that are present in a specified collection. It removes all other elements that do not match. This method is useful when performing set intersection operations in Java collections.

Example 1: This example demonstrates how the retainAll() method removes elements that are not present in the second collection.

// Java program to illustrate retainAll() method 
import java.util.*;

public class Geeks {
    public static void main(String[] args) {
        
        // Creating the first collection
        List<String> l1 = new ArrayList<>();
        l1.add("one");
        l1.add("two");
        l1.add("three");

        // Creating the second collection
        List<String> l2 = new ArrayList<>();
        l2.add("three");
        l2.add("one");
        l2.add("five");

        System.out.println("List 1: " + l1);
        System.out.println("List 2: " + l2);

        // Retaining only the common elements
        l2.retainAll(l1);

        System.out.println("List 2 after retainAll(): " + l2);
    }
}

List 1: [one, two, three]
List 2: [three, one, five]
List 2 after retainAll(): [three, one]

Explanation: In the above example, list2.retainAll(list1) removes “five” because it is not present in list1. Only “one” and “three” are retained in list2.

Syntax of retainAll() Method

boolean retainAll(Collection c);

• Parameters: This method accepts a parameter collection which is the collection containing elements that need to be retained.
• Return Value: It returns “true” if the elements in the collections are retained successfully and if they are not, a “false” value is returned.

Exceptions: This method throws the following exceptions:

• UnsupportedOperationException: If the retainAll() method is not supported by the collection.
• ClassCastException: If any element in the main collection is incompatible with the specified collection, this is optional.
• NullPointerException: If the main collection has null values and the specified collection doesn’t allow them, or if the specified collection has nulls, this is optional.

Example 2: This example demonstrates what happens when retainAll() is called with a null collection.

// Handling NullPointerException in retainAll()
import java.util.*;

public class Geeks {
    public static void main(String[] args) {
        
        // Creating a collection
        List<String> l = new ArrayList<>();
        l.add("apple");
        l.add("banana");
        l.add("cherry");

        // Display collection before retainAll()
        System.out.println("List before retainAll(): " + l);

        try {
            // Passing null to retainAll()
            l.retainAll(null);
        } catch (NullPointerException e) {
            System.out.println("Exception caught: " + e);
        }
    }
}

List before retainAll(): [apple, banana, cherry]
Exception caught: java.lang.NullPointerException

Explanation: In the above example, the retainAll(null) is not a valid operation, so a NullPointerException is thrown. The exception is caught in the catch block, preventing the program from crashing.