Package ortus.boxlang.runtime.async

Class BoxFuture<T>

java.lang.Object

java.util.concurrent.CompletableFuture<T>

ortus.boxlang.runtime.async.BoxFuture<T>

All Implemented Interfaces:

CompletionStage<T>, Future<T>

public class BoxFuture<T>
extends CompletableFuture<T>

This is the BoxLang version of a CompletableFuture to allow for more dynamic goodness and fluent features. This class extends CompletableFuture and adds some additional methods.

Nested Class Summary

Nested classes/interfaces inherited from class java.util.concurrent.CompletableFuture

CompletableFuture.AsynchronousCompletionTask

Nested classes/interfaces inherited from interface java.util.concurrent.Future

Future.State

Constructor Summary

Constructors

Constructor	Description
BoxFuture()	Default constructor

Method Summary

Modifier and Type	Method	Description
static BoxFuture<Array>	all(IBoxContext context, Array futures)	This method accepts an array of future objects, closures or an array of future objects/closures in order to execute them in parallel.
static BoxFuture<Array>	all(IBoxContext context, Array futures, ExecutorRecord executorRecord)	This method accepts an array of future objects, closures or an array of future objects/closures in order to execute them in parallel.
static Object	allApply(IBoxContext context, Object items, Function mapper, Function errorHandler)	This function can accept an array of items or a struct of items and apply a function to each of the item's in parallel.
static Object	allApply(IBoxContext context, Object items, Function mapper, Function errorHandler, long timeout, Object unit)	This function can accept an array of items or a struct of items and apply a function to each of the item's in parallel.
static Object	allApply(IBoxContext context, Object items, Function mapper, Function errorHandler, long timeout, Object unit, ExecutorRecord executor)	This function can accept an array of items or a struct of items and apply a function to each of the item's in parallel.
static Object	allApply(IBoxContext context, Object items, Function mapper, Function errorHandler, ExecutorRecord executor)	This function can accept an array of items or a struct of items and apply a function to each of the item's in parallel.
static BoxFuture<Object>	any(IBoxContext context, Array futures)	This method accepts an array of future objects, closures or an array of future objects/closures in order to execute them in parallel.
static BoxFuture<Object>	any(IBoxContext context, Array futures, ExecutorRecord executorRecord)	This method accepts an array of future objects, closures or an array of future objects/closures in order to execute them in parallel.
static <U> BoxFuture<U>	completedFuture(U value)	Creates a new BoxFuture from a CompletableFuture
Boolean	completeExceptionally(String message)	Completes exceptionally with a BoxLang exception and the passed message.
BoxFuture<T>	completeOnTimeout(T value, long timeout)	Completes this CompletableFuture with the given value if not otherwise completed before the given timeout in milliseconds as the default.
BoxFuture<T>	completeOnTimeout(T value, long timeout, Object unit)	Completes this CompletableFuture with the given value if not otherwise completed before the given timeout.
static Executor	delayedExecutor(long delay, Object unit)	Returns a new Executor that submits a task to the default executor after the given delay (or no delay if non-positive).
static Executor	delayedExecutor(long delay, Object 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).
static BoxFuture<?>	failedFuture(String message)	Returns a new BoxFuture that is already completed exceptionally with the given exception message.
static BoxFuture<?>[]	futuresWrap(IBoxContext context, Array futures, ExecutorRecord executorRecord)	This method accepts an array of future objects, closures or an array of future objects/closures
T	get(long timeout)	Waits if necessary for this future to complete, and then returns its result.
T	get(long timeout, Object unit)	Waits if necessary for this future to complete, and then returns its result.
Attempt<?>	getAsAttempt()	Get the result of the future as an Attempt object.
Attempt<?>	getAsAttempt(long timeout)	Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.
Attempt<?>	getAsAttempt(long timeout, Object unit)	Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.
T	getOrDefault(T valueIfAbsent)	Waits if necessary for this future to complete, and then returns its result with the option to return a default value if the result is null.
T	joinOrDefault(T valueIfAbsent)	Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally.
static BoxFuture<?>	ofCompletableFuture(CompletableFuture<?> future)	Creates a new BoxFuture from a CompletableFuture
static BoxFuture<?>	ofFunction(IBoxContext context, Function function)	Creates a new BoxFuture that is completed by executing the supplier on the default executor.
static BoxFuture<?>	ofFunction(IBoxContext context, Function function, Executor executor)	Creates a new BoxFuture that is completed by executing the supplier on passed in executor.
static BoxFuture<?>	ofValue(Object value)	Creates a new BoxFuture that is already completed with the given value.
BoxFuture<T>	onError(Function<Throwable,T> errorFunction)	Alias to CompletableFuture.exceptionally(java.util.function.Function<java.lang.Throwable, ? extends T>) for fluency
BoxFuture<T>	orTimeout(long timeout)	Exceptionally completes this CompletableFuture with a TimeoutException if not otherwise completed before the given timeout.
BoxFuture<T>	orTimeout(long timeout, Object unit)	Exceptionally completes this CompletableFuture with a TimeoutException if not otherwise completed before the given timeout.
static <T> BoxFuture<T>	run(Supplier<T> supplier)	Alias to supplyAsync for fluency, mostly used by BoxLang directly
static <T> BoxFuture<T>	run(Supplier<T> supplier, Executor executor)	Alias to supplyAsync for fluency, mostly used by BoxLang directly using a specific executor
<U> BoxFuture<U>	then(Function<T,U> function)	Alias to thenApply for fluency
<U> BoxFuture<U>	then(Function<T,U> function, Executor executor)	Alias to thenApply for fluency
<U> BoxFuture<U>	thenAsync(Function<T,U> function)	Alias to thenApplyAsync for fluency
<U> BoxFuture<U>	thenAsync(Function<T,U> function, Executor executor)	Alias to thenApplyAsync for fluency

