Skip to content

Commit

Permalink
docs: improve javadoc of exceptionally* methods, add best practice …
Browse files Browse the repository at this point in the history 
…recommendation 💣 📚
  • Loading branch information
@oldratlee
oldratlee committed Aug 23, 2024
1 parent 755bbb7 commit 721dfbd
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 0 deletions.
30 changes: 30 additions & 0 deletions cffu-core/src/main/java/io/foldright/cffu/Cffu.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1785,10 +1785,15 @@ public <X extends Throwable> Cffu<T> catchingAsync(
* is executed with this stage's exception as the argument to the supplied function.
* Otherwise, if this stage completes normally,
* then the returned stage also completes normally with the same value.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catching(Class, Function)}
* instead in your biz application.
*
* @param fn the function to use to compute the value of the returned Cffu
* if this Cffu completed exceptionally
* @return the new Cffu
* @see #catching(Class, Function)
*/
@Override
public Cffu<T> exceptionally(Function<Throwable, ? extends T> fn) {
Expand All @@ -1801,10 +1806,15 @@ public Cffu<T> exceptionally(Function<Throwable, ? extends T> fn) {
* using {@link #defaultExecutor()}.
* Otherwise, if this stage completes normally,
* then the returned stage also completes normally with the same value.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingAsync(Class, Function)}
* instead in your biz application.
*
* @param fn the function to use to compute the value of the returned Cffu
* if this Cffu completed exceptionally
* @return the new Cffu
* @see #catchingAsync(Class, Function)
*/
@Override
public Cffu<T> exceptionallyAsync(Function<Throwable, ? extends T> fn) {
Expand All @@ -1816,11 +1826,16 @@ public Cffu<T> exceptionallyAsync(Function<Throwable, ? extends T> fn) {
* is executed with this stage's exception as the argument to the supplied function,
* using the supplied Executor. Otherwise, if this stage completes normally,
* then the returned stage also completes normally with the same value.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingAsync(Class, Function, Executor)}
* instead in your biz application.
*
* @param fn the function to use to compute the value of the returned Cffu
* if this Cffu completed exceptionally
* @param executor the executor to use for asynchronous execution
* @return the new Cffu
* @see #catchingAsync(Class, Function, Executor)
*/
@Override
public Cffu<T> exceptionallyAsync(Function<Throwable, ? extends T> fn, Executor executor) {
Expand Down Expand Up @@ -2091,10 +2106,15 @@ public <X extends Throwable> Cffu<T> catchingComposeAsync(
/**
* Returns a new CompletionStage that, when this stage completes exceptionally,
* is composed using the results of the supplied function applied to this stage's exception.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingCompose(Class, Function)}
* instead in your biz application.
*
* @param fn the function to use to compute the returned CompletionStage
* if this CompletionStage completed exceptionally
* @return the new CompletionStage
* @see #catchingCompose(Class, Function)
*/
@Override
public Cffu<T> exceptionallyCompose(Function<Throwable, ? extends CompletionStage<T>> fn) {
Expand All @@ -2105,10 +2125,15 @@ public Cffu<T> exceptionallyCompose(Function<Throwable, ? extends CompletionStag
* Returns a new Cffu that, when this stage completes exceptionally,
* is composed using the results of the supplied function applied to this stage's exception,
* using {@link #defaultExecutor()}.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingComposeAsync(Class, Function)}
* instead in your biz application.
*
* @param fn the function to use to compute the returned CompletionStage
* if this Cffu completed exceptionally
* @return the new Cffu
* @see #catchingComposeAsync(Class, Function)
*/
@Override
public Cffu<T> exceptionallyComposeAsync(Function<Throwable, ? extends CompletionStage<T>> fn) {
Expand All @@ -2119,11 +2144,16 @@ public Cffu<T> exceptionallyComposeAsync(Function<Throwable, ? extends Completio
* Returns a new Cffu that, when this stage completes exceptionally,
* is composed using the results of the supplied function applied to this stage's exception,
* using the supplied Executor.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingComposeAsync(Class, Function, Executor)}
* instead in your biz application.
*
* @param fn the function to use to compute the returned CompletionStage
* if this Cffu completed exceptionally
* @param executor the executor to use for asynchronous execution
* @return the new Cffu
* @see #catchingComposeAsync(Class, Function, Executor)
*/
@Override
public Cffu<T> exceptionallyComposeAsync(
Expand Down
25 changes: 25 additions & 0 deletions cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3634,10 +3634,15 @@ C catchingAsync(C cfThis, Class<X> exceptionType, Function<? super X, ? extends
* stage's exception as the argument to the supplied function, using given stage's
* default asynchronous execution facility. Otherwise, if given stage completes normally,
* then the returned stage also completes normally with the same value.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingAsync(CompletionStage, Class, Function)}
* instead in your biz application.
*
* @param fn the function to use to compute the value of the returned CompletableFuture
* if given CompletionStage completed exceptionally
* @return the new CompletableFuture
* @see #catchingAsync(CompletionStage, Class, Function)
*/
public static <T, C extends CompletionStage<? super T>>
C exceptionallyAsync(C cfThis, Function<Throwable, ? extends T> fn) {
Expand All @@ -3648,11 +3653,16 @@ C exceptionallyAsync(C cfThis, Function<Throwable, ? extends T> fn) {
* Returns a new CompletionStage that, when given stage completes exceptionally, is executed with given
* stage's exception as the argument to the supplied function, using the supplied Executor. Otherwise,
* if given stage completes normally, then the returned stage also completes normally with the same value.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingAsync(CompletionStage, Class, Function, Executor)}
* instead in your biz application.
*
* @param fn the function to use to compute the value of the returned CompletableFuture
* if given CompletionStage completed exceptionally
* @param executor the executor to use for asynchronous execution
* @return the new CompletableFuture
* @see #catchingAsync(CompletionStage, Class, Function, Executor)
*/
@SuppressWarnings("unchecked")
public static <T, C extends CompletionStage<? super T>>
Expand Down Expand Up @@ -3940,10 +3950,15 @@ public static <T, X extends Throwable, C extends CompletionStage<? super T>> C c
/**
* Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally,
* is composed using the results of the supplied function applied to given stage's exception.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingCompose(CompletionStage, Class, Function)}
* instead in your biz application.
*
* @param fn the function to use to compute the returned CompletableFuture
* if given CompletionStage completed exceptionally
* @return the new CompletableFuture
* @see #catchingCompose(CompletionStage, Class, Function)
*/
@SuppressWarnings({"unchecked", "rawtypes"})
public static <T, C extends CompletionStage<? super T>>
Expand All @@ -3961,10 +3976,15 @@ C exceptionallyCompose(C cfThis, Function<Throwable, ? extends CompletionStage<T
* Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally,
* is composed using the results of the supplied function applied to given stage's exception,
* using given CompletableFuture's default asynchronous execution facility.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingComposeAsync(CompletionStage, Class, Function)}
* instead in your biz application.
*
* @param fn the function to use to compute the returned CompletableFuture
* if given CompletionStage completed exceptionally
* @return the new CompletableFuture
* @see #catchingComposeAsync(CompletionStage, Class, Function)
*/
public static <T, C extends CompletionStage<? super T>>
C exceptionallyComposeAsync(C cfThis, Function<Throwable, ? extends CompletionStage<T>> fn) {
Expand All @@ -3974,11 +3994,16 @@ C exceptionallyComposeAsync(C cfThis, Function<Throwable, ? extends CompletionSt
/**
* Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally, is composed using
* the results of the supplied function applied to given stage's exception, using the supplied Executor.
* <p>
* Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
* <strong>Strong recommend</strong> using {@link #catchingComposeAsync(CompletionStage, Class, Function, Executor)}
* instead in your biz application.
*
* @param fn the function to use to compute the returned CompletableFuture
* if given CompletionStage completed exceptionally
* @param executor the executor to use for asynchronous execution
* @return the new CompletableFuture
* @see #catchingComposeAsync(CompletionStage, Class, Function, Executor)
*/
@SuppressWarnings({"unchecked", "rawtypes"})
public static <T, C extends CompletionStage<? super T>>
Expand Down

0 comments on commit 721dfbd

Please sign in to comment.