Future (Jadex Active Component Platform 3.0.86 API)

java.lang.Object
- jadex.commons.future.Future<E>

All Implemented Interfaces:

IForwardCommandFuture, IFuture<E>

Direct Known Subclasses:

IntermediateFuture, TerminableDelegationFuture, TerminableFuture
```
public class Future<E>
extends java.lang.Object
implements IFuture<E>, IForwardCommandFuture
```
Future that includes mechanisms for callback notification. This allows a caller to decide if a) a blocking call to get() should be used b) a callback shall be invoked

Nested Class Summary
- Nested classes/interfaces inherited from interface jadex.commons.future.IForwardCommandFuture
  IForwardCommandFuture.Type

Field Summary

Fields
Modifier and Type	Field and Description
`protected static java.lang.String`	`CALLER_QUEUED` A caller is queued for suspension.
`protected static java.lang.String`	`CALLER_RESUMED` A caller is resumed.
`protected static java.lang.String`	`CALLER_SUSPENDED` A caller is suspended.
`protected java.util.Map<ISuspendable,java.lang.String>`	`callers` The blocked callers (caller->state).
`protected java.lang.Exception`	`creation` For capturing call stack of future creation.
`static boolean`	`DEBUG` Debug flag.
`protected java.lang.Exception`	`exception` The exception (if any).
`protected java.util.Map<ICommand<java.lang.Object>,IFilter<java.lang.Object>>`	`fcommands` The list of commands.
`protected java.lang.Exception`	`first` For capturing call stack of first setResult/Exception call.
`protected IResultListener<E>`	`listener` The first listener (for avoiding array creation).
`protected java.util.List<IResultListener<E>>`	`listeners` The listeners.
`static boolean`	`NO_STACK_COMPACTION` Disable Stack unfolding for easier debugging.
`static long`	`NONE` Constant for no timeout.
`protected E`	`result` The result.
`protected boolean`	`resultavailable` Flag indicating if result is available.
`static java.lang.ThreadLocal<java.util.List<Tuple2<Future<?>,IResultListener<?>>>>`	`STACK` Notification stack for unwinding call stack to topmost future.
`protected boolean`	`undone` The undone flag.
`static long`	`UNSET` Constant for unset.

Fields inherited from interface jadex.commons.future.IFuture
DONE, FALSE, TRUE

Constructor Summary

