com.ebay.bascomtask.core

Interface Orchestrator

All Superinterfaces:

CommonConfig

All Known Implementing Classes:

Engine

public interface Orchestrator
extends CommonConfig

Provides entry points for task method activation, and for common configuration among all such tasks. Activation means that task methods are scheduled for execution which will happen once all of their CompletableFuture arguments are completed.

The prototypical use of this class involves adding a POJO task class to this orchestrator, calling one of its task methods, activating that method, and retrieving the result. These operations are commonly performed together as in the following example:

 1.    Orchestrator $ = Orchestrator.create();
 2.    CompletableFuture<T> future = $.task(new MyTask()).myMethod(...);
 3.    T value = future.get();
 

The task class that is added to this Orchestrator through the call to $.task() at line 2 can take can be any class that implements TaskInterface. A wrapper is returned that enables the subsequent call to myMethod to have its dependencies recorded but not yet (at that point) be activated; the returned CompletableFuture is not and will not be completed until activation occurs. In the example above, activation occurs implicitly through the call to get() at line 3.

Explicit activation can also be done by calling activate(CompletableFuture) on this class. There are a number of variations of the activate method providing different semantics for completion guarantees and return results. Explicitly calling activate is also the only way to activate multiple CompletableFutures at once, which can be desirable for maximizing parallelism.

Exceptions thrown from task methods are propagated to the caller, regardless of thread, through the CompletableFutures returned by those task methods, e.g. by calling CompletableFuture.get() or CompletableFuture.handle(BiFunction). As seen in any resulting stack trace, whatever operation that initiated activation will be the starting point, even though the exception might not be visible until a later point in the code. Thus one might get an exception on a call to get() that if activated separately from the get will have only reflect the activating stack trace.

There is no limit on the number of orchestrators created. They are thread-safe and relatively lightweight. Task activation/execution is only tied to its orchestrator for configuration purposes. Tasks from different orchestrators can be freely intermixed.

Author:

Brendan McCarthy

Method Summary