Methods inherited from class java.util.concurrent.CompletableFuture

acceptEither, acceptEitherAsync, acceptEitherAsync, allOf, anyOf, applyToEither, applyToEitherAsync, applyToEitherAsync, cancel, complete, completeAsync, completeAsync, completedStage, completeExceptionally, completeOnTimeout, copy, defaultExecutor, delayedExecutor, delayedExecutor, exceptionally, exceptionallyAsync, exceptionallyAsync, exceptionallyCompose, exceptionallyComposeAsync, exceptionallyComposeAsync, exceptionNow, failedFuture, failedStage, get, get, getNow, getNumberOfDependents, handle, handleAsync, handleAsync, isCancelled, isCompletedExceptionally, isDone, join, minimalCompletionStage, newIncompleteFuture, obtrudeException, obtrudeValue, orTimeout, resultNow, runAfterBoth, runAfterBothAsync, runAfterBothAsync, runAfterEither, runAfterEitherAsync, runAfterEitherAsync, runAsync, runAsync, state, supplyAsync, supplyAsync, thenAccept, thenAcceptAsync, thenAcceptAsync, thenAcceptBoth, thenAcceptBothAsync, thenAcceptBothAsync, thenApply, thenApplyAsync, thenApplyAsync, thenCombine, thenCombineAsync, thenCombineAsync, thenCompose, thenComposeAsync, thenComposeAsync, thenRun, thenRunAsync, thenRunAsync, toCompletableFuture, toString, whenComplete, whenCompleteAsync, whenCompleteAsync

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

BoxFuture

public BoxFuture()

Default constructor

Method Details

completeExceptionally

public Boolean completeExceptionally(String message)

Completes exceptionally with a BoxLang exception and the passed message. If not already completed, causes invocations of get() and related methods to throw the given exception.

Parameters:

message - The message to include in the exception

Returns:

true if this invocation caused this CompletableFuture to transition to a completed state, else false

completeOnTimeout

public BoxFuture<T> completeOnTimeout(T value,
 long timeout)

Completes this CompletableFuture with the given value if not otherwise completed before the given timeout in milliseconds as the default.

Parameters:

value - The value to complete the future with

timeout - The maximum time to wait in milliseconds

Returns:

A stage that will complete with the result of the given stage

completeOnTimeout

public BoxFuture<T> completeOnTimeout(T value,
 long timeout,
 Object unit)

Completes this CompletableFuture with the given value if not otherwise completed before the given timeout.

Parameters:

value - The value to complete the future with

timeout - The maximum time to wait

unit - The time unit of the timeout argument. This can be a TimeUnit or a string representation of a TimeUnit

Returns:

A stage that will complete with the result of the given stage

joinOrDefault

public T joinOrDefault(T valueIfAbsent)

Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally. To better conform with the use of common functional forms, if a computation involved in the completion of this CompletableFuture threw an exception, this method throws an (unchecked) CompletionException with the underlying exception as its cause.

Parameters:

valueIfAbsent - If the returned value is null, then we can pass a default value to return

Returns:

The result value or the default value if the result is null

Throws:

CompletionException - - if this future completed exceptionally or a completion computation threw an exception

CancellationException - - if the computation was cancelled

getOrDefault

