# Class QueueUtils

java.lang.Object
org.apache.commons.collections4.QueueUtils

public class QueueUtils extends Object
Provides utility methods and decorators for `Queue` instances.

Since:
  4.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Queue`
  `EMPTY_QUEUE`
  An empty unmodifiable queue.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <E> Queue<E>`
  `emptyQueue()`
  Gets an empty `Queue`.
  `static <E> Queue<E>`
  `predicatedQueue(Queue<E> queue, Predicate<? super E> predicate)`
  Returns a predicated (validating) queue backed by the given queue.
  `static <E> Queue<E>`
  `synchronizedQueue(Queue<E> queue)`
  Returns a synchronized (thread-safe) queue backed by the given queue.
  `static <E> Queue<E>`
  `transformingQueue(Queue<E> queue, Transformer<? super E,? extends E> transformer)`
  Returns a transformed queue backed by the given queue.
  `static <E> Queue<E>`
  `unmodifiableQueue(Queue<? extends E> queue)`
  Returns an unmodifiable queue backed by the given queue.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### EMPTY_QUEUE

    public static final Queue EMPTY_QUEUE
    An empty unmodifiable queue.

- ## Method Details

  - ### emptyQueue

    public static <E> Queue<E> emptyQueue()
    Gets an empty `Queue`.
    Type Parameters:
      `E` - the type of the elements in the queue
    Returns:
      an empty `Queue`

  - ### predicatedQueue

    public static <E> Queue<E> predicatedQueue(Queue<E> queue, Predicate<? super E> predicate)
    Returns a predicated (validating) queue backed by the given queue.

    Only objects that pass the test in the given predicate can be added to the queue. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original queue after invoking this method, as it is a backdoor for adding invalid objects.

    Type Parameters:
      `E` - the type of the elements in the queue
    Parameters:
      `queue` - the queue to predicate, must not be null
      `predicate` - the predicate used to evaluate new elements, must not be null
    Returns:
      a predicated queue
    Throws:
      `NullPointerException` - if the queue or predicate is null

  - ### synchronizedQueue

    public static <E> Queue<E> synchronizedQueue(Queue<E> queue)
    Returns a synchronized (thread-safe) queue backed by the given queue. In order to guarantee serial access, it is critical that all access to the backing queue is accomplished through the returned queue.

    It is imperative that the user manually synchronize on the returned queue when iterating over it:

         Queue queue = QueueUtils.synchronizedQueue(new CircularFifoQueue());
         ...
         synchronized(queue) {
             Iterator i = queue.iterator(); // Must be in synchronized block
             while (i.hasNext())
                 foo(i.next());
             }
         }

    Failure to follow this advice may result in non-deterministic behavior.

    Type Parameters:
      `E` - the element type
    Parameters:
      `queue` - the queue to synchronize, must not be null
    Returns:
      a synchronized queue backed by that queue
    Throws:
      `NullPointerException` - if the queue is null
    Since:
      4.2

  - ### transformingQueue

    public static <E> Queue<E> transformingQueue(Queue<E> queue, Transformer<? super E,? extends E> transformer)
    Returns a transformed queue backed by the given queue.

    Each object is passed through the transformer as it is added to the Queue. It is important not to use the original queue after invoking this method, as it is a backdoor for adding untransformed objects.

    Existing entries in the specified queue will not be transformed. If you want that behavior, see `TransformedQueue.transformedQueue(java.util.Queue<E>, org.apache.commons.collections4.Transformer<? super E, ? extends E>)`.

    Type Parameters:
      `E` - the type of the elements in the queue
    Parameters:
      `queue` - the queue to predicate, must not be null
      `transformer` - the transformer for the queue, must not be null
    Returns:
      a transformed queue backed by the given queue
    Throws:
      `NullPointerException` - if the queue or transformer is null

  - ### unmodifiableQueue

    public static <E> Queue<E> unmodifiableQueue(Queue<? extends E> queue)
    Returns an unmodifiable queue backed by the given queue.
    Type Parameters:
      `E` - the type of the elements in the queue
    Parameters:
      `queue` - the queue to make unmodifiable, must not be null
    Returns:
      an unmodifiable queue backed by that queue
    Throws:
      `NullPointerException` - if the queue is null