PriorityBlockingQueue drainTo() method in Java

The drainTo(Collection col) method of PriorityBlockingQueue removes all available elements from this LinkedBlocking Queue and adds them to the given collection passed as a parameter.

drainTo(Collection<? super E> col)

The drainTo(Collection<? super E> col) method of PriorityBlockingQueue removes all of the elements from this queue and adds them to the given collection col. This is a more efficient way than repeatedly polling this queue.
There is also possibilities of failure encountered while attempting to add elements to collection c from the queue and due to that failure, elements is distributed between both collections when the associated exception is thrown. If a queue is tried to drainTo() to queue itself, then 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, one needs to take care of this type of situation to overcome exceptions.
Syntax:

public int drainTo(Collection<? super E> col)

Parameter: This method accepts one parameter col which represents the collection to transfer elements from PriorityBlockingQueue.
Return Value: This method returns the number of elements drained to collection from queue.
Exception: This method throws following exceptions: 

• UnsupportedOperationException– if collection cannot able to add elements.
• ClassCastException– if class of element stops method to add element to collection.
• NullPointerException– if the collection is null
• IllegalArgumentException– if arguments of the method prevents it from being added to the specified collection

Below programs illustrates drainTo() method of PriorityBlockingQueue class:
Example 1: Program to demonstrate drainTo() method on PriorityBlockingQueue which contains a list of numbers to a ArrayList.

Java

// Java Program Demonstrate drainTo()
// method of PriorityBlockingQueue

import java.util.concurrent.PriorityBlockingQueue;
import java.util.*;
public class GFG {

    public static void main(String[] args)
    {
        // define capacity of PriorityBlockingQueue
        int capacityOfQueue = 5;

        // create object of PriorityBlockingQueue
        PriorityBlockingQueue<Integer> PrioQueue
            = new PriorityBlockingQueue<Integer>(capacityOfQueue);

        // Add numbers to PriorityBlockingQueue
        PrioQueue.put(7855642);
        PrioQueue.put(35658786);
        PrioQueue.put(5278367);
        PrioQueue.put(74381793);
        PrioQueue.put(76487590);
        PrioQueue.put(87625142);

        // create a ArrayList of Integers
        ArrayList<Integer> list = new ArrayList<Integer>();

        // drain all elements of PriorityBlockingQueue to ArrayList
        // Using drainTo() method
        int noOfElementDrained = PrioQueue.drainTo(list);

        // print details
        System.out.println("No of elements drained :" + noOfElementDrained);
        System.out.println("ArrayList Contains element");

        for (int i : list)
            System.out.println(i);
    }
}

Output:

No of elements drained :6
ArrayList Contains element
5278367
7855642
35658786
74381793
76487590
87625142

Example 2:
Below program demonstrate Exception thrown by drainTo() method. 

Java

// Java Program Demonstrate drainTo()
// method of PriorityBlockingQueue

import java.util.concurrent.PriorityBlockingQueue;
import java.util.*;
public class GFG {

    public static void main(String[] args)
    {
        // define capacity of PriorityBlockingQueue
        int capacityOfQueue = 5;

        // create object of PriorityBlockingQueue which contains
        // name of students
        PriorityBlockingQueue<String> names
            = new PriorityBlockingQueue<String>(capacityOfQueue);

        // Add names of students of girls college
        names.add("Joyita");
        names.add("Priyanka");
        names.add("Joydeep");

        // create a collection with null
        ArrayList<String> collection = null;

        // try to drain to collection equals to null
        try {
            names.drainTo(collection);
        }
        catch (Exception e) {
            System.out.println("Exception Thrown: " + e);
        }
    }
}

Output:

Exception Thrown: java.lang.NullPointerException

drainTo(Collection<? super E> col, int maxElements)

The drainTo(Collection<? super E> col, int maxElements) used to transfer fixed number elements which is passed as integer in drainTo() to collection which is also passed as parameter to method. After transferring the elements, PriorityBlockingQueue has only those elements which are not transferred to collection. This function is same as above function with some limitations to transfer fixed no of element.
Syntax:

