# 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 `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, retainAll, size, toArray, toArray`
  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  Attempts to add `object` to the contents of this `Collection` (optional).
  `boolean`
  `addAll(Collection<? extends E> collection)`
  Attempts to add all of the objects contained in `Collection` to the contents of this `Collection` (optional).
  `void`
  `clear()`
  Removes all elements from this `Collection`, leaving it empty (optional).
  `boolean`
  `contains(Object object)`
  Tests whether this `Collection` contains the specified object.
  `boolean`
  `containsAll(Collection<?> collection)`
  Tests whether this `Collection` contains all objects contained in the specified `Collection`.
  `boolean`
  `equals(Object object)`
  Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.
  `int`
  `hashCode()`
  Returns an integer hash code for the receiver.
  `boolean`
  `isEmpty()`
  Returns if this `Collection` contains no elements.
  `Iterator<E>`
  `iterator()`
  Returns an instance of `Iterator` that may be used to access the objects contained by this `Collection`.
  `boolean`
  `remove(Object object)`
  Removes one instance of the specified object from this `Collection` if one is contained (optional).
  `boolean`
  `removeAll(Collection<?> collection)`
  Removes all occurrences in this `Collection` of each object in the specified `Collection` (optional).
  `boolean`
  `retainAll(Collection<?> collection)`
  Removes all objects from this `Collection` that are not also found in the `Collection` passed (optional).
  `int`
  `size()`
  Returns a count of how many objects this `Collection` contains.
  `Object[]`
  `toArray()`
  Returns a new array containing all elements contained in this `Collection`.
  `<T> T[]`
  `toArray(T[] array)`
  Returns an array containing all elements contained in this `Collection`.

- ## 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(E)`, since the latter might throw an exception if the operation fails.
    Parameters:
      `o` - the specified element to insert into the queue.
    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:
      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:
      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.