Modifier and Type	Method and Description
default void	activate(CompletableFuture<?>... futures) Activates (enables for execution) the task methods behind each supplied CompletableFuture if they were generated through BascomTask and if they are have not already been activated.
default <T> CompletableFuture<T>	activate(CompletableFuture<T> future) Variant of activate(CompletableFuture[] futures) that accepts only a single CompletableFuture argument and returns that same argument after having activated it.
void	activate(long timeoutMs, CompletableFuture<?>... futures) Variant of activate(CompletableFuture[]) that will timeout according to the TimeoutStrategy * in effect.
<T> CompletableFuture<T>	activate(long timeoutMs, CompletableFuture<T> future)
default void	activate(long timeout, TimeUnit timeUnit, CompletableFuture<?>... futures) Variant of activate(long, CompletableFuture[]) with TimeUnit option.
default <T> CompletableFuture<T>	activate(long timeout, TimeUnit timeUnit, CompletableFuture<T> future)
default void	activateAndWait(CompletableFuture<?>... futures) Variant of activate(CompletableFuture[]) that waits for all of its arguments to complete (successfully or exceptionally).
default <T> CompletableFuture<T>	activateAndWait(CompletableFuture<T> future)
default <T> List<T>	activateAndWait(List<CompletableFuture<T>> futures) Variant of activateAndWait(CompletableFuture[]) that returns a typed result from typed input.
void	activateAndWait(long timeoutMs, CompletableFuture<?>... futures) Variant of activateAndWait(CompletableFuture[]) that will timeout according to the TimeoutStrategy in effect.
<T> CompletableFuture<T>	activateAndWait(long timeoutMs, CompletableFuture<T> future)
<T> List<T>	activateAndWait(long timeoutMs, List<CompletableFuture<T>> futures) Variant of activateAndWait(long timeout, CompletableFuture[]) that returns a typed result matching the supplied typed input.
default void	activateAndWait(long timeout, TimeUnit timeUnit, CompletableFuture<?>... futures) Variant of activateAndWait(long, CompletableFuture[]) with TimeUnit option.
default <T> CompletableFuture<T>	activateAndWait(long timeout, TimeUnit timeUnit, CompletableFuture<T> future) Activates then returns its single argument.
default <T> List<T>	activateAndWait(long timeout, TimeUnit timeUnit, List<CompletableFuture<T>> futures) Variant of activateAndWait(long timeout, List) with TimeUnit option.
default <T> void	activateAsReady(List<CompletableFuture<T>> futures, TriConsumer<T,Throwable,Integer> completionFn) Variant of activateAsReady(long, List, TriConsumer) without a timeout.
<T> void	activateAsReady(long timeoutMs, List<CompletableFuture<T>> futures, TriConsumer<T,Throwable,Integer> completionFn) Activate each supplied future and invoke the supplied completionFn callback with each result as soon as each result becomes individually available.
default <T> void	activateAsReady(long timeout, TimeUnit timeUnit, List<CompletableFuture<T>> futures, TriConsumer<T,Throwable,Integer> completionFn) Variant of activateAsReady(long, List, TriConsumer) TimeUnit option.
default <T> CompletableFuture<List<T>>	activateFuture(List<CompletableFuture<T>> futures) Initiates asynchronous activation on the supplied futures all using spawned threads, keeping the calling thread free.
<T> CompletableFuture<List<T>>	activateFuture(long timeoutMs, List<CompletableFuture<T>> futures) Variant of activateFuture(List) that will timeout according to the TimeoutStrategy in effect
default <T> CompletableFuture<List<T>>	activateFuture(long timeout, TimeUnit timeUnit, List<CompletableFuture<T>> futures) Variant of activateFuture(long, List) with TimeUnit option.
default <R> CompletableFuture<Optional<R>>	cond(CompletableFuture<Boolean> condition, CompletableFuture<R> thenFuture) Activate the supplied CompletableFuture if the supplied condition evaluates to true.
<R> CompletableFuture<Optional<R>>	cond(CompletableFuture<Boolean> condition, CompletableFuture<R> thenFuture, boolean thenActivate) Variant of cond(CompletableFuture, CompletableFuture) with an additional boolean argument indicating whether to proactively activate thenFuture at the same time as condition.
<R> CompletableFuture<R>	cond(CompletableFuture<Boolean> condition, CompletableFuture<R> thenFuture, boolean thenActivate, CompletableFuture<R> elseFuture, boolean elseActivate) Variant of cond(CompletableFuture, CompletableFuture, CompletableFuture) with additional boolean arguments indicating whether to proactively activate thenFuture and/or elseFuture when condition is activated.
default <R> CompletableFuture<R>	cond(CompletableFuture<Boolean> condition, CompletableFuture<R> thenFuture, CompletableFuture<R> elseFuture) Activate one of two choices depending on the result of the supplied condition.
static Orchestrator	create() Creates an Orchestrator with no name.
static Orchestrator	create(String name) Creates a new named Orchestrator with the supplied name.
static Orchestrator	create(String name, Object arg) Creates an Orchestrator with the given name and argument.
static Orchestrator	current() Returns the orchestrator used to activate the current task method in the current thread.
default void	execute(CompletableFuture<?>... futures) Deprecated.
default void	execute(long timeoutMs, CompletableFuture<?>... futures) Deprecated.
default void	execute(long timeout, TimeUnit timeUnit, CompletableFuture<?>... futures) Deprecated.
default void	executeAndWait(CompletableFuture<?>... futures) Deprecated.
default void	executeAndWait(long timeoutMs, CompletableFuture<?>... futures) Deprecated.
default void	executeAndWait(long timeout, TimeUnit timeUnit, CompletableFuture<?>... futures) Deprecated.
CompletableFuture<Boolean>	fate(CompletableFuture<?>... cfs) Ties the 'fates' of the supplied CompletableFutures together, which means that as soon as there is a fault on any one of them, back-pressure is applied to prevent any of the remaining tasks or their predecessors (as determined recursively) from starting if they have not already been started, and forcing a TaskNotStartedException on any CompletableFuture that was prevented from starting in that manner.
default <IN1,IN2,R> CompletableFuture<R>	fn(CompletableFuture<IN1> in1, Supplier<IN2> s2, BiFunction<IN1,IN2,R> fn) Produces function task value that takes mixed arguments and produces one result.
default <T,U,R> CompletableFuture<R>	fn(CompletableFuture<T> firstInput, CompletableFuture<U> secondInput, BiFunction<T,U,R> fn) Produces function result from two arguments.
default <T,R> CompletableFuture<R>	fn(CompletableFuture<T> input, Function<T,R> fn) Produces function result from one argument.
default <IN,R> CompletableFuture<R>	fn(Supplier<IN> s1, Function<IN,R> fn) Produces function task value that takes one argument and produces one result.
default <IN1,IN2,R> CompletableFuture<R>	fn(Supplier<IN1> s1, CompletableFuture<IN2> in2, BiFunction<IN1,IN2,R> fn) Produces function task value that takes mixed arguments and produces one result.
default <IN1,IN2,R> CompletableFuture<R>	fn(Supplier<IN1> s1, Supplier<IN2> s2, BiFunction<IN1,IN2,R> fn) Produces function task value that takes two lambda arguments and produces one result.
default <R> CompletableFuture<R>	fn(Supplier<R> fn) Produces function task value that takes no arguments and produces one result.
default <IN1,IN2,R> SupplierTask<R>	fnTask(CompletableFuture<IN1> in1, Supplier<IN2> s2, BiFunction<IN1,IN2,R> fn) Produces function task that takes mixed arguments and produces one result.
<T,U,R> SupplierTask<R>	fnTask(CompletableFuture<T> firstInput, CompletableFuture<U> secondInput, BiFunction<T,U,R> fn) Produces function task that takes two arguments.
<T,R> SupplierTask<R>	fnTask(CompletableFuture<T> input, Function<T,R> fn) Produces function task that takes one argument.
<IN,R> SupplierTask<R>	fnTask(Supplier<IN> s1, Function<IN,R> fn) Produces function task that takes one argument and produces one result.
default <IN1,IN2,R> SupplierTask<R>	fnTask(Supplier<IN1> s1, CompletableFuture<IN2> in2, BiFunction<IN1,IN2,R> fn) Produces function task that takes mixed arguments and produces one result.
default <IN1,IN2,R> SupplierTask<R>	fnTask(Supplier<IN1> s1, Supplier<IN2> s2, BiFunction<IN1,IN2,R> fn) Produces function task that takes two lambda arguments and produces one result.
<R> SupplierTask<R>	fnTask(Supplier<R> fn) Produces function task that takes no arguments and produces one result.
int	getCountOfThreadsSpawned() Returns the number of threads that have been spawned by this Orchestrator.
String	getName() Name as set from create(String) or setName(String).
TaskMeta	getTaskMeta(CompletableFuture<?> cf) Returns details for any future previously registered with activate(CompletableFuture[]) (directly or through an operation on a CompletableFuture return value).
void	setName(String name) Sets name that will become part of the name for any threads spawned by this Orchestrator.
<BASE,SUB extends TaskInterface<BASE>> BASE	task(SUB userTask) Creates a task wrapper around any POJO class whose interface X in turn implements TaskInterface<X>.
default <TASK,R> CompletableFuture<R>	task(TASK userTask, Function<TASK,R> fn) Creates a task wrapper on any user pojo task method.
default <IN1,IN2> CompletableFuture<Void>	vfn(CompletableFuture<IN1> cf1, CompletableFuture<IN2> cf2, BiConsumer<IN1,IN2> fn) Produces function task value that takes non-lambda arguments and produces no result.
default <IN1,IN2> CompletableFuture<Void>	vfn(CompletableFuture<IN1> cf1, Supplier<IN2> s2, BiConsumer<IN1,IN2> fn) Produces function task value that takes mixed arguments and produces no result.
default <IN> CompletableFuture<Void>	vfn(Supplier<IN> s1, Consumer<IN> fn) Produces function task value that takes one lambda argument and produces no result.
default <IN1,IN2> CompletableFuture<Void>	vfn(Supplier<IN1> s1, CompletableFuture<IN2> cf2, BiConsumer<IN1,IN2> fn) Produces function task value that takes mixed arguments and produces no result.
default <IN1,IN2> CompletableFuture<Void>	vfn(Supplier<IN1> s1, Supplier<IN2> s2, BiConsumer<IN1,IN2> fn) Produces function task value that takes two lambda arguments and produces no result.
<IN1,IN2> ConsumerTask	vfnTask(CompletableFuture<IN1> cf1, CompletableFuture<IN2> cf2, BiConsumer<IN1,IN2> fn) Produces function task that takes non-lambda arguments and produces no result.
<IN1,IN2> ConsumerTask	vfnTask(CompletableFuture<IN1> cf1, Supplier<IN2> s2, BiConsumer<IN1,IN2> fn) Produces function task that takes mixed arguments and produces no result.
<IN> ConsumerTask	vfnTask(Supplier<IN> s1, Consumer<IN> fn) Produces function task that takes one lambda argument and produces no result.
<IN1,IN2> ConsumerTask	vfnTask(Supplier<IN1> s1, CompletableFuture<IN2> cf2, BiConsumer<IN1,IN2> fn) Produces function task that takes mixed arguments and produces no result.
<IN1,IN2> ConsumerTask	vfnTask(Supplier<IN1> s1, Supplier<IN2> s2, BiConsumer<IN1,IN2> fn) Produces function task that takes two lambda arguments and produces no result.
default <TASK> CompletableFuture<Void>	voidTask(TASK userTask, Consumer<TASK> fn) Adds a task wrapper on any user pojo task method with a void result.

