Método ArrayBlockingQueue DrainTo() en Java

ArrayBlockingQueue es una cola de bloqueo limitada que almacena los elementos respaldados internamente por una array. 

• La clase ArrayBlockingQueue es miembro de Java Collections Framework.
• Acotado significa que tendrá un tamaño fijo, no puede almacenar el número de elementos más que la capacidad de la cola.
• La cola también sigue la regla FIFO (primero en entrar, primero en salir) para almacenar y eliminar elementos de la cola.
• Si intenta colocar un elemento en una cola llena o tomar un elemento de una cola vacía, la cola lo bloqueará.

El método de drenaje ( Colección c ) elimina todos los elementos disponibles de esta cola y los agrega a la colección dada . También se puede fijar el número de elementos que deben drenarse proporcionando el número de elemento ‘n’ como segundo parámetro del método.

Hay dos tipos de método de drenaje en función del parámetro que se le pasa:

1. El método DrainTo() se usa para transferir todos los elementos a una colección. La operación de drenaje es más eficiente que sondear repetidamente esta cola mediante bucles. También hay posibilidades de que se produzca un error al intentar agregar elementos a la colección c y, debido a ese error, los elementos pueden estar presentes en ninguna de las colecciones, en una o en ambas cuando se lanza la excepción asociada. si intenta drenar una cola a sí misma, se lanzará IllegalArgumentException. Si la colección especificada se modifica mientras la operación está en curso, el comportamiento de esta operación no está definido. Entonces, para usar tales métodos, debemos ocuparnos de este tipo de situación para que podamos superar las excepciones.

Sintaxis

public int drainTo(Collection c)

Parámetro: El método acepta un parámetro c que se refiere a la colección para transferir elementos

Valor devuelto: el método devuelve el número de elementos drenados.

Excepción: el método puede arrojar tres tipos de excepción:

• UnsupportedOperationException : si la colección especificada no admite la adición de elementos
• ClassCastException : si la clase de un elemento de esta cola impide que se agregue a la colección especificada
• NullPointerException : si la colección especificada es nula
• IllegalArgumentException : si la colección especificada es esta cola, o alguna propiedad de un elemento de esta cola impide que se agregue a la colección especificada

El siguiente programa ilustra el método de drenaje ( Colección c ) de ArrayBlockingQueue.

// 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 before drainTo operation
        System.out.println("After drainTo Operation");
        System.out.println("queue = " + queue);
        System.out.println("collection = " + list);
    }
}

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

2. El método de drenaje a ( Colección c, int maxElements ) se utiliza para transferir elementos de número fijo a la colección. Después de transferir el número de elemento especificado, la cola ArrayBlocking contiene solo aquellos elementos que no se transfieren a la colección. Esta función es la misma que la anterior, pero tiene algunas limitaciones.

Sintaxis:

public int drainTo(Collection c, int maxElements)

Parámetro: El método acepta dos parámetros:

• c – Se refiere a la colección para transferir elementos.
• maxElements: es de tipo entero y se refiere a la cantidad máxima de elementos que se transferirán a la colección.

Valor devuelto: 
el número de elementos drenados.

Excepciones: 

• UnsupportedOperationException : si la colección especificada no admite la adición de elementos
• ClassCastException : si la clase de un elemento de esta cola impide que se agregue a la colección especificada
• NullPointerException : si la colección especificada es nula
• IllegalArgumentException : si la colección especificada es esta cola, o alguna propiedad de un elemento de esta cola impide que se agregue a la colección especificada

El siguiente programa ilustra el funcionamiento del método de drenaje a (Colección c, int maxElements) de ArrayBlockingQueue.

// 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 before drainTo operation
        System.out.println("After drainTo Operation");
        System.out.println("queue = " + queue);
        System.out.println("collection = " + list);
    }
}

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

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