Promise (Java Scala Utils 1.3 API)

Type Parameters:

T - The type this Promise will produce as result
```
public interface Promise<T>
```
A Promise that can be completed once with a value or failed once with an exception.
Together with a Future this allows a safe publication of asynchronously calculated results into another thread.
The basic principle is to first create a Promise.

Promise<String> promise = Promise.apply();
Using that instance one can get hold of the Future that is the container for the value-to-be.

Future<String> future = promise.future();
To complete the Promise and by extension completing the Future one can use any of several methods:
E.g.
promise.success("Peter was here");
Note that only one of the methods may be invoked as the Promise can only be fulfilled once.
The above methods come with a variant tryNNN which allows for multiple invocations without raising an exception.
Though still only the first invocation/completion counts.
Since:

1.2

Author:

Peter Nerg

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`static <T> Promise<T>`	`apply()` Creates an instance of Promise.
`void`	`complete(Try<T> result)` Completes the `Promise` with either a `Success` or a `Failure`.
`void`	`completeWith(Future<T> future)` Completes this `Promise` with the value from the provided `Future` once that is completed.
`void`	`failure(Throwable throwable)` Completes the `Promise` with an exception.
`Future<T>`	`future()` Get a `Future` that will hold the value once this Promise is completed.
`boolean`	`isCompleted()` Check if the `Promise` have been completed, with a value or an exception.
`void`	`success(T result)` Completes the `Promise` with a value.
`boolean`	`tryComplete(Try<T> result)` Tries to complete the `Promise` with either a `Success` or a `Failure`.
`boolean`	`tryCompleteWith(Future<T> future)` Tries to complete this `Promise` with the value from the provided `Future` once that is completed.
`boolean`	`tryFailure(Throwable throwable)` Tries to complete the `Promise` with an exception.
`boolean`	`trySuccess(T result)` Tries to complete the `Promise` with a value.

- Method Detail
  - apply
```
static <T> Promise<T> apply()
```
    Creates an instance of Promise.
    E.g. Promise<String> p = Promise.apply();
    
    Type Parameters:
    
    T - The type the Promise is expected to deliver
    
    Returns:
    
    The Promise instance
  - future
```
Future<T> future()
```
    Get a Future that will hold the value once this Promise is completed.
    Each Promise is connected to a single Future, invoking this method multiple times will always return the same Future instance.
    
    Returns:
    
    A Future that will hold the value once this Promise is completed.
  - isCompleted
```
boolean isCompleted()
```
    Check if the Promise have been completed, with a value or an exception.
    
    Returns:
    
    true if the Promise has been completed. false otherwise.
  - complete
```
void complete(Try<T> result)
```
    Completes the Promise with either a Success or a Failure.
    
    Parameters:
    
    result - The result to complete with.
    
    Throws:
    
    IllegalStateException - Thrown if the Promise is already completed.
    
    Since:
    
    1.3
  - completeWith
```
void completeWith(Future<T> future)
```
    Completes this Promise with the value from the provided Future once that is completed.
    
    Parameters:
    
    future - The future whose value will complete this Promise
    
    Throws:
    
    IllegalStateException - Thrown if the Promise is already completed.
    
    Since:
    
    1.3
  - success
```
void success(T result)
```
    Completes the Promise with a value.
    
    Parameters:
    
    result - The value to complete with.
    
    Throws:
    
    IllegalStateException - Thrown if the Promise is already completed.
  - failure
```
void failure(Throwable throwable)
```
    Completes the Promise with an exception.
    
    Parameters:
    
    throwable - The Throwable to complete with.
    
    Throws:
    
    IllegalStateException - Thrown if the Promise is already completed.
  - tryComplete
```
boolean tryComplete(Try<T> result)
```
    Tries to complete the Promise with either a Success or a Failure.
    Contrary to the complete(Try) method this does not throw an exception in case the Promise is already completed.
    
    Parameters:
    
    result - The result to complete with.
    
    Returns:
    
    true if the Promise was not completed before, false otherwise
    
    Since:
    
    1.3
  - tryCompleteWith
```
boolean tryCompleteWith(Future<T> future)
```
    Tries to complete this Promise with the value from the provided Future once that is completed.
    Contrary to the complete(Try) method this does not throw an exception in case the Promise is already completed.
    
    Parameters:
    
    future - The future whose value will complete this Promise
    
    Returns:
    
    true if the Promise was not completed before, false otherwise
    
    Since:
    
    1.3
  - trySuccess
```
boolean trySuccess(T result)
```
    Tries to complete the Promise with a value.
    Contrary to the success(Object) method this does not throw an exception in case the Promise is already completed.
    
    Parameters:
    
    result - The value to complete with.
    
    Returns:
    
    true if the Promise was not completed before, false otherwise
    
    Since:
    
    1.3
  - tryFailure
```
boolean tryFailure(Throwable throwable)
```
    Tries to complete the Promise with an exception.
    Contrary to the failure(Throwable) method this does not throw an exception in case the Promise is already completed.
    
    Parameters:
    
    throwable - The Throwable to complete with.
    
    Returns:
    
    true if the Promise was not completed before, false otherwise
    
    Since:
    
    1.3

Interface Promise<T>

Method Summary

Method Detail

apply

future

isCompleted

complete

completeWith

success

failure

tryComplete

tryCompleteWith

trySuccess

tryFailure