com.linkedin.parseq.promise

Interface Promise<P>

All Known Subinterfaces:

ParTask<T>, SettablePromise<P>, Task<T>, Tuple10Task<T1,T2,T3,T4,T5,T6,T7,T8,T9,T10>, Tuple11Task<T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11>, Tuple12Task<T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12>, Tuple13Task<T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13>, Tuple14Task<T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14>, Tuple15Task<T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15>, Tuple2Task<T1,T2>, Tuple3Task<T1,T2,T3>, Tuple4Task<T1,T2,T3,T4>, Tuple5Task<T1,T2,T3,T4,T5>, Tuple6Task<T1,T2,T3,T4,T5,T6>, Tuple7Task<T1,T2,T3,T4,T5,T6,T7>, Tuple8Task<T1,T2,T3,T4,T5,T6,T7,T8>, Tuple9Task<T1,T2,T3,T4,T5,T6,T7,T8,T9>

All Known Implementing Classes:

ActionTask, AsyncCallableTask, BaseTask, CallableTask, DelegatingPromise, Par10Task, Par11Task, Par12Task, Par13Task, Par14Task, Par15Task, Par2Task, Par3Task, Par4Task, Par5Task, Par6Task, Par7Task, Par8Task, Par9Task, ResolvedError, ResolvedValue, SystemHiddenTask, Tuple10TaskDelegate, Tuple11TaskDelegate, Tuple12TaskDelegate, Tuple13TaskDelegate, Tuple14TaskDelegate, Tuple15TaskDelegate, Tuple2TaskDelegate, Tuple3TaskDelegate, Tuple4TaskDelegate, Tuple5TaskDelegate, Tuple6TaskDelegate, Tuple7TaskDelegate, Tuple8TaskDelegate, Tuple9TaskDelegate

public interface Promise<P>

A Promise, like a Future, represents the result of an asynchronous computation. However, Promises are designed to work in an entirely asynchronous work flow. Except where specifically mentioned, none of the methods in the Promise will block the current thread while waiting for a response.

Author:

Chris Pettitt ([email protected])

Method Summary

Modifier and Type	Method and Description
void	addListener(PromiseListener<P> listener) Adds a listener to this promise that will be notified when the promise is resolved.
void	await() Blocks the current thread for an unbounded amount of time until the promise has be resolved.
boolean	await(long time, TimeUnit unit) Blocks the current thread for up to the specified amount of time or until the promise has been resolved.
P	get() If the promise's value is set, then this method returns the value.
Throwable	getError() Returns the error in this promise, if there is one.
P	getOrDefault(P defaultValue) Gets the value in this promise or, if the promise contains an error, returns the given default value.
boolean	isDone() Returns true if this promise is resolved.
boolean	isFailed() Returns true if the promise has an error.
default CompletionStage<P>	toCompletionStage() Converts {@code Promise

Method Detail

get

P get()
throws PromiseException

If the promise's value is set, then this method returns the value. If the promise has an error, the error is thrown, wrapped in a PromiseException. If the promise has not yet been resolved (i.e. it has no value and no error) then this method raises a PromiseUnresolvedException.

Returns:

the value of the promise if it is available

Throws:

PromiseException - if the promise has an error

PromiseUnresolvedException - if the promise has not yet been resolved

getError

Throwable getError()
            throws PromiseUnresolvedException

Returns the error in this promise, if there is one. If this promise contains a value, then this method will return null. If this promise has no value and no error (i.e. it is unresolved) then a PromiseUnresolvedException is thrown.

Returns:

the error contained in this promise, or null if the promise contains a value.

Throws:

PromiseUnresolvedException - if the promise has not yet been resolved

getOrDefault

P getOrDefault(P defaultValue)
        throws PromiseUnresolvedException

Gets the value in this promise or, if the promise contains an error, returns the given default value. This is one mechanism for gracefully handling promise failure.

If the promise has not been resolved then this method will throw PromiseUnresolvedException.

Parameters:

defaultValue - the default value to return if this promise contains an error.

Returns:

the value in this promise or the default value if this promise contains an error.

Throws:

PromiseUnresolvedException - if the promise has not yet been resolved

await

void await()
    throws InterruptedException

Blocks the current thread for an unbounded amount of time until the promise has be resolved.

For asynchronous workflows, use addListener(PromiseListener), which will notify the user when the promise is resolved instead of blocking the current thread.

Throws:

InterruptedException - if the current thread is interrupted

await

boolean await(long time,
              TimeUnit unit)
       throws InterruptedException

Blocks the current thread for up to the specified amount of time or until the promise has been resolved. If the promise was resolved before the specified time has expired, this method returns true.

For asynchronous workflows, use addListener(PromiseListener), which will notify the user when the promise is resolved instead of blocking the current thread.

Parameters:

time - the amount of time to wait

unit - the units for the wait time

Returns:

true if the promise is resolved within the specified time

Throws:

InterruptedException - if the current thread is interrupted

addListener

void addListener(PromiseListener<P> listener)

Adds a listener to this promise that will be notified when the promise is resolved. If the promise has already been resolved then the listener is notified immediately.

Listener will be called on a thread that completed this promise.

The instance passed in to PromiseListener.onResolved(Promise) method does not have to be the exact same instance the PromiseListener was registered with.

Parameters:

listener - the listener to add to this promise

isDone

boolean isDone()

Returns true if this promise is resolved. A promise is resolved when it has a value or an error.

Returns:

true if this promise has been resolved.

isFailed

boolean isFailed()

Returns true if the promise has an error. Errors can retrieved using getError().

Returns:

true if the promise has en error.

toCompletionStage

default CompletionStage<P> toCompletionStage()

Converts Promise<P> into CompletionStage<P>.

Returns:

CompletionStage