Package org.junit.platform.commons.function

Class Try<V>

java.lang.Object

org.junit.platform.commons.function.Try<V>

@API(status=MAINTAINED,
     since="1.4")
public abstract class Try<V>
extends Object

A container object which may either contain a nullable value in case of success or an exception in case of failure.

Instances of this class should be returned by methods instead of Optional when callers might want to report the exception via logging or by wrapping it in another exception at a later point in time, e.g. via getOrThrow(Function).

Moreover, it makes it particularly convenient to attach follow-up actions should the Try have been successful (cf. andThen(java.util.function.Function<V, org.junit.platform.commons.function.Try<U>>) and andThenTry(org.junit.platform.commons.function.Try.Transformer<V, U>)) or fallback actions should it not have been (cf. orElse(java.util.function.Supplier<org.junit.platform.commons.function.Try<V>>) and orElseTry(java.util.concurrent.Callable<V>)).

Since:

1.4

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Try.Transformer<S,T>	A transformer for values of type S to type T.

Method Summary

Modifier and Type	Method	Description
abstract <U> Try<U>	andThen(Function<V,Try<U>> function)	If this Try is a success, apply the supplied function to its value and return the resulting Try; if this Try is a failure, do nothing.
abstract <U> Try<U>	andThenTry(Try.Transformer<V,U> transformer)	If this Try is a success, apply the supplied transformer to its value and return a new successful or failed Try depending on the transformer's outcome; if this Try is a failure, do nothing.
static <V> Try<V>	call(Callable<V> action)	Call the supplied Callable and return a successful Try that contains the returned value or, in case an exception was thrown, a failed Try that contains the exception.
static <V> Try<V>	failure(Exception cause)	Convert the supplied exception into a failed Try.
abstract V	get()	If this Try is a success, get the contained value; if this Try is a failure, throw the contained exception.
abstract <E extends Exception> V	getOrThrow(Function<? super Exception,E> exceptionTransformer)	If this Try is a success, get the contained value; if this Try is a failure, call the supplied Function with the contained exception and throw the resulting Exception.
abstract Try<V>	ifFailure(Consumer<Exception> causeConsumer)	If this Try is a failure, call the supplied Consumer with the contained exception; otherwise, do nothing.
abstract Try<V>	ifSuccess(Consumer<V> valueConsumer)	If this Try is a success, call the supplied Consumer with the contained value; otherwise, do nothing.
abstract Try<V>	orElse(Supplier<Try<V>> supplier)	If this Try is a failure, call the supplied supplier and return the resulting Try; if this Try is a success, do nothing.
abstract Try<V>	orElseTry(Callable<V> action)	If this Try is a failure, call the supplied action and return a new successful or failed Try depending on the action's outcome; if this Try is a success, do nothing.
static <V> Try<V>	success(V value)	Convert the supplied value into a succeeded Try.
abstract Optional<V>	toOptional()	If this Try is a failure, return an empty Optional; if this Try is a success, wrap the contained value using Optional.ofNullable(Object).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

call

public static <V> Try<V> call(Callable<V> action)

Call the supplied Callable and return a successful Try that contains the returned value or, in case an exception was thrown, a failed Try that contains the exception.

Parameters:

action - the action to try; must not be null

Returns:

a succeeded or failed Try depending on the outcome of the supplied action; never null

See Also:

success(Object), failure(Exception)

success

public static <V> Try<V> success(V value)

Convert the supplied value into a succeeded Try.

Parameters:

value - the value to wrap; potentially null

Returns:

a succeeded Try that contains the supplied value; never null

failure

public static <V> Try<V> failure(Exception cause)

Convert the supplied exception into a failed Try.

Parameters:

cause - the exception to wrap; must not be null

Returns:

a failed Try that contains the supplied value; never null

andThenTry

public abstract <U> Try<U> andThenTry(Try.Transformer<V,U> transformer)

If this Try is a success, apply the supplied transformer to its value and return a new successful or failed Try depending on the transformer's outcome; if this Try is a failure, do nothing.

Parameters:

transformer - the transformer to try; must not be null

Returns:

a succeeded or failed Try; never null

andThen

public abstract <U> Try<U> andThen(Function<V,Try<U>> function)

If this Try is a success, apply the supplied function to its value and return the resulting Try; if this Try is a failure, do nothing.

Parameters:

function - the function to apply; must not be null

Returns:

a succeeded or failed Try; never null

orElseTry

public abstract Try<V> orElseTry(Callable<V> action)

If this Try is a failure, call the supplied action and return a new successful or failed Try depending on the action's outcome; if this Try is a success, do nothing.

Parameters:

action - the action to try; must not be null

Returns:

a succeeded or failed Try; never null

orElse

public abstract Try<V> orElse(Supplier<Try<V>> supplier)

If this Try is a failure, call the supplied supplier and return the resulting Try; if this Try is a success, do nothing.

Parameters:

supplier - the supplier to call; must not be null

Returns:

a succeeded or failed Try; never null

get

public abstract V get()
               throws Exception

If this Try is a success, get the contained value; if this Try is a failure, throw the contained exception.

Returns:

the contained value, if available; potentially null

Throws:

Exception - if this Try is a failure

getOrThrow

public abstract <E extends Exception> V getOrThrow(Function<? super Exception,E> exceptionTransformer)
                                            throws E extends Exception

If this Try is a success, get the contained value; if this Try is a failure, call the supplied Function with the contained exception and throw the resulting Exception.

Parameters:

exceptionTransformer - the transformer to be called with the contained exception, if available; must not be null

Returns:

the contained value, if available

Throws:

E - if this Try is a failure

E extends Exception

ifSuccess

public abstract Try<V> ifSuccess(Consumer<V> valueConsumer)

If this Try is a success, call the supplied Consumer with the contained value; otherwise, do nothing.

Parameters:

valueConsumer - the consumer to be called with the contained value, if available; must not be null

Returns:

the same Try for method chaining

ifFailure

public abstract Try<V> ifFailure(Consumer<Exception> causeConsumer)

If this Try is a failure, call the supplied Consumer with the contained exception; otherwise, do nothing.

Parameters:

causeConsumer - the consumer to be called with the contained exception, if available; must not be null

Returns:

the same Try for method chaining

toOptional

public abstract Optional<V> toOptional()

If this Try is a failure, return an empty Optional; if this Try is a success, wrap the contained value using Optional.ofNullable(Object).

Returns:

an Optional; never null but potentially empty