Class DeadLetterQueue<K>

java.lang.Object
cloud.opencode.base.cache.dlq.DeadLetterQueue<K>
Type Parameters:
K - key type | 键类型

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
  • Null-safe: Yes - 空值安全: 是
All Implemented Interfaces:
AutoCloseable
public class DeadLetterQueue<K> extends Object implements AutoCloseable
Dead Letter Queue - Tracks failed cache load operations 死信队列 - 跟踪失败的缓存加载操作

Manages keys that failed to load, with support for retry scheduling, exponential backoff, and failure analysis.

管理加载失败的键，支持重试调度、指数退避和故障分析。

Features | 主要功能:

  • Failed load tracking - 失败加载跟踪
  • Automatic retry with backoff - 带退避的自动重试
  • Failure pattern analysis - 故障模式分析
  • Manual drain operations - 手动排空操作
  • Alerting integration - 告警集成

Usage Examples | 使用示例:

// Create DLQ
DeadLetterQueue<String> dlq = DeadLetterQueue.<String>builder()
    .maxRetries(3)
    .initialBackoff(Duration.ofSeconds(1))
    .maxBackoff(Duration.ofMinutes(5))
    .retryLoader(key -> loadFromBackend(key))
    .build();

// Add failed key
dlq.add("user:1001", new IOException("Connection refused"));

// Process retries automatically
dlq.startRetryProcessor();

// Or drain manually
List<FailedEntry<String>> failed = dlq.drain(10);

// Get failure analysis
DlqAnalysis analysis = dlq.analyze();
Since:
JDK 25, opencode-base-cache V2.0.5
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • builder

      public static <K> DeadLetterQueue.Builder<K> builder()
      Create a builder 创建构建器
      Type Parameters:
      K - key type | 键类型
      Returns:
      builder | 构建器

    • add

      public boolean add(K key, Throwable error)
      Add a failed key to the DLQ 将失败的键添加到 DLQ
      Parameters:
      key - the failed key | 失败的键
      error - the error that caused failure | 导致失败的错误
      Returns:
      true if added, false if max queue size reached | 如果添加成功返回 true，如果达到最大队列大小返回 false

    • addAll

      public void addAll(Iterable<? extends K> keys, Throwable error)
      Add multiple failed keys 添加多个失败的键
      Parameters:
      keys - the failed keys | 失败的键
      error - the error | 错误

    • startRetryProcessor

      public void startRetryProcessor()
      Start automatic retry processor 启动自动重试处理器

    • stopRetryProcessor

      public void stopRetryProcessor()
      Stop automatic retry processor 停止自动重试处理器

    • processRetries

      public int processRetries()
      Process pending retries 处理待处理的重试
      Returns:
      number of entries processed | 处理的条目数

    • retry

      public boolean retry(K key)
      Retry a single failed entry 重试单个失败的条目
      Parameters:
      key - the key to retry | 要重试的键
      Returns:
      true if recovered, false otherwise | 如果恢复返回 true，否则返回 false

    • drain

      public List<DeadLetterQueue.FailedEntry<K>> drain(int maxEntries)
      Drain up to N entries from the DLQ 从 DLQ 排空最多 N 个条目
      Parameters:
      maxEntries - maximum entries to drain | 要排空的最大条目数
      Returns:
      list of drained entries | 排空的条目列表

    • drainAll

      public List<DeadLetterQueue.FailedEntry<K>> drainAll()
      Drain all entries 排空所有条目
      Returns:
      list of all entries | 所有条目列表

    • drainMatching

      public List<DeadLetterQueue.FailedEntry<K>> drainMatching(Predicate<DeadLetterQueue.FailedEntry<K>> predicate)
      Drain entries matching predicate 排空匹配谓词的条目
      Parameters:
      predicate - filter predicate | 过滤谓词
      Returns:
      list of matching entries | 匹配条目列表

    • contains

      public boolean contains(K key)
      Check if key is in DLQ 检查键是否在 DLQ 中
      Parameters:
      key - the key | 键
      Returns:
      true if in DLQ | 如果在 DLQ 中返回 true

    • get

      public DeadLetterQueue.FailedEntry<K> get(K key)
      Get failed entry for key 获取键的失败条目
      Parameters:
      key - the key | 键
      Returns:
      failed entry or null | 失败条目或 null

    • getFailedKeys

      public Set<K> getFailedKeys()
      Get all failed keys 获取所有失败的键
      Returns:
      set of failed keys | 失败键集合

    • size

      public int size()
      Get current queue size 获取当前队列大小
      Returns:
      queue size | 队列大小

    • isEmpty

      public boolean isEmpty()
      Check if DLQ is empty 检查 DLQ 是否为空
      Returns:
      true if empty | 如果为空返回 true

    • analyze

      public DeadLetterQueue.DlqAnalysis<K> analyze()
      Analyze DLQ contents 分析 DLQ 内容
      Returns:
      analysis result | 分析结果

    • getStats

      public DeadLetterQueue.DlqStats getStats()
      Get DLQ statistics 获取 DLQ 统计
      Returns:
      statistics | 统计

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable