Top Description Inners Fields Constructors Methods
org.osgi.util.promise

public Class PromiseFactory

extends Object
Class Inheritance
Annotations
@ConsumerType
Static Imports
java.util.Objects.requireNonNull, org.osgi.util.promise.PromiseImpl.uncaughtException

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.

Author
$Id: 9e941a7a33ba3a70cdb8821972dd2b69abbcd3f0 $
Since
1.1

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
PromiseFactory.All<T, S extends T>

A callback used to resolve the specified Promise when the specified list of Promises are resolved for the PromiseFactory#all(Collection) method.

private static class
PromiseFactory.DefaultExecutors

Default executors for Promises.

private static class
PromiseFactory.InlineExecutor

An Executor implementation which executes the task immediately on the thread calling the Executor.execute method.

public static enum
PromiseFactory.Option

Defines the options for a Promise factory.

Field Summary

Modifier and TypeField and Description
private final boolean
private final Executor
callbackExecutor

The executor to use for callbacks.

pack-priv static final PromiseFactory
defaultFactory

The default factory which uses the default callback executor and default scheduled executor.

private final ScheduledExecutorService
scheduledExecutor

The executor to use for scheduled operations.

Constructor Summary

AccessConstructor and Description
public
PromiseFactory(Executor
The executor to use for callbacks. null can be specified for the default callback executor.
callbackExecutor
)

Create a new PromiseFactory with the specified callback executor.

public
PromiseFactory(Executor
The executor to use for callbacks. null can be specified for the default callback executor.
callbackExecutor
,
ScheduledExecutorService
The scheduled executor for use for scheduled operations. null can be specified for the default scheduled executor.
scheduledExecutor
)

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

public
PromiseFactory(Executor
The executor to use for callbacks. null can be specified for the default callback executor.
callbackExecutor
,
ScheduledExecutorService
The scheduled executor for use for scheduled operations. null can be specified for the default scheduled executor.
scheduledExecutor
,
PromiseFactory.Option...
Options for PromiseFactory.
options
)

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

Method Summary

Modifier and TypeMethod and Description
public <
The value type of the List value associated with the returned Promise.
T
,
The value type of the specified Promises.
S extends T
>
Promise<List<T>>

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.
all
(Collection<Promise<S>>
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.
promises
)

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

pack-priv boolean
private static <E, C extends Collection<E>> C
combiner(C t, C u)

private static PromiseFactory.Option[]
public <
The value type associated with the returned Deferred.
T
>
Deferred<T>

Returns:

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

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

public Executor

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.
executor
()

Returns the executor to use for callbacks.

public <
The value type associated with the returned Promise.
T
>
Promise<T>

Returns:

A new Promise that has been resolved with the specified failure.
failed
(Throwable
The failure of the resolved Promise. Must not be null.
failure
)

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

public static Executor

Returns:

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

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

public <
The value type associated with the returned Promise.
T
>
Promise<T>

Returns:

A new Promise that has been resolved with the specified value.
resolved
(T
The value of the resolved Promise.
value
)

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

public <
The value type associated with the returned Promise.
T
>
Promise<T>

Returns:

A new Promise that will be resolved with the result of the specified CompletionStage.
resolvedWith
(CompletionStage<? extends T>
A CompletionStage whose result will be used to resolve the returned Promise. Must not be null.
with
)

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

public <
The value type associated with the returned Promise.
T
>
Promise<T>

Returns:

A new Promise that is resolved with the specified Promise.
resolvedWith
(Promise<? extends T>
A Promise whose value or failure must be used to resolve the returned Promise. Must not be null.
with
)

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

public ScheduledExecutorService

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.
scheduledExecutor
()

Returns the scheduled executor to use for scheduled operations.

public <
The value type associated with the returned Promise.
T
>
Promise<T>

Returns:

A new Promise that will hold the result of the specified task.
submit
(Callable<? extends T>
The task whose result will be available from the returned Promise.
task
)

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

public <
The value type of the List value result of the collected all(Collection) Promise.
T
,
The value type of the input Promises.
S extends T
>
Collector<Promise<S>, ?, Promise<List<T>>>

Returns:

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

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

allowCurrentThreadback to summary
private final boolean allowCurrentThread
callbackExecutorback to summary
private final Executor callbackExecutor

The executor to use for callbacks. If null, the default callback executor is used.

defaultFactoryback to summary
pack-priv static final PromiseFactory defaultFactory

The default factory which uses the default callback executor and default scheduled executor.

scheduledExecutorback to summary
private final ScheduledExecutorService scheduledExecutor

The executor to use for scheduled operations. If null, the default scheduled executor is used.

Constructor Detail

PromiseFactoryback to summary
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:Executor

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

PromiseFactoryback to summary
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:Executor

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

scheduledExecutor:ScheduledExecutorService

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

PromiseFactoryback to summary
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:Executor

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

scheduledExecutor:ScheduledExecutorService

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

