Package javascalautils.concurrent

Interface Promise<T>

  • Type Parameters:
    T - The type this Promise will produce as result
    public interface Promise<T>
    The Promise is the promise to deliver a value at some time in the future.
    This is the handle the actual computation side of of the job uses.
    Once a job is finished it will report the outcome to the Promise which in turn relays it to the Future the client/application is monitoring.
    A promise can be fulfilled either by invoking success or failure but not both.
    Nor can success/failure be invoked twice.
    The principle is that a Promise will deliver exactly one successful or failure response.
    The successful response is of any type whilst the failure is expected to be of type (or subclass of) Throwable.

    Together with a Future this allows a safe publication of asynchronously calculated results into another thread.
    The basic principle is to first create a Promise.
    Promise<String> promise = Promise.apply();
    Using that instance one can get hold of the Future that is the container for the value-to-be.
    Future<String> future = promise.future();
    To complete the Promise and by extension completing the Future one can use any of several methods: E.g.
    promise.success("Peter was here");
    Note that only one of the methods may be invoked as the Promise can only be fulfilled once.
    The above methods come with a variant tryNNN which allows for multiple invocations without raising an exception.
    Though still only the first invocation/completion counts.
    Since:
    1.2

    • Method Detail

      • apply

        static <T> Promise<T> apply()
        Creates an instance of Promise.
        E.g. Promise<String> p = Promise.apply();
        Type Parameters:
        T - The type this Promise will produce as result
        Returns:
        The Promise instance
        Since:
        1.2

      • future

        Future<T> future()
        Get a Future that will hold the value once this Promise is completed.
        Each Promise is connected to a single Future, invoking this method multiple times will always return the same Future instance.
        Returns:
        A Future that will hold the value once this Promise is completed.
        Since:
        1.2

      • isCompleted

        boolean isCompleted()
        Check if the Promise have been completed, with a value or an exception.
        Returns:
        true if the Promise has been completed. false otherwise.
        Since:
        1.2

      • complete

        void complete​(Try<T> result)
        Completes the Promise with either a Success or a Failure.
        Parameters:
        result - The result to complete with.
        Throws:
        java.lang.IllegalStateException - Thrown if the Promise is already completed.
        Since:
        1.3

      • completeWith

        void completeWith​(Future<T> future)
        Completes the Promise with the value from the provided Future once that is completed.
        Parameters:
        future - The future whose value will complete this Promise
        Throws:
        java.lang.IllegalStateException - Thrown if the Promise is already completed.
        Since:
        1.3

      • success

        void success​(T result)
        Completes the Promise with a value.
        Parameters:
        result - The value to complete with.
        Throws:
        java.lang.IllegalStateException - Thrown if the Promise is already completed.
        Since:
        1.2

      • failure

        void failure​(java.lang.Throwable throwable)
        Completes the Promise with an exception.
        Parameters:
        throwable - The Throwable to complete with.
        Throws:
        java.lang.IllegalStateException - Thrown if the Promise is already completed.
        Since:
        1.2

      • tryComplete

        boolean tryComplete​(Try<T> result)
        Tries to complete the Promise with either a Success or a Failure.
        Contrary to the complete(Try) method this does not throw an exception in case the Promise is already completed.
        Parameters:
        result - The result to complete with.
        Returns:
        true if the Promise was not completed before, false otherwise
        Since:
        1.3

      • tryCompleteWith

        boolean tryCompleteWith​(Future<T> future)
        Tries to complete this Promise with the value from the provided Future once that is completed.
        Contrary to the complete(Try) method this does not throw an exception in case the Promise is already completed.
        Parameters:
        future - The future whose value will complete this Promise
        Returns:
        true if the Promise was not completed before, false otherwise
        Since:
        1.3

      • trySuccess

        boolean trySuccess​(T result)
        Tries to complete the Promise with a value.
        Contrary to the success(Object) method this does not throw an exception in case the Promise is already completed.
        Parameters:
        result - The value to complete with.
        Returns:
        true if the Promise was not completed before, false otherwise
        Since:
        1.3

      • tryFailure

        boolean tryFailure​(java.lang.Throwable throwable)
        Tries to complete the Promise with an exception.
        Contrary to the failure(Throwable) method this does not throw an exception in case the Promise is already completed.
        Parameters:
        throwable - The Throwable to complete with.
        Returns:
        true if the Promise was not completed before, false otherwise
        Since:
        1.3