wirebox.system.async.tasks

Class Future

lucee.Component
    extended by wirebox.system.async.tasks.Future

This is the ColdBox Future object modeled and backed by Java's CompletableFuture but with Dynamic Goodness!

Class Attributes:
  • synchronized : false
    •  
  • see : https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/CompletableFuture.html
    •  
  • accessors : true
    •  
  • persistent : false
    •  
    Property Summary
    type property default serializable required
    boolean debug
          Add debugging output to the thread management and operations.

    • access = public
    • returntype = any
    		 false true false
    any executor
          The custom executor to use with the future execution, or it can be null.

    • access = public
    • returntype = any
    		 true false
    struct futureTimeout
          The timeout you can set on this future via the withTimeout() method.

    • access = public
    • returntype = any
    		 true false
    boolean loadAppContext
          Load the CFML App context and page context's into the spawned threads.

    • access = public
    • returntype = any
    		 true true false
    any native
          The native Completable future we model: java.

    • access = public
    • returntype = any
    		 true false
    Constructor Summary
    init([any value], [any executor], [boolean debug='false'], [boolean loadAppContext='true'])
          Construct a new ColdBox Future backed by a Java Completable Future.
    Method Summary
    Future all()
         This method accepts an infinite amount of future objects, closures or an array of future objects/closures.
    any allApply([any items], [any fn], [any executor], [any timeout], [any timeUnit])
         This function can accept an array of items or a struct of items and apply a function.
    Future anyOf()
         This method accepts an infinite amount of future objects or closures and will execute them in parallel.
    boolean cancel([boolean mayInterruptIfRunning='true'])
         If not already completed, completes this Future with a CancellationException.
    boolean complete(any value)
         If not already completed, sets the value returned by get() and related methods to the given value.
    Future completeExceptionally([any message='Future operation completed with manual exception'])
         If not already completed, causes invocations of get() and related methods to throw the given exception.
    Future completeOnTimeout(any value, any timeout, [any timeUnit='milliseconds'])
         Completes this CompletableFuture with the given value if not otherwise completed before the given timeout.
    Future completeWithException()
         Alias to completeExceptionally.
    Future completedFuture(any value)
         Returns a new ColdBox Future that is already completed with the given value.
    Future exceptionally(any target)
         Register an event handler for any exceptions that happen before it is registered.
    private any futuresWrap()
         This utility wraps in the coming futures or closures and makes sure the return.
    any get([numeric timeout='0'], [string timeUnit='milliseconds'], [any defaultValue])
         Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.
    string getDebug()
    string getExecutor()
    string getFutureTimeout()
    string getLoadAppContext()
    string getNative()
    any getNow(any defaultValue)
         Returns the result value (or throws any encountered exception) if completed, else returns the given defaultValue.
    Future handle(any action)
         Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed with this stage's result.
    Future handleAsync(any action, [any executor])
         Returns a new CompletionStage that, when this stage completes either normally or exceptionally,.
    boolean isCancelled()
         Returns true if this Future was cancelled before it completed normally.
    boolean isCompletedExceptionally()
         Returns true if this Future completed exceptionally, in any way.
    boolean isDone()
         Returns true if completed in any fashion: normally, exceptionally, or via cancellation.
    any join([any defaultValue])
         Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally.
    any onException(any target)
         Alias to exceptionally().
    Future orTimeout(any timeout, [any timeUnit='milliseconds'])
         Exceptionally completes this CompletableFuture with a TimeoutException if not otherwise completed before the given timeout.
    Future run(any supplier, [any method='run'], [any executor='[runtime expression]'])
         Executes a runnable closure or component method via Java's CompletableFuture and gives you back a ColdBox Future:.
    Future runAsync(any runnable, [any executor])
         Alias to the `run()` method but left here to help Java developers.
    any setDebug(boolean debug)
    any setExecutor(any executor)
    any setFutureTimeout(struct futureTimeout)
    any setLoadAppContext(boolean loadAppContext)
    any setNative(any native)
    Future supplyAsync(any supplier, [any executor])
         Alias to the `run()` method but left here to help Java developers.
    Future then(any target)
         Executed once the computation has finalized and a result is passed in to the target:.
    Future thenAccept()
         Alias to thenRun().
    Future thenAcceptAsync()
         Alias to thenRunAsync().
    Future thenApply()
         Alias to `then()` left to help Java devs feel at Home.
    Future thenApplyAsync()
         Alias to `thenAsync()` left to help Java devs feel at Home.
    Future thenAsync(any target, [any executor])
         Executed once the computation has finalized and a result is passed in to the target but.
    Future thenCombine(any future, [any fn])
         This used when you want two Futures to run independently and do something after.
    Future thenCompose(any fn)
         Returns a new CompletionStage that, when this stage completes normally,.
    Future thenRun(any target)
         Returns a new CompletionStage that, when this stage completes normally, is executed with this.
    Future thenRunAsync(any target, [any executor])
         Returns a new CompletionStage that, when this stage completes normally,.
    Future whenComplete(any action)
         Returns a new CompletionStage with the same result or exception as this stage, that executes the given action when this stage completes.
    Future whenCompleteAsync(any action, [any executor])
         Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using this stage's.
    Future withTimeout([numeric timeout='0'], [string timeUnit='milliseconds'])
         This method seeds a timeout into this future that can be used by the following operations:.
     
    Methods inherited from class lucee.Component
    None
    Constructor Detail

    init

    public init([any value], [any executor], [boolean debug='false'], [boolean loadAppContext='true'])

    Construct a new ColdBox Future backed by a Java Completable Future

    Parameters:
    value - The actual closure/lambda/udf to run with or a completed value to seed the future with
    executor - A custom executor to use with the future, else use the default
    debug - Add output debugging
    loadAppContext - Load the CFML App contexts or not, disable if not used
    Property Detail

    debug

    property boolean debug = [false]

    Add debugging output to the thread management and operations. Defaults to false

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    executor

    property any executor

    The custom executor to use with the future execution, or it can be null

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    futureTimeout

    property struct futureTimeout

    The timeout you can set on this future via the withTimeout() method which is used in operations like allOf() and anyOf()

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    loadAppContext

    property boolean loadAppContext = [true]

    Load the CFML App context and page context's into the spawned threads. Defaults to true

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    native

    property any native

    The native Completable future we model: java.util.concurrent.CompletableFuture

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true
    Method Detail

    all

    public Future all()

    This method accepts an infinite amount 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. 

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

    allApply

    public any allApply([any items], [any fn], [any executor], [any timeout], [any timeUnit])

    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 `fn` argument receives the appropriate item and must return a result. Consider this a parallel map() operation 

    // 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:
    items - An array or struct to process in parallel
    fn - The function that will be applied to each of the collection's items
    executor - The custom executor to use if passed, else the forkJoin Pool
    timeout - The timeout to use when waiting for each item to be processed
    timeUnit - The time unit to use, available units are: days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds
    Returns:
    An array or struct with the items processed in parallel
    Throws:
    UnsupportedCollectionException - When something other than an array or struct is passed as items

    anyOf

    public Future anyOf()

    This method accepts an infinite amount of future objects or closures and will execute them in parallel. However, instead of returning all of the results in an array like allOf(), this method will return the future that executes the fastest! 

    // Let's say f2 executes the fastest!
