org.osgi.util.promise

Class PromiseFactory

java.lang.Object

org.osgi.util.promise.PromiseFactory

@ConsumerType
public class PromiseFactory
extends Object

Promise factory to create Deferred and Promise objects.

Instances of this class can be used to create Deferred and Promise objects which use the executors used to construct this object for any callback or scheduled operation execution.

Since:

1.1

"Immutable"

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PromiseFactory.Option Defines the options for a Promise factory.

Constructor Summary

Constructors

Constructor and Description
PromiseFactory(Executor callbackExecutor) Create a new PromiseFactory with the specified callback executor.
PromiseFactory(Executor callbackExecutor, ScheduledExecutorService scheduledExecutor) Create a new PromiseFactory with the specified callback executor and specified scheduled executor.
PromiseFactory(Executor callbackExecutor, ScheduledExecutorService scheduledExecutor, PromiseFactory.Option... options) Create a new PromiseFactory with the specified callback executor, specified scheduled executor, and specified options.

Method Summary

Modifier and Type	Method and Description
<T,S extends T> Promise<List<T>>	all(Collection<Promise<S>> promises) Returns a new Promise that is a latch on the resolution of the specified Promises.
<T> Deferred<T>	deferred() Create a new Deferred with the callback executor and scheduled executor of this PromiseFactory object.
Executor	executor() Returns the executor to use for callbacks.
<T> Promise<T>	failed(Throwable failure) Returns a new Promise that has been resolved with the specified failure.
static Executor	inlineExecutor() Returns an Executor implementation that executes tasks immediately on the thread calling the Executor.execute method.
<T> Promise<T>	resolved(T value) Returns a new Promise that has been resolved with the specified value.
<T> Promise<T>	resolvedWith(CompletionStage<? extends T> with) Returns a new Promise that will be resolved with the result of the specified CompletionStage.
<T> Promise<T>	resolvedWith(Promise<? extends T> with) Returns a new Promise that will be resolved with the specified Promise.
ScheduledExecutorService	scheduledExecutor() Returns the scheduled executor to use for scheduled operations.
<T> Promise<T>	submit(Callable<? extends T> task) Returns a new Promise that will hold the result of the specified task.
<T,S extends T> Collector<Promise<S>,?,Promise<List<T>>>	toPromise() Returns a Collector that accumulates the results of the input Promises into a new all(Collection) Promise.

Methods inherited from class java.lang.Object

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

Constructor Detail

PromiseFactory

public PromiseFactory(Executor callbackExecutor)

Create a new PromiseFactory with the specified callback executor.

The default scheduled executor and default options will be used.

Parameters:

callbackExecutor - The executor to use for callbacks. null can be specified for the default callback executor.

PromiseFactory

public PromiseFactory(Executor callbackExecutor,
                      ScheduledExecutorService scheduledExecutor)

Create a new PromiseFactory with the specified callback executor and specified scheduled executor.

The default options will be used.

Parameters:

callbackExecutor - The executor to use for callbacks. null can be specified for the default callback executor.

scheduledExecutor - The scheduled executor for use for scheduled operations. null can be specified for the default scheduled executor.

PromiseFactory

public PromiseFactory(Executor callbackExecutor,
                      ScheduledExecutorService scheduledExecutor,
                      PromiseFactory.Option... options)

Create a new PromiseFactory with the specified callback executor, specified scheduled executor, and specified options.

Parameters:

callbackExecutor - The executor to use for callbacks. null can be specified for the default callback executor.

scheduledExecutor - The scheduled executor for use for scheduled operations. null can be specified for the default scheduled executor.

options - Options for PromiseFactory.

Since:

1.2

Method Detail

executor

public Executor executor()

Returns the executor to use for callbacks.

Returns:

The executor to use for callbacks. This will be the default callback executor if null was specified for the callback executor when this PromiseFactory was created.

scheduledExecutor

public ScheduledExecutorService scheduledExecutor()

Returns the scheduled executor to use for scheduled operations.

Returns:

The scheduled executor to use for scheduled operations. This will be the default scheduled executor if null was specified for the scheduled executor when this PromiseFactory was created.

