Class RetryExecutor

java.lang.Object
cloud.opencode.base.cache.resilience.RetryExecutor
public final class RetryExecutor extends Object
Retry Executor — Executes operations with retry according to a RetryPolicy. 重试执行器 — 根据 RetryPolicy 执行带重试的操作。

Complements the RetryPolicy strategy interface by providing a reusable execution engine that applies the policy to arbitrary Supplier, Runnable, and async operations. Tracks cumulative statistics for observability.

通过提供可复用的执行引擎来补充 RetryPolicy 策略接口， 该引擎将策略应用于任意 Supplier、Runnable 和异步操作。 跟踪累积统计信息以供可观测性使用。

Features | 主要功能:

  • Works with any RetryPolicy — fixed delay, exponential backoff, custom - 适用于任何 RetryPolicy
  • Synchronous, void, and async execution modes - 同步、无返回值和异步执行模式
  • Cumulative retry statistics (attempts, successes, failures, total delay) - 累积重试统计
  • Virtual thread friendly (Thread.sleep does not pin carrier thread) - 对虚拟线程友好

Usage Examples | 使用示例:

RetryPolicy policy = RetryPolicy.exponentialBackoff(3,
        Duration.ofMillis(100), Duration.ofSeconds(5));

RetryExecutor executor = RetryExecutor.of(policy);

// Execute a Supplier with retry
String value = executor.execute(() -> remoteCache.get("key"));

// Execute a Runnable with retry
executor.execute(() -> remoteCache.put("key", "value"));

// Execute async with retry
CompletableFuture<String> future = executor.executeAsync(
        () -> CompletableFuture.supplyAsync(() -> fetchFromRemote("key")));

// Check statistics
RetryStats stats = executor.stats();

Performance | 性能特性:

  • Lock-free statistics with AtomicLong counters - AtomicLong 无锁统计
  • Thread.sleep for delays (virtual thread friendly) - Thread.sleep 对虚拟线程友好

Security | 安全性:

  • Thread-safe: Yes (AtomicLong counters, immutable policy) - 线程安全: 是
  • Null-safe: No (operation must not be null) - 空值安全: 否（操作不能为 null）
Since:
JDK 25, opencode-base-cache V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • of

      public static RetryExecutor of(RetryPolicy policy)
      Creates a RetryExecutor backed by the given policy. 使用给定策略创建 RetryExecutor。
      Parameters:
      policy - the retry policy | 重试策略
      Returns:
      a new executor | 新的执行器

    • noRetry

      public static RetryExecutor noRetry()
      Creates a RetryExecutor that never retries. 创建从不重试的 RetryExecutor。
      Returns:
      a no-retry executor | 不重试的执行器

    • execute

      public <T> T execute(Supplier<T> operation)
      Executes an operation with retry and returns its result. 带重试地执行操作并返回结果。

      Attempts up to maxRetries + 1 times. Sleeps between retries according to the policy's delay. Retries only if the exception passes RetryPolicy.shouldRetry(Throwable).

      最多尝试 maxRetries + 1 次。根据策略的延迟在重试之间休眠。 仅当异常通过 RetryPolicy.shouldRetry(Throwable) 时才重试。

      Type Parameters:
      T - the return type | 返回类型
      Parameters:
      operation - the operation to execute | 要执行的操作
      Returns:
      the result of the first successful attempt | 第一次成功尝试的结果
      Throws:
      RuntimeException - if all retries are exhausted | 所有重试耗尽时抛出

    • execute

      public void execute(Runnable operation)
      Executes a void operation with retry. 带重试地执行无返回值操作。
      Parameters:
      operation - the operation to execute | 要执行的操作
      Throws:
      RuntimeException - if all retries are exhausted | 所有重试耗尽时抛出

    • executeAsync

      public <T> CompletableFuture<T> executeAsync(Supplier<CompletableFuture<T>> operation)
      Executes an async operation with retry, returning a CompletableFuture. 带重试地执行异步操作，返回 CompletableFuture。

      On exceptional completion, retries after the policy delay using an async chain. Tracks statistics across all async attempts.

      异常完成时，通过异步链在策略延迟后重试。跟踪所有异步尝试的统计信息。

      Type Parameters:
      T - the return type | 返回类型
      Parameters:
      operation - the async operation supplier | 异步操作 supplier
      Returns:
      a future that resolves to the result | 解析为结果的 future

    • stats

      public RetryExecutor.RetryStats stats()
      Returns a snapshot of the current retry statistics. 返回当前重试统计信息的快照。
      Returns:
      the retry statistics | 重试统计信息

    • getPolicy

      public RetryPolicy getPolicy()
      Returns the retry policy backing this executor. 返回此执行器使用的重试策略。
      Returns:
      the retry policy | 重试策略