Methods inherited from interface com.ebay.bascomtask.core.CommonConfig

firstInterceptWith, getExecutorService, getNumberOfInterceptors, getSpawnMode, getTimeoutMs, getTimeoutStrategy, lastInterceptWith, removeAllInterceptors, removeInterceptor, restoreConfigurationDefaults, restoreDefaultExecutorService, setExecutorService, setSpawnMode, setTimeout, setTimeoutMs, setTimeoutStrategy

Method Detail

create

static Orchestrator create()

Creates an Orchestrator with no name.

Returns:

new Orchestrator

create

static Orchestrator create(String name)

Creates a new named Orchestrator with the supplied name. The name can also later be changed by calling setName(name).

Parameters:

name - for orchestrator, useful in logging output

Returns:

new Orchestrator

create

static Orchestrator create(String name,
                           Object arg)

Creates an Orchestrator with the given name and argument.

Parameters:

name - optional / possibly null for this orchestrator, useful for logging

arg - to pass to GlobalOrchestratorConfig.Config.updateConfigurationOn(Orchestrator, Object).

Returns:

new Orchestrator

current

static Orchestrator current()

Returns the orchestrator used to activate the current task method in the current thread. This is provided for use inside task methods when adding new tasks, and is an alternative to passing in the outer orchestrator as an argument although both approaches achieve the same result. Task methods can also simply create new Orchestrators when desired, but any configuration set in an outer orchestrator will not then be propagated.

The mechanism here uses ThreadLocal and is therefore thread-safe. It works for all cases even when the processing thread comes from the completion of CompletableFuture outside of BascomTask's control.

Returns:

active orchestrator or null if not called inside an activated task method

getName

String getName()

Name as set from create(String) or setName(String).

Returns:

name

setName

void setName(String name)

Sets name that will become part of the name for any threads spawned by this Orchestrator.

Parameters:

name - to set

getTaskMeta

TaskMeta getTaskMeta(CompletableFuture<?> cf)

Returns details for any future previously registered with activate(CompletableFuture[]) (directly or through an operation on a CompletableFuture return value).

Parameters:

cf - to map

