Modifier and Type | Class and Description |
---|---|
private static class |
PromiseImpl.Chain<R>
A callback used to resolve the chained Promise when the Promise promise
is resolved.
|
private static class |
PromiseImpl.FallbackTo<T>
A callback used by the
fallbackTo(Promise) method. |
private static class |
PromiseImpl.Filter<T>
A callback used by the
filter(Predicate) method. |
private static class |
PromiseImpl.FlatMap<T,R>
A callback used by the
flatMap(Function) method. |
private static class |
PromiseImpl.Logger
Use the lazy initialization holder class idiom to delay creating a Logger
until we actually need it.
|
private static class |
PromiseImpl.Map<T,R>
A callback used by the
map(Function) method. |
private static class |
PromiseImpl.Recover<T>
A callback used by the
recover(Function) method. |
private static class |
PromiseImpl.RecoverWith<T>
A callback used by the
recoverWith(Function) method. |
private class |
PromiseImpl.ResolveWith
A callback used to resolve this Promise with another Promise for the
resolveWith(Promise) method. |
private class |
PromiseImpl.Then<R>
A callback used to chain promises for the
then(Success, Failure)
method. |
Modifier and Type | Field and Description |
---|---|
private java.util.concurrent.ConcurrentLinkedQueue<java.lang.Runnable> |
callbacks
A ConcurrentLinkedQueue to hold the callbacks for this Promise, so no
additional synchronization is required to write to or read from the
queue.
|
private java.lang.Throwable |
fail
The failure of this Promise if resolved with a failure or
null if
successfully resolved. |
private java.util.concurrent.CountDownLatch |
resolved
A CountDownLatch to manage the resolved state of this Promise.
|
private T |
value
The value of this Promise if successfully resolved.
|
Constructor and Description |
---|
PromiseImpl()
Initialize this Promise.
|
PromiseImpl(T v,
java.lang.Throwable f)
Initialize and resolve this Promise.
|
Modifier and Type | Method and Description |
---|---|
Promise<T> |
fallbackTo(Promise<? extends T> fallback)
Fall back to the value of the specified Promise if this Promise fails.
|
Promise<T> |
filter(Predicate<? super T> predicate)
Filter the value of this Promise.
|
<R> Promise<R> |
flatMap(Function<? super T,Promise<? extends R>> mapper)
FlatMap the value of this Promise.
|
java.lang.Throwable |
getFailure()
Returns the failure of this Promise.
|
T |
getValue()
Returns the value of this Promise.
|
boolean |
isDone()
Returns whether this Promise has been resolved.
|
<R> Promise<R> |
map(Function<? super T,? extends R> mapper)
Map the value of this Promise.
|
private void |
notifyCallbacks()
Call any registered callbacks if this Promise is resolved.
|
Promise<T> |
onResolve(java.lang.Runnable callback)
Register a callback to be called when this Promise is resolved.
|
Promise<T> |
recover(Function<Promise<?>,? extends T> recovery)
Recover from a failure of this Promise with a recovery value.
|
Promise<T> |
recoverWith(Function<Promise<?>,Promise<? extends T>> recovery)
Recover from a failure of this Promise with a recovery Promise.
|
(package private) static <V> V |
requireNonNull(V value) |
(package private) void |
resolve(T v,
java.lang.Throwable f)
Resolve this Promise.
|
(package private) Promise<java.lang.Void> |
resolveWith(Promise<? extends T> with)
Resolve this Promise with the specified Promise.
|
<R> Promise<R> |
then(Success<? super T,? extends R> success)
Chain a new Promise to this Promise with a Success callback.
|
<R> Promise<R> |
then(Success<? super T,? extends R> success,
Failure failure)
Chain a new Promise to this Promise with Success and Failure callbacks.
|
private final java.util.concurrent.ConcurrentLinkedQueue<java.lang.Runnable> callbacks
private final java.util.concurrent.CountDownLatch resolved
This object is used as the synchronizing object to provide a critical
section in resolve(Object, Throwable)
so that only a single
thread can write the resolved state variables and open the latch.
The resolved state variables, value
and fail
, must only
be written when the latch is closed (getCount() != 0) and must only be
read when the latch is open (getCount() == 0). The latch state must
always be checked before writing or reading since the resolved state
variables' memory consistency is guarded by the latch.
private java.lang.Throwable fail
null
if
successfully resolved.resolved
PromiseImpl()
PromiseImpl(T v, java.lang.Throwable f)
v
- The value of this resolved Promise.f
- The failure of this resolved Promise.void resolve(T v, java.lang.Throwable f)
v
- The value of this Promise.f
- The failure of this Promise.private void notifyCallbacks()
public boolean isDone()
This Promise may be successfully resolved or resolved with a failure.
public T getValue() throws java.lang.reflect.InvocationTargetException, java.lang.InterruptedException
If this Promise is not resolved
, this method must block
and wait for this Promise to be resolved before completing.
If this Promise was successfully resolved, this method returns with the
value of this Promise. If this Promise was resolved with a failure, this
method must throw an InvocationTargetException
with the
failure exception
as the cause.
getValue
in interface Promise<T>
java.lang.reflect.InvocationTargetException
- If this Promise was resolved with a
failure. The cause of the InvocationTargetException
is
the failure exception.java.lang.InterruptedException
- If the current thread was interrupted while
waiting.public java.lang.Throwable getFailure() throws java.lang.InterruptedException
If this Promise is not resolved
, this method must block
and wait for this Promise to be resolved before completing.
If this Promise was resolved with a failure, this method returns with the
failure of this Promise. If this Promise was successfully resolved, this
method must return null
.
getFailure
in interface Promise<T>
null
if this
Promise was successfully resolved.java.lang.InterruptedException
- If the current thread was interrupted while
waiting.public Promise<T> onResolve(java.lang.Runnable callback)
The specified callback is called when this Promise is resolved either successfully or with a failure.
This method may be called at any time including before and after this Promise has been resolved.
Resolving this 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.
A callback may be called on a different thread than the thread which registered the callback. So the callback must be thread safe but can rely upon that the registration of the callback happens-before the registered callback is called.
public <R> Promise<R> then(Success<? super T,? extends R> success, Failure failure)
The specified Success
callback is called when this Promise is
successfully resolved and the specified Failure
callback is
called when this Promise is resolved with a failure.
This method returns a new Promise which is chained to this Promise. The returned Promise must be resolved when this Promise is resolved after the specified Success or Failure callback is executed. The result of the executed callback must be used to resolve the returned Promise. Multiple calls to this method can be used to create a chain of promises which are resolved in sequence.
If this Promise is successfully resolved, the Success callback is executed and the result Promise, if any, or thrown exception is used to resolve the returned Promise from this method. If this Promise is resolved with a failure, the Failure callback is executed and the returned Promise from this method is failed.
This method may be called at any time including before and after this Promise has been resolved.
Resolving this 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.
A callback may be called on a different thread than the thread which registered the callback. So the callback must be thread safe but can rely upon that the registration of the callback happens-before the registered callback is called.
then
in interface Promise<T>
R
- The value type associated with the returned Promise.success
- A Success callback to be called when this Promise is
successfully resolved. May be null
if no Success callback
is required. In this case, the returned Promise must be resolved
with the value null
when this Promise is successfully
resolved.failure
- A Failure callback to be called when this Promise is
resolved with a failure. May be null
if no Failure
callback is required.public <R> Promise<R> then(Success<? super T,? extends R> success)
This method performs the same function as calling
Promise.then(Success, Failure)
with the specified Success callback and
null
for the Failure callback.
then
in interface Promise<T>
R
- The value type associated with the returned Promise.success
- A Success callback to be called when this Promise is
successfully resolved. May be null
if no Success callback
is required. In this case, the returned Promise must be resolved
with the value null
when this Promise is successfully
resolved.Promise.then(Success, Failure)
Promise<java.lang.Void> resolveWith(Promise<? extends T> with)
If the specified Promise is successfully resolved, this Promise is resolved with the value of the specified Promise. If the specified Promise is resolved with a failure, this Promise is resolved with the failure of the specified Promise.
with
- A Promise whose value or failure must be used to resolve this
Promise. Must not be null
.null
, if this Promise was
resolved by the specified Promise. The returned Promise must be
resolved with a failure of IllegalStateException
, if this
Promise was already resolved when the specified Promise was
resolved.public Promise<T> filter(Predicate<? super T> predicate)
If this Promise is successfully resolved, the returned Promise must
either be resolved with the value of this Promise, if the specified
Predicate accepts that value, or failed with a
NoSuchElementException
, if the specified Predicate does not
accept that value. If the specified Predicate throws an exception, the
returned Promise must be failed with the exception.
If this Promise is resolved with a failure, the returned Promise must be failed with that failure.
This method may be called at any time including before and after this Promise has been resolved.
public <R> Promise<R> map(Function<? super T,? extends R> mapper)
If this Promise is successfully resolved, the returned Promise must be resolved with the value of specified Function as applied to the value of this Promise. If the specified Function throws an exception, the returned Promise must be failed with the exception.
If this Promise is resolved with a failure, the returned Promise must be failed with that failure.
This method may be called at any time including before and after this Promise has been resolved.
map
in interface Promise<T>
R
- The value type associated with the returned Promise.mapper
- The Function that must map the value of this Promise to the
value that must be used to resolve the returned Promise. Must not
be null
.public <R> Promise<R> flatMap(Function<? super T,Promise<? extends R>> mapper)
If this Promise is successfully resolved, the returned Promise must be resolved with the Promise from the specified Function as applied to the value of this Promise. If the specified Function throws an exception, the returned Promise must be failed with the exception.
If this Promise is resolved with a failure, the returned Promise must be failed with that failure.
This method may be called at any time including before and after this Promise has been resolved.
flatMap
in interface Promise<T>
R
- The value type associated with the returned Promise.mapper
- The Function that must flatMap the value of this Promise to
a Promise that must be used to resolve the returned Promise. Must
not be null
.public Promise<T> recover(Function<Promise<?>,? extends T> recovery)
If this Promise is successfully resolved, the returned Promise must be resolved with the value of this Promise.
If this Promise is resolved with a failure, the specified Function is applied to this Promise to produce a recovery value.
null
, the returned Promise must
be resolved with the recovery value.null
, the returned Promise must be
failed with the failure of this Promise.
To recover from a failure of this Promise with a recovery value of
null
, the Promise.recoverWith(Function)
method must be used. The
specified Function for Promise.recoverWith(Function)
can return
Promises.resolved(null)
to supply the desired null
value.
This method may be called at any time including before and after this Promise has been resolved.
recover
in interface Promise<T>
recovery
- If this Promise resolves with a failure, the specified
Function is called to produce a recovery value to be used to
resolve the returned Promise. Must not be null
.public Promise<T> recoverWith(Function<Promise<?>,Promise<? extends T>> recovery)
If this Promise is successfully resolved, the returned Promise must be resolved with the value of this Promise.
If this Promise is resolved with a failure, the specified Function is applied to this Promise to produce a recovery Promise.
null
, the returned Promise
must be resolved with the recovery Promise.null
, the returned Promise must be
failed with the failure of this Promise.This method may be called at any time including before and after this Promise has been resolved.
recoverWith
in interface Promise<T>
recovery
- If this Promise resolves with a failure, the specified
Function is called to produce a recovery Promise to be used to
resolve the returned Promise. Must not be null
.public Promise<T> fallbackTo(Promise<? extends T> fallback)
If this Promise is successfully resolved, the returned Promise must be resolved with the value of this Promise.
If this Promise is resolved with a failure, the successful result of the specified Promise is used to resolve the returned Promise. If the specified Promise is resolved with a failure, the returned Promise must be failed with the failure of this Promise rather than the failure of the specified Promise.
This method may be called at any time including before and after this Promise has been resolved.
fallbackTo
in interface Promise<T>
fallback
- The Promise whose value must be used to resolve the
returned Promise if this Promise resolves with a failure. Must not
be null
.static <V> V requireNonNull(V value)