f2 = anyOf( f1, f2, f3 )

    Returns:
    The fastest executed future

    cancel

    public boolean cancel([boolean mayInterruptIfRunning='true'])

    If not already completed, completes this Future with a CancellationException. Dependent Futures that have not already completed will also complete exceptionally, with a CompletionException caused by this CancellationException.

    Parameters:
    mayInterruptIfRunning
    Returns:
    true if this task is now cancelled

    complete

    public boolean complete(any value)

    If not already completed, sets the value returned by get() and related methods to the given value.

    Parameters:
    value - The value to set
    Returns:
    true if this invocation caused this CompletableFuture to transition to a completed state, else false

    completeExceptionally

    public Future completeExceptionally([any message='Future operation completed with manual exception'])

    If not already completed, causes invocations of get() and related methods to throw the given exception. The exception type is of `java.lang.RuntimeException` and you can choose the message to throw with it.

    Parameters:
    message - An optional message to add to the exception to be thrown.
    Returns:
    The same Future

    completeOnTimeout

    public Future completeOnTimeout(any value, any timeout, [any timeUnit='milliseconds'])

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

    Parameters:
    value - The value to use upon timeout
    timeout - how long to wait before completing normally with the given value, in units of unit
    timeUnit - The time unit to use, available units are: days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds

    completeWithException

    public Future completeWithException()

    Alias to completeExceptionally

    completedFuture

    public Future completedFuture(any value)

    Returns a new ColdBox Future that is already completed with the given value.

    Parameters:
    value - The value to set
    Returns:
    The ColdBox completed future

    exceptionally

    public Future exceptionally(any target)

    Register an event handler for any exceptions that happen before it is registered in the future pipeline. Whatever this function returns, will be used for the next registered functions in the pipeline. The function takes in the exception that occurred and can return a new value as well: 

    ( exception ) => newValue;
