Package io.foldright.cffu
Class CffuFactory
java.lang.Object
io.foldright.cffu.CffuFactory
@ThreadSafe
@ParametersAreNonnullByDefault
@ReturnValuesAreNonnullByDefault
public final class CffuFactory
extends Object
This class
CffuFactory is equivalent to CompletableFuture,
contains the static (factory) methods of CompletableFuture.
The methods that equivalent to the instance methods of CompletableFuture is in Cffu class.
Use builder(Executor) to config and build CffuFactory.
About factory methods conventions of CffuFactory:
- factory methods return
Cffuinstead ofCompletableFuture. - only provide varargs methods for multiply Cffu/CF input arguments;
if you have
Listinput, use static util methodscffuListToArray(List)orCompletableFutureUtils.completableFutureListToArray(List)to convert it to array first.
- Author:
- Jerry Lee (oldratlee at gmail dot com)
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionallOf(CompletionStage<?>... cfs) Returns a new Cffu that is completed when all the given stages complete.allOfFastFail(CompletionStage<?>... cfs) Returns a new Cffu that is successful when all the given stages success, the results(Cffu<Void>) of the given stages are not reflected in the returned Cffu, but may be obtained by inspecting them individually.allResultsOf(CompletionStage<? extends T>... cfs) Returns a new Cffu with the results in the same order of all the given stages, the new Cffu is completed when all the given stages complete.allResultsOfFastFail(CompletionStage<? extends T>... cfs) Returns a new Cffu with the results in the same order of all the given stages, the new Cffu success when all the given stages success.allTupleOf(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2) Returns a new Cffu that is completed when the given two CompletableFutures complete.allTupleOf(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3) Returns a new Cffu that is completed when the given three CompletableFutures complete.allTupleOf(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3, CompletionStage<? extends T4> cf4) Returns a new Cffu that is completed when the given 4 CompletableFutures complete.allTupleOf(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3, CompletionStage<? extends T4> cf4, CompletionStage<? extends T5> cf5) Returns a new Cffu that is completed when the given 5 CompletableFutures complete.allTupleOfFastFail(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2) Returns a new Cffu that is successful when the given two CompletableFutures success.allTupleOfFastFail(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3) Returns a new Cffu that is successful when the given three CompletableFutures success.allTupleOfFastFail(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3, CompletionStage<? extends T4> cf4) Returns a new Cffu that is successful when the given four CompletableFutures success.allTupleOfFastFail(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3, CompletionStage<? extends T4> cf4, CompletionStage<? extends T5> cf5) Returns a new Cffu that is successful when the given five CompletableFutures success.final <T> Cffu<T> anyOf(CompletionStage<? extends T>... cfs) Returns a new Cffu that is completed when any of the given stages complete, with the same result.
Otherwise, if it completed exceptionally, the returned Cffu also does so, with a CompletionException holding this exception as its cause.
If no stages are provided, returns an incomplete Cffu.final <T> Cffu<T> anyOfSuccess(CompletionStage<? extends T>... cfs) Returns a new Cffu that is successful when any of the given stages success, with the same result.static CffuFactoryBuilderReturns aCffuFactoryBuilderwithdefaultExecutorsetting.static <T> CompletableFuture<T>[]cffuArrayUnwrap(Cffu<T>... cfs) A convenient util method for unwrap inputCffuarray elements byCffu.cffuUnwrap().static <T> Cffu<T>[]cffuListToArray(List<Cffu<T>> cffuList) Convert Cffu list to Cffu array.<T> Cffu<T> completedFuture(T value) Returns a new Cffu that is already completed with the given value.<T> CompletionStage<T> completedStage(T value) Returns a new CompletionStage that is already completed with the given value and supports only those methods in interfaceCompletionStage.Returns the default Executor used for async methods that do not specify an Executor.delayedExecutor(long delay, TimeUnit unit) Returns a new Executor that submits a task to the default executor after the given delay (or no delay if non-positive).delayedExecutor(long delay, TimeUnit unit, Executor executor) Returns a new Executor that submits a task to the given base executor after the given delay (or no delay if non-positive).<T> Cffu<T> Returns a new Cffu that is already completed exceptionally with the given exception.<T> CompletionStage<T> failedStage(Throwable ex) Returns a new CompletionStage that is already completed exceptionally with the given exception and supports only those methods in interfaceCompletionStage.booleanReturnsforbidObtrudeMethodsor not.<T> Cffu<T> Return an incomplete Cffu, equivalent toCompletableFuture()constructor.Returns a new Cffu that is asynchronously completed by a task running in thedefaultExecutor()after it runs the given action.Returns a new Cffu that is asynchronously completed by a task running in the given executor after it runs the given action.<T> Cffu<T> supplyAsync(Supplier<T> supplier) Returns a new Cffu that is asynchronously completed by a task running in thedefaultExecutor()with the value obtained by calling the given Supplier.<T> Cffu<T> supplyAsync(Supplier<T> supplier, Executor executor) Returns a new Cffu that is asynchronously completed by a task running in the given executor with the value obtained by calling the given Supplier.<T> Cffu<T> toCffu(CompletionStage<T> stage) final <T> Cffu<T>[]toCffuArray(CompletionStage<T>... stages) A convenient util method for wrap inputCompletableFuture/CompletionStage/Cffuarray element bytoCffu(CompletionStage).
-
Method Details
-
builder
Returns aCffuFactoryBuilderwithdefaultExecutorsetting.- See Also:
-
completedFuture
Returns a new Cffu that is already completed with the given value.- Type Parameters:
T- the type of the value- Parameters:
value- the value- Returns:
- the completed Cffu
- See Also:
-
completedStage
Returns a new CompletionStage that is already completed with the given value and supports only those methods in interfaceCompletionStage.CAUTION:
if run on old Java 8, just return a Cffu with a *normal* underlying CompletableFuture which is NOT with a *minimal* CompletionStage.- Type Parameters:
T- the type of the value- Parameters:
value- the value- Returns:
- the completed CompletionStage
- See Also:
-
failedFuture
Returns a new Cffu that is already completed exceptionally with the given exception.- Type Parameters:
T- the type of the value- Parameters:
ex- the exception- Returns:
- the exceptionally completed Cffu
- See Also:
-
failedStage
Returns a new CompletionStage that is already completed exceptionally with the given exception and supports only those methods in interfaceCompletionStage.CAUTION:
if run on old Java 8, just return a Cffu with a *normal* underlying CompletableFuture which is NOT with a *minimal* CompletionStage.- Type Parameters:
T- the type of the value- Parameters:
ex- the exception- Returns:
- the exceptionally completed CompletionStage
- See Also:
-
runAsync
Returns a new Cffu that is asynchronously completed by a task running in thedefaultExecutor()after it runs the given action.- Parameters:
action- the action to run before completing the returned Cffu- Returns:
- the new Cffu
- See Also:
-
runAsync
Returns a new Cffu that is asynchronously completed by a task running in the given executor after it runs the given action.- Parameters:
action- the action to run before completing the returned Cffuexecutor- the executor to use for asynchronous execution- Returns:
- the new Cffu
- See Also:
-
supplyAsync
@CheckReturnValue(explanation="should use the returned Cffu; otherwise, prefer method `runAsync`") public <T> Cffu<T> supplyAsync(Supplier<T> supplier) Returns a new Cffu that is asynchronously completed by a task running in thedefaultExecutor()with the value obtained by calling the given Supplier.- Type Parameters:
T- the function's return type- Parameters:
supplier- a function returning the value to be used to complete the returned Cffu- Returns:
- the new Cffu
- See Also:
-
supplyAsync
@CheckReturnValue(explanation="should use the returned Cffu; otherwise, prefer method `runAsync`") public <T> Cffu<T> supplyAsync(Supplier<T> supplier, Executor executor) Returns a new Cffu that is asynchronously completed by a task running in the given executor with the value obtained by calling the given Supplier.- Type Parameters:
T- the function's return type- Parameters:
supplier- a function returning the value to be used to complete the returned Cffuexecutor- the executor to use for asynchronous execution- Returns:
- the new Cffu
- See Also:
-
newIncompleteCffu
Return an incomplete Cffu, equivalent toCompletableFuture()constructor.In general, should not use this method in biz code, prefer below factory methods of Cffu:
- See Also:
-
toCffu
Wrap an existedCompletableFuture/CompletionStage/CffutoCffu. forCompletableFutureclass instances,Cffu.cffuUnwrap()is the inverse operation to this method.NOTE, keep input stage unchanged if possible when wrap:
- if input stage is a
Cffu, re-wrapped with the config of thisCffuFactorybyCffu.resetCffuFactory(CffuFactory). - if input stage is a CompletableFuture, wrap it by setting it as the underlying cf of returned cffu.
- otherwise use input
stage.toCompletableFutureas the underlying cf of returned cffu.
- Throws:
NullPointerException- if the given stage is null- See Also:
- if input stage is a
-
toCffuArray
@Contract(pure=true) @SafeVarargs public final <T> Cffu<T>[] toCffuArray(CompletionStage<T>... stages) A convenient util method for wrap inputCompletableFuture/CompletionStage/Cffuarray element bytoCffu(CompletionStage).- Throws:
NullPointerException- if the array or any of its elements arenull- See Also:
-
allOf
Returns a new Cffu that is completed when all the given stages complete. If any of the given stages complete exceptionally, then the returned Cffu also does so, with a CompletionException holding this exception as its cause.
Otherwise, the results, if any, of the given stages are not reflected in the returned Cffu(Cffu<Void>), but may be obtained by inspecting them individually.
If no stages are provided, returns a Cffu completed with the valuenull.if you need the results of given stages, prefer below methods:
allResultsOf(CompletionStage[])allTupleOf(CompletionStage, CompletionStage)/allTupleOf(CompletionStage, CompletionStage, CompletionStage, CompletionStage, CompletionStage)(provided overloaded methods with 2~5 input)
- Parameters:
cfs- the stages- Returns:
- a new Cffu that is completed when all the given stages complete
- Throws:
NullPointerException- if the array or any of its elements arenull- See Also:
-
allOfFastFail
Returns a new Cffu that is successful when all the given stages success, the results(Cffu<Void>) of the given stages are not reflected in the returned Cffu, but may be obtained by inspecting them individually. If any of the given stages complete exceptionally, then the returned Cffu also does so *without* waiting other incomplete given stages, with a CompletionException holding this exception as its cause. If no stages are provided, returns a Cffu completed with the valuenull.- Parameters:
cfs- the stages- Returns:
- a new Cffu that is successful when all the given stages success
- Throws:
NullPointerException- if the array or any of its elements arenull- See Also:
-
allResultsOf
@Contract(pure=true) @SafeVarargs public final <T> Cffu<List<T>> allResultsOf(CompletionStage<? extends T>... cfs) Returns a new Cffu with the results in the same order of all the given stages, the new Cffu is completed when all the given stages complete. If any of the given stages complete exceptionally, then the returned Cffu also does so, with a CompletionException holding this exception as its cause. If no stages are provided, returns a Cffu completed with the value empty list.- Parameters:
cfs- the stages- Returns:
- a new Cffu that is completed when all the given stages complete
- Throws:
NullPointerException- if the array or any of its elements arenull- See Also:
-
allResultsOfFastFail
@Contract(pure=true) @SafeVarargs public final <T> Cffu<List<T>> allResultsOfFastFail(CompletionStage<? extends T>... cfs) Returns a new Cffu with the results in the same order of all the given stages, the new Cffu success when all the given stages success. If any of the given stages complete exceptionally, then the returned Cffu also does so *without* waiting other incomplete given stages, with a CompletionException holding this exception as its cause. If no stages are provided, returns a Cffu completed with the value empty list.- Parameters:
cfs- the stages- Returns:
- a new Cffu that is successful when all the given stages success
- Throws:
NullPointerException- if the array or any of its elements arenull- See Also:
-
anyOf
@Contract(pure=true) @SafeVarargs public final <T> Cffu<T> anyOf(CompletionStage<? extends T>... cfs) Returns a new Cffu that is completed when any of the given stages complete, with the same result.
Otherwise, if it completed exceptionally, the returned Cffu also does so, with a CompletionException holding this exception as its cause.
If no stages are provided, returns an incomplete Cffu.- Parameters:
cfs- the stages- Returns:
- a new Cffu that is completed with the result or exception from any of the given stages when one completes
- Throws:
NullPointerException- if the array or any of its elements arenull- See Also:
-
anyOfSuccess
Returns a new Cffu that is successful when any of the given stages success, with the same result. Otherwise, all the given stages complete exceptionally, the returned Cffu also does so, with a CompletionException holding an exception from any of the given stages as its cause. If no stages are provided, returns a new Cffu that is already completed exceptionally with a CompletionException holding aNoCfsProvidedExceptionas its cause.- Parameters:
cfs- the stages- Returns:
- a new Cffu
- Throws:
NullPointerException- if the array or any of its elements arenull
-
allTupleOf
@Contract(pure=true) public <T1,T2> Cffu<Tuple2<T1,T2>> allTupleOf(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2) Returns a new Cffu that is completed when the given two CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned Cffu also does so, with a CompletionException holding this exception as its cause.- Returns:
- a new Cffu that is completed when the given 2 CompletableFutures complete
- Throws:
NullPointerException- if any of the given CompletableFutures arenull- See Also:
-
allTupleOfFastFail
@Contract(pure=true) public <T1,T2> Cffu<Tuple2<T1,T2>> allTupleOfFastFail(CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2) Returns a new Cffu that is successful when the given two CompletableFutures success. If any of the given CompletableFutures complete exceptionally, then the returned Cffu also does so *without* waiting other incomplete given CompletableFutures, with a CompletionException holding this exception as its cause.- Returns:
- a new Cffu that is successful when the given two CompletableFutures success
- Throws:
NullPointerException- if any of the given CompletableFutures arenull- See Also:
-
allTupleOf
@Contract(pure=true) public <T1,T2, Cffu<Tuple3<T1,T3> T2, allTupleOfT3>> (CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3) Returns a new Cffu that is completed when the given three CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned Cffu also does so, with a CompletionException holding this exception as its cause.- Returns:
- a new Cffu that is completed when the given 3 CompletableFutures complete
- Throws:
NullPointerException- if any of the given CompletableFutures arenull- See Also:
-
allTupleOfFastFail
@Contract(pure=true) public <T1,T2, Cffu<Tuple3<T1,T3> T2, allTupleOfFastFailT3>> (CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3) Returns a new Cffu that is successful when the given three CompletableFutures success. If any of the given CompletableFutures complete exceptionally, then the returned Cffu also does so *without* waiting other incomplete given CompletableFutures, with a CompletionException holding this exception as its cause.- Returns:
- a new Cffu that is successful when the given three CompletableFutures success
- Throws:
NullPointerException- if any of the given CompletableFutures arenull- See Also:
-
allTupleOf
@Contract(pure=true) public <T1,T2, Cffu<Tuple4<T1,T3, T4> T2, allTupleOfT3, T4>> (CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3, CompletionStage<? extends T4> cf4) Returns a new Cffu that is completed when the given 4 CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned Cffu also does so, with a CompletionException holding this exception as its cause.- Returns:
- a new Cffu that is completed when the given 4 CompletableFutures complete
- Throws:
NullPointerException- if any of the given CompletableFutures arenull- See Also:
-
allTupleOfFastFail
@Contract(pure=true) public <T1,T2, Cffu<Tuple4<T1,T3, T4> T2, allTupleOfFastFailT3, T4>> (CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3, CompletionStage<? extends T4> cf4) Returns a new Cffu that is successful when the given four CompletableFutures success. If any of the given CompletableFutures complete exceptionally, then the returned Cffu also does so *without* waiting other incomplete given CompletableFutures, with a CompletionException holding this exception as its cause.- Returns:
- a new Cffu that is successful when the given four CompletableFutures success
- Throws:
NullPointerException- if any of the given CompletableFutures arenull- See Also:
-
allTupleOf
@Contract(pure=true) public <T1,T2, Cffu<Tuple5<T1,T3, T4, T5> T2, allTupleOfT3, T4, T5>> (CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3, CompletionStage<? extends T4> cf4, CompletionStage<? extends T5> cf5) Returns a new Cffu that is completed when the given 5 CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned Cffu also does so, with a CompletionException holding this exception as its cause.- Returns:
- a new Cffu that is completed when the given 5 CompletableFutures complete
- Throws:
NullPointerException- if any of the given CompletableFutures arenull- See Also:
-
allTupleOfFastFail
@Contract(pure=true) public <T1,T2, Cffu<Tuple5<T1,T3, T4, T5> T2, allTupleOfFastFailT3, T4, T5>> (CompletionStage<? extends T1> cf1, CompletionStage<? extends T2> cf2, CompletionStage<? extends T3> cf3, CompletionStage<? extends T4> cf4, CompletionStage<? extends T5> cf5) Returns a new Cffu that is successful when the given five CompletableFutures success. If any of the given CompletableFutures complete exceptionally, then the returned Cffu also does so *without* waiting other incomplete given CompletableFutures, with a CompletionException holding this exception as its cause.- Returns:
- a new Cffu that is successful when the given five CompletableFutures success
- Throws:
NullPointerException- if any of the given CompletableFutures arenull- See Also:
-
delayedExecutor
Returns a new Executor that submits a task to the default executor after the given delay (or no delay if non-positive). Each delay commences upon invocation of the returned executor'sexecutemethod.- Parameters:
delay- how long to delay, in units ofunitunit- aTimeUnitdetermining how to interpret thedelayparameter- Returns:
- the new delayed executor
-
delayedExecutor
Returns a new Executor that submits a task to the given base executor after the given delay (or no delay if non-positive). Each delay commences upon invocation of the returned executor'sexecutemethod.- Parameters:
delay- how long to delay, in units ofunitunit- aTimeUnitdetermining how to interpret thedelayparameterexecutor- the base executor- Returns:
- the new delayed executor
-
cffuArrayUnwrap
@Contract(pure=true) @SafeVarargs public static <T> CompletableFuture<T>[] cffuArrayUnwrap(Cffu<T>... cfs) A convenient util method for unwrap inputCffuarray elements byCffu.cffuUnwrap().- Parameters:
cfs- the Cffus- See Also:
-
cffuListToArray
Convert Cffu list to Cffu array. -
defaultExecutor
Returns the default Executor used for async methods that do not specify an Executor. Configured bybuilder(Executor).- Returns:
- the default executor
- See Also:
-
forbidObtrudeMethods
ReturnsforbidObtrudeMethodsor not.- See Also:
-