# Queue

public interface **Queue** implements [Collection](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html)\<E\>

|---|---|---|
| Known Indirect Subclasses [AbstractQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/AbstractQueue.html)\<E\>, [ArrayBlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ArrayBlockingQueue.html)\<E\>, [ArrayDeque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ArrayDeque.html)\<E\>, [BlockingDeque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/BlockingDeque.html)\<E\>, [BlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/BlockingQueue.html)\<E\>, [ConcurrentLinkedDeque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ConcurrentLinkedDeque.html)\<E\>, [ConcurrentLinkedQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ConcurrentLinkedQueue.html)\<E\>, [DelayQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/DelayQueue.html)\<E extends [Delayed](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Delayed.html)\>, [Deque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Deque.html)\<E\>, [LinkedBlockingDeque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/LinkedBlockingDeque.html)\<E\>, [LinkedBlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/LinkedBlockingQueue.html)\<E\>, [LinkedList](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/LinkedList.html)\<E\>, [LinkedTransferQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/LinkedTransferQueue.html)\<E\>, [PriorityBlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/PriorityBlockingQueue.html)\<E\>, [PriorityQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/PriorityQueue.html)\<E\>, [SynchronousQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/SynchronousQueue.html)\<E\>, [TransferQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TransferQueue.html)\<E\> |---|---| | [AbstractQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/AbstractQueue.html)\<E\> | This class provides skeletal implementations of some `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html` operations. | | [ArrayBlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ArrayBlockingQueue.html)\<E\> | A bounded {@linkplain BlockingQueue blocking queue} backed by an array. | | [ArrayDeque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ArrayDeque.html)\<E\> | Resizable-array implementation of the `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Deque.html` interface. | | [BlockingDeque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/BlockingDeque.html)\<E\> | A `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Deque.html` that additionally supports blocking operations that wait for the deque to become non-empty when retrieving an element, and wait for space to become available in the deque when storing an element. | | [BlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/BlockingQueue.html)\<E\> | A `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html` that additionally supports operations that wait for the queue to become non-empty when retrieving an element, and wait for space to become available in the queue when storing an element. | | [ConcurrentLinkedDeque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ConcurrentLinkedDeque.html)\<E\> | An unbounded concurrent {@linkplain Deque deque} based on linked nodes. | | [ConcurrentLinkedQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ConcurrentLinkedQueue.html)\<E\> | An unbounded thread-safe {@linkplain Queue queue} based on linked nodes. | | [DelayQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/DelayQueue.html)\<E extends [Delayed](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Delayed.html)\> | An unbounded {@linkplain BlockingQueue blocking queue} of `Delayed` elements, in which an element can only be taken when its delay has expired. | | [Deque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Deque.html)\<E\> | A linear collection that supports element insertion and removal at both ends. | | [LinkedBlockingDeque](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/LinkedBlockingDeque.html)\<E\> | An optionally-bounded {@linkplain BlockingDeque blocking deque} based on linked nodes. | | [LinkedBlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/LinkedBlockingQueue.html)\<E\> | An optionally-bounded {@linkplain BlockingQueue blocking queue} based on linked nodes. | | [LinkedList](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/LinkedList.html)\<E\> | Doubly-linked list implementation of the `List` and `Deque` interfaces. | | [LinkedTransferQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/LinkedTransferQueue.html)\<E\> | An unbounded `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TransferQueue.html` based on linked nodes. | | [PriorityBlockingQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/PriorityBlockingQueue.html)\<E\> | An unbounded {@linkplain BlockingQueue blocking queue} that uses the same ordering rules as class `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/PriorityQueue.html` and supplies blocking retrieval operations. | | [PriorityQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/PriorityQueue.html)\<E\> | An unbounded priority {@linkplain Queue queue} based on a priority heap. | | [SynchronousQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/SynchronousQueue.html)\<E\> | A {@linkplain BlockingQueue blocking queue} in which each insert operation must wait for a corresponding remove operation by another thread, and vice versa. | | [TransferQueue](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TransferQueue.html)\<E\> | A `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/BlockingQueue.html` in which producers may wait for consumers to receive elements. | |||

