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.

@ProviderType
public class Deferred<T>
extends 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.

"Immutable"

Constructor Summary

Constructors

Constructor and Description
Deferred() Create a new Deferred.

Method Summary

Modifier and Type	Method and Description
void	fail(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<Void>	resolveWith(CompletionStage<? extends T> with) Resolve the Promise associated with this Deferred with the specified CompletionStage.
Promise<Void>	resolveWith(Promise<? extends T> with) Resolve the Promise associated with this Deferred with the specified Promise.
String	toString() Returns a string representation of the associated Promise.

Methods inherited from class java.lang.Object

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

Constructor Detail

Deferred

public Deferred()

Create a new Deferred.

The associated promise will use the default callback executor and default scheduled executor.

See Also:

PromiseFactory.deferred()

Method Detail

getPromise

public Promise<T> getPromise()

Returns the Promise associated with this Deferred.

All Promise objects created by the associated Promise will use the executors of the associated Promise.

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. This may occur asynchronously to this method.

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:

IllegalStateException - If the associated Promise was already resolved.

fail

public void fail(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. This may occur asynchronously to this method.

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:

IllegalStateException - If the associated Promise was already resolved.

resolveWith

public Promise<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. This may occur asynchronously to this method.

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.

toString

public String toString()

Returns a string representation of the associated Promise.

Overrides:

toString in class Object

Returns:

A string representation of the associated Promise.

Since:

1.1

resolveWith

public Promise<Void> resolveWith(CompletionStage<? extends T> with)

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

If the specified CompletionStage is completed normally, the associated Promise is resolved with the value of the specified CompletionStage. If the specified CompletionStage is completed exceptionally, the associated Promise is resolved with the failure of the specified CompletionStage.

After the associated Promise is resolved with the specified CompletionStage, all registered callbacks are called and any chained Promises are resolved. This may occur asynchronously to this method.

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 CompletionStage whose result 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 CompletionStage. The returned Promise must be successfully resolved with the value null, if the associated Promise was resolved by the specified CompletionStage. The returned Promise must be resolved with a failure of IllegalStateException, if the associated Promise was already resolved when the specified CompletionStage was completed.

Since:

1.2