public T getOrDefault(T valueIfAbsent)
               throws InterruptedException,
ExecutionException,
CancellationException

Waits if necessary for this future to complete, and then returns its result with the option to return a default value if the result is null.

Parameters:

valueIfAbsent - If the returned value is null, then we can pass a default value to return

Returns:

The result value or the default value if the result is null

Throws:

ExecutionException - - if this future completed exceptionally or a completion computation threw an exception

InterruptedException - - if the current thread was interrupted while waiting

CancellationException

getAsAttempt

public Attempt<?> getAsAttempt()

Get the result of the future as an Attempt object. If the future completed exceptionally, then the exception will be returned as an Attempt.

Returns:

The result as an Attempt object

getAsAttempt

public Attempt<?> getAsAttempt(long timeout)

Waits if necessary for at most the given time for this future to complete, and then returns its result, if available. If the future completed exceptionally, then the exception will be returned as an Attempt.

Parameters:

timeout - The maximum time to wait in milliseconds

Returns:

The result as an Attempt object

getAsAttempt

public Attempt<?> getAsAttempt(long timeout,
 Object unit)

Waits if necessary for at most the given time for this future to complete, and then returns its result, if available. If the future completed exceptionally, then the exception will be returned as an Attempt.

Parameters:

timeout - The maximum time to wait

unit - The time unit of the timeout argument. This can be a TimeUnit or a string representation of a TimeUnit

Returns:

The result as an Attempt object

get

public T get(long timeout)
      throws InterruptedException,
ExecutionException,
CancellationException,
TimeoutException

Waits if necessary for this future to complete, and then returns its result. If the timeout occurs, then a TimeoutException is thrown.

Parameters:

timeout - The maximum time to wait in milliseconds

Returns:

The result value or the default value if the result is null

Throws:

ExecutionException - - if this future completed exceptionally or a completion computation threw an exception

InterruptedException - - if the current thread was interrupted while waiting

TimeoutException - - if the wait timed out

CancellationException

get

public T get(long timeout,
 Object unit)
      throws InterruptedException,
ExecutionException,
CancellationException,
TimeoutException

Waits if necessary for this future to complete, and then returns its result. If the timeout occurs, then a TimeoutException is thrown.

Parameters:

timeout - The maximum time to wait

unit - The time unit of the timeout argument. This can be a TimeUnit or a string representation of a TimeUnit

Returns:

The result value or the default value if the result is null

Throws:

ExecutionException - - if this future completed exceptionally or a completion computation threw an exception

InterruptedException - - if the current thread was interrupted while waiting

TimeoutException - - if the wait timed out

CancellationException

orTimeout

public BoxFuture<T> orTimeout(long timeout)

Exceptionally completes this CompletableFuture with a TimeoutException if not otherwise completed before the given timeout.

Parameters:

timeout - The maximum time to wait in milliseconds

Returns:

A stage that will complete with the result of the given stage

orTimeout

public BoxFuture<T> orTimeout(long timeout,
 Object unit)

Exceptionally completes this CompletableFuture with a TimeoutException if not otherwise completed before the given timeout.

Parameters:

timeout - The maximum time to wait

unit - The time unit of the timeout argument. This can be a TimeUnit or a string representation of a TimeUnit

Returns:

A stage that will complete with the result of the given stage

onError

public BoxFuture<T> onError(Function<Throwable,T> errorFunction)

Alias to CompletableFuture.exceptionally(java.util.function.Function<java.lang.Throwable, ? extends T>) for fluency

Parameters:

errorFunction - The function to apply if an exception occurs

Returns:

The future

then

public <U> BoxFuture<U> then(Function<T,U> function)

Alias to thenApply for fluency

Parameters:

function - The function to apply

Returns:

The future

thenAsync

public <U> BoxFuture<U> thenAsync(Function<T,U> function)

Alias to thenApplyAsync for fluency

Parameters:

function - The function to apply

Returns:

The future

then

public <U> BoxFuture<U> then(Function<T,U> function,
 Executor executor)

Alias to thenApply for fluency

Parameters:

function - The function to apply

executor - The executor to run the function on

Returns:

The future

thenAsync

public <U> BoxFuture<U> thenAsync(Function<T,U> function,
 Executor executor)

Alias to thenApplyAsync for fluency

Parameters:

function - The function to apply

executor - The executor to run the function on

Returns:

The future

failedFuture

public static BoxFuture<?> failedFuture(String message)

Returns a new BoxFuture that is already completed exceptionally with the given exception message. The type will be BoxRuntimeException.

run