public int drainTo(Collection<? super E> col, int maxElements)

Parameter: The method accepts two parameters: 

• col– It represents the collection to transfer elements from PriorityBlockingQueue.
• maxElements– This is of integer type and refers to the maximum number of elements to be transferred to the collection.

Return Value: The method returns the number of elements drained to collection from queue.
Exception: This method throws following exceptions: 

• UnsupportedOperationException – if collection cannot able to add elements.
• ClassCastException -if class of element stops method to add element to collection.
• NullPointerException – if the collection is null
• IllegalArgumentException – if arguments of the method prevents it from being added to the specified collection

Below programs illustrates drainTo(Collection<? super E> col, int maxElements) method of PriorityBlockingQueue class:
Example 1: Program to demonstrate drainTo(Collection<? super E> c, int maxElements) method on PriorityBlockingQueue which contains a list of numbers to a ArrayList and we only going to transfer 3 elements.

Java

// Java Program Demonstrate drainTo()
// method of PriorityBlockingQueue

import java.util.concurrent.PriorityBlockingQueue;
import java.util.*;
public class GFG {

    public static void main(String[] args)
    {
        // define capacity of PriorityBlockingQueue
        int capacityOfQueue = 5;

        // create object of PriorityBlockingQueue
        PriorityBlockingQueue<Integer> PrioQueue
            = new PriorityBlockingQueue<Integer>(capacityOfQueue);

        // Add numbers to PriorityBlockingQueue
        PrioQueue.put(7855642);
        PrioQueue.put(35658786);
        PrioQueue.put(5278367);
        PrioQueue.put(74381793);
        PrioQueue.put(76487590);
        PrioQueue.put(87625142);

        // create maxElement variable
        // Contains no of elements we want to transfer
        int maxElement = 3;

        // create a ArrayList of Integers
        ArrayList<Integer> list = new ArrayList<Integer>();

        // drain all elements of PriorityBlockingQueue to ArrayList
        // Using drainTo() method
        int noOfElementDrained = PrioQueue.drainTo(list, maxElement);

        // print details
        System.out.println("ArrayList Contains element");

        for (int i : list)
            System.out.println(i);
    }
}

Output:

ArrayList Contains element
5278367
7855642
35658786

Example 2:
Below program demonstrate drainTo(Collection<? super E> c, int maxElements) method on list of names and transfer two names to a arraylist and print the list. 

Java

// Java Program Demonstrate drainTo()
// method of PriorityBlockingQueue

import java.util.concurrent.PriorityBlockingQueue;
import java.util.*;
public class GFG {

    public static void main(String[] args)
    {
        // define capacity of PriorityBlockingQueue
        int capacityOfQueue = 5;

        // create object of PriorityBlockingQueue which contains
        // name of students
        PriorityBlockingQueue<String> names
            = new PriorityBlockingQueue<String>(capacityOfQueue);

        // Add names of students of girls college
        names.add("Joyita");
        names.add("Priyanka");
        names.add("Ravi");
        names.add("Suraj");

        // create maxElement variable
        // Contains no of elements we want to transfer
        // here we want to transfer only two names
        int maxElement = 2;

        // create a collection with null
        ArrayList<String> collection = new ArrayList<String>();

        // drain all elements of PriorityBlockingQueue to ArrayList
        // Using drainTo() method
        int noOfElementDrained = names.drainTo(collection, maxElement);

        // print details
        System.out.println("ArrayList Contains element");

        int i = 0;
        for (String str : collection) {
            System.out.println("Element " + i + " : " + str);
            i++;
        }
    }
}

Output:

ArrayList Contains element
Element 0 : Joyita
Element 1 : Priyanka

Reference:

• https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/PriorityBlockingQueue.html#drainTo-java.util.Collection-
• https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/PriorityBlockingQueue.html#drainTo-java.util.Collection-int-