gololang.error

Class Result<T,E extends java.lang.Throwable>

java.lang.Object

gololang.error.Result<T,E>

All Implemented Interfaces:

java.lang.Iterable<T>

public final class Result<T,E extends java.lang.Throwable>
extends java.lang.Object
implements java.lang.Iterable<T>

A container object which represent the result of a maybe failing operation.

This object is used when chaining computations (e.g. using map-filter operations) that can produce an error. Instead of raising an exception, the operation can use this object to encapsulate the result. This is similar to Optional, but also encapsulate the type of error in the form of a Throwable instance that can be raised later.

This is similar to the Either or Result type in other functional languages (e.g. Haskell, Rust or Scala)

Typical usage:

• return empty() instead of returning null,
• use error(java.lang.Throwable) or fail(java.lang.String) instead of throwing an exception,
• use ok(java.lang.Object) to return a normal value.

Method Summary

Modifier and Type	Method and Description
java.lang.Object[]	__$$_destruct(int number, boolean substruct, java.lang.Object[] toSkip) New style destructuring helper.
Result<?,?>	and(Result<?,?> other) Conjunctive chaining.
Result<?,? extends java.lang.Throwable>	andThen(FunctionReference mapper) Same as map or flatMap depending on the type returned by mapper.
Result<?,?>	apply(Result<?,?> other) Apply the function contained is this result to the given result.
Tuple	destruct() Deprecated. This method should not be called directly and is no more used by new style destructuring.
java.lang.Object	either(FunctionReference mapping, FunctionReference recover) Case analysis for the result.
java.lang.Object	either(FunctionReference mapping, FunctionReference recover, FunctionReference def) Three way case analysis for the result.
static <T,E extends java.lang.Throwable> Result<T,E>	empty() Returns an empty Result.
boolean	equals(java.lang.Object o) Indicate whether some other object is equal to this Result.
static <T,E extends java.lang.Throwable> Result<T,E>	error(E throwable) Returns a failed Result.
static <T> Result<T,java.lang.RuntimeException>	fail(java.lang.String message) Returns a failed Result.
Result<T,E>	filter(java.util.function.Predicate<? super T> predicate) If a value is present and matches the given predicate, return a Result describing the value, otherwise return an empty Result.
<U,X extends java.lang.Throwable> Result<U,X>	flatMap(java.util.function.Function<? super T,Result<U,X>> mapper) If a value is present, apply the provided Result-bearing mapping function to it, otherwise return the Result itself.
Result<java.lang.Object,java.lang.Throwable>	flatMap(FunctionReference mapper) Golo compatible version of flatMap.
Result<?,?>	flattened() Remove one level of result.
T	get() If a value is present, returns the value, if empty throws NoSuchElementException, otherwise throws the contained error.
int	hashCode()
boolean	isEmpty()
boolean	isError()
boolean	isError(java.lang.Class<?> type)
boolean	isValue()
boolean	isValue(java.lang.Object val)
java.util.Iterator<T>	iterator()
<U,X extends java.lang.Throwable> Result<U,X>	map(java.util.function.Function<? super T,? extends U> mapper) If a value is present, apply the provided mapping function to it, otherwise return the Result itself.
Result<java.lang.Object,java.lang.Throwable>	map(FunctionReference mapper) Golo compatible version of map.
<X extends java.lang.Throwable> Result<T,X>	mapError(java.util.function.Function<? super E,? extends X> mapper) If this result is an error, apply the provided mapping function to the contained error, otherwise return the Result itself.
static Result<java.lang.Object,java.lang.Throwable>	of(java.lang.Object value) Dynamic polymorphic constructor.
static <T,E extends java.lang.Throwable> Result<T,E>	ok(T value) Returns a valid Result.
static <T,E extends java.lang.Throwable> Result<T,E>	option(java.util.Optional<T> opt) Construct a Result from a Optional.
static <T> Result<T,java.util.NoSuchElementException>	option(java.util.Optional<T> opt, java.lang.String message) Construct a Result from a Optional.
Result<?,?>	or(Result<?,?> other) Disjunctive chaining.
T	orElse(T other) Return the value of present, otherwise return other.
java.lang.Object	orElseGet(FunctionReference fun) Return the value of present, otherwise return the result of the invocation of fun.
java.lang.Object	reduce(java.lang.Object init, FunctionReference func) Reduce this using func with init as initial value.
java.util.List<E>	toErrorList() Convert this Result into a List of error.
java.util.List<T>	toList() Convert this Result into a List of values.
java.util.Optional<T>	toOptional() Convert this Result into a Optional describing its value.
java.util.Optional<E>	toOptionalError() Convert this Result into a Optional describing its error.
java.lang.String	toString()
static <T> Result<T,java.lang.Throwable>	trying(java.util.function.Supplier<T> fun) Runs a function that can raise an exception and return a Result.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

