ArrayBlockingQueue drainTo() Method in Java

ArrayBlockingQueue is bounded, blocking queue that stores the elements internally backed by an array. 

• ArrayBlockingQueue class is a member of the Java Collections Framework.
• Bounded means it will have a fixed size, you can not store number the elements more than the capacity of the queue.
• The queue also follows FIFO (first-in-first-out) rule for storing and removing elements from the queue.
• If you try to put an element into a full queue or to take an element from an empty queue then the queue will block you.

The drainTo(Collection c) method removes all available elements from this queue and adds them to the given collection. The number of elements can also be fixed which are required to be drained by providing the number of element ‘n’ as the second parameter to the method.

There are two types of drainTo method depending upon parameter passed to it:

1. The drainTo() method is used to transfer all elements to a collection. The drain operation is more efficient than repeatedly polling this queue using loops. There is also possibilities of failure encountered while attempting to add elements to collection c and because of that failure elements can be present in neither, either or both collections when the associated exception is thrown. if you attempt to drain a queue to itself IllegalArgumentException will be thrown. If the specified collection is modified while the operation is in progress, the behavior of this operation is undefined . So for using such methods we need to take care of this type of situation so we can overcome exceptions.

Syntax

public int drainTo(Collection c)

Parameter: The method accepts one parameter c which refers to the collection to transfer elements

Return Value: The method returns the number of elements drained.

Exception: The method might throw three types of exception:

• UnsupportedOperationException – if addition of elements is not supported by the specified collection
• ClassCastException – if the class of an element of this queue prevents it from being added to the specified collection
• NullPointerException – if the specified collection is null
• IllegalArgumentException – if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection

Below program illustrates drainTo(Collection c) method of ArrayBlockingQueue.

Java

// Program to demonstrate drainTo(Collection c)

import java.util.ArrayList;
import java.util.concurrent.ArrayBlockingQueue;

public class GFG {

    public static void main(String[] args)
    {
        // Define capacity of ArrayBlockingQueue
        int capacity = 10;

        // Create object of  ArrayBlockingQueue
        ArrayBlockingQueue queue = new
              ArrayBlockingQueue(capacity);

        // Add elements to ArrayBlockingQueue
        queue.add(23);
        queue.add(32);
        queue.add(45);
        queue.add(12);
        queue.add(27);
        queue.add(67);

        // Print queue before drainTo operation
        System.out.println("Before drainTo Operation");
        System.out.println("queue = " + queue);

        // Create Collection object to
        // transfer elements
        ArrayList list = new
                           ArrayList();

        // Call drainTo method of queue
        // and pass collection as parameter.
        queue.drainTo(list);

        // Print queue after drainTo operation
        System.out.println("After drainTo Operation");
        System.out.println("queue = " + queue);
        System.out.println("collection = " + list);
    }
}

Output:

Before drainTo Operation
queue = [23, 32, 45, 12, 27, 67]
After drainTo Operation
queue = []
collection = [23, 32, 45, 12, 27, 67]

2. The drainTo(Collection c, int maxElements) Method is used to transfer fixed number elements to the collection. After transferring the no of element specified ArrayBlocking queue contains only those elements which are not transferred to collection. This function is same as above function but this has some limitations.

Syntax:

public int drainTo(Collection c, int maxElements)

Parameter: The method accepts two parameters:

• c – This refers to the collection to transfer elements.
• maxElements – This is of integer type and refers to the maximum number of elements to be transferred to the collection.

Return Value:
the number of elements drained.

Exceptions:

• UnsupportedOperationException – if addition of elements is not supported by the specified collection
• ClassCastException – if the class of an element of this queue prevents it from being added to the specified collection
• NullPointerException – if the specified collection is null
• IllegalArgumentException – if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection

Below program illustrates the working of drainTo(Collection c, int maxElements) method of ArrayBlockingQueue.

Java

// Program Demonstrate drainTo(Collection c, int maxElements)
// method of ArrayBlockingQueue

import java.util.ArrayList;
import java.util.concurrent.ArrayBlockingQueue;

public class GFG {

    public static void main(String[] args)
    {
        // Define capacity of ArrayBlockingQueue
        int capacity = 10;

        // Create object of  ArrayBlockingQueue
        ArrayBlockingQueue queue = new
               ArrayBlockingQueue(capacity);

        // Add elements to ArrayBlockingQueue
        queue.add("aman");
        queue.add("sudhir");
        queue.add("harsh");
        queue.add("rahul");
        queue.add("raunak");

        // Print queue before drainTo operation
        System.out.println("Before drainTo Operation");
        System.out.println("queue = " + queue);

        // Transfer elements from ArrayBlockingQueue;
        ArrayList list = new ArrayList();

        // Define no of elements to be  transferred
        int maxElements = 3;

        // Call drainTo method of queue and pass
        // the collection as parameter.
        queue.drainTo(list, maxElements);

        // Print queue after drainTo operation
        System.out.println("After drainTo Operation");
        System.out.println("queue = " + queue);
        System.out.println("collection = " + list);
    }
}

Output:

Before drainTo Operation
queue = [aman, sudhir, harsh, rahul, raunak]
After drainTo Operation
queue = [rahul, raunak]
collection = [aman, sudhir, harsh]

Reference: https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ArrayBlockingQueue.html#drainTo(java.util.Collection)