Interface Promise<D,​F,​P>

    • Method Detail

      • state

        Promise.State state()
        Returns:
        the state of this promise.
      • isPending

        boolean isPending()
        Queries the state of this promise, returning true iff it is State.PENDING.
        Returns:
        true if the current state of this promise is State.PENDING, false otherwise.
        See Also:
        Promise.State.PENDING
      • isResolved

        boolean isResolved()
        Queries the state of this promise, returning true iff it is State.RESOLVED.
        Returns:
        true if the current state of this promise is State.RESOLVED, false otherwise.
        See Also:
        Promise.State.RESOLVED
      • isRejected

        boolean isRejected()
        Queries the state of this promise, returning true iff it is State.REJECTED.
        Returns:
        true if the current state of this promise is State.REJECTED, false otherwise.
        See Also:
        Promise.State.REJECTED
      • filter

        <D_OUT> Promise<D_OUT,​F,​P> filter​(DoneFilter<? super D,​? extends D_OUT> doneFilter)
        Equivalent to filter(doneFilter, null, null)
        Parameters:
        doneFilter - the filter to execute when a result is available
        Returns:
        a new promise for the filtered result
        See Also:
        filter(DoneFilter, FailFilter, ProgressFilter)
      • filter

        <D_OUT,​F_OUT> Promise<D_OUT,​F_OUT,​P> filter​(DoneFilter<? super D,​? extends D_OUT> doneFilter,
                                                                      FailFilter<? super F,​? extends F_OUT> failFilter)
        Equivalent to filter(doneFilter, failFilter, null)
        Parameters:
        doneFilter - the filter to execute when a result is available
        failFilter - the filter to execute when a failure is available
        Returns:
        a new promise for the filtered result and failure.
        See Also:
        filter(DoneFilter, FailFilter, ProgressFilter)
      • filter

        <D_OUT,​F_OUT,​P_OUT> Promise<D_OUT,​F_OUT,​P_OUT> filter​(DoneFilter<? super D,​? extends D_OUT> doneFilter,
                                                                                      FailFilter<? super F,​? extends F_OUT> failFilter,
                                                                                      ProgressFilter<? super P,​? extends P_OUT> progressFilter)
        This method will register filters such that when a Deferred object is either resolved (Deferred.resolve(Object)), rejected (Deferred.reject(Object)) or is notified of progress (Deferred.notify(Object)), the corresponding filter will be invoked. The result of the filter will be used to invoke the same action on the returned promise. DoneFilter and FailFilter will be triggered at the time the Deferred object is resolved or rejected. If the Deferred object is already resolved or rejected the filter is triggered immediately. Filters allow to transform the outcome of a promise into something else. This concept is equivalent to the map() method of the java stream API. If any of the filter is not specified (null), a default No Op filter is used. If your filter is returning a Promise consider using pipe(DonePipe, FailPipe, ProgressPipe).
         
         Deferred deferred = new DeferredObject();
         Promise promise = deferred.promise();
         Promise filtered = promise.filter(new DoneFilter() {
           Integer filterDone(Integer result) {
             return result * 10;
           }
         });
        
         filtered.then(new DoneCallback() {
           void onDone(Integer result) {
             System.out.println(result);
           }
         });
        
         deferred.resolve(1); // prints 10
         
         
        Parameters:
        doneFilter - the filter to execute when a result is available. If null, use FilteredPromise.NoOpDoneFilter
        failFilter - the filter to execute when a failure is available. If null, use FilteredPromise.NoOpFailFilter
        progressFilter - the filter to execute when progress info is available. If null, use FilteredPromise.NoOpProgressFilter
        Returns:
        a new promise for the filtered result, failure and progress.
      • pipe

        <D_OUT> Promise<D_OUT,​F,​P> pipe​(DonePipe<? super D,​? extends D_OUT,​? extends F,​? extends P> donePipe)
        Equivalent to {#code pipe(DonePipe, null, null)}
        Parameters:
        donePipe - the pipe to invoke when a result is available
        Returns:
        a new promise for the piped result.
        See Also:
        pipe(DonePipe, FailPipe, ProgressPipe)
      • pipe

        <D_OUT,​F_OUT> Promise<D_OUT,​F_OUT,​P> pipe​(DonePipe<? super D,​? extends D_OUT,​? extends F_OUT,​? extends P> donePipe,
                                                                    FailPipe<? super F,​? extends D_OUT,​? extends F_OUT,​? extends P> failPipe)
        Equivalent to pipe(DonePipe, FailPipe, null)
        Parameters:
        donePipe - the pipe to invoke when a result is available
        failPipe - the pipe to invoke when a failure is available
        Returns:
        a new promise for the piped result and failure.
        See Also:
        pipe(DonePipe, FailPipe, ProgressPipe)
      • pipe

        <D_OUT,​F_OUT,​P_OUT> Promise<D_OUT,​F_OUT,​P_OUT> pipe​(DonePipe<? super D,​? extends D_OUT,​? extends F_OUT,​? extends P_OUT> donePipe,
                                                                                    FailPipe<? super F,​? extends D_OUT,​? extends F_OUT,​? extends P_OUT> failPipe,
                                                                                    ProgressPipe<? super P,​? extends D_OUT,​? extends F_OUT,​? extends P_OUT> progressPipe)
        This method will register pipes such that when a Deferred object is either resolved (Deferred.resolve(Object)), rejected (Deferred.reject(Object)) or is notified of progress (Deferred.notify(Object)), the corresponding pipe will be invoked. DonePipe and FailPipe will be triggered at the time the Deferred object is resolved or rejected. If the Deferred object is already resolved or rejected the filter is triggered immediately. This method is similar to JQuery's pipe() method, where a new Promise is returned by the the pipe filter instead of the original. This is useful to handle return values and then rewiring it to different callbacks. Pipes start a new Deferred object. This allows to chain asynchronous calls. If your pipe does not do any asynchronous work consider using filter(DoneFilter, FailFilter, ProgressFilter)
         
         promise.pipe(new DonePipe() {
           @Override
           Deferred pipeDone(Integer result) {
             // Reject values greater than 100
             if (result > 100) {
               return new DeferredObject().reject("Failed");
             } else {
               return new DeferredObject().resolve(result);
             }
           }
         }).done(...)
         .fail(...);
         
         
        Parameters:
        donePipe - the pipe to invoke when a result is available. If null, result is piped unchanged
        failPipe - the pipe to invoke when a failure is available. If null, failure is piped unchanged
        progressPipe - the pipe to execute when progress info is available. If null, progress is piped unchanged
        Returns:
        a new promise for the piped result, failure and progress.
      • pipeAlways

        <D_OUT,​F_OUT> Promise<D_OUT,​F_OUT,​P> pipeAlways​(AlwaysPipe<? super D,​? super F,​? extends D_OUT,​? extends F_OUT,​? extends P> alwaysPipe)
        This method will register a pipe such that when a Deferred object is either resolved (Deferred.resolve(Object)) or rejected (Deferred.reject(Object)) the pipe will be invoked. AlwaysPipe will be triggered at the time the Deferred object is resolved or rejected. If the Deferred object is already resolved or rejected the filter is triggered immediately. This method is similar to JQuery's pipe() method, where a new Promise is returned by the the pipe filter instead of the original. This is useful to handle return values and then rewiring it to different callbacks. Pipes start a new Deferred object. This allows to chain asynchronous calls.
         
         promise.pipeAlways(new pipe() {
           @Override
           Promise pipeAlways(State state, Integer resolved, Integer rejected) {
             if (state == State.RESOLVED) {
               return new DeferredObject().resolve("Success");
             } else {
               return new DeferredObject().reject("Failed");
             }
           }
         }).done(...)
         .fail(...);
         
         
        Parameters:
        alwaysPipe - the pipe to invoke when a result or failure is available.
        Returns:
        a new promise for the piped result or failure.
        Since:
        2.0
      • done

        Promise<D,​F,​P> done​(DoneCallback<? super D> callback)
        This method will register DoneCallback so that when a Deferred object is resolved (Deferred.resolve(Object)), DoneCallback will be triggered. If the Deferred object is already resolved then the DoneCallback is triggered immediately. You can register multiple DoneCallback by calling the method multiple times. The order of callback trigger is based on the order they have been registered.
         
         promise.progress(new DoneCallback(){
           public void onDone(Object done) {
             ...
           }
         });
         
         
        Parameters:
        callback - the callback to be triggered
        Returns:
        this for chaining more calls
        See Also:
        Deferred.resolve(Object)
      • fail

        Promise<D,​F,​P> fail​(FailCallback<? super F> callback)
        This method will register FailCallback so that when a Deferred object is rejected (Deferred.reject(Object)), FailCallback will be triggered. If the Deferred object is already rejected then the FailCallback is triggered immediately. You can register multiple FailCallback by calling the method multiple times. The order of callback trigger is based on the order they have been registered.
         
         promise.fail(new FailCallback(){
           public void onFail(Object rejection) {
             ...
           }
         });
         
         
        Parameters:
        callback - the callback to be triggered
        Returns:
        this for chaining more calls
        See Also:
        Deferred.reject(Object)
      • progress

        Promise<D,​F,​P> progress​(ProgressCallback<? super P> callback)
        This method will register ProgressCallback so that when a Deferred object is notified of progress (Deferred.notify(Object)), ProgressCallback will be triggered. You can register multiple ProgressCallback by calling the method multiple times. The order of callback trigger is based on the order they have been registered.
         
         promise.progress(new ProgressCallback(){
           public void onProgress(Object progress) {
             // e.g., update progress in the GUI while the background task is still running.
           }
         });
         
         
        Parameters:
        callback - the callback to be triggered
        Returns:
        this for chaining more calls
        See Also:
        Deferred.notify(Object)
      • waitSafely

        void waitSafely()
                 throws java.lang.InterruptedException
        This method will wait as long as the State is Pending. This method will return fast when State is not Pending.
        Throws:
        java.lang.InterruptedException - if thread is interrupted while waiting
      • waitSafely

        void waitSafely​(long timeout)
                 throws java.lang.InterruptedException
        This method will wait when the State is Pending, and return when timeout has reached. This method will return fast when State is not Pending.
        Parameters:
        timeout - the maximum time to wait in milliseconds
        Throws:
        java.lang.InterruptedException - if thread is interrupted while waiting