of

public static Result<java.lang.Object,java.lang.Throwable> of(java.lang.Object value)

Dynamic polymorphic constructor.

Dynamically dispatch on empty(), error(java.lang.Throwable), option(java.util.Optional) or ok(java.lang.Object) depending on the value type. This is mainly useful in Golo code.

Parameters:

value - the value to encapsulate

Returns:

a Result representing the value

empty

public static <T,E extends java.lang.Throwable> Result<T,E> empty()

Returns an empty Result.

Represents a successful computation that returns nothing.

Returns:

an empty Result

ok

public static <T,E extends java.lang.Throwable> Result<T,E> ok(T value)

Returns a valid Result.

Represents a successful computation's result.

Type Parameters:

T - the class of the value

Parameters:

value - the possibly-null value to describe

Returns:

a Result containing the value if the specified value is non-null, otherwise an empty Result

error

public static <T,E extends java.lang.Throwable> Result<T,E> error(E throwable)

Returns a failed Result.

Represent a computation that failed.

Type Parameters:

E - the class of the throwable

Parameters:

throwable - the error that occurred

Returns:

a Result containing the throwable

option

public static <T,E extends java.lang.Throwable> Result<T,E> option(java.util.Optional<T> opt)

Construct a Result from a Optional.

Type Parameters:

T - the class of the value

Parameters:

opt - the Optional representing the possibly present value

Returns:

a Result containing the value if isPresent() is true, otherwise an empty Result

option

public static <T> Result<T,java.util.NoSuchElementException> option(java.util.Optional<T> opt,
                                                                    java.lang.String message)

Construct a Result from a Optional.

Type Parameters:

T - the class of the value

Parameters:

opt - the Optional representing the possibly present value

message - a message used to create an error if the Optional is empty

Returns:

a Result containing the value if isPresent() is true, otherwise an error containing NoSuchElementException

fail

public static <T> Result<T,java.lang.RuntimeException> fail(java.lang.String message)

Returns a failed Result.

Represent a computation that failed. This is similar to error(java.lang.Throwable) but only the message is provided, and a RuntimeException is automatically created.

Parameters:

message - the message representing the error

Returns:

a Result containing a RuntimeException

trying

public static <T> Result<T,java.lang.Throwable> trying(java.util.function.Supplier<T> fun)

Runs a function that can raise an exception and return a Result.

Parameters:

fun - the function to run

Returns:

a Result containing either the raised exception or the value produced by the function.

get

public T get()
      throws E extends java.lang.Throwable,
             java.util.NoSuchElementException

If a value is present, returns the value, if empty throws NoSuchElementException, otherwise throws the contained error.

Returns:

the non-null value contained in this Result

Throws:

java.util.NoSuchElementException - if the Result is empty

E - if the Result is an error

E extends java.lang.Throwable

toOptional

public java.util.Optional<T> toOptional()

Convert this Result into a Optional describing its value.

Returns:

an Optional containing the value of this Result, or an empty Optional if isValue() is false

toList

public java.util.List<T> toList()

Convert this Result into a List of values.

Returns:

an singleton list containing the value if present, otherwise an empty list

toErrorList

public java.util.List<E> toErrorList()

Convert this Result into a List of error.

Returns:

an singleton list containing the error if present, otherwise an empty list

iterator

public java.util.Iterator<T> iterator()

Specified by:

iterator in interface java.lang.Iterable<T>

toOptionalError

public java.util.Optional<E> toOptionalError()

Convert this Result into a Optional describing its error.

Returns:

an Optional containing the error of this Result, or an empty Optional if isError() is false

orElse

public T orElse(T other)

Return the value of present, otherwise return other.

Parameters:

other - the value to return if is empty

Returns:

