org.osgi.util.promise
Class Deferred<T>

java.lang.Object
  org.osgi.util.promise.Deferred<T>

Type Parameters:

T - The value type associated with the created Promise.

public class Deferred<T>
extends java.lang.Object

A Deferred Promise resolution.

Instances of this class can be used to create a Promise that can be resolved in the future. The associated Promise can be successfully resolved with resolve(Object) or resolved with a failure with fail(Throwable). It can also be resolved with the resolution of another promise using resolveWith(Promise).

The associated Promise can be provided to any one, but the Deferred object should be made available only to the party that will responsible for resolving the Promise.

Author:

$Id: e9ff0a6fa2189934a38d3cf210d5418f8cfaeac7 $

Immutable

Constructor Summary

Deferred()
Create a new Deferred with an associated Promise.

Method Summary

void	fail(java.lang.Throwable failure) Fail the Promise associated with this Deferred.
Promise<T>	getPromise() Returns the Promise associated with this Deferred.
void	resolve(T value) Successfully resolve the Promise associated with this Deferred.
Promise<java.lang.Void>	resolveWith(Promise<? extends T> with) Resolve the Promise associated with this Deferred with the specified Promise.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Deferred

public Deferred()

Create a new Deferred with an associated Promise.

Method Detail

getPromise

public Promise<T> getPromise()

Returns the Promise associated with this Deferred.

Returns:

The Promise associated with this Deferred.

resolve

public void resolve(T value)

Successfully resolve the Promise associated with this Deferred.

After the associated Promise is resolved with the specified value, all registered callbacks are called and any chained Promises are resolved.

Resolving the associated Promise happens-before any registered callback is called. That is, in a registered callback, Promise.isDone() must return true and Promise.getValue() and Promise.getFailure() must not block.

Parameters:

value - The value of the resolved Promise.

Throws:

java.lang.IllegalStateException - If the associated Promise was already resolved.

fail

public void fail(java.lang.Throwable failure)

Fail the Promise associated with this Deferred.

After the associated Promise is resolved with the specified failure, all registered callbacks are called and any chained Promises are resolved.

Resolving the associated Promise happens-before any registered callback is called. That is, in a registered callback, Promise.isDone() must return true and Promise.getValue() and Promise.getFailure() must not block.

Parameters:

failure - The failure of the resolved Promise. Must not be null.

Throws:

java.lang.IllegalStateException - If the associated Promise was already resolved.

resolveWith

public Promise<java.lang.Void> resolveWith(Promise<? extends T> with)

Resolve the Promise associated with this Deferred with the specified Promise.

If the specified Promise is successfully resolved, the associated Promise is resolved with the value of the specified Promise. If the specified Promise is resolved with a failure, the associated Promise is resolved with the failure of the specified Promise.

After the associated Promise is resolved with the specified Promise, all registered callbacks are called and any chained Promises are resolved.

Resolving the associated Promise happens-before any registered callback is called. That is, in a registered callback, Promise.isDone() must return true and Promise.getValue() and Promise.getFailure() must not block.

Parameters:

with - A Promise whose value or failure must be used to resolve the associated Promise. Must not be null.

Returns:

A Promise that is resolved only when the associated Promise is resolved by the specified Promise. The returned Promise must be successfully resolved with the value null, if the associated Promise was resolved by the specified Promise. The returned Promise must be resolved with a failure of IllegalStateException, if the associated Promise was already resolved when the specified Promise was resolved.