Package org.apache.commons.collections4.queue

# Class CircularFifoQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
org.apache.commons.collections4.queue.CircularFifoQueue<E>

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

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

public class CircularFifoQueue<E> extends AbstractCollection<E> implements Queue<E>, BoundedCollection<E>, Serializable
CircularFifoQueue is a first-in first-out queue with a fixed size that replaces its oldest element if full.

The removal order of a `CircularFifoQueue` is based on the insertion order; elements are removed in the same order in which they were added. The iteration order is the same as the removal order.

The `add(Object)`, `remove()`, `peek()`, `poll()`, `offer(Object)` operations all perform in constant time. All other operations perform in linear time or worse.

This queue prevents null objects from being added.

Since:
  4.0
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CircularFifoQueue()`
  Constructor that creates a queue with the default size of 32.
  `CircularFifoQueue(int size)`
  Constructor that creates a queue with the specified size.
  `CircularFifoQueue(Collection<? extends E> coll)`
  Constructor that creates a queue from the specified collection.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E element)`
  Adds the given element to this queue.
  `void`
  `clear()`
  Clears this queue.
  `E`
  `element()`
  `E`
  `get(int index)`
  Returns the element at the specified position in this queue.
  `boolean`
  `isAtFullCapacity()`
  Returns `true` if the capacity limit of this queue has been reached, i.e.
  `boolean`
  `isEmpty()`
  Returns true if this queue is empty; false otherwise.
  `boolean`
  `isFull()`
  Returns true if this collection is full and no new elements can be added.
  `Iterator<E>`
  `iterator()`
  Returns an iterator over this queue's elements.
  `int`
  `maxSize()`
  Gets the maximum size of the collection (the bound).
  `boolean`
  `offer(E element)`
  Adds the given element to this queue.
  `E`
  `peek()`
  `E`
  `poll()`
  `E`
  `remove()`
  `int`
  `size()`
  Returns the number of elements stored in the queue.

  ### Methods inherited from class java.util.AbstractCollection

  `addAll, contains, containsAll, remove, removeAll, retainAll, 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, contains, containsAll, equals, hashCode, parallelStream, remove, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray`

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

  `forEach`

- ## Constructor Details

  - ### CircularFifoQueue

    public CircularFifoQueue()
    Constructor that creates a queue with the default size of 32.

  - ### CircularFifoQueue

    public CircularFifoQueue(Collection<? extends E> coll)
    Constructor that creates a queue from the specified collection. The collection size also sets the queue size.
    Parameters:
      `coll` - the collection to copy into the queue, may not be null
    Throws:
      `NullPointerException` - if the collection is null

  - ### CircularFifoQueue

    public CircularFifoQueue(int size)
    Constructor that creates a queue with the specified size.
    Parameters:
      `size` - the size of the queue (cannot be changed)
    Throws:
      `IllegalArgumentException` - if the size is < 1

- ## Method Details

  - ### add

    public boolean add(E element)
    Adds the given element to this queue. If the queue is full, the least recently added element is discarded so that a new element can be inserted.
    Specified by:
      `add` in interface `Collection<E>`
    Specified by:
      `add` in interface `Queue<E>`
    Overrides:
      `add` in class `AbstractCollection<E>`
    Parameters:
      `element` - the element to add
    Returns:
      true, always
    Throws:
      `NullPointerException` - if the given element is null

  - ### clear

    public void clear()
    Clears this queue.
    Specified by:
      `clear` in interface `Collection<E>`
    Overrides:
      `clear` in class `AbstractCollection<E>`

  - ### element

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

  - ### get

    public E get(int index)
    Returns the element at the specified position in this queue.
    Parameters:
      `index` - the position of the element in the queue
    Returns:
      the element at position `index`
    Throws:
      `NoSuchElementException` - if the requested position is outside the range [0, size)

  - ### isAtFullCapacity

    public boolean isAtFullCapacity()
    Returns `true` if the capacity limit of this queue has been reached, i.e. the number of elements stored in the queue equals its maximum size.
    Returns:
      `true` if the capacity limit has been reached, `false` otherwise
    Since:
      4.1

  - ### isEmpty

    public boolean isEmpty()
    Returns true if this queue is empty; false otherwise.
    Specified by:
      `isEmpty` in interface `Collection<E>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E>`
    Returns:
      true if this queue is empty

  - ### isFull

    public boolean isFull()
    Returns true if this collection is full and no new elements can be added.

    A `CircularFifoQueue` can never be full, thus this returns always `false`.

    Specified by:
      `isFull` in interface `BoundedCollection<E>`
    Returns:
      always returns `false`

  - ### iterator

    public Iterator<E> iterator()
    Returns an iterator over this queue's elements.
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Specified by:
      `iterator` in class `AbstractCollection<E>`
    Returns:
      an iterator over this queue's elements

  - ### maxSize

    public int maxSize()
    Gets the maximum size of the collection (the bound).
    Specified by:
      `maxSize` in interface `BoundedCollection<E>`
    Returns:
      the maximum number of elements the collection can hold

  - ### offer

    public boolean offer(E element)
    Adds the given element to this queue. If the queue is full, the least recently added element is discarded so that a new element can be inserted.
    Specified by:
      `offer` in interface `Queue<E>`
    Parameters:
      `element` - the element to add
    Returns:
      true, always
    Throws:
      `NullPointerException` - if the given element is null

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

  - ### size

    public int size()
    Returns the number of elements stored in the queue.
    Specified by:
      `size` in interface `Collection<E>`
    Specified by:
      `size` in class `AbstractCollection<E>`
    Returns:
      this queue's size