options:PromiseFactory.Option[]

Options for PromiseFactory.

Since
1.2

Method Detail

allback to summary
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.

Parameters
<T>
The value type of the List value associated with the returned Promise.
<S>
The value type of the specified Promises.
promises:Collection<Promise<S>>

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:Promise<List<T>>

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.

allowCurrentThreadback to summary
pack-priv boolean allowCurrentThread()
combinerback to summary
private static <E, C extends Collection<E>> C combiner(C t, C u)
defaultOptionsback to summary
private static PromiseFactory.Option[] defaultOptions()
deferredback to summary
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#Deferred() to create a new Deferred whose associated Promise uses executors other than the default executors.

Parameters
<T>
The value type associated with the returned Deferred.
Returns:Deferred<T>

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

executorback to summary
public Executor executor()

Returns the executor to use for callbacks.

Returns:Executor

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.

failedback to summary
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.

Parameters
<T>
The value type associated with the returned Promise.
failure:Throwable

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

Returns:Promise<T>

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

inlineExecutorback to summary
public static Executor inlineExecutor()

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

Returns:Executor

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

resolvedback to summary
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.

Parameters
<T>
The value type associated with the returned Promise.
value:T

The value of the resolved Promise.

Returns:Promise<T>

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

resolvedWithback to summary
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.

Parameters
<T>
The value type associated with the returned Promise.
with:CompletionStage<? extends T>

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

Returns:Promise<T>

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

Since
1.2
resolvedWithback to summary
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.

Parameters
<T>
The value type associated with the returned Promise.
with:Promise<? extends T>

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

Returns:Promise<T>

A new Promise that is resolved with the specified Promise.

Since
1.2
scheduledExecutorback to summary
public ScheduledExecutorService scheduledExecutor()

Returns the scheduled executor to use for scheduled operations.

Returns:ScheduledExecutorService

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.

submitback to summary
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.

Parameters
<T>
The value type associated with the returned Promise.
task:Callable<? extends T>

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

Returns:Promise<T>

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

toPromiseback to summary
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.

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:Collector<Promise<S>, ?, Promise<List<T>>>

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

Since
1.2
org.osgi.util.promise back to summary

private final Class PromiseFactory.All<T, S extends T>

extends Object
implements Runnable, InlineCallback
Class Inheritance
All Implemented Interfaces
org.osgi.util.promise.PromiseImpl.InlineCallback, java.lang.Runnable

A callback used to resolve the specified Promise when the specified list of Promises are resolved for the PromiseFactory#all(Collection) method.

Field Summary

Modifier and TypeField and Description
private final DeferredPromiseImpl<List<T>>
private final AtomicInteger
private final List<Promise<S>>

Constructor Summary

AccessConstructor and Description
pack-priv
All(DeferredPromiseImpl<List<T>> chained, List<Promise<S>> promises)

Method Summary

Modifier and TypeMethod and Description
public void
run()

Implements java.lang.Runnable.run.

Runs this operation.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

chainedback to summary
private final DeferredPromiseImpl<List<T>> chained
promiseCountback to summary
private final AtomicInteger promiseCount
promisesback to summary
private final List<Promise<S>> promises

Constructor Detail

Allback to summary
pack-priv All(DeferredPromiseImpl<List<T>> chained, List<Promise<S>> promises)

Method Detail

runback to summary
public void run()

Implements java.lang.Runnable.run.

Doc from java.lang.Runnable.run.

Runs this operation.

Annotations
@Override
org.osgi.util.promise back to summary

private final Class PromiseFactory.DefaultExecutors

extends Object
implements ThreadFactory, RejectedExecutionHandler, Runnable
Class Inheritance
All Implemented Interfaces
java.lang.Runnable, java.util.concurrent.RejectedExecutionHandler, java.util.concurrent.ThreadFactory

Default executors for Promises.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
PromiseFactory.DefaultExecutors.ScheduledExecutor

ScheduledThreadPoolExecutor for scheduled execution.

Field Summary

Modifier and TypeField and Description
private static final ThreadPoolExecutor
private static final PromiseFactory.DefaultExecutors
private final ThreadFactory
private static final PromiseFactory.DefaultExecutors.ScheduledExecutor
private final AtomicBoolean

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
pack-priv static Executor
public Thread
newThread(Runnable
a runnable to be executed by new thread instance
r
)

Implements java.util.concurrent.ThreadFactory.newThread.

Executor threads should not prevent VM from exiting.

public void
rejectedExecution(Runnable
the runnable task requested to be executed
callback
,
ThreadPoolExecutor
the executor attempting to execute this task
executor
)

Implements java.util.concurrent.RejectedExecutionHandler.rejectedExecution.

Call the callback using the caller's thread because the thread pool rejected the execution.

public void
run()

Implements java.lang.Runnable.run.

Shutdown hook

pack-priv static ScheduledExecutorService
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

