refactor: rename parameter and revise javadoc of `ListenableFutureUti…

…ls.toCompletableFuture/toCffu`
foldright · Jul 27, 2024 · a14b9ef · a14b9ef
1 parent 1ea8888
commit a14b9ef
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 21 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
@@ -30,24 +30,31 @@ public class ListenableFutureUtils {
      * Callback from ListenableFuture is executed using the given executor,
      * 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}.
+     * Cancelling({@link Future#cancel(boolean)}) the returned CompletableFuture
+     * will also cancel underlying ListenableFuture.
      * <p>
-     * Note: CompletionException caused by this CancellationException is also considered cancellation.
+     * Use param {@code interruptLfWhenCancellationException} to control whether to cancel ListenableFuture with
+     * interruption when CancellationException occurred (including CompletionException/ExecutionException with
+     * CancellationException cause, more info see {@link CompletableFutureUtils#unwrapCfException(Throwable)}).
      * <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. {@link CompletableFuture#complete(Object)},
+     * {@link CompletableFuture#completeExceptionally(Throwable)}) of the returned CompletableFuture:
+     * <ul>
+     * <li>the underlying ListenableFuture can benefit from cancellation propagation.
+     * <li>the writing of the returned CompletableFuture won't affect the underlying ListenableFuture.
+     * </ul>
      *
-     * @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).
-     * @return the completable future
+     * @param lf                                   the underlying ListenableFuture
+     * @param executor                             the executor to use for ListenableFuture callback execution
+     * @param interruptLfWhenCancellationException whether to cancel ListenableFuture with interruption when CancellationException occurred
+     * @return the CompletableFuture adapter
      * @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 +75,7 @@ public String toString() {
         CompletableFutureUtils.peek(ret, (v, ex) -> {
             ex = CompletableFutureUtils.unwrapCfException(ex);
             if (ex instanceof CancellationException) {
-                lf.cancel(mayInterruptIfRunning);
+                lf.cancel(interruptLfWhenCancellationException);
             }
         });
 
@@ -90,10 +97,13 @@ public void onFailure(Throwable ex) {
      * Converts input {@link ListenableFuture} to {@link Cffu}.
      * <p>
      * Callback from ListenableFuture is executed using cffuFactory's default executor.
+     * <p>
+     * More info see {@link #toCompletableFuture(ListenableFuture, Executor, boolean)}.
      */
     @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));
     }
 
     /**

diff --git a/cffu-kotlin/src/main/java/io/foldright/cffu/kotlin/ListenableFutureExtensions.kt b/cffu-kotlin/src/main/java/io/foldright/cffu/kotlin/ListenableFutureExtensions.kt
@@ -15,9 +15,9 @@ import java.util.concurrent.Executor
   ---------------------
   Implementation Note:
   ---------------------
-  the methods of this file MUST NOT be defined in CompletableFutureExtensions or CffuExtensions;
+  The methods of this file MUST NOT be defined in `CompletableFutureExtensions` or `CffuExtensions`;
   Otherwise `NoClassDefFoundError` when loading CompletableFutureExtensions/CffuExtensions
-  if ListenableFuture class(`ClassNotFoundException` aka. guava dependency) absent.
+  if `ListenableFuture` class(`ClassNotFoundException` aka. `Guava` dependency) is absent.
 */
 
 /**
@@ -26,17 +26,18 @@ import java.util.concurrent.Executor
  * Callback from ListenableFuture is executed using the given executor,
  * use {[MoreExecutors.directExecutor]} if you need skip executor switch.
  */
-fun <T> ListenableFuture<T>.toCompletableFuture(executor: Executor, mayInterruptIfRunning: Boolean): CompletableFuture<T> =
-    ListenableFutureUtils.toCompletableFuture(this, executor, mayInterruptIfRunning)
+fun <T> ListenableFuture<T>.toCompletableFuture(
+    executor: Executor, interruptLfWhenCancellationException: Boolean
+): CompletableFuture<T> =
+    ListenableFutureUtils.toCompletableFuture(this, executor, interruptLfWhenCancellationException)
 
 /**
  * Converts input [ListenableFuture] to [Cffu].
  *
  * Callback from ListenableFuture is executed using cffuFactory's default executor.
  */
-fun <T> ListenableFuture<T>.toCffu(cffuFactory: CffuFactory, mayInterruptIfRunning: Boolean): Cffu<T> {
-    return ListenableFutureUtils.toCffu(this, cffuFactory, mayInterruptIfRunning)
-}
+fun <T> ListenableFuture<T>.toCffu(cffuFactory: CffuFactory, interruptLfWhenCancellationException: Boolean): Cffu<T> =
+    ListenableFutureUtils.toCffu(this, cffuFactory, interruptLfWhenCancellationException)
 
 /**
  * Converts input [CompletableFuture] to [ListenableFuture].