org.jdeferred.Promise Maven / Gradle / Ivy
Show all versions of jdeferred-core Show documentation
/*
* Copyright 2013 Ray Tsang
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jdeferred;
/**
* Promise interface to observe when some action has occurred on the corresponding {@link Deferred} 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");
*
*
*
*
* @see Deferred#resolve(Object)
* @see Deferred#reject(Object)
* @see Deferred#notify(Object)
*
* @author Ray Tsang
*
* @param
* Type used for {@link #done(DoneCallback)}
* @param
* Type used for {@link #fail(FailCallback)}
* @param
* Type used for {@link #progress(ProgressCallback)}
*/
public interface Promise {
public enum State {
/**
* The Promise is still pending - it could be created, submitted for execution,
* or currently running, but not yet finished.
*/
PENDING,
/**
* The Promise has finished running and a failure occurred.
* Thus, the Promise is rejected.
*
* @see Deferred#reject(Object)
*/
REJECTED,
/**
* The Promise has finished running successfully.
* Thus the Promise is resolved.
*
* @see Deferred#resolve(Object)
*/
RESOLVED
}
public State state();
/**
* @see State#PENDING
* @return
*/
public boolean isPending();
/**
* @see State#RESOLVED
* @return
*/
public boolean isResolved();
/**
* @see State#REJECTED
* @return
*/
public boolean isRejected();
/**
* Equivalent to {@link #done(DoneCallback)}
*
* @param doneCallback {@link #done(DoneCallback)}
* @return
*/
public Promise then(DoneCallback doneCallback);
/**
* Equivalent to {@link #done(DoneCallback)} and then {@link FailCallback}
* @param doneCallback {@link #done(DoneCallback)}
* @param failCallback {@link #fail(FailCallback)}
* @return
*/
public Promise then(DoneCallback doneCallback,
FailCallback failCallback);
/**
* Equivalent to {@link #done(DoneCallback)}, then {@link FailCallback}, then {@link #progress(ProgressCallback)}
*
* @param doneCallback {@link #done(DoneCallback)}
* @param failCallback {@link #fail(FailCallback)}
* @param progressCallback {@link #progress(ProgressCallback)}
* @return
*/
public Promise then(DoneCallback doneCallback,
FailCallback failCallback, ProgressCallback progressCallback);
/**
* Equivalent to then(doneFilter, null, null)
* @see {@link #then(DoneFilter, FailFilter, ProgressFilter)}
* @param doneFilter
* @return
*/
public Promise then(
DoneFilter doneFilter);
/**
* Equivalent to then(doneFilter, failFilter, null)
* @see {@link #then(DoneFilter, FailFilter, ProgressFilter)}
* @param doneFilter
* @param failFilter
* @return
*/
public Promise then(
DoneFilter doneFilter, FailFilter failFilter);
/**
* If any of the filter is not specified, a default No Op filter would be used.
* This is also known as "piping", or "chaining" of callbacks and being able to modify the return value.
*
*
*
* Deferred deferred = new DeferredObject();
* Promise promise = deferred.promise();
* Promise filtered = promise.then(new DoneFilter() {
* public Integer filterDone(Integer result) {
* return result * 10;
* }
* });
*
* filtered.then(new DoneCallback() {
* public void onDone(Integer result) {
* System.out.println(result);
* }
* });
*
* deferred.resolve(1); // prints 10
*
*
*
* @param doneFilter if null, use {@link NoOpDoneFilter}
* @param failFilter if null, use {@link NoOpFailFilter}
* @param progressFilter if null, use {@link NoOpProgressFilter}
* @return
*/
public Promise then(
DoneFilter doneFilter, FailFilter failFilter,
ProgressFilter progressFilter);
/**
* Equivalent to then(DonePipe, null, null)
*
* @param donePipe
* @return
*/
public Promise then(
DonePipe donePipe);
/**
* Equivalent to then(DonePipe, FailPipe, null)
*
* @param donePipe
* @param failPipe
* @return
*/
public Promise then(
DonePipe donePipe, FailPipe failPipe);
/**
* This method is similar to JQuery's pipe() method, where a new {@link 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.
*
*
*
* promise.then(new DonePipe() {
* @Override
* public 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(...);
*
*
*
* @param donePipe
* @param failPipe
* @param progressPipe
* @return
*/
public Promise then(
DonePipe donePipe, FailPipe failPipe,
ProgressPipe progressPipe);
/**
* This method will register {@link DoneCallback} so that when a Deferred object
* is resolved ({@link Deferred#resolve(Object)}), {@link DoneCallback} will be triggered.
*
* You can register multiple {@link DoneCallback} by calling the method multiple times.
* The order of callback trigger is based on the order you call this method.
*
*
*
* promise.progress(new DoneCallback(){
* public void onDone(Object done) {
* ...
* }
* });
*
*
*
* @see Deferred#resolve(Object)
* @param callback
* @return
*/
public Promise done(DoneCallback callback);
/**
* This method will register {@link FailCallback} so that when a Deferred object
* is rejected ({@link Deferred#reject(Object)}), {@link FailCallback} will be triggered.
*
* You can register multiple {@link FailCallback} by calling the method multiple times.
* The order of callback trigger is based on the order you call this method.
*
*
*
* promise.fail(new FaillCallback(){
* public void onFail(Object rejection) {
* ...
* }
* });
*
*
*
* @see Deferred#reject(Object)
* @param callback
* @return
*/
public Promise fail(FailCallback callback);
/**
* This method will register {@link AlwaysCallback} so that when it's always triggered
* regardless of whether the corresponding Deferred object was resolved or rejected.
*
* You can register multiple {@link AlwaysCallback} by calling the method multiple times.
* The order of callback trigger is based on the order you call this method.
*
*
*
* promise.always(new AlwaysCallback(){
* public void onAlways(State state, Object result, Object rejection) {
* if (state == State.RESOLVED) {
* // do something w/ result
* } else {
* // do something w/ rejection
* }
* }
* });
*
*
*
* @see Deferred#resolve(Object)
* @see Deferred#reject(Object)
* @param callback
* @return
*/
public Promise always(AlwaysCallback callback);
/**
* This method will register {@link ProgressCallback} so that when a Deferred object
* is notified of progress ({@link Deferred#notify(Object)}), {@link ProgressCallback} will be triggered.
*
* You can register multiple {@link ProgressCallback} by calling the method multiple times.
* The order of callback trigger is based on the order you call this method.
*
*
*
* promise.progress(new ProgressCallback(){
* public void onProgress(Object progress) {
* // e.g., update progress in the GUI while the background task is still running.
* }
* });
*
*
*
* @see Deferred#notify(Object)
* @param callback
* @return
*/
public Promise progress(ProgressCallback callback);
/**
* This method will wait as long as the State is Pending. This method will fail fast
* when State is not Pending.
*
* @throws InterruptedException
*/
public void waitSafely() throws InterruptedException;
/**
* This method will wait when the State is Pending, and return when timeout has reached.
* This method will fail fast when State is not Pending.
*
* @throws InterruptedException
*/
public void waitSafely(long timeout) throws InterruptedException;
}