Returns:

unique TaskMeta for supplied argument or null if no match

getCountOfThreadsSpawned

int getCountOfThreadsSpawned()

Returns the number of threads that have been spawned by this Orchestrator. The result is non-deterministic due the inherent timing variations across threads that may vary for no externally-visible reason.

Note that a physical thread may have been returned to the thread pool and retrieved again, but these would count as separate logical threads as far as this return value is concerned.

Returns:

number of logically-spawned threads

activate

default void activate(CompletableFuture<?>... futures)

Activates (enables for execution) the task methods behind each supplied CompletableFuture if they were generated through BascomTask and if they are have not already been activated. Also for each such activation, activates any task method providing a parameter to the newly-activated task method, recursively.

The actual execution of a task method will take place as soon as all of its CompletableFuture inputs (if any) have completed (thus accessing a CompletableFuture inside a task method will never block). The execution sequencing and thread assignment is determined automatically.

Each task method will only be activated/executed only once even if passed multiple times to this method or any of its variants or access operations such as CompletableFuture.get() that implicitly call this method. As compared with the latter (where a single future is activated) this method call is only needed to start multiple futures at the same time, or for starting tasks whose purpose is to perform a side-effect that occurs without any other call to access its a value from it, or for any other situation where an access of its value is not possible nor desirable.

In contrast to activateAndWait(CompletableFuture[]), this call does not necessarily wait for any of the activated task methods to finish executing. More specifically, it does not wait on any threads that might be spawned to finish. Thus calls such as CompletableFuture.get(), made after calling this method, may block.

Exceptions may be thrown from activated task methods but are not immediately thrown by this call even if the task method completes prior to its return. Those exceptions are instead exposed through the CompletableFutures being passed as arguments.

Parameters:

futures - to activate

activate

default <T> CompletableFuture<T> activate(CompletableFuture<T> future)

Variant of activate(CompletableFuture[] futures) that accepts only a single CompletableFuture argument and returns that same argument after having activated it. This is provided as a convenient way to activate CompletableFutures for chaining, e.g.:

     $.task.activate(future).thenAccept(v->doSomethingWith(v));
 

Type Parameters:

T - type of argument

Parameters:

future - to activate

Returns:

future, after its task method (if any) has been activated (if not already activated)

activate

default void activate(long timeout,
                      TimeUnit timeUnit,
                      CompletableFuture<?>... futures)

Variant of activate(long, CompletableFuture[]) with TimeUnit option.

Parameters:

timeout - to set

timeUnit - time units to apply to timeout

futures - to activate

activate

default <T> CompletableFuture<T> activate(long timeout,
                                          TimeUnit timeUnit,
                                          CompletableFuture<T> future)

activate

<T> CompletableFuture<T> activate(long timeoutMs,
                                  CompletableFuture<T> future)

activate

void activate(long timeoutMs,
              CompletableFuture<?>... futures)

Variant of activate(CompletableFuture[]) that will timeout according to the TimeoutStrategy * in effect.

Parameters:

timeoutMs - timout in milliseconds

futures - to activate

execute

@Deprecated
default void execute(CompletableFuture<?>... futures)

Deprecated.

Use activate(CompletableFuture[]) instead.

Parameters:

futures - to activate

execute

@Deprecated
default void execute(long timeoutMs,
                                 CompletableFuture<?>... futures)

Deprecated.

Use activate(long,CompletableFuture[]) instead.

Parameters:

timeoutMs - timout in milliseconds

futures - to activate

execute

@Deprecated
default void execute(long timeout,
                                 TimeUnit timeUnit,
                                 CompletableFuture<?>... futures)

Deprecated.

Use activate(long,TimeUnit,CompletableFuture[]) instead.

Parameters:

timeout - timout in milliseconds

timeUnit - time units to apply to timeout

futures - to activate

activateAndWait

default void activateAndWait(CompletableFuture<?>... futures)

Variant of activate(CompletableFuture[]) that waits for all of its arguments to complete (successfully or exceptionally). After this call, any call on the supplied futures will not block since they will have already completed (successfully or exceptionally).

Parameters:

futures - to activate and then wait on

activateAndWait

default <T> CompletableFuture<T> activateAndWait(CompletableFuture<T> future)

activateAndWait

default void activateAndWait(long timeout,
                             TimeUnit timeUnit,
                             CompletableFuture<?>... futures)

Variant of activateAndWait(long, CompletableFuture[]) with TimeUnit option.

Parameters:

timeout - to set

timeUnit - time units to apply to timeout

futures - to activate

activateAndWait

default <T> CompletableFuture<T> activateAndWait(long timeout,
                                                 TimeUnit timeUnit,
                                                 CompletableFuture<T> future)

Activates then returns its single argument. Useful for easily enabling a future for chaining.

Type Parameters:

T - type of argument

Parameters:

timeout - to set

timeUnit - time units to apply to timeout

future - to activate

Returns:

completed future

activateAndWait

void activateAndWait(long timeoutMs,
                     CompletableFuture<?>... futures)

Variant of activateAndWait(CompletableFuture[]) that will timeout according to the TimeoutStrategy in effect.

Parameters:

timeoutMs - timout in milliseconds

futures - to activate

activateAndWait

<T> CompletableFuture<T> activateAndWait(long timeoutMs,
                                         CompletableFuture<T> future)