Constructors
Constructor and Description
`Future()` Create a new future.
`Future(E result)` Create a future that is already done.
`Future(java.lang.Exception exception)` Create a future that is already failed.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`abortGet(ISuspendable caller)` Abort a blocking get call.
`IFuture<java.lang.Void>`	`acceptEither(IFuture<E> other, Consumer<E> action, java.lang.Class<?> futuretype)` The given consumer will be executed with either of the result of this and the given other future.
`void`	`addForwardCommand(IFilter<java.lang.Object> filter, ICommand<java.lang.Object> command)` Add a forward command with a filter.
`void`	`addResultListener(IFunctionalResultListener<E> sucListener)` Add an functional result listener, which is only called on success.
`void`	`addResultListener(IFunctionalResultListener<E> sucListener, IFunctionalExceptionListener exListener)` Add a result listener by combining an OnSuccessListener and an OnExceptionListener.
`void`	`addResultListener(IResultListener<E> listener)` Add a result listener.
`<U> IFuture<U>`	`applyToEither(IFuture<E> other, Function<E,U> fn, java.lang.Class<?> futuretype)` The given function will be executed with either of the result of this and the given other future.
`protected boolean`	`doSetException(java.lang.Exception exception, boolean undone)` Set the exception (internal implementation for normal and if-undone).
`protected boolean`	`doSetResult(E result, boolean undone)` Set the result without notifying listeners.
`E`	`get()` Get the result - blocking call.
`E`	`get(boolean realtime)` Get the result - blocking call.
`E`	`get(long timeout)` Get the result - blocking call.
`E`	`get(long timeout, boolean realtime)` Get the result - blocking call.
`E`	`get(ThreadSuspendable sus)` Deprecated. - From 3.0. Use the version without suspendable. Will NOT use the suspendable given as parameter. Get the result - blocking call.
`static <T> IFuture<T>`	`getEmptyFuture()` Get the empty future of some type.
`java.lang.Exception`	`getException()` Get the exception, if any.
`<T> Future<T>`	`getFuture(java.lang.Class<?> futuretype)` Sequential execution of async methods via implicit delegation.
`boolean`	`hasResultListener()` Check, if the future has at least one listener.
`boolean`	`isDone()` Test if done, i.e.
`protected void`	`notifyListener(IResultListener<E> listener)` Notify a result listener.
`protected void`	`notifyListenerCommand(IResultListener<E> listener, java.lang.Object command)` Notify the command listeners.
`void`	`removeForwardCommand(ICommand<java.lang.Object> command)` Add a command with a filter.
`protected void`	`resume()` Resume after result or exception has been set.
`void`	`sendForwardCommand(java.lang.Object command)` Send a (forward) command to the listeners.
`void`	`setException(java.lang.Exception exception)` Set the exception.
`boolean`	`setExceptionIfUndone(java.lang.Exception exception)` Set the exception.
`void`	`setResult(E result)` Set the result.
`boolean`	`setResultIfUndone(E result)` Set the result.
`IFuture<java.lang.Void>`	`thenAccept(Consumer<? super E> consumer)` Applies a synchronous function consuming the result after it is available.
`IFuture<java.lang.Void>`	`thenAccept(Consumer<? super E> consumer, java.lang.Class<?> futuretype)` Applies a function consuming the result after it is available.
`<T> IFuture<T>`	`thenApply(Function<? super E,? extends T> function)` Applies a function after the result is available, using the result of this Future as input.
`<T> IFuture<T>`	`thenApply(Function<? super E,? extends T> function, java.lang.Class<?> futuretype)` Applies a function after the result is available, using the result of this Future as input.
`<U,V> IFuture<V>`	`thenCombine(IFuture<U> other, BiFunction<? super E,? super U,? extends V> function, java.lang.Class<?> futuretype)` Combines this and another future and uses the given bifunction to calculate the result.
`<T> IFuture<T>`	`thenCompose(Function<? super E,IFuture<T>> function)` The result of this future is delegated to the given (future-returning) function.
`<T> IFuture<T>`	`thenCompose(Function<? super E,IFuture<T>> function, java.lang.Class<?> futuretype)` The result of this future is delegated to the given (future-returning) function.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - STACK
```
public static final java.lang.ThreadLocal<java.util.List<Tuple2<Future<?>,IResultListener<?>>>> STACK
```
    Notification stack for unwinding call stack to topmost future.
  - CALLER_QUEUED
```
protected static final java.lang.String CALLER_QUEUED
```
    A caller is queued for suspension.
    
    See Also:
    
    Constant Field Values
  - CALLER_RESUMED
```
protected static final java.lang.String CALLER_RESUMED
```
    A caller is resumed.
    
    See Also:
    
    Constant Field Values
  - CALLER_SUSPENDED
```
protected static final java.lang.String CALLER_SUSPENDED
```
    A caller is suspended.
    
    See Also:
    
    Constant Field Values
  - DEBUG
```
public static boolean DEBUG
```
    Debug flag.
  - NO_STACK_COMPACTION
```
public static boolean NO_STACK_COMPACTION
```
    Disable Stack unfolding for easier debugging.
  - NONE
```
public static final long NONE
```
    Constant for no timeout.
    
    See Also:
    
    Constant Field Values
  - UNSET
```
public static final long UNSET
```
    Constant for unset.
    
    See Also:
    
    Constant Field Values
  - result
```
protected E result
```
    The result.
  - exception
```
protected java.lang.Exception exception
```
    The exception (if any).
  - resultavailable
```
protected volatile boolean resultavailable
```
    Flag indicating if result is available.
  - callers
```
protected java.util.Map<ISuspendable,java.lang.String> callers
```
    The blocked callers (caller->state).
  - listener
```
protected IResultListener<E> listener
```
    The first listener (for avoiding array creation).
  - listeners
```
protected java.util.List<IResultListener<E>> listeners
```
    The listeners.
  - creation
