PartialFuture (FoundationDB Java Client API)

Type Parameters:
T - the type of the eventual value of the PartialFuture

All Superinterfaces:

Cancellable, Disposable

All Known Subinterfaces:

Future<T>

All Known Implementing Classes:

AbstractFuture, AbstractPartialFuture, ReadyFuture, ReadyPartialFuture, SettableFuture, SettablePartialFuture
```
public interface PartialFuture<T>
extends Cancellable, Disposable
```
The typed result of an asynchronous process. A PartialFuture will be set exactly once to either a "completed" T or to an Exception. A PartialFuture is "partial" in that some outcomes of the process involve the error output being a checked exception. A Future is a special case of a PartialFuture that cannot result in a checked exception.

A PartialFuture can be waited on by blocking, or by using asynchronous callbacks.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`blockInterruptibly()` Blocks until this `Future` is set to either a value or an error.
`void`	`blockUntilReady()` Blocks until this `Future` is set to either a value or an error.
`void`	`cancel()` Cancels this asynchronous operation.
`void`	`dispose()` Equivalent to calling `cancel()`.
`<V> PartialFuture<V>`	`flatMap(PartialFunction<? super T,? extends PartialFuture<V>> m)` Applies the successful result of this operation as the input into another asynchronous operation and returns a handle to that result.
`T`	`get()` Blocks until a value is set on this `PartialFuture` and returns it.
`Throwable`	`getError()` Gets the error from a `Future` if it has been set to this state.
`T`	`getInterruptibly()` Blocks until a value is set on this `PartialFuture` and returns it.
`boolean`	`isDone()` Gets the readiness of this `Future`.
`boolean`	`isError()` Tests if this `Future` is set to an error
`<V> PartialFuture<V>`	`map(PartialFunction<? super T,V> m)` Apply a function to the successful result of this operation.
`void`	`onReady(Runnable r)` Registers a `Runnable` to run as the callback for this `Future` on a default thread.
`boolean`	`onReadyAlready(Runnable r)` Checks if this `Future` is ready and, if not, atomically registers a `Runnable` to run as the callback for this future on a default thread.
`Future<T>`	`rescue(Function<? super Exception,Future<T>> m)` Convert an error output of this operation into another asynchronous process.
`PartialFuture<T>`	`rescue(PartialFunction<? super Exception,? extends PartialFuture<T>> m)` Map any error result of this `Future` to another asynchronous process.

- Method Detail
  - onReady
```
void onReady(Runnable r)
```
    Registers a Runnable to run as the callback for this Future on a default thread. It will be called after the future becomes ready, including if the future is set to a value, set to an error, or cancelled.
    
    Consider using map(PartialFunction) and flatMap(PartialFunction) instead, as they automatically provide error propagation and cancellation.
    
    Parameters:
    r - the code to run when the future is set either to value or error
  - onReadyAlready
```
boolean onReadyAlready(Runnable r)
```
    Checks if this Future is ready and, if not, atomically registers a Runnable to run as the callback for this future on a default thread. The callback will not be called if the future is ready. Callers can rely on the guarantee that if this function returns false their callback will be executed on completion (including if the future is set to a value, set to an error, or cancelled), and if true they can then call get() without blocking.
    
    Parameters:
    r - the code to run when the future is set if it is not currently ready
    
    Returns:
    true if the future is ready, false otherwise
  - map
```
<V> PartialFuture<V> map(PartialFunction<? super T,V> m)
```
    Apply a function to the successful result of this operation. Errors in the execution of this operation are sent to the resulting Future.
    
    If the returned Future is cancelled the input input Future will also be cancelled.
    
    Parameters:
    m - the map to the conversion to be run
    
    Returns:
    a new Future that passes errors and converts output of this Future.
  - flatMap
```
<V> PartialFuture<V> flatMap(PartialFunction<? super T,? extends PartialFuture<V>> m)
```
    Applies the successful result of this operation as the input into another asynchronous operation and returns a handle to that result. That is, when the operation represented by this Future is complete and a result is returned, the Mapper m is invoked to begin a new asynchronous process using the result. Errors in the execution of either operation are sent to the resulting Future.
    
    If the returned Future is cancelled the input input Future will also be cancelled.
    
    Parameters:
    m - the map to the asynchronous process to be run
    
    Returns:
    a new Future that passes errors and converts output of this Future to the output of another asynchronous process.
  - rescue