callbackExecutorback to summary
private static final ThreadPoolExecutor callbackExecutor
callbacksback to summary
private static final PromiseFactory.DefaultExecutors callbacks
delegateThreadFactoryback to summary
private final ThreadFactory delegateThreadFactory
scheduledExecutorback to summary
private static final PromiseFactory.DefaultExecutors.ScheduledExecutor scheduledExecutor
shutdownHookInstalledback to summary
private final AtomicBoolean shutdownHookInstalled

Constructor Detail

DefaultExecutorsback to summary
private DefaultExecutors()

Method Detail

callbackExecutorback to summary
pack-priv static Executor callbackExecutor()
newThreadback to summary
public Thread newThread(Runnable r)

Implements java.util.concurrent.ThreadFactory.newThread.

Executor threads should not prevent VM from exiting.

Parameters
r:Runnable

Doc from java.util.concurrent.ThreadFactory.newThread.

a runnable to be executed by new thread instance

Returns:Thread

Doc from java.util.concurrent.ThreadFactory.newThread.

constructed thread, or null if the request to create a thread is rejected

Annotations
@Override
rejectedExecutionback to summary
public void rejectedExecution(Runnable callback, ThreadPoolExecutor executor)

Implements java.util.concurrent.RejectedExecutionHandler.rejectedExecution.

Call the callback using the caller's thread because the thread pool rejected the execution.

Parameters
callback:Runnable

Doc from java.util.concurrent.RejectedExecutionHandler.rejectedExecution.

the runnable task requested to be executed

executor:ThreadPoolExecutor

Doc from java.util.concurrent.RejectedExecutionHandler.rejectedExecution.

the executor attempting to execute this task

Annotations
@Override
runback to summary
public void run()

Implements java.lang.Runnable.run.

Shutdown hook

Annotations
@Override
scheduledExecutorback to summary
pack-priv static ScheduledExecutorService scheduledExecutor()
org.osgi.util.promise back to summary

private final Class PromiseFactory.DefaultExecutors.ScheduledExecutor

extends ScheduledThreadPoolExecutor
Class Inheritance

ScheduledThreadPoolExecutor for scheduled execution.

Constructor Summary

AccessConstructor and Description
pack-priv
ScheduledExecutor(int corePoolSize, ThreadFactory threadFactory)

Constructor Detail

ScheduledExecutorback to summary
pack-priv ScheduledExecutor(int corePoolSize, ThreadFactory threadFactory)

Method Detail

afterExecuteback to summary
protected void afterExecute(Runnable r, Throwable t)

Overrides java.util.concurrent.ThreadPoolExecutor.afterExecute.

Handle uncaught exceptions

Parameters
r:Runnable

Doc from java.util.concurrent.ThreadPoolExecutor.afterExecute.

the runnable that has completed

t:Throwable

Doc from java.util.concurrent.ThreadPoolExecutor.afterExecute.

the exception that caused termination, or null if execution completed normally

Annotations
@Override
org.osgi.util.promise back to summary

private final Class PromiseFactory.InlineExecutor

extends Object
implements Executor
Class Inheritance
All Implemented Interfaces
java.util.concurrent.Executor

An Executor implementation which executes the task immediately on the thread calling the Executor.execute method.

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
public void
execute(Runnable
the runnable task
callback
)

Implements java.util.concurrent.Executor.execute.

Executes the given command at some time in the future.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

InlineExecutorback to summary
pack-priv InlineExecutor()

Method Detail

executeback to summary
public void execute(Runnable callback)

Implements java.util.concurrent.Executor.execute.

Doc from java.util.concurrent.Executor.execute.

Executes the given command at some time in the future. The command may execute in a new thread, in a pooled thread, or in the calling thread, at the discretion of the Executor implementation.

Parameters
callback:Runnable

the runnable task

Annotations
@Override
org.osgi.util.promise back to summary

public final Enum PromiseFactory.Option

extends Enum<PromiseFactory.Option>
Class Inheritance

Defines the options for a Promise factory.

The default options are no options unless the boolean system property org.osgi.util.promise.allowCurrentThread is set to false. When this is the case, the option Option#CALLBACKS_EXECUTOR_THREAD is a default option.

Since
1.2

Field Summary

Modifier and TypeField and Description
public static final PromiseFactory.Option
CALLBACKS_EXECUTOR_THREAD

Run callbacks on an executor thread.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static PromiseFactory.Option
public static PromiseFactory.Option[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

CALLBACKS_EXECUTOR_THREADback to summary
public static final PromiseFactory.Option CALLBACKS_EXECUTOR_THREAD

Run callbacks on an executor thread. If this option is not set, callbacks added to a resolved Promise may be immediately called on the caller's thread to avoid a thread context switch.

Constructor Detail

Optionback to summary
private Option()

Method Detail

valueOfback to summary
public static PromiseFactory.Option valueOf(String name)
valuesback to summary
public static PromiseFactory.Option[] values()