A collection designed for holding elements prior to processing.
Besides basic `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html` operations,
queues provide additional insertion, extraction, and inspection
operations. Each of these methods exists in two forms: one throws
an exception if the operation fails, the other returns a special
value (either `null` or `false`, depending on the
operation). The latter form of the insert operation is designed
specifically for use with capacity-restricted `Queue`
implementations; in most implementations, insert operations cannot
fail.

|---|---|---|
|   | *Throws exception* | *Returns special value* |
| **Insert** | `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#add(E)` | `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#offer(E)` |
| **Remove** | `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#remove()` | `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#poll()` |
| **Examine** | `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#element()` | `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#peek()` |
[Summary of Queue methods]

Queues typically, but do not necessarily, order elements in a
FIFO (first-in-first-out) manner. Among the exceptions are
priority queues, which order elements according to a supplied
comparator, or the elements' natural ordering, and LIFO queues (or
stacks) which order the elements LIFO (last-in-first-out).
Whatever the ordering used, the *head* of the queue is that
element which would be removed by a call to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#remove()` or
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#poll()`. In a FIFO queue, all new elements are inserted at
the *tail* of the queue. Other kinds of queues may use
different placement rules. Every `Queue` implementation
must specify its ordering properties.

The `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#offer(E)` method inserts an element if possible,
otherwise returning `false`. This differs from the `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#add(E)` method, which can fail to
add an element only by throwing an unchecked exception. The
`offer` method is designed for use when failure is a normal,
rather than exceptional occurrence, for example, in fixed-capacity
(or "bounded") queues.

The `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#remove()` and `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#poll()` methods remove and
return the head of the queue.
Exactly which element is removed from the queue is a
function of the queue's ordering policy, which differs from
implementation to implementation. The `remove()` and
`poll()` methods differ only in their behavior when the
queue is empty: the `remove()` method throws an exception,
while the `poll()` method returns `null`.

The `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#element()` and `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#peek()` methods return, but do
not remove, the head of the queue.

The `Queue` interface does not define the *blocking queue methods*, which are common in concurrent programming. These methods,
which wait for elements to appear or for space to become available, are
defined in the `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/BlockingQueue.html` interface, which
extends this interface.

