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:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serialization version.
      See Also:

    • elements

      private transient E[] elements
      Underlying storage array.

    • start

      private transient int start
      Array index of first (oldest) queue element.

    • end

      private transient int end
      Index mod maxElements of the array position following the last queue element. Queue elements start at elements[start] and "wrap around" elements[maxElements-1], ending at elements[decrement(end)]. For example, elements = {c,a,b}, start=1, end=1 corresponds to the queue [a,b,c].

    • full

      private transient boolean full
      Flag to indicate if the queue is currently full.

    • maxElements

      private final int maxElements
      Capacity of the queue.

  • Constructor Details

    • 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 Details

    • writeObject

      private void writeObject(ObjectOutputStream out) throws IOException
      Write the queue out using a custom routine.
      Parameters:
      out - the output stream
      Throws:
      IOException - if an I/O error occurs while writing to the output stream

    • readObject

      private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException
      Read the queue in using a custom routine.
      Parameters:
      in - the input stream
      Throws:
      IOException - if an I/O error occurs while writing to the output stream
      ClassNotFoundException - if the class of a serialized object can not be found

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

    • increment

      private int increment(int index)
      Increments the internal index.
      Parameters:
      index - the index to increment
      Returns:
      the updated index

    • decrement

      private int decrement(int index)
      Decrements the internal index.
      Parameters:
      index - the index to decrement
      Returns:
      the updated index

    • 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