# Class PredicatedQueue<E>

java.lang.Object
org.apache.commons.collections4.collection.AbstractCollectionDecorator<E>
org.apache.commons.collections4.collection.PredicatedCollection<E>
org.apache.commons.collections4.queue.PredicatedQueue<E>

Type Parameters:
  `E` - the type of elements held in this queue

All Implemented Interfaces:
  `Serializable`, `Iterable<E>`, `Collection<E>`, `Queue<E>`

public class PredicatedQueue<E> extends PredicatedCollection<E> implements Queue<E>
Decorates another `Queue` to validate that additions match a specified predicate.

This queue exists to provide validation for the decorated queue. It is normally created to decorate an empty queue. If an object cannot be added to the queue, an IllegalArgumentException is thrown.

One usage would be to ensure that no null entries are added to the queue.

    Queue queue = PredicatedQueue.predicatedQueue(new UnboundedFifoQueue(), NotNullPredicate.INSTANCE);

Since:
  4.0
See Also:
  - Serialized Form

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class org.apache.commons.collections4.collection.PredicatedCollection

  `PredicatedCollection.Builder<E>`

- ## Field Summary

  ### Fields inherited from class org.apache.commons.collections4.collection.PredicatedCollection

  `predicate`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `PredicatedQueue(Queue<E> queue, Predicate<? super E> predicate)`
  Constructor that wraps (not copies).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected Queue<E>`
  `decorated()`
  Gets the queue being decorated.
  `E`
  `element()`
  `boolean`
  `offer(E object)`
  Override to validate the object being added to ensure it matches the predicate.
  `E`
  `peek()`
  `E`
  `poll()`
  `static <E> PredicatedQueue<E>`
  `predicatedQueue(Queue<E> Queue, Predicate<? super E> predicate)`
  Factory method to create a predicated (validating) queue.
  `E`
  `remove()`

  ### Methods inherited from class org.apache.commons.collections4.collection.PredicatedCollection

  `add, addAll, builder, notNullBuilder, predicatedCollection, validate`

  ### Methods inherited from class org.apache.commons.collections4.collection.AbstractCollectionDecorator

  `clear, contains, containsAll, isEmpty, iterator, remove, removeAll, removeIf, retainAll, setCollection, size, toArray, toArray, toString`

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

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

  ### Methods inherited from interface java.util.Collection

  `addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, remove, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray`

  ### Methods inherited from interface java.lang.Iterable

  `forEach`

  ### Methods inherited from interface java.util.Queue

  `add`

- ## Constructor Details

  - ### PredicatedQueue

    protected PredicatedQueue(Queue<E> queue, Predicate<? super E> predicate)
    Constructor that wraps (not copies).

    If there are any elements already in the collection being decorated, they are validated.

    Parameters:
      `queue` - the queue to decorate, must not be null
      `predicate` - the predicate to use for validation, must not be null
    Throws:
      `NullPointerException` - if queue or predicate is null
      `IllegalArgumentException` - if the Queue contains invalid elements

- ## Method Details

  - ### predicatedQueue

    public static <E> PredicatedQueue<E> predicatedQueue(Queue<E> Queue, Predicate<? super E> predicate)
    Factory method to create a predicated (validating) queue.

    If there are any elements already in the queue being decorated, they are validated.

    Type Parameters:
      `E` - the type of the elements in the queue
    Parameters:
      `Queue` - the queue to decorate, must not be null
      `predicate` - the predicate to use for validation, must not be null
    Returns:
      a new predicated queue
    Throws:
      `NullPointerException` - if queue or predicate is null
      `IllegalArgumentException` - if the queue contains invalid elements

  - ### decorated

    protected Queue<E> decorated()
    Gets the queue being decorated.
    Overrides:
      `decorated` in class `AbstractCollectionDecorator<E>`
    Returns:
      the decorated queue

  - ### element

    public E element()
    Specified by:
      `element` in interface `Queue<E>`

  - ### offer

    public boolean offer(E object)
    Override to validate the object being added to ensure it matches the predicate.
    Specified by:
      `offer` in interface `Queue<E>`
    Parameters:
      `object` - the object being added
    Returns:
      the result of adding to the underlying queue
    Throws:
      `IllegalArgumentException` - if the add is invalid

  - ### peek

    public E peek()
    Specified by:
      `peek` in interface `Queue<E>`

  - ### poll

    public E poll()
    Specified by:
      `poll` in interface `Queue<E>`

  - ### remove

    public E remove()
    Specified by:
      `remove` in interface `Queue<E>`