Class EvictingQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
cloud.opencode.base.collections.specialized.EvictingQueue<E>
Type Parameters:
E - element type | 元素类型
All Implemented Interfaces:
Serializable, Iterable<E>, Collection<E>, Queue<E>
public final class EvictingQueue<E> extends AbstractQueue<E> implements Serializable
EvictingQueue - Fixed-size Queue with Automatic Eviction EvictingQueue - 自动淘汰的固定大小队列

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 queue orders elements FIFO (first-in-first-out).

一个非阻塞队列，当队列已满时尝试添加新元素会自动从队列头部淘汰元素。 此队列按 FIFO（先进先出）顺序排列元素。

Features | 主要功能:

  • Fixed maximum size - 固定最大容量
  • Automatic eviction of oldest elements - 自动淘汰最旧元素
  • FIFO ordering - FIFO 顺序
  • Non-blocking operations - 非阻塞操作
  • Optional eviction listener - 可选淘汰监听器

Usage Examples | 使用示例:

// Create a queue with max size 3 | 创建最大容量为3的队列
EvictingQueue<String> queue = EvictingQueue.create(3);

queue.add("a");  // [a]
queue.add("b");  // [a, b]
queue.add("c");  // [a, b, c]
queue.add("d");  // [b, c, d] - "a" was evicted

queue.poll();    // returns "b", queue is [c, d]

// With eviction listener | 使用淘汰监听器
EvictingQueue<String> monitored = EvictingQueue.<String>builder(3)
    .onEviction(evicted -> System.out.println("Evicted: " + evicted))
    .create();

// Great for keeping last N items | 非常适合保留最后 N 个项目
EvictingQueue<LogEntry> recentLogs = EvictingQueue.create(1000);

Use Cases | 使用场景:

  • Keeping last N log entries - 保留最后 N 条日志
  • Recent history tracking - 最近历史跟踪
  • Sliding window calculations - 滑动窗口计算
  • Buffer with automatic cleanup - 自动清理的缓冲区

Performance | 性能特性:

  • add/offer: O(1) - add/offer: O(1)
  • poll/peek: O(1) - poll/peek: O(1)
  • remainingCapacity: O(1) - remainingCapacity: O(1)

Thread Safety | 线程安全:

This class is NOT thread-safe. External synchronization is required for concurrent access.

此类非线程安全。并发访问需要外部同步。

Since:
JDK 25, opencode-base-collections V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static <E> EvictingQueue<E> create(int maxSize)
      Create an EvictingQueue with the specified maximum size. 创建具有指定最大容量的 EvictingQueue。
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      maxSize - maximum size | 最大容量
      Returns:
      new EvictingQueue | 新 EvictingQueue
      Throws:
      IllegalArgumentException - if maxSize is not positive | 如果 maxSize 非正数

    • create

      public static <E> EvictingQueue<E> create(int maxSize, Collection<? extends E> collection)
      Create an EvictingQueue from existing elements with specified maximum size. 从现有元素创建具有指定最大容量的 EvictingQueue。
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      maxSize - maximum size | 最大容量
      collection - initial elements | 初始元素
      Returns:
      new EvictingQueue | 新 EvictingQueue

    • builder

      public static <E> EvictingQueue.Builder<E> builder(int maxSize)
      Create a builder for customized EvictingQueue. 创建自定义 EvictingQueue 的构建器。
      Type Parameters:
      E - element type | 元素类型
      Parameters:
      maxSize - maximum size | 最大容量
      Returns:
      new builder | 新构建器

    • offer

      public boolean offer(E e)
      Adds element to queue. If queue is at capacity, the oldest element is evicted. 向队列添加元素。如果队列已满，最旧的元素将被淘汰。
      Specified by:
      offer in interface Queue<E>
      Parameters:
      e - element to add | 要添加的元素
      Returns:
      always true (eviction ensures space) | 始终为 true（淘汰确保空间）
      Throws:
      NullPointerException - if element is null | 如果元素为 null

    • add

      public boolean add(E e)
      Adds element to queue. Always returns true. 向队列添加元素。始终返回 true。
      Specified by:
      add in interface Collection<E>
      Specified by:
      add in interface Queue<E>
      Overrides:
      add in class AbstractQueue<E>
      Parameters:
      e - element to add | 要添加的元素
      Returns:
      always true | 始终为 true

    • poll

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

    • peek

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

    • size

      public int size()
      Specified by:
      size in interface Collection<E>
      Specified by:
      size in class AbstractCollection<E>

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Collection<E>
      Overrides:
      isEmpty in class AbstractCollection<E>

    • clear

      public void clear()
      Specified by:
      clear in interface Collection<E>
      Overrides:
      clear in class AbstractQueue<E>

    • iterator

      public Iterator<E> iterator()
      Specified by:
      iterator in interface Collection<E>
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in class AbstractCollection<E>

    • contains

      public boolean contains(Object o)
      Specified by:
      contains in interface Collection<E>
      Overrides:
      contains in class AbstractCollection<E>

    • remove

      public boolean remove(Object o)
      Specified by:
      remove in interface Collection<E>
      Overrides:
      remove in class AbstractCollection<E>

    • toArray

      public Object[] toArray()
      Specified by:
      toArray in interface Collection<E>
      Overrides:
      toArray in class AbstractCollection<E>

    • toArray

      public <T> T[] toArray(T[] a)
      Specified by:
      toArray in interface Collection<E>
      Overrides:
      toArray in class AbstractCollection<E>

    • maxSize

      public int maxSize()
      Returns the maximum size of this queue. 返回此队列的最大容量。
      Returns:
      maximum size | 最大容量

    • remainingCapacity

      public int remainingCapacity()
      Returns the remaining capacity of this queue. 返回此队列的剩余容量。
      Returns:
      remaining capacity | 剩余容量

    • isFull

      public boolean isFull()
      Returns true if the queue is at maximum capacity. 如果队列已达到最大容量，则返回 true。
      Returns:
      true if full | 如果已满则返回 true

    • peekLast

      public E peekLast()
      Returns the element at the tail of the queue (most recently added). 返回队列尾部的元素（最近添加的）。
      Returns:
      the last element, or null if empty | 最后一个元素，如果为空则返回 null

    • toList

      public List<E> toList()
      Returns a list containing all elements in FIFO order. 返回包含所有元素的列表，按 FIFO 顺序排列。
      Returns:
      list of elements | 元素列表