function( exception ) => {
return newValue;
}
    Note that, the error will not be propagated further in the callback chain if you handle it once.

    Parameters:
    target - The function that will be called when the exception is triggered
    Returns:
    The future with the exception handler registered

    futuresWrap

    private any futuresWrap()

    This utility wraps in the coming futures or closures and makes sure the return is an array of futures.

    get

    public any get([numeric timeout='0'], [string timeUnit='milliseconds'], [any defaultValue])

    Waits if necessary for at most the given time for this future to complete, and then returns its result, if available. If the result is null, then you can pass the defaultValue argument to return it.

    Parameters:
    timeout - The timeout value to use, defaults to forever
    timeUnit - The time unit to use, available units are: days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds
    defaultValue - If the Future did not produce a value, then it will return this default value.
    Returns:
    The result value
    Throws:
    CancellationException , ExecutionException, InterruptedException, TimeoutException

    getDebug

    public string getDebug()

    getExecutor

    public string getExecutor()

    getFutureTimeout

    public string getFutureTimeout()

    getLoadAppContext

    public string getLoadAppContext()

    getNative

    public string getNative()

    getNow

    public any getNow(any defaultValue)

    Returns the result value (or throws any encountered exception) if completed, else returns the given defaultValue.

    Parameters:
    defaultValue - The value to return if not completed
    Returns:
    The result value, if completed, else the given defaultValue
    Throws:
    CancellationException , CompletionException

    handle

    public Future handle(any action)

    Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed with this stage's result and exception as arguments to the supplied function. When this stage is complete, the given function is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments, and the function's result is used to complete the returned stage. The action is a closure/udf with the incoming input (if any) or an exception (if any) and returns a new result if you want 

    handle( (input, exception) => {} )
handle( function( input, exception ){} )

    Parameters:
    action - the function to use to compute the value of the returned CompletionStage
    Returns:
    The new completion stage

    handleAsync

    public Future handleAsync(any action, [any executor])

    Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using this stage's default asynchronous execution facility, with this stage's result and exception as arguments to the supplied function. When this stage is complete, the given function is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments, and the function's result is used to complete the returned stage. The action is a closure/udf with the incoming input (if any) or an exception (if any) and returns a new result if you want 

    handleAsync( (input, exception) => {} )