`Queue` implementations generally do not allow insertion
of `null` elements, although some implementations, such as
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/LinkedList.html`, do not prohibit insertion of `null`.
Even in the implementations that permit it, `null` should
not be inserted into a `Queue`, as `null` is also
used as a special return value by the `poll` method to
indicate that the queue contains no elements.

`Queue` implementations generally do not define
element-based versions of methods `equals` and
`hashCode` but instead inherit the identity based versions
from class `Object`, because element-based equality is not
always well-defined for queues with the same elements but different
ordering properties.

### Public Method Summary

|---|---|
| abstract boolean | [add](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#add(E))(E e) Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and throwing an `IllegalStateException` if no space is currently available. |
| abstract E | [element](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#element())() Retrieves, but does not remove, the head of this queue. |
| abstract boolean | [offer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#offer(E))(E e) Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions. |
| abstract E | [peek](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#peek())() Retrieves, but does not remove, the head of this queue, or returns `null` if this queue is empty. |
| abstract E | [poll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#poll())() Retrieves and removes the head of this queue, or returns `null` if this queue is empty. |
| abstract E | [remove](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#remove())() Retrieves and removes the head of this queue. |

### Inherited Method Summary

From interface [java.util.Collection](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html)

|---|---|
| abstract boolean | [add](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#add(E))(E e) Ensures that this collection contains the specified element (optional operation). |
| abstract boolean | [addAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#addAll(java.util.Collection<?%20extends%20E>))([Collection](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html)\<? extends E\> c) Adds all of the elements in the specified collection to this collection (optional operation). |
| abstract void | [clear](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#clear())() Removes all of the elements from this collection (optional operation). |
| abstract boolean | [contains](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#contains(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o) Returns true if this collection contains the specified element. |
| abstract boolean | [containsAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#containsAll(java.util.Collection<?>))([Collection](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html)\<?\> c) Returns true if this collection contains all of the elements in the specified collection. |
| abstract boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o) Compares the specified object with this collection for equality. |
| abstract int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#hashCode())() Returns the hash code value for this collection. |
| abstract boolean | [isEmpty](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#isEmpty())() Returns true if this collection contains no elements. |
| abstract [Iterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html)\<E\> | [iterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#iterator())() Returns an iterator over the elements in this collection. |
| [Stream](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Stream.html)\<E\> | [parallelStream](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#parallelStream())() Returns a possibly parallel `Stream` with this collection as its source. |
| abstract boolean | [remove](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#remove(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) o) Removes a single instance of the specified element from this collection, if it is present (optional operation). |
| abstract boolean | [removeAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#removeAll(java.util.Collection<?>))([Collection](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html)\<?\> c) Removes all of this collection's elements that are also contained in the specified collection (optional operation). |
| boolean | [removeIf](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#removeIf(java.util.function.Predicate<?%20super%20E>))([Predicate](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Predicate.html)\<? super E\> filter) Removes all of the elements of this collection that satisfy the given predicate. |
| abstract boolean | [retainAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#retainAll(java.util.Collection<?>))([Collection](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html)\<?\> c) Retains only the elements in this collection that are contained in the specified collection (optional operation). |
| abstract int | [size](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#size())() Returns the number of elements in this collection. |
| [Spliterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Spliterator.html)\<E\> | [spliterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#spliterator())() Creates a `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Spliterator.html` over the elements in this collection. |
| [Stream](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Stream.html)\<E\> | [stream](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#stream())() Returns a sequential `Stream` with this collection as its source. |
| abstract \<T\> T\[\] | [toArray](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#toArray(T[]))(T\[\] a) Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. |
| abstract [Object\[\]](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [toArray](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#toArray())() Returns an array containing all of the elements in this collection. |

From interface [java.lang.Iterable](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Iterable.html)

|---|---|
| void | [forEach](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Iterable.html#forEach(java.util.function.Consumer<?%20super%20T>))([Consumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Consumer.html)\<? super T\> action) Performs the given action for each element of the `Iterable` until all elements have been processed or the action throws an exception. |
| abstract [Iterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html)\<E\> | [iterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Iterable.html#iterator())() Returns an iterator over elements of type `T`. |
| [Spliterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Spliterator.html)\<E\> | [spliterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Iterable.html#spliterator())() Creates a `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Spliterator.html` over the elements described by this `Iterable`. |

## Public Methods

#### public abstract boolean
**add**
(E e)

Inserts the specified element into this queue if it is possible to do so
immediately without violating capacity restrictions, returning
`true` upon success and throwing an `IllegalStateException`
if no space is currently available.

##### Parameters

| e | the element to add |
|---|---|

##### Returns

- `true` (as specified by `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html#add(E)`)

##### Throws

| [IllegalStateException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalStateException.html) | if the element cannot be added at this time due to capacity restrictions |
| [ClassCastException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/ClassCastException.html) | if the class of the specified element prevents it from being added to this queue |
| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if the specified element is null and this queue does not permit null elements |
| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if some property of this element prevents it from being added to this queue |
|---|---|

#### public abstract E
**element**
()

Retrieves, but does not remove, the head of this queue. This method
differs from `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#peek()` only in that it throws an exception
if this queue is empty.

##### Returns

- the head of this queue

##### Throws

| [NoSuchElementException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/NoSuchElementException.html) | if this queue is empty |
|---|---|

#### public abstract boolean
**offer**
(E e)

Inserts the specified element into this queue if it is possible to do
so immediately without violating capacity restrictions.
When using a capacity-restricted queue, this method is generally
preferable to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#add(E)`, which can fail to insert an element only
by throwing an exception.

##### Parameters

| e | the element to add |
|---|---|

##### Returns

- `true` if the element was added to this queue, else `false`

##### Throws

| [ClassCastException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/ClassCastException.html) | if the class of the specified element prevents it from being added to this queue |
| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if the specified element is null and this queue does not permit null elements |
| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if some property of this element prevents it from being added to this queue |
|---|---|

#### public abstract E
**peek**
()

Retrieves, but does not remove, the head of this queue,
or returns `null` if this queue is empty.

##### Returns

- the head of this queue, or `null` if this queue is empty

#### public abstract E
**poll**
()

Retrieves and removes the head of this queue,
or returns `null` if this queue is empty.

##### Returns

- the head of this queue, or `null` if this queue is empty

#### public abstract E
**remove**
()

Retrieves and removes the head of this queue. This method differs
from `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Queue.html#poll()` only in that it throws an exception if this
queue is empty.

##### Returns

- the head of this queue

##### Throws

| [NoSuchElementException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/NoSuchElementException.html) | if this queue is empty |
|---|---|