Class Futures

java.lang.Object
cloud.opencode.base.parallel.Futures
public final class Futures extends Object
Futures - CompletableFuture Aggregation Utilities Futures - CompletableFuture 聚合工具

Provides static utility methods for common CompletableFuture aggregation patterns, similar to Guava's Futures class. All methods are null-safe and return well-defined results for empty inputs.

提供常用的 CompletableFuture 聚合模式的静态工具方法， 类似于 Guava 的 Futures 类。所有方法均为 null 安全， 对空输入返回明确定义的结果。

Example | 示例:

// Collect all results (fail-fast)
CompletableFuture<List<String>> all = Futures.allAsList(future1, future2, future3);

// Collect only successful results
CompletableFuture<List<String>> successes = Futures.successfulAsList(futures);

// Settle all - get both successes and failures
CompletableFuture<ParallelResult<String>> settled = Futures.settleAll(futures);

// Race - first successful wins
CompletableFuture<String> first = Futures.firstSuccessful(futures);

// Timeout
CompletableFuture<String> timed = Futures.withTimeout(future, Duration.ofSeconds(5));

Security | 安全性:

  • Thread-safe: Yes (utility class, stateless) - 线程安全: 是（工具类，无状态）
  • Null-safe: All methods validate inputs - Null 安全: 所有方法验证输入
Since:
JDK 25, opencode-base-parallel V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • allAsList

      @SafeVarargs public static <T> CompletableFuture<List<T>> allAsList(CompletableFuture<T>... futures)
      Collects all future results into a list. If any future fails, the returned future completes exceptionally. 将所有 Future 结果收集到列表中。如果任何 Future 失败， 返回的 Future 将异常完成。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      futures - the futures to collect - 要收集的 Future
      Returns:
      a future completing with all results, or failing if any future fails - 一个包含所有结果的 Future，如果任何 Future 失败则失败
      Throws:
      NullPointerException - if futures is null - 如果 futures 为 null

    • allAsList

      public static <T> CompletableFuture<List<T>> allAsList(List<CompletableFuture<T>> futures)
      Collects all future results into a list. If any future fails, the returned future completes exceptionally. 将所有 Future 结果收集到列表中。如果任何 Future 失败， 返回的 Future 将异常完成。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      futures - the futures to collect - 要收集的 Future
      Returns:
      a future completing with all results, or failing if any future fails - 一个包含所有结果的 Future，如果任何 Future 失败则失败
      Throws:
      NullPointerException - if futures is null - 如果 futures 为 null

    • successfulAsList

      public static <T> CompletableFuture<List<T>> successfulAsList(List<CompletableFuture<T>> futures)
      Collects only the successful results from the given futures. Failed futures are silently ignored. The returned future always completes normally. 仅收集给定 Future 中的成功结果。失败的 Future 被静默忽略。 返回的 Future 始终正常完成。

      The order of results in the returned list corresponds to the order of successful completions, which may differ from the input order.

      返回列表中结果的顺序对应成功完成的顺序，可能与输入顺序不同。

      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      futures - the futures to collect - 要收集的 Future
      Returns:
      a future completing with only the successful results - 一个仅包含成功结果的 Future
      Throws:
      NullPointerException - if futures is null - 如果 futures 为 null

    • settleAll

      public static <T> CompletableFuture<ParallelResult<T>> settleAll(List<CompletableFuture<T>> futures)
      Settles all futures, collecting both successes and failures into a ParallelResult. The returned future always completes normally regardless of individual future outcomes. 结算所有 Future，将成功和失败收集到 ParallelResult 中。 无论单个 Future 的结果如何，返回的 Future 始终正常完成。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      futures - the futures to settle - 要结算的 Future
      Returns:
      a future completing with a ParallelResult containing all outcomes - 一个包含所有结果的 ParallelResult 的 Future
      Throws:
      NullPointerException - if futures is null - 如果 futures 为 null

    • firstSuccessful

      public static <T> CompletableFuture<T> firstSuccessful(List<CompletableFuture<T>> futures)
      Returns the first future that completes successfully. All remaining futures are cancelled once a winner is found. If all futures fail, the returned future completes exceptionally with OpenParallelException. 返回首个成功完成的 Future。一旦找到获胜者，所有剩余的 Future 将被取消。 如果所有 Future 都失败，返回的 Future 将以 OpenParallelException 异常完成。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      futures - the futures to race - 要竞争的 Future
      Returns:
      a future completing with the first successful result - 一个包含首个成功结果的 Future
      Throws:
      NullPointerException - if futures is null - 如果 futures 为 null
      IllegalArgumentException - if futures is empty - 如果 futures 为空

    • withTimeout

      public static <T> CompletableFuture<T> withTimeout(CompletableFuture<T> future, Duration timeout)
      Adds a timeout to the given future. If the future does not complete within the specified duration, it completes exceptionally with OpenParallelException. 为给定的 Future 添加超时。如果 Future 未在指定时间内完成， 将以 OpenParallelException 异常完成。
      Type Parameters:
      T - the result type - 结果类型
      Parameters:
      future - the future to add timeout to - 要添加超时的 Future
      timeout - the timeout duration - 超时时长
      Returns:
      a new future that completes with the result or times out - 一个新的 Future，包含结果或超时
      Throws:
      NullPointerException - if future or timeout is null - 如果 future 或 timeout 为 null