handleAsync( function( input, exception ){} )
handleAsync( (input, exception) => {}, asyncManager.$executors.newFixedThreadPool() )

    Parameters:
    action - the function to use to compute the value of the returned CompletionStage
    executor - the java executor to use for asynchronous execution, can be empty
    Returns:
    The new completion stage

    isCancelled

    public boolean isCancelled()

    Returns true if this Future was cancelled before it completed normally.

    isCompletedExceptionally

    public boolean isCompletedExceptionally()

    Returns true if this Future completed exceptionally, in any way. Possible causes include cancellation, explicit invocation of completeWithException, and abrupt termination of a CompletionStage action.

    isDone

    public boolean isDone()

    Returns true if completed in any fashion: normally, exceptionally, or via cancellation.

    join

    public any join([any defaultValue])

    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:
    defaultValue - If the returned value is null, then we can pass a default value to return
    Returns:
    The result value
    Throws:
    CancellationException - if the computation was cancelled

    onException

    public any onException(any target)

    Alias to exceptionally()

    Parameters:
    target

    orTimeout

    public Future orTimeout(any timeout, [any timeUnit='milliseconds'])

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

    Parameters:
    timeout - how long to wait before completing normally with the given value, in units of unit
    timeUnit - The time unit to use, available units are: days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds

    run

    public Future run(any supplier, [any method='run'], [any executor='[runtime expression]'])

    Executes a runnable closure or component method via Java's CompletableFuture and gives you back a ColdBox Future: - This method calls `supplyAsync()` in the Java API - This future is asynchronously completed by a task running in the ForkJoinPool.commonPool() with the value obtained by calling the given Supplier.

    Parameters:
    supplier - A CFC instance or closure or lambda or udf to execute and return the value to be used in the future
    method - If the supplier is a CFC, then it executes a method on the CFC for you. Defaults to the `run()` method
    executor - An optional executor to use for asynchronous execution of the task
    Returns:
    The new completion stage (Future)

    runAsync

    public Future runAsync(any runnable, [any executor])

    Alias to the `run()` method but left here to help Java developers feel at home. Since in our futures, everything becomes a supplier of some sort.

    Parameters:
    runnable - A CFC instance or closure or lambda or udf to execute and return the value to be used in the future
    executor - An optional executor to use for asynchronous execution of the task
    Returns:
    The new completion stage (Future)

    setDebug

    public any setDebug(boolean debug)

    Parameters:
    debug

    setExecutor

    public any setExecutor(any executor)

    Parameters:
    executor

    setFutureTimeout

    public any setFutureTimeout(struct futureTimeout)

    Parameters:
    futureTimeout

    setLoadAppContext

    public any setLoadAppContext(boolean loadAppContext)

    Parameters:
    loadAppContext

    setNative

    public any setNative(any native)

    Parameters:
    native

    supplyAsync

    public Future supplyAsync(any supplier, [any executor])

    Alias to the `run()` method but left here to help Java developers feel at home. Since in our futures, everything becomes a supplier of some sort.

    Parameters:
    supplier - A CFC instance or closure or lambda or udf to execute and return the value to be used in the future
    executor - An optional executor to use for asynchronous execution of the task
    Returns:
    The new completion stage (Future)

    then

    public Future then(any target)

    Executed once the computation has finalized and a result is passed in to the target: - The target can use the result, manipulate it and return a new result from the this completion stage - The target can use the result and return void - This stage executes in the calling thread 

    // Just use the result and not return anything
then( (result) => systemOutput( result ) )
// Get the result and manipulate it, much like a map() function
then( (result) => ucase( result ) );

    Parameters:
    target - The closure/lambda or udf that will receive the result
    Returns:
    The new completion stage (Future)

    thenAccept

    public Future thenAccept()

    Alias to thenRun()

    thenAcceptAsync

    public Future thenAcceptAsync()

    Alias to thenRunAsync()

    thenApply

    public Future thenApply()

    Alias to `then()` left to help Java devs feel at Home Remember, the closure accepts the data and MUST return the data if not the next stage could be receiving a null result.

    thenApplyAsync

    public Future thenApplyAsync()

    Alias to `thenAsync()` left to help Java devs feel at Home

    thenAsync

    public Future thenAsync(any target, [any executor])

    Executed once the computation has finalized and a result is passed in to the target but this will execute in a separate thread. By default it uses the ForkJoin.commonPool() but you can pass your own executor service. - The target can use the result, manipulate it and return a new result from the this completion stage - The target can use the result and return void 

    // Just use the result and not return anything
