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 correspondingDeferred
object. A promise object should be obtained from {@link Deferred#promise()), or by using DeferredManager.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");
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Promise.State
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Promise<D,F,P>
always(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.Promise<D,F,P>
done(DoneCallback<? super D> callback)
This method will registerDoneCallback
so that when a Deferred object is resolved (Deferred.resolve(Object)
),DoneCallback
will be triggered.Promise<D,F,P>
fail(FailCallback<? super F> callback)
This method will registerFailCallback
so that when a Deferred object is rejected (Deferred.reject(Object)
),FailCallback
will be triggered.<D_OUT> Promise<D_OUT,F,P>
filter(DoneFilter<? super D,? extends D_OUT> doneFilter)
Equivalent tofilter(doneFilter, null, null)
<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 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
isPending()
Queries the state of this promise, returningtrue
iff it isState.PENDING
.boolean
isRejected()
Queries the state of this promise, returningtrue
iff it isState.REJECTED
.boolean
isResolved()
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.<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 topipe(DonePipe, FailPipe, null)
<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)}<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.Promise<D,F,P>
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.Promise.State
state()
Promise<D,F,P>
then(DoneCallback<? super D> doneCallback)
Equivalent todone(DoneCallback)
Promise<D,F,P>
then(DoneCallback<? super D> doneCallback, FailCallback<? super F> failCallback)
Equivalent todone(DoneCallback)
.fail(FailCallback)
Promise<D,F,P>
then(DoneCallback<? super D> doneCallback, FailCallback<? super F> failCallback, ProgressCallback<? super P> progressCallback)
void
waitSafely()
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 Detail
-
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:
Promise.State.PENDING
-
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:
Promise.State.RESOLVED
-
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:
Promise.State.REJECTED
-
then
Promise<D,F,P> then(DoneCallback<? super D> doneCallback)
Equivalent todone(DoneCallback)
- Parameters:
doneCallback
- seedone(DoneCallback)
- Returns:
this
for chaining more calls
-
then
Promise<D,F,P> then(DoneCallback<? super D> doneCallback, FailCallback<? super F> failCallback)
Equivalent todone(DoneCallback)
.fail(FailCallback)
- Parameters:
doneCallback
- seedone(DoneCallback)
failCallback
- seefail(FailCallback)
- Returns:
this
for chaining more calls
-
then
Promise<D,F,P> then(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
<D_OUT> Promise<D_OUT,F,P> filter(DoneFilter<? super D,? extends D_OUT> doneFilter)
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(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 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(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
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 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. 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,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 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(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
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 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. 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,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 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 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 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:
Deferred.resolve(Object)
-
fail
Promise<D,F,P> fail(FailCallback<? super F> callback)
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:
Deferred.reject(Object)
-
always
Promise<D,F,P> always(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. 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:
Deferred.resolve(Object)
,Deferred.reject(Object)
-
progress
Promise<D,F,P> 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. 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:
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
-
-