```
protected java.lang.Exception creation
```
    For capturing call stack of future creation.
  - first
```
protected java.lang.Exception first
```
    For capturing call stack of first setResult/Exception call.
  - undone
```
protected boolean undone
```
    The undone flag.
  - fcommands
```
protected java.util.Map<ICommand<java.lang.Object>,IFilter<java.lang.Object>> fcommands
```
    The list of commands.
- Constructor Detail
  - Future
```
public Future()
```
    Create a new future.
  - Future
```
public Future(E result)
```
    Create a future that is already done.
    
    Parameters:
    
    result - The result, if any.
  - Future
```
public Future(java.lang.Exception exception)
```
    Create a future that is already failed.
    
    Parameters:
    
    exception - The exception.
- Method Detail
  - getEmptyFuture
```
public static <T> IFuture<T> getEmptyFuture()
```
    Get the empty future of some type.
    
    Returns:
    
    The empty future.
  - isDone
```
public boolean isDone()
```
    Test if done, i.e. result is available.
    
    Specified by:
    
    isDone in interface IFuture<E>
    
    Returns:
    
    True, if done.
  - getException
```
public java.lang.Exception getException()
```
    Get the exception, if any.
    
    Specified by:
    
    getException in interface IFuture<E>
    
    Returns:
    
    The exception, if any, or null if the future is not yet done or succeeded without exception.
  - get
```
public E get(ThreadSuspendable sus)
```
    Deprecated. - From 3.0. Use the version without suspendable. Will NOT use the suspendable given as parameter. Get the result - blocking call.
    
    Specified by:
    
    get in interface IFuture<E>
    
    Returns:
    
    The future result.
  - get
```
public E get()
```
    Get the result - blocking call.
    
    Specified by:
    
    get in interface IFuture<E>
    
    Returns:
    
    The future result.
  - get
```
public E get(boolean realtime)
```
    Get the result - blocking call.
    
    Specified by:
    
    get in interface IFuture<E>
    
    Parameters:
    
    realtime - Flag, if wait should be realtime (in constrast to simulation time).
    
    Returns:
    
    The future result.
  - get
```
public E get(long timeout)
```
    Get the result - blocking call.
    
    Specified by:
    
    get in interface IFuture<E>
    
    Parameters:
    
    timeout - The timeout in millis.
    
    Returns:
    
    The future result.
  - get
```
public E get(long timeout,
             boolean realtime)
```
    Get the result - blocking call.
    
    Specified by:
    
    get in interface IFuture<E>
    
    Parameters:
    
    timeout - The timeout in millis.
    
    realtime - Flag if timeout is realtime (in contrast to simulation time).
    
    Returns:
    
    The future result.
  - doSetException
```
protected boolean doSetException(java.lang.Exception exception,
                                 boolean undone)
```
    Set the exception (internal implementation for normal and if-undone).
  - setException
```
public void setException(java.lang.Exception exception)
```
    Set the exception. Listener notifications occur on calling thread of this method.
    
    Parameters:
    
    exception - The exception.
  - setExceptionIfUndone
```
public boolean setExceptionIfUndone(java.lang.Exception exception)
```
    Set the exception. Listener notifications occur on calling thread of this method.
    
    Parameters:
    
    exception - The exception.
  - setResult
```
public void setResult(E result)
```
    Set the result. Listener notifications occur on calling thread of this method.
    
    Parameters:
    
    result - The result.
  - setResultIfUndone
```
public boolean setResultIfUndone(E result)
```
    Set the result. Listener notifications occur on calling thread of this method.
    
    Parameters:
    
    result - The result.
    
    Returns:
    
    True if result was set.
  - doSetResult
```
protected boolean doSetResult(E result,
                              boolean undone)
```
    Set the result without notifying listeners.
  - resume
```
protected void resume()
```
    Resume after result or exception has been set.
  - abortGet
```
public void abortGet(ISuspendable caller)
```
    Abort a blocking get call.
  - addResultListener