then( (result) => systemOutput( result ) )
// Get the result and manipulate it, much like a map() function
then( (result) => ucase( result ) );

    Parameters:
    target - The closure/lambda or udf that will receive the result
    executor
    Returns:
    The new completion stage (Future)

    thenCombine

    public Future thenCombine(any future, [any fn])

    This used when you want two Futures to run independently and do something after both are complete.

    Parameters:
    future - The ColdBox Future to combine
    fn - The closure that will combine them: ( r1, r2 ) =>

    thenCompose

    public Future thenCompose(any fn)

    Returns a new CompletionStage that, when this stage completes normally, is executed with this stage as the argument to the supplied function. Basically, this used to combine two Futures where one future is dependent on the other If not, you return a future of a future

    Parameters:
    fn - the function returning a new CompletionStage
    Returns:
    the CompletionStage

    thenRun

    public Future thenRun(any target)

    Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied action. See the CompletionStage documentation for rules covering exceptional completion. - The target can use the result and return void - This stage executes in the calling thread 

    // Just use the result and not return anything
thenRun( (result) => systemOutput( result ) )

    Parameters:
    target - The action to perform before completing the returned CompletionStage
    Returns:
    The new completion stage (Future)

    thenRunAsync

    public Future thenRunAsync(any target, [any executor])

    Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied action. See the CompletionStage documentation for rules covering exceptional completion. - The target can use the result and return void - This stage executes in the passed executor or the stage's executor facility 

    // Just use the result and not return anything
thenRunAsync( (result) => systemOutput( result ) )
thenRunAsync( (result) => systemOutput( result ), myExecutor )

    Parameters:
    target - The action to perform before completing the returned CompletionStage
    executor - If passed, the executor to use to run the target
    Returns:
    The new completion stage (Future)

    whenComplete

    public Future whenComplete(any action)

    Returns a new CompletionStage with the same result or exception as this stage, that executes the given action when this stage completes. When this stage is complete, the given action is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments. The returned stage is completed when the action returns. If the supplied action itself encounters an exception, then the returned stage exceptionally completes with this exception unless this stage also completed exceptionally. The action is a closure/udf with the incoming input (if any) or an exception (if any) and returns void. 

    whenComplete( (input, exception) => {} )
whenComplete( function( input, exception ){} )

    Parameters:
    action - the action to perform
    Returns:
    The new completion stage

    whenCompleteAsync

    public Future whenCompleteAsync(any action, [any executor])

    Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using this stage's default asynchronous execution facility when this stage completes. When this stage is complete, the given action is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments. The returned stage is completed when the action returns. If the supplied action itself encounters an exception, then the returned stage exceptionally completes with this exception unless this stage also completed exceptionally. The action is a closure/udf with the incoming input (if any) or an exception (if any) and returns void. 

    whenCompleteAsync( (input, exception) => {} )
whenCompleteAsync( function( input, exception ){} )
whenCompleteAsync( (input, exception) => {}, asyncManager.$executors.newFixedThreadPool() )

    Parameters:
    action - the action to perform
    executor - the java executor to use for asynchronous execution, can be empty
    Returns:
    The new completion stage

    withTimeout

    public Future withTimeout([numeric timeout='0'], [string timeUnit='milliseconds'])

    This method seeds a timeout into this future that can be used by the following operations: - allApply()

    Parameters:
    timeout - The timeout value to use, defaults to forever
    timeUnit - The time unit to use, available units are: days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds
    Returns:
    This future