executeAndWait

@Deprecated
default void executeAndWait(CompletableFuture<?>... futures)

Deprecated.

Use activateAndWait(CompletableFuture[]) instead.

Parameters:

futures - to activate

executeAndWait

@Deprecated
default void executeAndWait(long timeout,
                                        TimeUnit timeUnit,
                                        CompletableFuture<?>... futures)

Deprecated.

Use activateAndWait(long,TimeUnit,CompletableFuture[]) instead.

Parameters:

timeout - to set

timeUnit - time units to apply to timeout

futures - to activate

executeAndWait

@Deprecated
default void executeAndWait(long timeoutMs,
                                        CompletableFuture<?>... futures)

Deprecated.

Use activateAndWait(long,CompletableFuture[]) instead.

Parameters:

timeoutMs - timout in milliseconds

futures -

activateAndWait

default <T> List<T> activateAndWait(List<CompletableFuture<T>> futures)

Variant of activateAndWait(CompletableFuture[]) that returns a typed result from typed input.

Type Parameters:

T - Type of list items

Parameters:

futures - to activate

Returns:

the completed input values

activateAndWait

default <T> List<T> activateAndWait(long timeout,
                                    TimeUnit timeUnit,
                                    List<CompletableFuture<T>> futures)

Variant of activateAndWait(long timeout, List) with TimeUnit option.

Type Parameters:

T - Type of list items

Parameters:

timeout - to set

timeUnit - time units to apply to timeout

futures - to activate

Returns:

the completed input values

activateAndWait

<T> List<T> activateAndWait(long timeoutMs,
                            List<CompletableFuture<T>> futures)

Variant of activateAndWait(long timeout, CompletableFuture[]) that returns a typed result matching the supplied typed input.

Type Parameters:

T - Type of list items

Parameters:

timeoutMs - timout in milliseconds

futures - to activate

Returns:

the completed input values

activateFuture

default <T> CompletableFuture<List<T>> activateFuture(List<CompletableFuture<T>> futures)

Initiates asynchronous activation on the supplied futures all using spawned threads, keeping the calling thread free. The returned future will be completed when all the future inputs are completed. The effect is close to setting SpawnMode.NEVER_MAIN and invoking CompletableFuture.allOf(CompletableFuture[]) on the same set of futures, except that using this method does not interfere with whatever SpawnMode is in effect. If, for example, SpawnMode.NEVER_SPAWN is set then calling this method will have no effect since that SpawnMode forces everything to be run in the calling thread.

Type Parameters:

T - Type of list items

Parameters:

futures - to activate

Returns:

future that will be bound list of values, one for each input, iff there is at least one

activateFuture

default <T> CompletableFuture<List<T>> activateFuture(long timeout,
                                                      TimeUnit timeUnit,
                                                      List<CompletableFuture<T>> futures)

Variant of activateFuture(long, List) with TimeUnit option.

Type Parameters:

T - Type of list items

Parameters:

timeout - to set

timeUnit - time units to apply to timeout

futures - to activate

Returns:

future that will be bound list of values, one for each input, iff there is at least one

activateFuture

<T> CompletableFuture<List<T>> activateFuture(long timeoutMs,
                                              List<CompletableFuture<T>> futures)

Variant of activateFuture(List) that will timeout according to the TimeoutStrategy in effect

Type Parameters:

T - Type of list items

Parameters:

timeoutMs - timout in milliseconds

futures - to activate

Returns:

future that will be bound list of values, one for each input, iff there is at least one

activateAsReady

default <T> void activateAsReady(List<CompletableFuture<T>> futures,
                                 TriConsumer<T,Throwable,Integer> completionFn)

Variant of activateAsReady(long, List, TriConsumer) without a timeout.

Type Parameters:

T - type of each element

Parameters:

futures - to activate

completionFn - that will be called as many times as there are entries in the futures list

activateAsReady

default <T> void activateAsReady(long timeout,
                                 TimeUnit timeUnit,
                                 List<CompletableFuture<T>> futures,
                                 TriConsumer<T,Throwable,Integer> completionFn)

Variant of activateAsReady(long, List, TriConsumer) TimeUnit option.

Type Parameters:

T - type of each element

Parameters:

timeout - to set

timeUnit - time units to apply to timeout

futures - to activate

completionFn - that will be called as many times as there are entries in the futures list

activateAsReady

<T> void activateAsReady(long timeoutMs,
                         List<CompletableFuture<T>> futures,
                         TriConsumer<T,Throwable,Integer> completionFn)

Activate each supplied future and invoke the supplied completionFn callback with each result as soon as each result becomes individually available. The callback contains either a valid result or an exception as the first and second arguments respectively, and in either case also includes as a third argument the ordinal finishing position. Recipients can recognize when the result is complete by checking for a zero value from that third argument.

Completion callbacks may be done from separate threads, but synchronization is employed so that only one thread at a time is allowed to make a completion call. The calling thread does not itself wait and is therefore never one to make a completion call.

Type Parameters:

T - of each each element

Parameters:

timeoutMs - timout in milliseconds

futures - to activate

completionFn - that will be called as many times as there are entries in the futures list

fate

CompletableFuture<Boolean> fate(CompletableFuture<?>... cfs)

