bayou.util

Interface Result<T>

All Superinterfaces:

Async<T>

public interface Result<T>
extends Async<T>

The result of an action, which is either a success or a failure.

A success Result contains a value of type T. A failure Result contains an exception of type Exception

See static methods Result.success(value) and Result.failure(exception) to create Result objects.

Every Result is also an Async that's immediately completed. A Result object can be used wherever an Async is expected.

Note: A success value could be null; however, a failure exception must be non-null.

Note: In failure, the type of the exception is Exception, not the more general Throwable. We consider that Error indicates something catastrophic, which is not a usual result of any action. Therefore we do not handle Error in Result.

Method Summary

Abstract Methods
boolean	isSuccess() Whether this result is a success.
boolean	isFailure() Whether this result is a failure.
T	getValue() Return the value if this result is a success; otherwise return null.
Exception	getException() Return the exception if this result is a failure; otherwise return null.
Default Methods
T	getOrThrow() Return the value if this result is a success; otherwise throw the exception.
Result<T>	pollResult() Implements Async.pollResult(); by default, return `this`.
boolean	isCompleted() return `true`
void	onCompletion(Consumer<Result<T>> callback) Implements Async.onCompletion(Consumer).
void	cancel(Exception reason) Implements Async.cancel(Exception); by default, do nothing, because a Result is a completed Async.
Result<T>	timeout(Duration duration) Implements Async.timeout(Duration); by default, do nothing, because a Result is a completed Async.
Static Methods
<T> Result<T>	success(T value) Create a success Result with the value.
<T> Result<T>	failure(Exception exception) Create a failure Result with the exception.
<T> Result<T>	call(Callable<T> action) Invoke action.call(), convert the outcome to a Result.

Methods inherited from interface bayou.async.Async

catch__, catch_, covary, finally_, finally_, map, map, peek, peek, sync, then, then, transform

Method Detail

isSuccess

boolean isSuccess()

Whether this result is a success.

isFailure

boolean isFailure()

Whether this result is a failure.

getValue

T getValue()

Return the value if this result is a success; otherwise return null.

Note that null could be legitimate success value.

getException

Exception getException()

Return the exception if this result is a failure; otherwise return null.

Note that if this method returns null, this result must be a success.

getOrThrow

default T getOrThrow()
              throws Exception

Return the value if this result is a success; otherwise throw the exception.

Throws:

Exception

pollResult

default Result<T> pollResult()

Implements Async.pollResult(); by default, return `this`.

Specified by:

pollResult in interface Async<T>

isCompleted

default boolean isCompleted()

return `true`

Specified by:

isCompleted in interface Async<T>

onCompletion

default void onCompletion(Consumer<Result<T>> callback)

Implements Async.onCompletion(Consumer). Note that `this` is already completed.

Specified by:

onCompletion in interface Async<T>

cancel

default void cancel(Exception reason)

Implements Async.cancel(Exception); by default, do nothing, because a Result is a completed Async.

Specified by:

cancel in interface Async<T>

timeout

default Result<T> timeout(Duration duration)

Implements Async.timeout(Duration); by default, do nothing, because a Result is a completed Async. Returns `this`.

Specified by:

timeout in interface Async<T>

Returns:

`this`

success

static <T> Result<T> success(T value)

Create a success Result with the value.

Example Usage:

     Result<Integer> result = Result.success(42);
 

Parameters:

value - the success value. Can be null.

failure

static <T> Result<T> failure(Exception exception)

Create a failure Result with the exception.

Example Usage:

     Result<Integer> result = Result.failure(new IOException("cannot read file"));
 

Parameters:

exception - the failure exception. Must be non-null.

call

static <T> Result<T> call(Callable<T> action)

Invoke action.call(), convert the outcome to a Result.

If action.call() returns a value, this method returns a success Result with the same value.

If action.call() throws an Exception, this method returns a failure Result with the same exception.

Example Usage:

     Result<Integer> result = Result.call( ()->Integer.parseInt("0.1") );
     // result is a failure with a NumberFormatException
 

See Callable_Void in case the `action` argument is a void-returning lambda expression or method reference.

Note: Result does not handle Error. If action.call() throws an Error, this method throws the same error.