deferred

public <T> Deferred<T> deferred()

Create a new Deferred with the callback executor and scheduled executor of this PromiseFactory object.

Use this method instead of Deferred() to create a new Deferred whose associated Promise uses executors other than the default executors.

Type Parameters:

T - The value type associated with the returned Deferred.

Returns:

A new Deferred with the callback and scheduled executors of this PromiseFactory object

resolved

public <T> Promise<T> resolved(T value)

Returns a new Promise that has been resolved with the specified value.

The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object.

Use this method instead of Promises.resolved(Object) to create a Promise which uses executors other than the default executors.

Type Parameters:

T - The value type associated with the returned Promise.

Parameters:

value - The value of the resolved Promise.

Returns:

A new Promise that has been resolved with the specified value.

failed

public <T> Promise<T> failed(Throwable failure)

Returns a new Promise that has been resolved with the specified failure.

The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object.

Use this method instead of Promises.failed(Throwable) to create a Promise which uses executors other than the default executors.

Type Parameters:

T - The value type associated with the returned Promise.

Parameters:

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

Returns:

A new Promise that has been resolved with the specified failure.

submit

public <T> Promise<T> submit(Callable<? extends T> task)

Returns a new Promise that will hold the result of the specified task.

The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object.

The specified task will be executed on the callback executor.

Type Parameters:

T - The value type associated with the returned Promise.

Parameters:

task - The task whose result will be available from the returned Promise.

Returns:

A new Promise that will hold the result of the specified task.

all

public <T,S extends T> Promise<List<T>> all(Collection<Promise<S>> promises)

Returns a new Promise that is a latch on the resolution of the specified Promises.

The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object.

The returned Promise acts as a gate and must be resolved after all of the specified Promises are resolved.

Type Parameters:

T - The value type of the List value associated with the returned Promise.

S - The value type of the specified Promises.

Parameters:

promises - The Promises which must be resolved before the returned Promise must be resolved. Must not be null and all of the elements in the collection must not be null.

Returns:

A Promise that must be successfully resolved with a List of the values in the order of the specified Promises if all the specified Promises are successfully resolved. The List in the returned Promise is the property of the caller and is modifiable. The returned Promise must be resolved with a failure of FailedPromisesException if any of the specified Promises are resolved with a failure. The failure FailedPromisesException must contain all of the specified Promises which resolved with a failure.

inlineExecutor

public static Executor inlineExecutor()

Returns an Executor implementation that executes tasks immediately on the thread calling the Executor.execute method.

Returns:

An Executor implementation that executes tasks immediately on the thread calling the Executor.execute method.

resolvedWith

public <T> Promise<T> resolvedWith(CompletionStage<? extends T> with)

Returns a new Promise that will be resolved with the result of the specified CompletionStage.

The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object.

If the specified CompletionStage is completed normally, the returned Promise is resolved with the value of the specified CompletionStage. If the specified CompletionStage is completed exceptionally, the returned Promise is resolved with the exception of the specified CompletionStage.

After the returned 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 returned 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.

Type Parameters:

T - The value type associated with the returned Promise.

Parameters:

with - A CompletionStage whose result will be used to resolve the returned Promise. Must not be null.

Returns:

A new Promise that will be resolved with the result of the specified CompletionStage.

Since:

1.2

resolvedWith

public <T> Promise<T> resolvedWith(Promise<? extends T> with)

Returns a new Promise that will be resolved with the specified Promise.

The returned Promise uses the callback executor and scheduled executor of this PromiseFactory object.

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

After the returned 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 returned 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.

Type Parameters:

T - The value type associated with the returned Promise.

Parameters:

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

Returns:

A new Promise that is resolved with the specified Promise.

Since:

1.2

toPromise

public <T,S extends T> Collector<Promise<S>,?,Promise<List<T>>> toPromise()

Returns a Collector that accumulates the results of the input Promises into a new all(Collection) Promise.

Type Parameters:

T - The value type of the List value result of the collected all(Collection) Promise.

S - The value type of the input Promises.

Returns:

A Collector which accumulates the results of all the input Promises into a new all(Collection) Promise.

Since:

1.2