org.apache.commons.collections4.queue

## Class CircularFifoQueue<E>

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

- 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
  Version:
    $Id: CircularFifoQueue.java 1648957 2015-01-01 22:01:31Z tn $
  See Also:
    Serialized Form

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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, remove, removeAll, retainAll, toArray, toArray`

- - ### Constructor Detail

    - #### CircularFifoQueue

          public CircularFifoQueue()

      Constructor that creates a queue with the default size of 32.

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

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

  - ### Method Detail

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

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

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

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

    - #### clear

          public void clear()

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

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

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

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

    - #### poll

          public E poll()

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

    - #### element

          public E element()

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

    - #### peek

          public E peek()

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

    - #### remove

          public E remove()

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

    - #### iterator

          public Iterator<E> iterator()

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

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