Ties the 'fates' of the supplied CompletableFutures together, which means that as soon as there is a fault on any one of them, back-pressure is applied to prevent any of the remaining tasks or their predecessors (as determined recursively) from starting if they have not already been started, and forcing a TaskNotStartedException on any CompletableFuture that was prevented from starting in that manner.

A return result of 'true' can be used to initiate compensating actions on any task that previously completed. Any such action can know whether any previous CompletableFuture was completed or not by calling CompletableFuture.isCompletedExceptionally().

Note that this method is only activated if the return value is activated.

Parameters:

cfs - to tie together

Returns:

true if at least one of the supplied arguments generated an exception

cond

default <R> CompletableFuture<Optional<R>> cond(CompletableFuture<Boolean> condition,
                                                CompletableFuture<R> thenFuture)

Activate the supplied CompletableFuture if the supplied condition evaluates to true. The CompletableFuture is not activated until the supplied condition completes, and that supplied condition is only activated if the output from this method is activated.

Type Parameters:

R - type of nested return value

Parameters:

condition - to first evaluate

thenFuture - to activate if condition evaluates to true

Returns:

thenFuture optional which only has value if condition evaluates to true

cond

<R> CompletableFuture<Optional<R>> cond(CompletableFuture<Boolean> condition,
                                        CompletableFuture<R> thenFuture,
                                        boolean thenActivate)

Variant of cond(CompletableFuture, CompletableFuture) with an additional boolean argument indicating whether to proactively activate thenFuture at the same time as condition. Activating thenFuture in that way may be wasteful since condition may eventually evaluate to false, but the overall result will be faster when condition evaluates to true.

Note that this method will not be activated until an access operation is performed on the return value, even though it is a void result.

Type Parameters:

R - type of nested return value

Parameters:

condition - to first evaluate

thenFuture - to activate if condition evaluates to true

thenActivate - iff true then activate at same time as condition

Returns:

thenFuture optional which only has value if condition evaluates to true

cond

default <R> CompletableFuture<R> cond(CompletableFuture<Boolean> condition,
                                      CompletableFuture<R> thenFuture,
                                      CompletableFuture<R> elseFuture)

Activate one of two choices depending on the result of the supplied condition. Neither choice is activated until condition completes, and condition is only activated if the output from this method is activated.

Type Parameters:

R - type of return result

Parameters:

condition - to first evaluate

thenFuture - chosen if condition evaluates to true

elseFuture - chosen if condition evaluates to false

Returns:

thenFuture or elseFuture

cond

<R> CompletableFuture<R> cond(CompletableFuture<Boolean> condition,
                              CompletableFuture<R> thenFuture,
                              boolean thenActivate,
                              CompletableFuture<R> elseFuture,
                              boolean elseActivate)

Variant of cond(CompletableFuture, CompletableFuture, CompletableFuture) with additional boolean arguments indicating whether to proactively activate thenFuture and/or elseFuture when condition is activated. Activating either of those futures in that way may be wasteful since the eventual condition result may choose the alternate, but the overall result will be faster when condition chooses a proactively activated choice.

Type Parameters:

R - type of return result

Parameters:

condition - to first evaluate

thenFuture - chosen if condition evaluates to true

thenActivate - iff true then activate thenFuture at same time as condition

elseFuture - chosen if condition evaluates to false

elseActivate - iff true then activate elseFuture at same time as condition

Returns:

thenFuture or elseFuture result

task

<BASE,SUB extends TaskInterface<BASE>> BASE task(SUB userTask)

Creates a task wrapper around any POJO class whose interface X in turn implements TaskInterface<X>. The returned wrapper implements the same interface X that intercepts all calls on it in order to provide alternate execution behavior where CompletableFutures are present as inputs or output:

• If it returns a CompletableFuture, the task method is suspended until it is activated (enabled for execution)
• Otherwise, or once activated, the task method is delayed until all CompletableFuture inputs have completed

Activation of a task method occurs the first time any of the following actions are performed on its returned CompletableFuture:

• Passing it to one of several variations of activate() defined on Orchestrator or TaskInterface
• Accessing its value through get(), getNow(), or join() which implicitly call the above
• Being passed as input to another task method that is activated

Activating a task method implicitly activates all tasks methods supplying CompletableFutures as inputs. Once activated, a task method will be executed, possibly in a different thread, as soon as all of its CompletableFuture input arguments (if any) have completed. A task method with no CompletableFuture arguments (perhaps no arguments at all) is executed right away, though (again) possibly in a different thread.

Internally, task method suspension (as described above) involves recording dependency links between the task method and its arguments for later execution if/when activated. Those dependency links are designed to have minimal performance cost so it is generally safe to build large dependency graphs in while later incrementally choosing which elements are actually needed. Such graphs need not be defined all at once, it can be extended at any time or place by calling this or similar methods on this class, including from within other task methods, regardless of the activation state of existing task methods or the completion state of any CompletableFutures.

The userTask argument can be wrapped by this call any number of times. There is in effect a many-to- one relationship between these wrappers and any target user POJO instance. It may be desirable to share stateful POJO instances or conversely to simply reuse stateless POJO instances to avoid the overhead of creating multiple POJO instances.

Type Parameters:

BASE - the interface for the task

SUB - the implementing class type

Parameters:

userTask - any userTask with an interface that extends TaskInterface

Returns:

a wrapper around the supplied userTask with the properties described above

