Package org.jdeferred2
Interface Promise<D,F,P>
- Type Parameters:
D
- Type used fordone(DoneCallback)
F
- Type used forfail(FailCallback)
P
- Type used forprogress(ProgressCallback)
- All Known Subinterfaces:
Deferred<D,
F, P>
- All Known Implementing Classes:
AbstractMasterDeferredObject
,AbstractPromise
,AllValuesDeferredObject
,DeferredObject
,DeferredPromise
,DelegatingPromise
,FilteredPromise
,MasterDeferredObject2
,MasterDeferredObject3
,MasterDeferredObject4
,MasterDeferredObject5
,MasterDeferredObjectN
,MasterDeferredObjectUntypedN
,PipedPromise
,SingleDeferredObject
public interface Promise<D,F,P>
Promise interface to observe when some action has occurred on the corresponding
Deferred
object.
A promise object should be obtained from invalid input: '{@link Deferred#promise()), or
by using DeferredManager.
<pre>
<code>
Deferred deferredObject = new DeferredObject();
Promise promise = deferredObject.promise();
promise.done(new' DoneCallback() {
public void onDone(Object result) {
// Done!
}
});
// another thread using the same deferredObject
deferredObject.resolve("OK");
- See Also:
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptionalways
(AlwaysCallback<? super D, ? super F> callback) This method will registerAlwaysCallback
so that when a Deferred object is either resolved (Deferred.resolve(Object)
) or rejected (Deferred.reject(Object)
),AlwaysCallback
will be triggered.done
(DoneCallback<? super D> callback) This method will registerDoneCallback
so that when a Deferred object is resolved (Deferred.resolve(Object)
),DoneCallback
will be triggered.fail
(FailCallback<? super F> callback) This method will registerFailCallback
so that when a Deferred object is rejected (Deferred.reject(Object)
),FailCallback
will be triggered.filter
(DoneFilter<? super D, ? extends D_OUT> doneFilter) Equivalent tofilter(doneFilter, null, null)
filter
(DoneFilter<? super D, ? extends D_OUT> doneFilter, FailFilter<? super F, ? extends F_OUT> failFilter) Equivalent tofilter(doneFilter, failFilter, null)
<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.boolean
Queries the state of this promise, returningtrue
iff it isState.PENDING
.boolean
Queries the state of this promise, returningtrue
iff it isState.REJECTED
.boolean
Queries the state of this promise, returningtrue
iff it isState.RESOLVED
.<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.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 topipe(DonePipe, FailPipe, null)
Equivalent to {#code pipe(DonePipe, null, null)}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.progress
(ProgressCallback<? super P> callback) This method will registerProgressCallback
so that when a Deferred object is notified of progress (Deferred.notify(Object)
),ProgressCallback
will be triggered.state()
then
(DoneCallback<? super D> doneCallback) Equivalent todone(DoneCallback)
then
(DoneCallback<? super D> doneCallback, FailCallback<? super F> failCallback) Equivalent todone(DoneCallback)
.fail(FailCallback)
then
(DoneCallback<? super D> doneCallback, FailCallback<? super F> failCallback, ProgressCallback<? super P> progressCallback) void
This method will wait as long as the State is Pending.void
waitSafely
(long timeout) This method will wait when the State is Pending, and return when timeout has reached.
-
Method Details
-
state
Promise.State state()- Returns:
- the state of this promise.
-
isPending
boolean isPending()Queries the state of this promise, returningtrue
iff it isState.PENDING
.- Returns:
true
if the current state of this promise isState.PENDING
,false
otherwise.- See Also:
-
isResolved
boolean isResolved()Queries the state of this promise, returningtrue
iff it isState.RESOLVED
.- Returns:
true
if the current state of this promise isState.RESOLVED
,false
otherwise.- See Also:
-
isRejected
boolean isRejected()Queries the state of this promise, returningtrue
iff it isState.REJECTED
.- Returns:
true
if the current state of this promise isState.REJECTED
,false
otherwise.- See Also:
-
then
Equivalent todone(DoneCallback)
- Parameters:
doneCallback
- seedone(DoneCallback)
- Returns:
this
for chaining more calls
-
then
Equivalent todone(DoneCallback)
.fail(FailCallback)
- Parameters:
doneCallback
- seedone(DoneCallback)
failCallback
- seefail(FailCallback)
- Returns:
this
for chaining more calls
-
then
Promise<D,F, thenP> (DoneCallback<? super D> doneCallback, FailCallback<? super F> failCallback, ProgressCallback<? super P> progressCallback) - Parameters:
doneCallback
- seedone(DoneCallback)
failCallback
- seefail(FailCallback)
progressCallback
- seeprogress(ProgressCallback)
- Returns:
this
for chaining more calls
-
filter
Equivalent tofilter(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
<D_OUT,F_OUT> Promise<D_OUT,F_OUT, filterP> (DoneFilter<? super D, ? extends D_OUT> doneFilter, FailFilter<? super F, ? extends F_OUT> failFilter) Equivalent tofilter(doneFilter, failFilter, null)
- Parameters:
doneFilter
- the filter to execute when a result is availablefailFilter
- the filter to execute when a failure is available- Returns:
- a new promise for the filtered result and failure.
- See Also:
-
filter
<D_OUT,F_OUT, Promise<D_OUT,P_OUT> F_OUT, filterP_OUT> (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
andFailFilter
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 aPromise
consider usingpipe(DonePipe, FailPipe, ProgressPipe)
.Deferred deferred = new DeferredObject(); Promise promise = deferred.promise(); Promise filtered = promise.filter(new DoneFilterinvalid input: '<'Integer, Integer>() { 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. Ifnull
, useFilteredPromise.NoOpDoneFilter
failFilter
- the filter to execute when a failure is available. Ifnull
, useFilteredPromise.NoOpFailFilter
progressFilter
- the filter to execute when progress info is available. Ifnull
, useFilteredPromise.NoOpProgressFilter
- Returns:
- a new promise for the filtered result, failure and progress.
-
pipe
<D_OUT> Promise<D_OUT,F, pipeP> (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
<D_OUT,F_OUT> Promise<D_OUT,F_OUT, pipeP> (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 topipe(DonePipe, FailPipe, null)
- Parameters:
donePipe
- the pipe to invoke when a result is availablefailPipe
- the pipe to invoke when a failure is available- Returns:
- a new promise for the piped result and failure.
- See Also:
-
pipe
<D_OUT,F_OUT, Promise<D_OUT,P_OUT> F_OUT, pipeP_OUT> (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
andFailPipe
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 newPromise
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 newDeferred
object. This allows to chain asynchronous calls. If your pipe does not do any asynchronous work consider usingfilter(DoneFilter, FailFilter, ProgressFilter)
promise.pipe(new DonePipeinvalid input: '<'Integer, Integer, String, Void>() { @Override Deferredinvalid input: '<'Integer, Void, Void> pipeDone(Integer result) { // Reject values greater than 100 if (result > 100) { return new DeferredObjectinvalid input: '<'Integer, Void, Void>().reject("Failed"); } else { return new DeferredObjectinvalid input: '<'Integer, Void, Void>().resolve(result); } } }).done(...) .fail(...);
- Parameters:
donePipe
- the pipe to invoke when a result is available. Ifnull
, result is piped unchangedfailPipe
- the pipe to invoke when a failure is available. Ifnull
, failure is piped unchangedprogressPipe
- the pipe to execute when progress info is available. Ifnull
, 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, pipeAlwaysP> (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 newPromise
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 newDeferred
object. This allows to chain asynchronous calls.promise.pipeAlways(new pipeinvalid input: '<'Integer, Integer, String, String, Void>() { @Override Promiseinvalid input: '<'Integer, Void, Void> pipeAlways(State state, Integer resolved, Integer rejected) { if (state == State.RESOLVED) { return new DeferredObjectinvalid input: '<'String, String, Void>().resolve("Success"); } else { return new DeferredObjectinvalid input: '<'String, String, Void>().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
This method will registerDoneCallback
so that when a Deferred object is resolved (Deferred.resolve(Object)
),DoneCallback
will be triggered. If the Deferred object is already resolved then theDoneCallback
is triggered immediately. You can register multipleDoneCallback
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:
-
fail
This method will registerFailCallback
so that when a Deferred object is rejected (Deferred.reject(Object)
),FailCallback
will be triggered. If the Deferred object is already rejected then theFailCallback
is triggered immediately. You can register multipleFailCallback
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:
-
always
This method will registerAlwaysCallback
so that when a Deferred object is either resolved (Deferred.resolve(Object)
) or rejected (Deferred.reject(Object)
),AlwaysCallback
will be triggered. If the Deferred object is already resolved or rejected then theAlwaysCallback
is triggered immediately. You can register multipleAlwaysCallback
by calling the method multiple times. The order of callback trigger is based on the order they have been registered.AlwaysCallback
s are triggered after anyDoneCallback
orFailCallback
respectively.promise.always(new AlwaysCallback(){ public void onAlways(State state, Object result, Object rejection) { if (state == State.RESOLVED) { // do something with result } else { // do something with rejection } } });
- Parameters:
callback
- the callback to be triggered- Returns:
this
for chaining more calls- See Also:
-
progress
This method will registerProgressCallback
so that when a Deferred object is notified of progress (Deferred.notify(Object)
),ProgressCallback
will be triggered. You can register multipleProgressCallback
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:
-
waitSafely
This method will wait as long as the State is Pending. This method will return fast when State is not Pending.- Throws:
InterruptedException
- if thread is interrupted while waiting
-
waitSafely
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:
InterruptedException
- if thread is interrupted while waiting
-