```
public void addResultListener(IFunctionalResultListener<E> sucListener)
```
    Add an functional result listener, which is only called on success. Exceptions will be handled by DefaultResultListener.
    
    Specified by:
    
    addResultListener in interface IFuture<E>
    
    Parameters:
    
    sucListener - The listener.
  - addResultListener
```
public void addResultListener(IFunctionalResultListener<E> sucListener,
                              IFunctionalExceptionListener exListener)
```
    Add a result listener by combining an OnSuccessListener and an OnExceptionListener.
    
    Specified by:
    
    addResultListener in interface IFuture<E>
    
    Parameters:
    
    sucListener - The listener that is called on success.
    
    exListener - The listener that is called on exceptions. Passing null enables default exception logging.
  - addResultListener
```
public void addResultListener(IResultListener<E> listener)
```
    Add a result listener.
    
    Specified by:
    
    addResultListener in interface IFuture<E>
    
    Parameters:
    
    listener - The listener.
  - notifyListener
```
protected void notifyListener(IResultListener<E> listener)
```
    Notify a result listener.
    
    Parameters:
    
    listener - The listener.
  - sendForwardCommand
```
public void sendForwardCommand(java.lang.Object command)
```
    Send a (forward) command to the listeners.
    
    Specified by:
    
    sendForwardCommand in interface IForwardCommandFuture
    
    Parameters:
    
    command - The command.
  - notifyListenerCommand
```
protected void notifyListenerCommand(IResultListener<E> listener,
                                     java.lang.Object command)
```
    Notify the command listeners.
    
    Parameters:
    
    listener - The listener.
    
    command - The command.
  - addForwardCommand
```
public void addForwardCommand(IFilter<java.lang.Object> filter,
                              ICommand<java.lang.Object> command)
```
    Add a forward command with a filter. Whenever the future receives an info it will check all registered filters.
  - removeForwardCommand
```
public void removeForwardCommand(ICommand<java.lang.Object> command)
```
    Add a command with a filter. Whenever the future receives an info it will check all registered filters.
  - hasResultListener
```
public boolean hasResultListener()
```
    Check, if the future has at least one listener.
  - thenApply
```
public <T> IFuture<T> thenApply(Function<? super E,? extends T> function)
```
    Description copied from interface: IFuture
    
    Applies a function after the result is available, using the result of this Future as input.
    
    Specified by:
    
    thenApply in interface IFuture<E>
    
    Parameters:
    
    function - Function that takes the result of this future as input and delivers t.
    
    Returns:
    
    Future of the result after the function has been applied.
  - thenApply
```
public <T> IFuture<T> thenApply(Function<? super E,? extends T> function,
                                java.lang.Class<?> futuretype)
```
    Description copied from interface: IFuture
    
    Applies a function after the result is available, using the result of this Future as input.
    
    Specified by:
    
    thenApply in interface IFuture<E>
    
    Parameters:
    
    function - Function that takes the result of this future as input and delivers t.
    
    futuretype - The type of the return future.
    
    Returns:
    
    Future of the result after the function has been applied.
  - thenCompose
```
public <T> IFuture<T> thenCompose(Function<? super E,IFuture<T>> function)
```
    Description copied from interface: IFuture
    
    The result of this future is delegated to the given (future-returning) function. The result of the function will be available in the returned future.
    
    Specified by:
    
    thenCompose in interface IFuture<E>
    
    Parameters:
    
    function - Function that takes the result of this future as input and delivers future(t).
    
    Returns:
    
    Future of the result of the second async call.
  - thenCompose
```
public <T> IFuture<T> thenCompose(Function<? super E,IFuture<T>> function,
                                  java.lang.Class<?> futuretype)
```
    Description copied from interface: IFuture
    
    The result of this future is delegated to the given (future-returning) function. The result of the function will be available in the returned future.
    
    Specified by:
    
    thenCompose in interface IFuture<E>
    
    Parameters:
    
    function - Function that takes the result of this future as input and delivers future(t).
    
    futuretype - The type of the return future. If null, a default future is created.
    
    Returns:
    
    Future of the result of the second async call.
  - thenAccept