task

default <TASK,R> CompletableFuture<R> task(TASK userTask,
                                           Function<TASK,R> fn)

Creates a task wrapper on any user pojo task method. This is useful when having POJOs extend TaskInterface and/or return CompletableFutures is not an option or is not otherwise desirable. The functional effect is the same as if the user pojo had done those things, although features like logging/tracing cannot be as precise because the actual method invocation is done inside a lambda and is not visible to the framework. An example using this method would be something like:

 CompletableFuture<String> cf = $.task(new Pojo(),p->p.anyMethod());
 return cf.get();
 </pre>
 This is a modest improvement over simply using the function-task alternatives defined below:
 <pre>
 CompletableFuture&lt;String&gt; cf = $.fn(new Pojo().anyMethod());
 return cf.get();
 

Type Parameters:

TASK - pojo's class

R - type of return result

Parameters:

userTask - pojo task

fn - function to apply to that pojo if/when task is activated

Returns:

CompletableFuture for the return result

voidTask

default <TASK> CompletableFuture<Void> voidTask(TASK userTask,
                                                Consumer<TASK> fn)

Adds a task wrapper on any user pojo task method with a void result.

Type Parameters:

TASK - type of user task

Parameters:

userTask - pojo task

fn - Consumer function (returns no value)

Returns:

CompletableFuture for void result -- activates only but doesn't return a value

fnTask

<R> SupplierTask<R> fnTask(Supplier<R> fn)

Produces function task that takes no arguments and produces one result. Method invocation is light by default.

Type Parameters:

R - type of return result

Parameters:

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fn

default <R> CompletableFuture<R> fn(Supplier<R> fn)

Produces function task value that takes no arguments and produces one result. Method invocation is light by default.

Type Parameters:

R - type of return result

Parameters:

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fnTask

<IN,R> SupplierTask<R> fnTask(Supplier<IN> s1,
                              Function<IN,R> fn)

Produces function task that takes one argument and produces one result. Method invocation is light by default.

Type Parameters:

IN - type of input

R - type of return result

Parameters:

s1 - Supplier function (returns a value)

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fn

default <IN,R> CompletableFuture<R> fn(Supplier<IN> s1,
                                       Function<IN,R> fn)

Produces function task value that takes one argument and produces one result. Method invocation is light by default.

Type Parameters:

IN - type of input

R - type of return result

Parameters:

s1 - Supplier function (returns a value)

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fnTask

<T,R> SupplierTask<R> fnTask(CompletableFuture<T> input,
                             Function<T,R> fn)

Produces function task that takes one argument. Method invocation is light by default.

Type Parameters:

T - unwrapped type of input

R - unwrapped type of type of function result

Parameters:

input - input to function

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fn

default <T,R> CompletableFuture<R> fn(CompletableFuture<T> input,
                                      Function<T,R> fn)

Produces function result from one argument. Method invocation is light by default.

Type Parameters:

T - unwrapped type of input

R - unwrapped type of function result

Parameters:

input - input to function

fn - function to apply to input when activated

Returns:

Wrapped result of calling function

fnTask

<T,U,R> SupplierTask<R> fnTask(CompletableFuture<T> firstInput,
                               CompletableFuture<U> secondInput,
                               BiFunction<T,U,R> fn)

Produces function task that takes two arguments. Method invocation is light by default.

Type Parameters:

T - unwrapped base type of first input

U - unwrapped base type of second input

R - unwrapped type of function result

Parameters:

firstInput - first input

secondInput - second input

fn - function to apply to inputs when activated

Returns:

Function task

fn

default <T,U,R> CompletableFuture<R> fn(CompletableFuture<T> firstInput,
                                        CompletableFuture<U> secondInput,
                                        BiFunction<T,U,R> fn)

Produces function result from two arguments. Method invocation is light by default.

Type Parameters:

T - unwrapped base type of first input

U - unwrapped base type of second input

R - unwrapped type of function result

Parameters:

firstInput - first input

secondInput - second input

fn - function to apply to inputs when activated

Returns:

Wrapped result of calling function

fnTask

default <IN1,IN2,R> SupplierTask<R> fnTask(Supplier<IN1> s1,
                                           CompletableFuture<IN2> in2,
                                           BiFunction<IN1,IN2,R> fn)

Produces function task that takes mixed arguments and produces one result. Method invocation is light by default.

Type Parameters:

IN1 - type of input1

IN2 - base type of input2

R - type of return result

Parameters:

s1 - provides first value for fn

in2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fn

default <IN1,IN2,R> CompletableFuture<R> fn(Supplier<IN1> s1,
                                            CompletableFuture<IN2> in2,
                                            BiFunction<IN1,IN2,R> fn)

Produces function task value that takes mixed arguments and produces one result. Method invocation is light by default.

Type Parameters:

IN1 - type of input1

IN2 - base type of input2

R - type of return result

Parameters:

s1 - provides first value for fn

in2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fnTask

default <IN1,IN2,R> SupplierTask<R> fnTask(CompletableFuture<IN1> in1,
                                           Supplier<IN2> s2,
                                           BiFunction<IN1,IN2,R> fn)

Produces function task that takes mixed arguments and produces one result. Method invocation is light by default.

Type Parameters:

IN1 - base type of input1

IN2 - type of input2

R - type of return result