the value if present, otherwise other

orElseGet

public java.lang.Object orElseGet(FunctionReference fun)
                           throws java.lang.Throwable

Return the value of present, otherwise return the result of the invocation of fun.

Parameters:

fun - the function to invoke if is empty (may return a default value or throw an exception)

Returns:

the value if present, otherwise the invocation of fun

Throws:

java.lang.Throwable

isEmpty

public boolean isEmpty()

Returns:

true if there is neither a value nor an error, otherwise false

isError

public boolean isError()

Returns:

true if there is an error (and no value), otherwise false

isError

public boolean isError(java.lang.Class<?> type)

Parameters:

type - the class to test the error for

Returns:

true if the present error is an instance of type

isValue

public boolean isValue()

Returns:

true if there is a value (and no error), otherwise false

isValue

public boolean isValue(java.lang.Object val)

Parameters:

val - the value to test for presence

Returns:

true if the present value is equal to val

map

public <U,X extends java.lang.Throwable> Result<U,X> map(java.util.function.Function<? super T,? extends U> mapper)

If a value is present, apply the provided mapping function to it, otherwise return the Result itself. If the application succeed with a value, return a Result containing it, if the result is null, return an empty Result, otherwise return a Result capturing the Throwable that was thrown.

Type Parameters:

U - The type of the result of the mapping function

Parameters:

mapper - a mapping function to apply to the value, if present

Returns:

a Result describing the result of applying the mapping function to the value of this Result

Throws:

java.lang.NullPointerException - if the mapping function is null

mapError

public <X extends java.lang.Throwable> Result<T,X> mapError(java.util.function.Function<? super E,? extends X> mapper)

If this result is an error, apply the provided mapping function to the contained error, otherwise return the Result itself. If the application succeed with a value, return a Result containing it, if the result is null, return an empty Result, otherwise return a Result capturing the Throwable that was thrown.

Type Parameters:

X - The type of the result of the mapping function

Parameters:

mapper - a mapping function to apply to the error, if present

Returns:

a Result describing the result of applying the mapping function to the error of this Result

Throws:

java.lang.NullPointerException - if the mapping function is null

flatMap

public <U,X extends java.lang.Throwable> Result<U,X> flatMap(java.util.function.Function<? super T,Result<U,X>> mapper)

If a value is present, apply the provided Result-bearing mapping function to it, otherwise return the Result itself. If the application succeed, return its result, otherwise return a Result capturing the Throwable that was thrown.

Type Parameters:

U - The type of the value of the Result returned by the mapping function

Parameters:

mapper - a mapping function to apply to the value, if present

Returns:

the result of applying the mapping function to the value of this Result

Throws:

java.lang.NullPointerException - if the mapping function is null or if it returns null

flatMap

public Result<java.lang.Object,java.lang.Throwable> flatMap(FunctionReference mapper)

Golo compatible version of flatMap. See issue 277

flattened

public Result<?,?> flattened()

Remove one level of result.

This is actually equivalent to flatMap(identity) (or r.flatMap(f) is equivalent to r.map(f).flattened())

For instance:

 ok(ok(42)).flattened() == ok(42)
 fail("error").flattened() == fail("error")
 empty().flattened() == empty()
 

Returns:

the value contained in this result if it's a result

Throws:

java.lang.ClassCastException - when the result does not contain a result.

andThen

public Result<?,? extends java.lang.Throwable> andThen(FunctionReference mapper)

Same as map or flatMap depending on the type returned by mapper.

This is a generic version for map and flatMap: if mapper returns a Result, it's equivalent to flatMap, otherwise, it's equivalent to map.

This allows code such as:

 Ok(21): andThen(|x| -> x + 1): andThen(|x| -> Ok(2 * x)) == Ok(42)
 

either

public java.lang.Object either(FunctionReference mapping,
                               FunctionReference recover)
                        throws java.lang.Throwable

Case analysis for the result.

If the result is a value, apply the first function to it; if it is an error, apply the second function to it.

Note that if the result is empty, i.e. the value is null, the mapping function is applied to null.

Parameters:

mapping - the function to apply to the contained value

recover - the function to apply to the contained error

Returns:

the result of applying the corresponding function

Throws:

java.lang.Throwable

either

