# Interface Queue<E>

All Superinterfaces:
  `Collection<E>, Iterable<E>`

All Known Subinterfaces:
  `Deque<E>`

All Known Implementing Classes:
  `AbstractQueue, ArrayDeque, LinkedList, PriorityQueue`

public interface Queue<E> extends Collection<E>

This kind of collection provides advanced operations compared to basic collections, such as insertion, extraction, and inspection.

Generally, a queue orders its elements by means of first-in-first-out. However, a priority queue orders its elements according to a comparator specified or the elements' natural order. Furthermore, a stack orders its elements last-in-first out.

A typical queue does not allow `null` to be inserted as its element, while some implementations such as `LinkedList` allow it. But `null` should not be inserted even in these implementations, since the method `poll` returns `null` to indicate that there is no element left in the queue.

`Queue` does not provide blocking queue methods, which would block until the operation of the method is allowed. See the `java.util.concurrent.BlockingQueue` interface for information about blocking queue methods.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `E`
  `element()`
  Gets but does not remove the element at the head of the queue.
  `boolean`
  `offer(E o)`
  Inserts the specified element into the queue provided that the condition allows such an operation.
  `E`
  `peek()`
  Gets but does not remove the element at the head of the queue.
  `E`
  `poll()`
  Gets and removes the element at the head of the queue, or returns `null` if there is no element in the queue.
  `E`
  `remove()`
  Gets and removes the element at the head of the queue.

  ### Methods inherited from interface Collection

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

  ### Methods inherited from interface Iterable

  `forEach`

- ## Method Details

  - ### offer

    boolean offer(E o)

    Inserts the specified element into the queue provided that the condition allows such an operation. The method is generally preferable to `Collection#add`, since the latter might throw an exception if the operation fails.

    ###### Parameters

    - `o`: the specified element to insert into the queue.

    ###### Returns

    Returns:
      `true` if the operation succeeds and `false` if it fails.

  - ### poll

    E poll()

    Gets and removes the element at the head of the queue, or returns `null` if there is no element in the queue.

    ###### Returns

    Returns:
      the element at the head of the queue or `null` if there is no element in the queue.

  - ### remove

    E remove()

    Gets and removes the element at the head of the queue. Throws a NoSuchElementException if there is no element in the queue.

    ###### Returns

    the element at the head of the queue.

    ###### Throws

    - `NoSuchElementException`: if there is no element in the queue.

  - ### peek

    E peek()

    Gets but does not remove the element at the head of the queue.

    ###### Returns

    Returns:
      the element at the head of the queue or `null` if there is no element in the queue.

  - ### element

    E element()

    Gets but does not remove the element at the head of the queue. Throws a `NoSuchElementException` if there is no element in the queue.

    ###### Returns

    the element at the head of the queue.

    ###### Throws

    - `NoSuchElementException`: if there is no element in the queue.