```
PartialFuture<T> rescue(PartialFunction<? super Exception,? extends PartialFuture<T>> m)
```
    Map any error result of this Future to another asynchronous process. This can be used when an error is expected or can be logically dealt with in some way. If the rescue process cannot handle the error, or if the rescue process itself throws an error, that error will be set on this Future. If the result of this call is used in place of this Future, the user of the output Future will see successes of this process, successes of the rescue process, or errors from the rescue process.
    
    Parameters:
    m - the process to run that maps an error into another asynchronous operation
    
    Returns:
    a newly created Future with modified error behavior
  - rescue
```
Future<T> rescue(Function<? super Exception,Future<T>> m)
```
    Convert an error output of this operation into another asynchronous process.
    
    Parameters:
    m - the process to run on completion into error state.
    
    Returns:
    the non-checked Future output with modified error behavior
  - blockUntilReady
```
void blockUntilReady()
```
    Blocks until this Future is set to either a value or an error. When this function returns without an error, isDone() will return true.
    Code should never block for a future to become ready in code invoked as a callback. Blocking in callback code will generally block client networking and cause a deadlock.
  - blockInterruptibly
```
void blockInterruptibly()
                        throws InterruptedException
```
    Blocks until this Future is set to either a value or an error. When this function returns without an error, isDone() will return true.
    Code should never block for a future to become ready in code invoked as a callback. Blocking in callback code will generally block client networking and cause a deadlock.
    
    Throws:
    
    InterruptedException - if the blocked thread is interrupted
  - get
```
T get()
      throws Exception
```
    Blocks until a value is set on this PartialFuture and returns it. If this PartialFuture is set to an Exception or Error this call will throw that error.
    
    Returns:
    the output value of the asynchronous process
    
    Throws:
    
    Exception - if the process was not successfully executed.
    
    InterruptedException - if the blocked thread is interrupted
    
    Error - if the process encountered a serious Error during execution.
  - getInterruptibly
```
T getInterruptibly()
                   throws Exception
```
    Blocks until a value is set on this PartialFuture and returns it. If this PartialFuture is set to an Exception or Error this call will throw that error.
    
    Returns:
    the output value of the asynchronous process
    
    Throws:
    
    Exception - if the process was not successfully executed.
    
    InterruptedException - if the blocked thread is interrupted
    
    Error - if the process encountered a serious Error during execution.
  - cancel
```
void cancel()
```
    Cancels this asynchronous operation. If called before the Future is ready, subsequent attempts to access its value will throw. Cancelling a Future which is already set has no effect. Cancelling a Future should not be assumed to eliminate the affects of launching the operation. Many asynchronous operations start work on remote machines -- this work will generally not be stopped if the local Future is cancelled.
    
    Specified by:
    
    cancel in interface Cancellable
  - isDone
```
boolean isDone()
```
    Gets the readiness of this Future. A Future is ready if the value has been set or an error has been set.
    
    Returns:
    true if the Future is set to a value or error
  - isError
```
boolean isError()
```
    Tests if this Future is set to an error
    
    Returns:
    true if in error state, false otherwise
  - getError
```
Throwable getError()
```
    Gets the error from a Future if it has been set to this state. If this Future is not yet set, or has not been set to an error, throws an exception. Although this method returns a Throwable, the set of possible types is more limited. A PartialFuture is limited to be set in an error state to an Exception (or a subclass thereof) or an unchecked Error.
    
    Returns:
    the error output of the Future
    
    Throws:
    
    IllegalStateException - if this PartialFuture is not in an error state
  - dispose
```
void dispose()
```
    Equivalent to calling cancel().
    
    Specified by:
    
    dispose in interface Disposable

Interface PartialFuture<T>

Method Summary

Method Detail

onReady

onReadyAlready

map

flatMap

rescue

rescue

blockUntilReady

blockInterruptibly

get

getInterruptibly

cancel

isDone

isError

getError

dispose