org.jdeferred.Deferred Maven / Gradle / Ivy
/*
* 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;
import org.jdeferred.impl.DeferredObject;
/**
* Deferred interface to trigger an event (resolve, reject, notify).
* Subsequently, this will allow Promise observers to listen in on the event
* (done, fail, progress).
*
* @see DeferredObject
* @author Ray Tsang
*
* @param
* Type used for {@link #resolve(Object)}
* @param
* Type used for {@link #reject(Object)}
* @param
* Type used for {@link #notify(Object)}
*/
public interface Deferred extends Promise {
/**
* This should be called when a task has completed successfully.
*
*
*
* {@link Deferred} deferredObject = new {@link DeferredObject}();
* {@link Promise} promise = deferredObject.promise();
* promise.done(new {@link DoneCallback}() {
* public void onDone(Object result) {
* // Done!
* }
* });
*
* // another thread using the same deferredObject
* deferredObject.resolve("OK");
*
*
*
*
* @param resolve
* @return
*/
Deferred resolve(final D resolve);
/**
* This should be called when a task has completed unsuccessfully,
* i.e., a failure may have occurred.
*
*
*
* {@link Deferred} deferredObject = new {@link DeferredObject}();
* {@link Promise} promise = deferredObject.promise();
* promise.fail(new {@link FailCallback}() {
* public void onFail(Object result) {
* // Failed :(
* }
* });
*
* // another thread using the same deferredObject
* deferredObject.reject("BAD");
*
*
*
*
* @param resolve
* @return
*/
Deferred reject(final F reject);
/**
* This should be called when a task is still executing and progress had been made,
* E.g., during a file download, notify the download progress.
*
*
*
* {@link Deferred} deferredObject = new {@link DeferredObject}();
* {@link Promise} promise = deferredObject.promise();
* promise.progress(new {@link ProgressCallback}() {
* public void onProgress(Object progress) {
* // Failed :(
* }
* });
*
* // another thread using the same deferredObject
* deferredObject.reject("100%");
*
*
*
*
* @param resolve
* @return
*/
Deferred notify(final P progress);
/**
* Return an {@link Promise} instance (i.e., an observer). You can register callbacks in this observer.
*
* @return
*/
Promise promise();
}