```
public IFuture<java.lang.Void> thenAccept(Consumer<? super E> consumer)
```
    Description copied from interface: IFuture
    
    Applies a synchronous function consuming the result after it is available.
    
    Specified by:
    
    thenAccept in interface IFuture<E>
    
    Parameters:
    
    consumer - Consumer that takes the result of this future as input and consumes it.
    
    Returns:
    
    Future of the result of the second async call.
  - thenAccept
```
public IFuture<java.lang.Void> thenAccept(Consumer<? super E> consumer,
                                          java.lang.Class<?> futuretype)
```
    Description copied from interface: IFuture
    
    Applies a function consuming the result after it is available.
    
    Specified by:
    
    thenAccept in interface IFuture<E>
    
    Parameters:
    
    consumer - Consumer that takes the result of this future as input and consumes it.
    
    futuretype - The type of the return future. If null, a default future is created.
    
    Returns:
    
    Future of the second async call (returning void).
  - thenCombine
```
public <U,V> IFuture<V> thenCombine(IFuture<U> other,
                                    BiFunction<? super E,? super U,? extends V> function,
                                    java.lang.Class<?> futuretype)
```
    Description copied from interface: IFuture
    
    Combines this and another future and uses the given bifunction to calculate the result. Both future results are passed to the function as input.
    
    Specified by:
    
    thenCombine in interface IFuture<E>
    
    function - BiFunction that takes the result of this and given other future as input and produces output.
    
    futuretype - The type of the return future. If null, a default future is created.
    
    Returns:
    
    Future of the second async call. Types: function is: E,U -> V
  - applyToEither
```
public <U> IFuture<U> applyToEither(IFuture<E> other,
                                    Function<E,U> fn,
                                    java.lang.Class<?> futuretype)
```
    Description copied from interface: IFuture
    
    The given function will be executed with either of the result of this and the given other future. The returned Future will receive the result of the function execution. If both futures return results, the first is used to call the function. If both futures throw exceptions, the last is passed to the returned future.
    
    Specified by:
    
    applyToEither in interface IFuture<E>
    
    Parameters:
    
    other - other future
    
    fn - function to receive result
    
    futuretype - The type of the return future. If null, a default future is created.
    
    Returns:
    
    Future of the async function execution.
  - acceptEither
```
public IFuture<java.lang.Void> acceptEither(IFuture<E> other,
                                            Consumer<E> action,
                                            java.lang.Class<?> futuretype)
```
    Description copied from interface: IFuture
    
    The given consumer will be executed with either of the result of this and the given other future. The returned Future will receive the result of the function execution. If both futures return results, the first is used to call the function. If both futures throw exceptions, the last is passed to the returned future.
    
    Specified by:
    
    acceptEither in interface IFuture<E>
    
    Parameters:
    
    other - other future
    
    futuretype - The type of the return future. If null, a default future is created.
    
    Returns:
    
    Future of the async function execution.
  - getFuture
```
public <T> Future<T> getFuture(java.lang.Class<?> futuretype)
```
    Sequential execution of async methods via implicit delegation.
    
    Parameters:
    
    futuretype - The type of the result future (cannot be automatically determined).
    
    Returns:
    
    Future of the result of the second async call.

Class Future<E>

Nested Class Summary

Nested classes/interfaces inherited from interface jadex.commons.future.IForwardCommandFuture

Field Summary

Fields inherited from interface jadex.commons.future.IFuture

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

STACK

CALLER_QUEUED

CALLER_RESUMED

CALLER_SUSPENDED

DEBUG

NO_STACK_COMPACTION

NONE

UNSET

result

exception

resultavailable

callers

listener

listeners

creation

first

undone

fcommands

Constructor Detail

Future

Future

Future

Method Detail

getEmptyFuture

isDone

getException

get

get

get

get

get

doSetException

setException

setExceptionIfUndone

setResult

setResultIfUndone

doSetResult

resume

abortGet

addResultListener

addResultListener

addResultListener

notifyListener

sendForwardCommand

notifyListenerCommand

addForwardCommand

removeForwardCommand

hasResultListener

thenApply

thenApply

thenCompose

thenCompose

thenAccept

thenAccept

thenCombine

applyToEither

acceptEither

getFuture