org.apache.commons.collections4.queue

## 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>

- 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
  Version:
    $Id: PredicatedQueue.java 1477765 2013-04-30 18:37:37Z tn $
  See Also:
    Serialized Form

- - ### Field Summary

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

      `predicate`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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, predicatedCollection, validate`

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

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

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

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

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

      `add`

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

      `addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray`

- - ### Constructor Detail

    - #### 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:
        `IllegalArgumentException` - if Queue or predicate is null
        `IllegalArgumentException` - if the Queue contains invalid elements

  - ### Method Detail

    - #### 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:
        `IllegalArgumentException` - 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

    - #### 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

    - #### poll

          public E poll()

      Specified by:
        `poll` in interface `Queue<E>`

    - #### peek

          public E peek()

      Specified by:
        `peek` in interface `Queue<E>`

    - #### element

          public E element()

      Specified by:
        `element` in interface `Queue<E>`

    - #### remove

          public E remove()

      Specified by:
        `remove` in interface `Queue<E>`

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.