public static <T> BoxFuture<T> run(Supplier<T> supplier)

Alias to supplyAsync for fluency, mostly used by BoxLang directly

Parameters:

supplier - The supplier to run

Returns:

The future of the supplier

run

public static <T> BoxFuture<T> run(Supplier<T> supplier,
 Executor executor)

Alias to supplyAsync for fluency, mostly used by BoxLang directly using a specific executor

Parameters:

supplier - The supplier to run

executor - The executor to run the supplier on

Returns:

The future of the supplier

delayedExecutor

public static Executor delayedExecutor(long delay,
 Object unit)

Returns a new Executor that submits a task to the default executor after the given delay (or no delay if non-positive).

Parameters:

delay - The time from now to delay execution

unit - The time unit of the delay argument. This can be a TimeUnit or a string representation of a TimeUnit

Returns:

A new Executor that submits a task to the default executor after the given delay

delayedExecutor

public static Executor delayedExecutor(long delay,
 Object 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).

Parameters:

delay - The time from now to delay execution

unit - The time unit of the delay argument. This can be a TimeUnit or a string representation of a TimeUnit

executor - The executor to run the task on

Returns:

A new Executor that submits a task to the given base executor after the given delay

all

public static BoxFuture<Array> all(IBoxContext context,
 Array futures)

This method accepts an array of future objects, closures or an array of future objects/closures in order to execute them in parallel. It will return back to you a future that will return back an array of results from every future that was executed. This way you can further attach processing and pipelining on the constructed array of values.

This means that the futures will be executed in parallel and the results will be returned in the order that they were passed in. This also means that this operation is non-blocking and will return immediately until you call get() on the future.

Each future can be a BoxFuture or a CompletableFuture or a BoxLang Function that will be treated as a future.

This uses the default executor (ForkJoinPool.commonPool()).

Parameters:

context - The context of the current execution

futures - The array of futures to execute

Returns:

A future that will return the results in an array

all

public static BoxFuture<Array> all(IBoxContext context,
 Array futures,
 ExecutorRecord executorRecord)

This method accepts an array of future objects, closures or an array of future objects/closures in order to execute them in parallel. It will return back to you a future that will return back an array of results from every future that was executed. This way you can further attach processing and pipelining on the constructed array of values.

This means that the futures will be executed in parallel and the results will be returned in the order that they were passed in. This also means that this operation is non-blocking and will return immediately until you call get() on the future.

Each future can be a BoxFuture or a CompletableFuture or a BoxLang Function that will be treated as a future.

You can also pass a custom ExecutorRecord to use for the execution of the futures if and ONLY if the incoming array of futures is an array of closures/lambdas or functions.

 results = all( [f1, f2, f3] ).get()
 all( [f1, f2, f3] ).then( (values) => logResults( values ) );
 

Parameters:

context - The context of the current execution

futures - The array of futures to execute

executorRecord - The executor to use

Returns:

A future that will return the results in an array

any

public static BoxFuture<Object> any(IBoxContext context,
 Array futures)

This method accepts an array of future objects, closures or an array of future objects/closures in order to execute them in parallel. It will return back to you a future that will return back the first result from the futures that was executed. This way you can further attach processing and pipelining on the constructed value.

This means that the futures will be executed in parallel and the result will be returned as soon as one of the futures completes. This also means that this operation is non-blocking and will return immediately until you call get() on the future.

Parameters:

context - The context of the current execution

futures - The array of futures to execute

Returns:

A future that will return the first result from the futures

any

public static BoxFuture<Object> any(IBoxContext context,
 Array futures,
 ExecutorRecord executorRecord)

This method accepts an array of future objects, closures or an array of future objects/closures in order to execute them in parallel. It will return back to you a future that will return back the first result from the futures that was executed. This way you can further attach processing and pipelining on the constructed value.

This means that the futures will be executed in parallel and the result will be returned as soon as one of the futures completes. This also means that this operation is non-blocking and will return immediately until you call get() on the future.

Parameters:

context - The context of the current execution

futures - The array of futures to execute

executorRecord - The executor to use for the execution of the futures if they are functions or closures

Returns:

A future that will return the first result from the futures

ofValue

public static BoxFuture<?> ofValue(Object value)

Creates a new BoxFuture that is already completed with the given value.

Parameters:

value - The value to complete the future with

Returns:

A future that is already completed with the given value

completedFuture

public static <U> BoxFuture<U> completedFuture(U value)

Creates a new BoxFuture from a CompletableFuture

Parameters:

value - The CompletableFuture to wrap

Returns:

A future that is already completed with the given value

ofCompletableFuture

public static BoxFuture<?> ofCompletableFuture(CompletableFuture<?> future)

Creates a new BoxFuture from a CompletableFuture

Parameters:

future - The CompletableFuture to wrap

Returns:

A future that is already completed with the given value

ofFunction

public static BoxFuture<?> ofFunction(IBoxContext context,
 Function function)

Creates a new BoxFuture that is completed by executing the supplier on the default executor.

Parameters:

context - The context of the current execution

function - The BoxLang function to execute

Returns:

A future that is completed by executing the supplier on the default executor

ofFunction

public static BoxFuture<?> ofFunction(IBoxContext context,
 Function function,
 Executor executor)

Creates a new BoxFuture that is completed by executing the supplier on passed in executor.

Parameters:

context - The context of the current execution

function - The BoxLang function to execute

executor - The executor to run the function on

Returns:

A future that is completed by executing the supplier on the default executor

allApply

public static Object allApply(IBoxContext context,
 Object items,
 Function mapper,
 Function errorHandler)

This function can accept an array of items or a struct of items and apply a function to each of the item's in parallel. The `mapper` argument receives the appropriate item and must return a result.

The timeout will be infinite by default and in the default fork/join pool.

 // Array
 allApply( items, ( item ) => item.getMemento() )
 // Struct: The result object is a struct of `key` and `value`
 allApply( data, ( item ) => item.key & item.value.toString() )
 

Parameters:

context - The context of the current execution

items - The items to apply the function to, this can be an array or a struct

mapper - The function to apply to each item

errorHandler - The function to handle any errors that occur, this can be null

Returns:

An array or struct of the results

allApply

public static Object allApply(IBoxContext context,
 Object items,
 Function mapper,
 Function errorHandler,
 ExecutorRecord executor)

This function can accept an array of items or a struct of items and apply a function to each of the item's in parallel. The `mapper` argument receives the appropriate item and must return a result.

The timeout will be infinite by default and in the passed executor.

 // Array
 allApply( items, ( item ) => item.getMemento() )
 // Struct: The result object is a struct of `key` and `value`
 allApply( data, ( item ) => item.key & item.value.toString() )
 

Parameters:

context - The context of the current execution

items - The items to apply the function to, this can be an array or a struct

mapper - The function to apply to each item

errorHandler - The function to handle any errors that occur, this can be null

executor - The executor to run the function on

Returns:

An array or struct of the results

allApply

public static Object allApply(IBoxContext context,
 Object items,
 Function mapper,
 Function errorHandler,
 long timeout,
 Object unit)

This function can accept an array of items or a struct of items and apply a function to each of the item's in parallel. The `mapper` argument receives the appropriate item and must return a result.

 // Array
 allApply( items, ( item ) => item.getMemento() )
 // Struct: The result object is a struct of `key` and `value`
 allApply( data, ( item ) => item.key & item.value.toString() )
 

Parameters:

context - The context of the current execution

items - The items to apply the function to, this can be an array or a struct

mapper - The function to apply to each item

errorHandler - The function to handle any errors that occur, this can be null

timeout - The maximum time to wait

unit - The time unit of the timeout argument. This can be a TimeUnit or a string representation of a TimeUnit

Returns:

An array or struct of the results

allApply

public static Object allApply(IBoxContext context,
 Object items,
 Function mapper,
 Function errorHandler,
 long timeout,
 Object unit,
 ExecutorRecord executor)

This function can accept an array of items or a struct of items and apply a function to each of the item's in parallel. The `mapper` argument receives the appropriate item and must return a result.

 // Array
 allApply( items, ( item ) => item.getMemento() )
 // Struct: The result object is a struct of `key` and `value`
 allApply( data, ( item ) => item.key & item.value.toString() )
 

Parameters:

context - The context of the current execution

items - The items to apply the function to, this can be an array or a struct

mapper - The function to apply to each item

errorHandler - The function to handle any errors that occur, this can be null

timeout - The maximum time to wait

unit - The time unit of the timeout argument. This can be a TimeUnit or a string representation of a TimeUnit

executor - The executor to run the function on

Returns:

An array or struct of the results

futuresWrap

public static BoxFuture<?>[] futuresWrap(IBoxContext context,
 Array futures,
 ExecutorRecord executorRecord)

This method accepts an array of future objects, closures or an array of future objects/closures

Parameters:

context - The context of the current execution

futures - The futures to execute. This can be one or more futures or an array of futures

executorRecord - The executor to use for running the futures

Returns:

An array of BoxFuture objects