refactor: rename parameter; revise javadoc.

foldright · Jul 22, 2024 · 8358d2a · 8358d2a
1 parent 16e6293
commit 8358d2a
Showing 1 changed file with 17 additions and 13 deletions.
diff --git a/cffu-core/src/main/java/io/foldright/cffu/ListenableFutureUtils.java b/cffu-core/src/main/java/io/foldright/cffu/ListenableFutureUtils.java
@@ -31,23 +31,26 @@ public class ListenableFutureUtils {
      * use {@link MoreExecutors#directExecutor()} if you need skip executor switch.
      * <p>
      * Cancelling the result {@link CompletableFuture} will also cancel inner {@link ListenableFuture}.
-     * Use param {@code mayInterruptIfRunning} to control whether to interrupt the thread of {@link ListenableFuture}.
+     * Use param {@code interruptLfWhenCancellationException} to control whether to
+     * interrupt the thread of {@link ListenableFuture} CancellationException occurred.
      * <p>
-     * Note: CompletionException caused by this CancellationException is also considered cancellation.
-     * <p>
-     * We encourage you to avoid using direct write methods in {@link CompletableFuture} so that the underlying
-     * {@link ListenableFuture} can benefit from cancel propagation.
+     * It's recommended to avoid using direct write methods(e.g. {@code complete()/completeExceptionally()})
+     * of the returned {@link CompletableFuture}:<br/>
+     * so that the underlying {@link ListenableFuture} can benefit from cancel propagation;<br/>
+     * and the writing of the returned CompletableFuture won't affect the underlying {@link ListenableFuture}.
      *
-     * @param lf                    the wrapped ListenableFuture
-     * @param executor              the executor
-     * @param mayInterruptIfRunning {@code true} if the thread of {@link ListenableFuture} should be interrupted when
-     *                              {@link CompletableFuture} canceled (if the thread is known to the implementation).
+     * @param lf                                   the wrapped ListenableFuture
+     * @param executor                             the executor
+     * @param interruptLfWhenCancellationException {@code true} if the thread of {@link ListenableFuture} should be interrupted when
+     *                                             {@link CompletableFuture} canceled (if the thread is known to the implementation).
      * @return the completable future
      * @see CompletableFuture#cancel(boolean)
      */
     @Contract(pure = true)
-    public static <T> CompletableFuture<T> toCompletableFuture(ListenableFuture<T> lf, Executor executor, boolean mayInterruptIfRunning) {
+    public static <T> CompletableFuture<T> toCompletableFuture(
+            ListenableFuture<T> lf, Executor executor, boolean interruptLfWhenCancellationException) {
         requireNonNull(lf, "listenableFuture is null");
+        requireNonNull(executor, "executor is null");
 
         CompletableFuture<T> ret = new CompletableFuture<T>() {
             @Override
@@ -68,7 +71,7 @@ public String toString() {
         CompletableFutureUtils.peek(ret, (v, ex) -> {
             ex = CompletableFutureUtils.unwrapCfException(ex);
             if (ex instanceof CancellationException) {
-                lf.cancel(mayInterruptIfRunning);
+                lf.cancel(interruptLfWhenCancellationException);
             }
         });
 
@@ -92,8 +95,9 @@ public void onFailure(Throwable ex) {
      * Callback from ListenableFuture is executed using cffuFactory's default executor.
      */
     @Contract(pure = true)
-    public static <T> Cffu<T> toCffu(ListenableFuture<T> lf, CffuFactory cffuFactory, boolean mayInterruptIfRunning) {
-        return cffuFactory.toCffu(toCompletableFuture(lf, cffuFactory.defaultExecutor(), mayInterruptIfRunning));
+    public static <T> Cffu<T> toCffu(
+            ListenableFuture<T> lf, CffuFactory cffuFactory, boolean interruptLfWhenCancellationException) {
+        return cffuFactory.toCffu(toCompletableFuture(lf, cffuFactory.defaultExecutor(), interruptLfWhenCancellationException));
     }
 
     /**