Package jadex.commons.future

Class Future<E>

    • Field Detail

      • 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.

      • 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.

    • 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.

      • scheduleNotification

        protected void scheduleNotification​(IFilter<IResultListener<E>> filter,
                                    ICommand<IResultListener<E>> command)
        Schedule a listener notification.
        Parameters:
        filter - Optional filter to select only specific listener (e.g. for forward commands). Otherwise uses all listeners.
        command - The notification command to execute for each selected listener.

      • scheduleNotification

        protected void scheduleNotification​(ICommand<IResultListener<E>> command)
        Schedule a notification for all listeners.
        Parameters:
        command - The notification command to execute for each currently registered listener.

      • scheduleNotification

        protected void scheduleNotification​(IResultListener<E> listener,
                                    ICommand<IResultListener<E>> command)
        Schedule a listener notification for a specific listener. Can be called from synchronized block.
        Parameters:
        listener - The listener to notify.
        command - The notification command to execute for the listener.

      • startScheduledNotifications

        protected final void startScheduledNotifications()
        Start scheduled listener notifications. Must not be called from synchronized block.

      • 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.

      • notifyListener

        protected void notifyListener()
        Notify all result listeners of the finished future (result or exception).

      • notifyListener

        protected void notifyListener​(IResultListener<E> listener)
        Notify a specific result listener of the finished future (result or exception).
        Parameters:
        listener - The listener.

      • getNotificationCommand

        protected ICommand<IResultListener<E>> getNotificationCommand()
        Get the notification command.

      • 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.

      • 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.

      • exceptionally

        public <T> void exceptionally​(Future<T> delegate)
        Sequential execution of async methods via implicit delegation.
        Specified by:
        exceptionally in interface IFuture<E>
        Parameters:
        function - Function that takes the result of this future as input and delivers future(t).
        ret - The

      • exceptionally

        public IFuture<E> exceptionally​(Consumer<? super java.lang.Exception> consumer,
                                java.lang.Class<?> futuretype)
        Specified by:
        exceptionally in interface IFuture<E>

      • 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.