What is the ConcurrentLinkedQueue.retainAll() method in Java?

The ConcurrentLinkedQueue is a thread-safe unbounded queue. The elements are ordered by FIFO (First-In-First-Out). The elements are inserted at the tail (end) and retrieved from the head (start) of the queue.

The null elements are not allowed as an element of the queue. We can use the ConcurrentLinkedQueue when multiple threads are sharing a single queue.

The retainAll method removes all the elements of the ConcurrentLinkedQueue object which are not present in the passed collection.

Syntax

public boolean retainAll(Collection<?> c)

Parameters

  • This method takes the collection object to be retained in this deque object as an argument.

  • The NullPointerException is thrown if the passed collections have null elements.

  • The ClassCastException is thrown if any one of the elements in the passed collection is incompatible with the specified collection.

Return value

This method returns true if the queue changes as a result of the call (any element is removed from the queue due to the element not being present in the passed collection). Otherwise, false is returned.

Code

The code below demonstrates how to use the retainAll method:

import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.ArrayList;
class RetainAll {
    public static void main( String args[] ) {
        ConcurrentLinkedQueue<Integer> queue = new ConcurrentLinkedQueue<>();
        queue.add(1);
        queue.add(2);
        queue.add(3);
        ArrayList<Integer> list = new ArrayList<>();
        list.add(1);
        list.add(4);
        System.out.println("The queue is "+ queue);
        System.out.println("The list is "+ list);
        System.out.println("\nCalling queue.retainAll(list). Is queue changed - " + queue.retainAll(list));
        System.out.println("\nThe queue is "+ queue);
    }
}

In the code above,

In line 1 and 2: We import the ConcurrentLinkedQueue and ArrayList classes.

From lines 5 to 8: We create a new ConcurrentLinkedQueue object with the name queue and add three elements (1,2,3) to the queue object using the add method.

From lines 10 to 12: We create a new ArrayList object with the name list and add two elements (1,4) to the list object using the add method.

In line 16: We use the retainAll method to retain only elements present in the list. In our case, the elements of the list and queue are listed below:

Elements of list -- 1,4
Elements of queue -- 1,2,3

The retainAll will,

  • Check if element 1 of queue is present in the list. The list contains 1. So the 1 is retained in the queue.

  • Check if element 2 of queue is present in the list. The list doesn’t contain 2. So the 2 is removed from the queue.

  • Check if element 3 of queue is present in the list. The list doesn’t contain 3. So the 3 is removed from the queue.

The resulting queue will be [1].

Free Resources

License: Creative Commons-Attribution-ShareAlike 4.0 (CC-BY-SA 4.0)