EvictingQueue
Date: 2016-05-24

com.google.common.collect

## Class EvictingQueue<E>

- java.lang.Object
- - com.google.common.collect.ForwardingObject
  - - com.google.common.collect.ForwardingCollection<E>
    - - com.google.common.collect.ForwardingQueue<E>
      - - com.google.common.collect.EvictingQueue<E>

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.Queue<E>

      @Beta
      @GwtCompatible
      public final class EvictingQueue<E>
      extends ForwardingQueue<E>
      implements java.io.Serializable

  A non-blocking queue which automatically evicts elements from the head of the queue when attempting to add new elements onto the queue and it is full. This data structure is logically equivalent to a circular buffer (i.e., cyclic buffer or ring buffer).

  An evicting queue must be configured with a maximum size. Each time an element is added to a full queue, the queue automatically removes its head element. This is different from conventional bounded queues, which either block or reject new elements when full.

  This class is not thread-safe, and does not accept null elements.

  Since:
    15.0
  See Also:
    Serialized Form

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(E e)` Adds the given element to this queue.
    `boolean` | `addAll(java.util.Collection<? extends E> collection)`
    `boolean` | `contains(java.lang.Object object)`
    `static <E> EvictingQueue<E>` | `create(int maxSize)` Creates and returns a new evicting queue that will hold up to `maxSize` elements.
    `protected java.util.Queue<E>` | `delegate()` Returns the backing delegate instance that methods are forwarded to.
    `boolean` | `offer(E e)` Adds the given element to this queue.
    `int` | `remainingCapacity()` Returns the number of additional elements that this queue can accept without evicting; zero if the queue is currently full.
    `boolean` | `remove(java.lang.Object object)`

    - ### Methods inherited from class com.google.common.collect.ForwardingQueue

      `element, peek, poll, remove, standardOffer, standardPeek, standardPoll`

    - ### Methods inherited from class com.google.common.collect.ForwardingCollection

      `clear, containsAll, isEmpty, iterator, removeAll, retainAll, size, standardAddAll, standardClear, standardContains, standardContainsAll, standardIsEmpty, standardRemove, standardRemoveAll, standardRetainAll, standardToArray, standardToArray, standardToString, toArray, toArray`

    - ### Methods inherited from class com.google.common.collect.ForwardingObject

      `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

      `clear, containsAll, equals, hashCode, isEmpty, iterator, removeAll, retainAll, size, toArray, toArray`

- - ### Method Detail

    - #### create

          public static <E> EvictingQueue<E> create(int maxSize)

      Creates and returns a new evicting queue that will hold up to `maxSize` elements.

      When `maxSize` is zero, elements will be evicted immediately after being added to the queue.

    - #### remainingCapacity

          public int remainingCapacity()

      Returns the number of additional elements that this queue can accept without evicting; zero if the queue is currently full.
      Since:
        16.0

    - #### delegate

          protected java.util.Queue<E> delegate()

      Description copied from class: `ForwardingObject`
      Returns the backing delegate instance that methods are forwarded to. Abstract subclasses generally override this method with an abstract method that has a more specific return type, such as `ForwardingSet.delegate()`. Concrete subclasses override this method to supply the instance being decorated.
      Specified by:
        `delegate` in class `ForwardingQueue<E>`

    - #### offer

          public boolean offer(E e)

      Adds the given element to this queue. If the queue is currently full, the element at the head of the queue is evicted to make room.
      Specified by:
        `offer` in interface `java.util.Queue<E>`
      Overrides:
        `offer` in class `ForwardingQueue<E>`
      Returns:
        `true` always

    - #### add

          public boolean add(E e)

      Adds the given element to this queue. If the queue is currently full, the element at the head of the queue is evicted to make room.
      Specified by:
        `add` in interface `java.util.Collection<E>`
      Specified by:
        `add` in interface `java.util.Queue<E>`
      Overrides:
        `add` in class `ForwardingCollection<E>`
      Returns:
        `true` always

    - #### addAll

          public boolean addAll(java.util.Collection<? extends E> collection)

      Specified by:
        `addAll` in interface `java.util.Collection<E>`
      Overrides:
        `addAll` in class `ForwardingCollection<E>`

    - #### contains

          public boolean contains(java.lang.Object object)

      Specified by:
        `contains` in interface `java.util.Collection<E>`
      Overrides:
        `contains` in class `ForwardingCollection<E>`

    - #### remove

          public boolean remove(java.lang.Object object)

      Specified by:
        `remove` in interface `java.util.Collection<E>`
      Overrides:
        `remove` in class `ForwardingCollection<E>`