public java.lang.Object either(FunctionReference mapping,
                               FunctionReference recover,
                               FunctionReference def)
                        throws java.lang.Throwable

Three way case analysis for the result.

If the result is a value, apply the first function to it; if it is an error, apply the second function to it; if it is empty, invoke the third function.

Parameters:

mapping - the function to apply to the contained value

recover - the function to apply to the contained error

def - the function to invoke if the result is empty (takes no arguments)

Returns:

the result of applying the corresponding function

Throws:

java.lang.Throwable

map

public Result<java.lang.Object,java.lang.Throwable> map(FunctionReference mapper)

Golo compatible version of map. See issue 277

filter

public Result<T,E> filter(java.util.function.Predicate<? super T> predicate)

If a value is present and matches the given predicate, return a Result describing the value, otherwise return an empty Result. If the Result is empty or is an error, return the Result itself.

Parameters:

predicate - a predicate to apply to the value, if present

Returns:

a Result describing the value of this Result if it maches the predicate

Throws:

java.lang.NullPointerException - if the predicate is null

reduce

public java.lang.Object reduce(java.lang.Object init,
                               FunctionReference func)
                        throws java.lang.Throwable

Reduce this using func with init as initial value.

For instance:

 Result.ok("b"): reduce("a", |x, y| -> x + y) == "ab"
 Result.empty(): reduce(42, |x, y| -> x + y) == 42
 Result.fail("error"): reduce(42, |x, y| -> x + y) == 42
 

Parameters:

init - the initial value

func - the aggregation function

Returns:

the initial value if this is not a value, the aggregated result otherwise

Throws:

java.lang.Throwable

apply

public Result<?,?> apply(Result<?,?> other)
                  throws java.lang.Throwable

Apply the function contained is this result to the given result.

If the function has several parameters, a result containing a partialized version is returned, that can be `apply`ed to subsequent results. This makes `Result` an “applicative functor”.

Throws:

java.lang.Throwable

and

public Result<?,?> and(Result<?,?> other)

Conjunctive chaining.

Parameters:

other - the other result

Returns:

other if this result is a value, otherwise this

or

public Result<?,?> or(Result<?,?> other)

Disjunctive chaining.

Parameters:

other - the other result

Returns:

other if this result is an error, otherwise this

equals

public boolean equals(java.lang.Object o)

Indicate whether some other object is equal to this Result. The other object is considered equal if:

• it is also a Result and;
• both instances are empty or;
• both instances have values that are equal via equals() or;
• both instances are errors of the same type with the same message.

Overrides:

equals in class java.lang.Object

Parameters:

o - an object to be tested for equality

Returns:

true if the other object is equal to this object, otherwise false

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

destruct

@Deprecated
public Tuple destruct()

Deprecated. This method should not be called directly and is no more used by new style destructuring.

Return a Tuple representing this Result.

Return a 2-tuple containing the error and the value contained by this Result, so that it can be used in a destructuring golo assignment. The first value is the error, and the second is the correct value (mnemonic: “right” also means “correct”). For instance:

 let e, v = Result.ok(42)        # e is null and v is 42
 let e, v = Result.empty()       # e is null and v is null
 let e, v = Result.fail("error") # e is RuntimeException("error") and v is null
 

This allows to deal with error in the same way as Go does for instance.

Returns:

a 2-tuple containing the error and the value contained by this Result

__$$_destruct

public java.lang.Object[] __$$_destruct(int number,
                                        boolean substruct,
                                        java.lang.Object[] toSkip)

New style destructuring helper.

Returns a 2-tuple containing the error and the value contained by this Result, so that it can be used in a destructuring golo assignment. The first value is the error, and the second is the correct value (mnemonic: “right” also means “correct”). For instance:

 let e, v = Result.ok(42)        # e is null and v is 42
 let e, v = Result.empty()       # e is null and v is null
 let e, v = Result.fail("error") # e is RuntimeException("error") and v is null
 

This allows to deal with error in the same way as Go does for instance.

New style destructuring must be exact. The number of variables to be affected is thus checked against the number of members of the structure.

The destructuring must be to exactly two values. No remainer syntax is allowed.

Parameters:

number - number of variable that will be affected.

substruct - whether the destructuring is complete or should contains a sub structure.

toSkip - a boolean array indicating the elements to skip.

Returns:

an array containing the values to assign.