Parameters:

in1 - provides first value for fn

s2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fn

default <IN1,IN2,R> CompletableFuture<R> fn(CompletableFuture<IN1> in1,
                                            Supplier<IN2> s2,
                                            BiFunction<IN1,IN2,R> fn)

Produces function task value that takes mixed arguments and produces one result. Method invocation is light by default.

Type Parameters:

IN1 - base type of input1

IN2 - type of input2

R - type of return result

Parameters:

in1 - provides first value for fn

s2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fnTask

default <IN1,IN2,R> SupplierTask<R> fnTask(Supplier<IN1> s1,
                                           Supplier<IN2> s2,
                                           BiFunction<IN1,IN2,R> fn)

Produces function task that takes two lambda arguments and produces one result. Method invocation is light by default.

Type Parameters:

IN1 - type of input1

IN2 - type of input2

R - type of return result

Parameters:

s1 - provides first value for fn

s2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

fn

default <IN1,IN2,R> CompletableFuture<R> fn(Supplier<IN1> s1,
                                            Supplier<IN2> s2,
                                            BiFunction<IN1,IN2,R> fn)

Produces function task value that takes two lambda arguments and produces one result. Method invocation is light by default.

Type Parameters:

IN1 - type of input1

IN2 - type of input2

R - type of return result

Parameters:

s1 - provides first value for fn

s2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfnTask

<IN> ConsumerTask vfnTask(Supplier<IN> s1,
                          Consumer<IN> fn)

Produces function task that takes one lambda argument and produces no result. Method invocation is light by default.

Type Parameters:

IN - type of input1

Parameters:

s1 - provides value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfn

default <IN> CompletableFuture<Void> vfn(Supplier<IN> s1,
                                         Consumer<IN> fn)

Produces function task value that takes one lambda argument and produces no result. Method invocation is light by default.

Type Parameters:

IN - type of input1

Parameters:

s1 - provides value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfnTask

<IN1,IN2> ConsumerTask vfnTask(CompletableFuture<IN1> cf1,
                               Supplier<IN2> s2,
                               BiConsumer<IN1,IN2> fn)

Produces function task that takes mixed arguments and produces no result. Method invocation is light by default.

Type Parameters:

IN1 - base type of input1

IN2 - type of input2

Parameters:

cf1 - provides first value for fn

s2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfn

default <IN1,IN2> CompletableFuture<Void> vfn(CompletableFuture<IN1> cf1,
                                              Supplier<IN2> s2,
                                              BiConsumer<IN1,IN2> fn)

Produces function task value that takes mixed arguments and produces no result. Method invocation is light by default.

Type Parameters:

IN1 - base type of input1

IN2 - type of input2

Parameters:

cf1 - provides first value for fn

s2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfnTask

<IN1,IN2> ConsumerTask vfnTask(CompletableFuture<IN1> cf1,
                               CompletableFuture<IN2> cf2,
                               BiConsumer<IN1,IN2> fn)

Produces function task that takes non-lambda arguments and produces no result. Method invocation is light by default.

Type Parameters:

IN1 - base type of input1

IN2 - base type of input2

Parameters:

cf1 - provides first value for fn

cf2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfn

default <IN1,IN2> CompletableFuture<Void> vfn(CompletableFuture<IN1> cf1,
                                              CompletableFuture<IN2> cf2,
                                              BiConsumer<IN1,IN2> fn)

Produces function task value that takes non-lambda arguments and produces no result. Method invocation is light by default.

Type Parameters:

IN1 - base type of input1

IN2 - base type of input2

Parameters:

cf1 - provides first value for fn

cf2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfnTask

<IN1,IN2> ConsumerTask vfnTask(Supplier<IN1> s1,
                               CompletableFuture<IN2> cf2,
                               BiConsumer<IN1,IN2> fn)

Produces function task that takes mixed arguments and produces no result. Method invocation is light by default.

Type Parameters:

IN1 - type of input1

IN2 - base type of input2

Parameters:

s1 - provides first value for fn

cf2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfn

default <IN1,IN2> CompletableFuture<Void> vfn(Supplier<IN1> s1,
                                              CompletableFuture<IN2> cf2,
                                              BiConsumer<IN1,IN2> fn)

Produces function task value that takes mixed arguments and produces no result. Method invocation is light by default.

Type Parameters:

IN1 - type of input1

IN2 - base type of input2

Parameters:

s1 - provides first value for fn

cf2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfnTask

<IN1,IN2> ConsumerTask vfnTask(Supplier<IN1> s1,
                               Supplier<IN2> s2,
                               BiConsumer<IN1,IN2> fn)

Produces function task that takes two lambda arguments and produces no result. Method invocation is light by default.

Type Parameters:

IN1 - type of input1

IN2 - type of input2

Parameters:

s1 - provides first value for fn

s2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task

vfn

default <IN1,IN2> CompletableFuture<Void> vfn(Supplier<IN1> s1,
                                              Supplier<IN2> s2,
                                              BiConsumer<IN1,IN2> fn)

Produces function task value that takes two lambda arguments and produces no result. Method invocation is light by default.

Type Parameters:

IN1 - type of input1

IN2 - type of input2

Parameters:

s1 - provides first value for fn

s2 - provides second value for fn

fn - function to apply to that pojo if/when task is activated

Returns:

Function task