io.vavr.control

Interface Try<T>

Type Parameters:

T - Value type in the case of success.

All Superinterfaces:

Iterable<T>, Serializable, Value<T>

All Known Implementing Classes:

Try.Failure, Try.Success

public interface Try<T>
extends Value<T>, Serializable

The Try control gives us the ability write safe code without focusing on try-catch blocks in the presence of exceptions.

The following exceptions are considered to be fatal/non-recoverable:

• InterruptedException
• LinkageError
• ThreadDeath
• VirtualMachineError (i.e. OutOfMemoryError or StackOverflowError)

Important note: Try may re-throw (undeclared) exceptions, e.g. on get(). From within a dynamic proxy InvocationHandler this will lead to an UndeclaredThrowableException. For more information, please read Dynamic Proxy Classes.

Author:

Daniel Dietrich

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Try.Failure<T> A failed Try.
static class	Try.Success<T> A succeeded Try.
static class	Try.WithResources1<T1 extends AutoCloseable> A Try-with-resources builder that operates on one AutoCloseable resource.
static class	Try.WithResources2<T1 extends AutoCloseable,T2 extends AutoCloseable> A Try-with-resources builder that operates on two AutoCloseable resources.
static class	Try.WithResources3<T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable> A Try-with-resources builder that operates on three AutoCloseable resources.
static class	Try.WithResources4<T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable> A Try-with-resources builder that operates on four AutoCloseable resources.
static class	Try.WithResources5<T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable> A Try-with-resources builder that operates on five AutoCloseable resources.
static class	Try.WithResources6<T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable> A Try-with-resources builder that operates on six AutoCloseable resources.
static class	Try.WithResources7<T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable,T7 extends AutoCloseable> A Try-with-resources builder that operates on seven AutoCloseable resources.
static class	Try.WithResources8<T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable,T7 extends AutoCloseable,T8 extends AutoCloseable> A Try-with-resources builder that operates on eight AutoCloseable resources.

Field Summary

Fields

Modifier and Type	Field and Description
static long	serialVersionUID

Method Summary

Modifier and Type	Method and Description
default Try<T>	andFinally(Runnable runnable) Provides try's finally behavior no matter what the result of the operation is.
default Try<T>	andFinallyTry(CheckedRunnable runnable) Provides try's finally behavior no matter what the result of the operation is.
default Try<T>	andThen(Consumer<? super T> consumer) Shortcut for andThenTry(consumer::accept), see andThenTry(CheckedConsumer).
default Try<T>	andThen(Runnable runnable) Shortcut for andThenTry(runnable::run), see andThenTry(CheckedRunnable).
default Try<T>	andThenTry(CheckedConsumer<? super T> consumer) Passes the result to the given consumer if this is a Success.
default Try<T>	andThenTry(CheckedRunnable runnable) Runs the given runnable if this is a Success, otherwise returns this Failure.
default <R> Try<R>	collect(PartialFunction<? super T,? extends R> partialFunction) Collects value that is in the domain of the given partialFunction by mapping the value to type R.
boolean	equals(Object o) Clarifies that values have a proper equals() method implemented.
default Try<Throwable>	failed() Returns Success(throwable) if this is a Failure(throwable), otherwise a Failure(new NoSuchElementException("Success.failed()")) if this is a Success.
static <T> Try<T>	failure(Throwable exception) Creates a Try.Failure that contains the given exception.
default Try<T>	filter(Predicate<? super T> predicate) Shortcut for filterTry(predicate::test), see filterTry(CheckedPredicate)}.
default Try<T>	filter(Predicate<? super T> predicate, Function<? super T,? extends Throwable> errorProvider) Shortcut for filterTry(predicate::test, errorProvider::apply), see filterTry(CheckedPredicate, CheckedFunction1)}.
default Try<T>	filter(Predicate<? super T> predicate, Supplier<? extends Throwable> throwableSupplier) Shortcut for filterTry(predicate::test, throwableSupplier), see filterTry(CheckedPredicate, Supplier)}.
default Try<T>	filterTry(CheckedPredicate<? super T> predicate) Returns this if this is a Failure or this is a Success and the value satisfies the predicate.
default Try<T>	filterTry(CheckedPredicate<? super T> predicate, CheckedFunction1<? super T,? extends Throwable> errorProvider) Returns this if this is a Failure or this is a Success and the value satisfies the predicate.
default Try<T>	filterTry(CheckedPredicate<? super T> predicate, Supplier<? extends Throwable> throwableSupplier) Returns this if this is a Failure or this is a Success and the value satisfies the predicate.
default <U> Try<U>	flatMap(Function<? super T,? extends Try<? extends U>> mapper) Shortcut for flatMapTry(mapper::apply), see flatMapTry(CheckedFunction1).
default <U> Try<U>	flatMapTry(CheckedFunction1<? super T,? extends Try<? extends U>> mapper) FlatMaps the value of a Success or returns a Failure.
default <X> X	fold(Function<? super Throwable,? extends X> ifFail, Function<? super T,? extends X> f) Folds either the Failure or the Success side of the Try value.
T	get() Gets the result of this Try if this is a Success or throws if this is a Failure.
Throwable	getCause() Gets the cause if this is a Failure or throws if this is a Success.
default T	getOrElseGet(Function<? super Throwable,? extends T> other)
default <X extends Throwable> T	getOrElseThrow(Function<? super Throwable,X> exceptionProvider)
int	hashCode() Clarifies that values have a proper hashCode() method implemented.
default boolean	isAsync() A Try's value is computed synchronously.
boolean	isEmpty() Checks whether this Try has no result, i.e.
boolean	isFailure() Checks if this is a Failure.
default boolean	isLazy() A Try's value is computed eagerly.
default boolean	isSingleValued() A Try is a single-valued.
boolean	isSuccess() Checks if this is a Success.
default Iterator<T>	iterator() Returns a rich io.vavr.collection.Iterator.
default <U> Try<U>	map(Function<? super T,? extends U> mapper) Shortcut for mapTry(mapper::apply), see mapTry(CheckedFunction1).
default Try<T>	mapFailure(API.Match.Case<? extends Throwable,? extends Throwable>... cases) Maps the cause to a new exception if this is a Failure or returns this instance if this is a Success.
default <U> Try<U>	mapTry(CheckedFunction1<? super T,? extends U> mapper) Runs the given checked function if this is a Try.Success, passing the result of the current expression to it.
static <T> Try<T>	narrow(Try<? extends T> t) Narrows a widened Try<? extends T> to Try<T> by performing a type-safe cast.
static <T> Try<T>	of(CheckedFunction0<? extends T> supplier) Creates a Try of a CheckedFunction0.
static <T> Try<T>	ofCallable(Callable<? extends T> callable) Creates a Try of a Callable.
static <T> Try<T>	ofSupplier(Supplier<? extends T> supplier) Creates a Try of a Supplier.
default <X extends Throwable> Try<T>	onFailure(Class<X> exceptionType, Consumer<? super X> action) Consumes the cause if this is a Try.Failure and the cause is instance of X.
default Try<T>	onFailure(Consumer<? super Throwable> action) Consumes the cause if this is a Try.Failure.
default Try<T>	onSuccess(Consumer<? super T> action) Consumes the value if this is a Try.Success.
default Try<T>	orElse(Supplier<? extends Try<? extends T>> supplier)
default Try<T>	orElse(Try<? extends T> other)
default void	orElseRun(Consumer<? super Throwable> action)
default Try<T>	peek(Consumer<? super T> action) Applies the action to the value of a Success or does nothing in the case of a Failure.
default <X extends Throwable> Try<T>	recover(Class<X> exceptionType, Function<? super X,? extends T> f) Returns this, if this is a Success or this is a Failure and the cause is not assignable from cause.getClass().
default <X extends Throwable> Try<T>	recover(Class<X> exceptionType, T value) Returns this, if this is a Try.Success or this is a Failure and the cause is not assignable from cause.getClass().
default Try<T>	recover(Function<? super Throwable,? extends T> f) Returns this, if this is a Success, otherwise tries to recover the exception of the failure with f, i.e.
default <X extends Throwable> Try<T>	recoverWith(Class<X> exceptionType, Function<? super X,Try<? extends T>> f) Returns this, if this is a Success or this is a Failure and the cause is not assignable from cause.getClass().
default <X extends Throwable> Try<T>	recoverWith(Class<X> exceptionType, Try<? extends T> recovered) Recovers this Try with the given recovered, if this is a Try.Failure and the given exceptionType is assignable to the underlying cause type.
default Try<T>	recoverWith(Function<? super Throwable,? extends Try<? extends T>> f) Returns this, if this is a Success, otherwise tries to recover the exception of the failure with f, i.e.
static Try<Void>	run(CheckedRunnable runnable) Creates a Try of a CheckedRunnable.
static Try<Void>	runRunnable(Runnable runnable) Creates a Try of a Runnable.
static <T> Try<Seq<T>>	sequence(Iterable<? extends Try<? extends T>> values) Reduces many Trys into a single Try by transforming an Iterable<Try<? extends T>> into a Try<Seq<T>>.
static <T> Try<T>	success(T value) Creates a Try.Success that contains the given value.
default Either<Throwable,T>	toEither() Converts this Try to an Either.
String	toString() Clarifies that values have a proper toString() method implemented.
default Validation<Throwable,T>	toValidation() Converts this Try to a Validation.
default <U> Validation<U,T>	toValidation(Function<? super Throwable,? extends U> throwableMapper) Converts this Try to a Validation, converting the Throwable (if present) to another object using passed Function.
default <U> U	transform(Function<? super Try<T>,? extends U> f) Transforms this Try.
static <T,U> Try<Seq<U>>	traverse(Iterable<? extends T> values, Function<? super T,? extends Try<? extends U>> mapper) Maps the values of an iterable to a sequence of mapped values into a single Try by transforming an Iterable<? extends T> into a Try<Seq<U>>.
static <T1 extends AutoCloseable> Try.WithResources1<T1>	withResources(CheckedFunction0<? extends T1> t1Supplier) Creates a Try-with-resources builder that operates on one AutoCloseable resource.
static <T1 extends AutoCloseable,T2 extends AutoCloseable> Try.WithResources2<T1,T2>	withResources(CheckedFunction0<? extends T1> t1Supplier, CheckedFunction0<? extends T2> t2Supplier) Creates a Try-with-resources builder that operates on two AutoCloseable resources.
static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable> Try.WithResources3<T1,T2,T3>	withResources(CheckedFunction0<? extends T1> t1Supplier, CheckedFunction0<? extends T2> t2Supplier, CheckedFunction0<? extends T3> t3Supplier) Creates a Try-with-resources builder that operates on three AutoCloseable resources.
static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable> Try.WithResources4<T1,T2,T3,T4>	withResources(CheckedFunction0<? extends T1> t1Supplier, CheckedFunction0<? extends T2> t2Supplier, CheckedFunction0<? extends T3> t3Supplier, CheckedFunction0<? extends T4> t4Supplier) Creates a Try-with-resources builder that operates on four AutoCloseable resources.
static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable> Try.WithResources5<T1,T2,T3,T4,T5>	withResources(CheckedFunction0<? extends T1> t1Supplier, CheckedFunction0<? extends T2> t2Supplier, CheckedFunction0<? extends T3> t3Supplier, CheckedFunction0<? extends T4> t4Supplier, CheckedFunction0<? extends T5> t5Supplier) Creates a Try-with-resources builder that operates on five AutoCloseable resources.
static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable> Try.WithResources6<T1,T2,T3,T4,T5,T6>	withResources(CheckedFunction0<? extends T1> t1Supplier, CheckedFunction0<? extends T2> t2Supplier, CheckedFunction0<? extends T3> t3Supplier, CheckedFunction0<? extends T4> t4Supplier, CheckedFunction0<? extends T5> t5Supplier, CheckedFunction0<? extends T6> t6Supplier) Creates a Try-with-resources builder that operates on six AutoCloseable resources.
static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable,T7 extends AutoCloseable> Try.WithResources7<T1,T2,T3,T4,T5,T6,T7>	withResources(CheckedFunction0<? extends T1> t1Supplier, CheckedFunction0<? extends T2> t2Supplier, CheckedFunction0<? extends T3> t3Supplier, CheckedFunction0<? extends T4> t4Supplier, CheckedFunction0<? extends T5> t5Supplier, CheckedFunction0<? extends T6> t6Supplier, CheckedFunction0<? extends T7> t7Supplier) Creates a Try-with-resources builder that operates on seven AutoCloseable resources.
static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable,T7 extends AutoCloseable,T8 extends AutoCloseable> Try.WithResources8<T1,T2,T3,T4,T5,T6,T7,T8>	withResources(CheckedFunction0<? extends T1> t1Supplier, CheckedFunction0<? extends T2> t2Supplier, CheckedFunction0<? extends T3> t3Supplier, CheckedFunction0<? extends T4> t4Supplier, CheckedFunction0<? extends T5> t5Supplier, CheckedFunction0<? extends T6> t6Supplier, CheckedFunction0<? extends T7> t7Supplier, CheckedFunction0<? extends T8> t8Supplier) Creates a Try-with-resources builder that operates on eight AutoCloseable resources.

Methods inherited from interface io.vavr.Value

collect, collect, contains, corresponds, eq, exists, forAll, forEach, getOrElse, getOrElse, getOrElseThrow, getOrElseTry, getOrNull, narrow, out, out, spliterator, stderr, stdout, stringPrefix, toArray, toCharSeq, toCompletableFuture, toEither, toEither, toInvalid, toInvalid, toJavaArray, toJavaArray, toJavaArray, toJavaCollection, toJavaList, toJavaList, toJavaMap, toJavaMap, toJavaMap, toJavaOptional, toJavaParallelStream, toJavaSet, toJavaSet, toJavaStream, toLeft, toLeft, toLinkedMap, toLinkedMap, toLinkedSet, toList, toMap, toMap, toOption, toPriorityQueue, toPriorityQueue, toQueue, toRight, toRight, toSet, toSortedMap, toSortedMap, toSortedMap, toSortedMap, toSortedSet, toSortedSet, toStream, toTree, toTree, toTry, toTry, toValid, toValid, toValidation, toValidation, toVector

Field Detail

serialVersionUID

static final long serialVersionUID

See Also:

Constant Field Values

Method Detail

of

static <T> Try<T> of(CheckedFunction0<? extends T> supplier)

Creates a Try of a CheckedFunction0.

Type Parameters:

T - Component type

Parameters:

supplier - A checked supplier

Returns:

Success(supplier.apply()) if no exception occurs, otherwise Failure(throwable) if an exception occurs calling supplier.apply().

ofSupplier

static <T> Try<T> ofSupplier(Supplier<? extends T> supplier)

Creates a Try of a Supplier.

Type Parameters:

T - Component type

Parameters:

supplier - A supplier

Returns:

Success(supplier.get()) if no exception occurs, otherwise Failure(throwable) if an exception occurs calling supplier.get().

ofCallable

static <T> Try<T> ofCallable(Callable<? extends T> callable)

Creates a Try of a Callable.

Type Parameters:

T - Component type

Parameters:

callable - A callable

Returns:

Success(callable.call()) if no exception occurs, otherwise Failure(throwable) if an exception occurs calling callable.call().

run

static Try<Void> run(CheckedRunnable runnable)

Creates a Try of a CheckedRunnable.

Parameters:

runnable - A checked runnable

Returns:

Success(null) if no exception occurs, otherwise Failure(throwable) if an exception occurs calling runnable.run().

runRunnable

static Try<Void> runRunnable(Runnable runnable)

Creates a Try of a Runnable.

Parameters:

runnable - A runnable

Returns:

Success(null) if no exception occurs, otherwise Failure(throwable) if an exception occurs calling runnable.run().

sequence

static <T> Try<Seq<T>> sequence(Iterable<? extends Try<? extends T>> values)

Reduces many Trys into a single Try by transforming an Iterable<Try<? extends T>> into a Try<Seq<T>>. If any of the Trys are Try.Failure, then this returns a Try.Failure.

Type Parameters:

T - type of the Trys

Parameters:

values - An Iterable of Trys

Returns:

A Try of a Seq of results

Throws:

NullPointerException - if values is null

traverse

static <T,U> Try<Seq<U>> traverse(Iterable<? extends T> values,
                                  Function<? super T,? extends Try<? extends U>> mapper)

Maps the values of an iterable to a sequence of mapped values into a single Try by transforming an Iterable<? extends T> into a Try<Seq<U>>.

Type Parameters:

T - The type of the given values.

U - The mapped value type.

Parameters:

values - An Iterable of values.

mapper - A mapper of values to Trys

Returns:

A Try of a Seq of results.

Throws:

NullPointerException - if values or f is null.

success

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

Creates a Try.Success that contains the given value. Shortcut for new Success<>(value).

Type Parameters:

T - Type of the given value.

Parameters:

value - A value.

Returns:

A new Success.

failure

static <T> Try<T> failure(Throwable exception)

Creates a Try.Failure that contains the given exception. Shortcut for new Failure<>(exception).

Type Parameters:

T - Component type of the Try.

Parameters:

exception - An exception.

Returns:

A new Failure.

narrow

static <T> Try<T> narrow(Try<? extends T> t)

Narrows a widened Try<? extends T> to Try<T> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.

Type Parameters:

T - Component type of the Try.

Parameters:

t - A Try.

Returns:

the given t instance as narrowed type Try<T>.

andThen

default Try<T> andThen(Consumer<? super T> consumer)

Shortcut for andThenTry(consumer::accept), see andThenTry(CheckedConsumer).

Parameters:

consumer - A consumer

Returns:

this Try if this is a Failure or the consumer succeeded, otherwise the Failure of the consumption.

Throws:

NullPointerException - if consumer is null

andThenTry

default Try<T> andThenTry(CheckedConsumer<? super T> consumer)

Passes the result to the given consumer if this is a Success.

The main use case is chaining checked functions using method references:

 
 Try.of(() -> 100)
    .andThen(i -> System.out.println(i));

 
 

Parameters:

consumer - A checked consumer

Returns:

this Try if this is a Failure or the consumer succeeded, otherwise the Failure of the consumption.

Throws:

NullPointerException - if consumer is null

andThen

default Try<T> andThen(Runnable runnable)

Shortcut for andThenTry(runnable::run), see andThenTry(CheckedRunnable).

Parameters:

runnable - A runnable

Returns:

this Try if this is a Failure or the runnable succeeded, otherwise the Failure of the run.

Throws:

NullPointerException - if runnable is null

andThenTry

default Try<T> andThenTry(CheckedRunnable runnable)

Runs the given runnable if this is a Success, otherwise returns this Failure.

The main use case is chaining runnables using method references:

 
 Try.run(A::methodRef).andThen(B::methodRef).andThen(C::methodRef);
 
 

Please note that these lines are semantically the same:

 
 Try.run(this::doStuff)
    .andThen(this::doMoreStuff)
    .andThen(this::doEvenMoreStuff);

 Try.run(() -> {
     doStuff();
     doMoreStuff();
     doEvenMoreStuff();
 });
 
 

Parameters:

runnable - A checked runnable

Returns:

this Try if this is a Failure or the runnable succeeded, otherwise the Failure of the run.

Throws:

NullPointerException - if runnable is null

collect

default <R> Try<R> collect(PartialFunction<? super T,? extends R> partialFunction)

Collects value that is in the domain of the given partialFunction by mapping the value to type R.

 partialFunction.isDefinedAt(value)
 

If the element makes it through that filter, the mapped instance is wrapped in Try

 R newValue = partialFunction.apply(value)
 

Type Parameters:

R - The new value type

Parameters:

partialFunction - A function that is not necessarily defined on value of this try.

Returns:

A new Try instance containing value of type R

Throws:

NullPointerException - if partialFunction is null

failed

default Try<Throwable> failed()

Returns Success(throwable) if this is a Failure(throwable), otherwise a Failure(new NoSuchElementException("Success.failed()")) if this is a Success.

Returns:

a new Try

filter

default Try<T> filter(Predicate<? super T> predicate,
                      Supplier<? extends Throwable> throwableSupplier)

Shortcut for filterTry(predicate::test, throwableSupplier), see filterTry(CheckedPredicate, Supplier)}.

Parameters:

predicate - A predicate

throwableSupplier - A supplier of a throwable

Returns:

a Try instance

Throws:

NullPointerException - if predicate or throwableSupplier is null

filter

default Try<T> filter(Predicate<? super T> predicate,
                      Function<? super T,? extends Throwable> errorProvider)

Shortcut for filterTry(predicate::test, errorProvider::apply), see filterTry(CheckedPredicate, CheckedFunction1)}.

Parameters:

predicate - A predicate

errorProvider - A function that provides some kind of Throwable for T

Returns:

a Try instance

Throws:

NullPointerException - if predicate or errorProvider is null

filter

default Try<T> filter(Predicate<? super T> predicate)

Shortcut for filterTry(predicate::test), see filterTry(CheckedPredicate)}.

Parameters:

predicate - A predicate

Returns:

a Try instance

Throws:

NullPointerException - if predicate is null

filterTry

default Try<T> filterTry(CheckedPredicate<? super T> predicate,
                         Supplier<? extends Throwable> throwableSupplier)

Returns this if this is a Failure or this is a Success and the value satisfies the predicate.

Returns a new Failure, if this is a Success and the value does not satisfy the Predicate or an exception occurs testing the predicate. The returned Failure wraps a Throwable instance provided by the given throwableSupplier.

Parameters:

predicate - A checked predicate

throwableSupplier - A supplier of a throwable

Returns:

a Try instance

Throws:

NullPointerException - if predicate or throwableSupplier is null

filterTry

default Try<T> filterTry(CheckedPredicate<? super T> predicate,
                         CheckedFunction1<? super T,? extends Throwable> errorProvider)

Returns this if this is a Failure or this is a Success and the value satisfies the predicate.

Returns a new Failure, if this is a Success and the value does not satisfy the Predicate or an exception occurs testing the predicate. The returned Failure wraps a Throwable instance provided by the given errorProvider.

Parameters:

predicate - A checked predicate

errorProvider - A provider of a throwable

Returns:

a Try instance

Throws:

NullPointerException - if predicate or errorProvider is null

filterTry

default Try<T> filterTry(CheckedPredicate<? super T> predicate)

Returns this if this is a Failure or this is a Success and the value satisfies the predicate.

Returns a new Failure, if this is a Success and the value does not satisfy the Predicate or an exception occurs testing the predicate. The returned Failure wraps a NoSuchElementException instance.

Parameters:

predicate - A checked predicate

Returns:

a Try instance

Throws:

NullPointerException - if predicate is null

flatMap

default <U> Try<U> flatMap(Function<? super T,? extends Try<? extends U>> mapper)

Shortcut for flatMapTry(mapper::apply), see flatMapTry(CheckedFunction1).

Type Parameters:

U - The new component type

Parameters:

mapper - A mapper

Returns:

a Try

Throws:

NullPointerException - if mapper is null

flatMapTry

default <U> Try<U> flatMapTry(CheckedFunction1<? super T,? extends Try<? extends U>> mapper)

FlatMaps the value of a Success or returns a Failure.

Type Parameters:

U - The new component type

Parameters:

mapper - A mapper

Returns:

a Try

Throws:

NullPointerException - if mapper is null

get

T get()

Gets the result of this Try if this is a Success or throws if this is a Failure.

IMPORTANT! If this is a Try.Failure, the underlying cause of type Throwable is thrown.

The thrown exception is exactly the same as the result of getCause().

Specified by:

get in interface Value<T>

Returns:

The result of this Try.

getCause

Throwable getCause()

Gets the cause if this is a Failure or throws if this is a Success.

Returns:

The cause if this is a Failure

Throws:

UnsupportedOperationException - if this is a Success

isAsync

default boolean isAsync()

A Try's value is computed synchronously.

Specified by:

isAsync in interface Value<T>

Returns:

false

isEmpty

boolean isEmpty()

Checks whether this Try has no result, i.e. is a Failure.

Specified by:

isEmpty in interface Value<T>

Returns:

true if this is a Failure, returns false if this is a Success.

isFailure

boolean isFailure()

Checks if this is a Failure.

Returns:

true, if this is a Failure, otherwise false, if this is a Success

isLazy

default boolean isLazy()

A Try's value is computed eagerly.

Specified by:

isLazy in interface Value<T>

Returns:

false

isSingleValued

default boolean isSingleValued()

A Try is a single-valued.

Specified by:

isSingleValued in interface Value<T>

Returns:

true

isSuccess

boolean isSuccess()

Checks if this is a Success.

Returns:

true, if this is a Success, otherwise false, if this is a Failure

iterator

default Iterator<T> iterator()

Description copied from interface: Value

Returns a rich io.vavr.collection.Iterator.

Specified by:

iterator in interface Iterable<T>

Specified by:

iterator in interface Value<T>

Returns:

A new Iterator

map

default <U> Try<U> map(Function<? super T,? extends U> mapper)

Shortcut for mapTry(mapper::apply), see mapTry(CheckedFunction1).

Specified by:

map in interface Value<T>

Type Parameters:

U - The new component type

Parameters:

mapper - A checked function

Returns:

a Try

Throws:

NullPointerException - if mapper is null

mapFailure

@GwtIncompatible
default Try<T> mapFailure(API.Match.Case<? extends Throwable,? extends Throwable>... cases)

Maps the cause to a new exception if this is a Failure or returns this instance if this is a Success.

If none of the given cases matches the cause, the same Failure is returned.

Parameters:

cases - A not necessarily exhaustive sequence of cases that will be matched against a cause.

Returns:

A new Try if this is a Failure, otherwise this.

mapTry

default <U> Try<U> mapTry(CheckedFunction1<? super T,? extends U> mapper)

Runs the given checked function if this is a Try.Success, passing the result of the current expression to it. If this expression is a Try.Failure then it'll return a new Try.Failure of type R with the original exception.

The main use case is chaining checked functions using method references:

 
 Try.of(() -> 0)
    .map(x -> 1 / x); // division by zero
 
 

Type Parameters:

U - The new component type

Parameters:

mapper - A checked function

Returns:

a Try

Throws:

NullPointerException - if mapper is null

onFailure

default Try<T> onFailure(Consumer<? super Throwable> action)

Consumes the cause if this is a Try.Failure.

 // (does not print anything)
 Try.success(1).onFailure(System.out::println);

 // prints "java.lang.Error"
 Try.failure(new Error()).onFailure(System.out::println);
 

Parameters:

action - An exception consumer

Returns:

this

Throws:

NullPointerException - if action is null

onFailure

@GwtIncompatible
default <X extends Throwable> Try<T> onFailure(Class<X> exceptionType,
                                                                Consumer<? super X> action)

Consumes the cause if this is a Try.Failure and the cause is instance of X.

 // (does not print anything)
 Try.success(1).onFailure(Error.class, System.out::println);

 // prints "Error"
 Try.failure(new Error())
    .onFailure(RuntimeException.class, x -> System.out.println("Runtime exception"))
    .onFailure(Error.class, x -> System.out.println("Error"));
 

Type Parameters:

X - the exception type that should be handled

Parameters:

exceptionType - the exception type that is handled

action - an excpetion consumer

Returns:

this

Throws:

NullPointerException - if exceptionType or action is null

onSuccess

default Try<T> onSuccess(Consumer<? super T> action)

Consumes the value if this is a Try.Success.

 // prints "1"
 Try.success(1).onSuccess(System.out::println);

 // (does not print anything)
 Try.failure(new Error()).onSuccess(System.out::println);
 

Parameters:

action - A value consumer

Returns:

this

Throws:

NullPointerException - if action is null

orElse

default Try<T> orElse(Try<? extends T> other)

orElse

default Try<T> orElse(Supplier<? extends Try<? extends T>> supplier)

getOrElseGet

default T getOrElseGet(Function<? super Throwable,? extends T> other)

orElseRun

default void orElseRun(Consumer<? super Throwable> action)

getOrElseThrow

default <X extends Throwable> T getOrElseThrow(Function<? super Throwable,X> exceptionProvider)
                                        throws X extends Throwable

Throws:

X extends Throwable

fold

default <X> X fold(Function<? super Throwable,? extends X> ifFail,
                   Function<? super T,? extends X> f)

Folds either the Failure or the Success side of the Try value.

Type Parameters:

X - type of the folded value

Parameters:

ifFail - maps the left value if this is a Failure

f - maps the value if this is a Success

Returns:

A value of type X

peek

default Try<T> peek(Consumer<? super T> action)

Applies the action to the value of a Success or does nothing in the case of a Failure.

Specified by:

peek in interface Value<T>

Parameters:

action - A Consumer

Returns:

this Try

Throws:

NullPointerException - if action is null

recover

@GwtIncompatible
default <X extends Throwable> Try<T> recover(Class<X> exceptionType,
                                                              Function<? super X,? extends T> f)

Returns this, if this is a Success or this is a Failure and the cause is not assignable from cause.getClass(). Otherwise tries to recover the exception of the failure with f, i.e. calling Try.of(() -> f.apply((X) getCause()).

 // = Success(13)
 Try.of(() -> 27/2).recover(ArithmeticException.class, x -> Integer.MAX_VALUE);

 // = Success(2147483647)
 Try.of(() -> 1/0)
    .recover(Error.class, x -> -1)
    .recover(ArithmeticException.class, x -> Integer.MAX_VALUE);

 // = Failure(java.lang.ArithmeticException: / by zero)
 Try.of(() -> 1/0).recover(Error.class, x -> Integer.MAX_VALUE);
 

Type Parameters:

X - Exception type

Parameters:

exceptionType - The specific exception type that should be handled

f - A recovery function taking an exception of type X

Returns:

a Try

Throws:

NullPointerException - if exception is null or f is null

recoverWith

@GwtIncompatible
default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType,
                                                                  Function<? super X,Try<? extends T>> f)

Returns this, if this is a Success or this is a Failure and the cause is not assignable from cause.getClass(). Otherwise tries to recover the exception of the failure with f which returns Try. If isFailure() returned by f function is true it means that recovery cannot take place due to some circumstances.

 // = Success(13)
 Try.of(() -> 27/2).recoverWith(ArithmeticException.class, x -> Try.success(Integer.MAX_VALUE));

 // = Success(2147483647)
 Try.of(() -> 1/0)
    .recoverWith(Error.class, x -> Try.success(-1))
    .recoverWith(ArithmeticException.class, x -> Try.success(Integer.MAX_VALUE));

 // = Failure(java.lang.ArithmeticException: / by zero)
 Try.of(() -> 1/0).recoverWith(Error.class, x -> Try.success(Integer.MAX_VALUE));
 

Type Parameters:

X - Exception type

Parameters:

exceptionType - The specific exception type that should be handled

f - A recovery function taking an exception of type X and returning Try as a result of recovery. If Try is isSuccess() then recovery ends up successfully. Otherwise the function was not able to recover.

Returns:

a Try

Throws:

NullPointerException - if exceptionType or f is null

recoverWith

@GwtIncompatible
default <X extends Throwable> Try<T> recoverWith(Class<X> exceptionType,
                                                                  Try<? extends T> recovered)

Recovers this Try with the given recovered, if this is a Try.Failure and the given exceptionType is assignable to the underlying cause type.

 // = Success(13)
 Try.of(() -> 27/2).recoverWith(ArithmeticException.class, Try.success(Integer.MAX_VALUE));

 // = Success(2147483647)
 Try.of(() -> 1/0)
    .recoverWith(Error.class, Try.success(-1))
    .recoverWith(ArithmeticException.class, Try.success(Integer.MAX_VALUE));

 // = Failure(java.lang.ArithmeticException: / by zero)
 Try.of(() -> 1/0).recoverWith(Error.class, Try.success(Integer.MAX_VALUE));
 

Type Parameters:

X - type of the exception that should be recovered

Parameters:

exceptionType - the exception type that is recovered

recovered - the substitute for a matching Failure

Returns:

the given recovered if this is a Try.Failure and the cause is of type X, else this

Throws:

NullPointerException - if exceptionType or recovered is null

recover

@GwtIncompatible
default <X extends Throwable> Try<T> recover(Class<X> exceptionType,
                                                              T value)

Returns this, if this is a Try.Success or this is a Failure and the cause is not assignable from cause.getClass(). Otherwise returns a Try.Success containing the given value.

 // = Success(13)
 Try.of(() -> 27/2).recover(ArithmeticException.class, Integer.MAX_VALUE);

 // = Success(2147483647)
 Try.of(() -> 1/0)
    .recover(Error.class, -1);
    .recover(ArithmeticException.class, Integer.MAX_VALUE);

 // = Failure(java.lang.ArithmeticException: / by zero)
 Try.of(() -> 1/0).recover(Error.class, Integer.MAX_VALUE);
 

Type Parameters:

X - Exception type

Parameters:

exceptionType - The specific exception type that should be handled

value - A value that is used in case of a recovery

Returns:

a Try

Throws:

NullPointerException - if exception is null

recover

default Try<T> recover(Function<? super Throwable,? extends T> f)

Returns this, if this is a Success, otherwise tries to recover the exception of the failure with f, i.e. calling Try.of(() -> f.apply(throwable)).

 // = Success(13)
 Try.of(() -> 27/2).recover(x -> Integer.MAX_VALUE);

 // = Success(2147483647)
 Try.of(() -> 1/0).recover(x -> Integer.MAX_VALUE);
 

Parameters:

f - A recovery function taking a Throwable

Returns:

a Try

Throws:

NullPointerException - if f is null

recoverWith

default Try<T> recoverWith(Function<? super Throwable,? extends Try<? extends T>> f)

Returns this, if this is a Success, otherwise tries to recover the exception of the failure with f, i.e. calling f.apply(cause.getCause()). If an error occurs recovering a Failure, then the new Failure is returned.

 // = Success(13)
 Try.of(() -> 27/2).recoverWith(x -> Try.success(Integer.MAX_VALUE));

 // = Success(2147483647)
 Try.of(() -> 1/0).recoverWith(x -> Try.success(Integer.MAX_VALUE));
 

Parameters:

f - A recovery function taking a Throwable

Returns:

a Try

Throws:

NullPointerException - if f is null

toEither

default Either<Throwable,T> toEither()

Converts this Try to an Either.

Returns:

A new Either

toValidation

default Validation<Throwable,T> toValidation()

Converts this Try to a Validation.

Returns:

A new Validation

toValidation

default <U> Validation<U,T> toValidation(Function<? super Throwable,? extends U> throwableMapper)

Converts this Try to a Validation, converting the Throwable (if present) to another object using passed Function.

 Validation<String, Integer> = Try.of(() -> 1/0).toValidation(Throwable::getMessage));
 

Type Parameters:

U - result type of the throwable mapper

Parameters:

throwableMapper - A transformation from throwable to desired invalid type of new Validation

Returns:

A new Validation

Throws:

NullPointerException - if the given throwableMapper is null.

transform

default <U> U transform(Function<? super Try<T>,? extends U> f)

Transforms this Try.

Type Parameters:

U - Type of transformation result

Parameters:

f - A transformation

Returns:

An instance of type U

Throws:

NullPointerException - if f is null

andFinally

default Try<T> andFinally(Runnable runnable)

Provides try's finally behavior no matter what the result of the operation is.

Parameters:

runnable - A runnable

Returns:

this Try.

Throws:

NullPointerException - if runnable is null

andFinallyTry

default Try<T> andFinallyTry(CheckedRunnable runnable)

Provides try's finally behavior no matter what the result of the operation is.

Parameters:

runnable - A runnable

Returns:

this Try.

Throws:

NullPointerException - if runnable is null

equals

boolean equals(Object o)

Description copied from interface: Value

Clarifies that values have a proper equals() method implemented.

See Object.equals(Object).

Specified by:

equals in interface Value<T>

Overrides:

equals in class Object

Parameters:

o - An object

Returns:

true, if this equals o, false otherwise

hashCode

int hashCode()

Description copied from interface: Value

Clarifies that values have a proper hashCode() method implemented.

See Object.hashCode().

Specified by:

hashCode in interface Value<T>

Overrides:

hashCode in class Object

Returns:

The hashcode of this object

toString

String toString()

Description copied from interface: Value

Clarifies that values have a proper toString() method implemented.

See Object.toString().

Specified by:

toString in interface Value<T>

Overrides:

toString in class Object

Returns:

A String representation of this object

withResources

static <T1 extends AutoCloseable> Try.WithResources1<T1> withResources(CheckedFunction0<? extends T1> t1Supplier)

Creates a Try-with-resources builder that operates on one AutoCloseable resource.

Type Parameters:

T1 - Type of the 1st resource.

Parameters:

t1Supplier - The supplier of the first resource.

Returns:

a new Try.WithResources1 instance.

withResources

static <T1 extends AutoCloseable,T2 extends AutoCloseable> Try.WithResources2<T1,T2> withResources(CheckedFunction0<? extends T1> t1Supplier,
                                                                                                   CheckedFunction0<? extends T2> t2Supplier)

Creates a Try-with-resources builder that operates on two AutoCloseable resources.

Type Parameters:

T1 - Type of the 1st resource.

T2 - Type of the 2nd resource.

Parameters:

t1Supplier - The supplier of the 1st resource.

t2Supplier - The supplier of the 2nd resource.

Returns:

a new Try.WithResources2 instance.

withResources

static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable> Try.WithResources3<T1,T2,T3> withResources(CheckedFunction0<? extends T1> t1Supplier,
                                                                                                                               CheckedFunction0<? extends T2> t2Supplier,
                                                                                                                               CheckedFunction0<? extends T3> t3Supplier)

Creates a Try-with-resources builder that operates on three AutoCloseable resources.

Type Parameters:

T1 - Type of the 1st resource.

T2 - Type of the 2nd resource.

T3 - Type of the 3rd resource.

Parameters:

t1Supplier - The supplier of the 1st resource.

t2Supplier - The supplier of the 2nd resource.

t3Supplier - The supplier of the 3rd resource.

Returns:

a new Try.WithResources3 instance.

withResources

static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable> Try.WithResources4<T1,T2,T3,T4> withResources(CheckedFunction0<? extends T1> t1Supplier,
                                                                                                                                                           CheckedFunction0<? extends T2> t2Supplier,
                                                                                                                                                           CheckedFunction0<? extends T3> t3Supplier,
                                                                                                                                                           CheckedFunction0<? extends T4> t4Supplier)

Creates a Try-with-resources builder that operates on four AutoCloseable resources.

Type Parameters:

T1 - Type of the 1st resource.

T2 - Type of the 2nd resource.

T3 - Type of the 3rd resource.

T4 - Type of the 4th resource.

Parameters:

t1Supplier - The supplier of the 1st resource.

t2Supplier - The supplier of the 2nd resource.

t3Supplier - The supplier of the 3rd resource.

t4Supplier - The supplier of the 4th resource.

Returns:

a new Try.WithResources4 instance.

withResources

static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable> Try.WithResources5<T1,T2,T3,T4,T5> withResources(CheckedFunction0<? extends T1> t1Supplier,
                                                                                                                                                                                       CheckedFunction0<? extends T2> t2Supplier,
                                                                                                                                                                                       CheckedFunction0<? extends T3> t3Supplier,
                                                                                                                                                                                       CheckedFunction0<? extends T4> t4Supplier,
                                                                                                                                                                                       CheckedFunction0<? extends T5> t5Supplier)

Creates a Try-with-resources builder that operates on five AutoCloseable resources.

Type Parameters:

T1 - Type of the 1st resource.

T2 - Type of the 2nd resource.

T3 - Type of the 3rd resource.

T4 - Type of the 4th resource.

T5 - Type of the 5th resource.

Parameters:

t1Supplier - The supplier of the 1st resource.

t2Supplier - The supplier of the 2nd resource.

t3Supplier - The supplier of the 3rd resource.

t4Supplier - The supplier of the 4th resource.

t5Supplier - The supplier of the 5th resource.

Returns:

a new Try.WithResources5 instance.

withResources

static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable> Try.WithResources6<T1,T2,T3,T4,T5,T6> withResources(CheckedFunction0<? extends T1> t1Supplier,
                                                                                                                                                                                                                   CheckedFunction0<? extends T2> t2Supplier,
                                                                                                                                                                                                                   CheckedFunction0<? extends T3> t3Supplier,
                                                                                                                                                                                                                   CheckedFunction0<? extends T4> t4Supplier,
                                                                                                                                                                                                                   CheckedFunction0<? extends T5> t5Supplier,
                                                                                                                                                                                                                   CheckedFunction0<? extends T6> t6Supplier)

Creates a Try-with-resources builder that operates on six AutoCloseable resources.

Type Parameters:

T1 - Type of the 1st resource.

T2 - Type of the 2nd resource.

T3 - Type of the 3rd resource.

T4 - Type of the 4th resource.

T5 - Type of the 5th resource.

T6 - Type of the 6th resource.

Parameters:

t1Supplier - The supplier of the 1st resource.

t2Supplier - The supplier of the 2nd resource.

t3Supplier - The supplier of the 3rd resource.

t4Supplier - The supplier of the 4th resource.

t5Supplier - The supplier of the 5th resource.

t6Supplier - The supplier of the 6th resource.

Returns:

a new Try.WithResources6 instance.

withResources

static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable,T7 extends AutoCloseable> Try.WithResources7<T1,T2,T3,T4,T5,T6,T7> withResources(CheckedFunction0<? extends T1> t1Supplier,
                                                                                                                                                                                                                                               CheckedFunction0<? extends T2> t2Supplier,
                                                                                                                                                                                                                                               CheckedFunction0<? extends T3> t3Supplier,
                                                                                                                                                                                                                                               CheckedFunction0<? extends T4> t4Supplier,
                                                                                                                                                                                                                                               CheckedFunction0<? extends T5> t5Supplier,
                                                                                                                                                                                                                                               CheckedFunction0<? extends T6> t6Supplier,
                                                                                                                                                                                                                                               CheckedFunction0<? extends T7> t7Supplier)

Creates a Try-with-resources builder that operates on seven AutoCloseable resources.

Type Parameters:

T1 - Type of the 1st resource.

T2 - Type of the 2nd resource.

T3 - Type of the 3rd resource.

T4 - Type of the 4th resource.

T5 - Type of the 5th resource.

T6 - Type of the 6th resource.

T7 - Type of the 7th resource.

Parameters:

t1Supplier - The supplier of the 1st resource.

t2Supplier - The supplier of the 2nd resource.

t3Supplier - The supplier of the 3rd resource.

t4Supplier - The supplier of the 4th resource.

t5Supplier - The supplier of the 5th resource.

t6Supplier - The supplier of the 6th resource.

t7Supplier - The supplier of the 7th resource.

Returns:

a new Try.WithResources7 instance.

withResources

static <T1 extends AutoCloseable,T2 extends AutoCloseable,T3 extends AutoCloseable,T4 extends AutoCloseable,T5 extends AutoCloseable,T6 extends AutoCloseable,T7 extends AutoCloseable,T8 extends AutoCloseable> Try.WithResources8<T1,T2,T3,T4,T5,T6,T7,T8> withResources(CheckedFunction0<? extends T1> t1Supplier,
                                                                                                                                                                                                                                                                           CheckedFunction0<? extends T2> t2Supplier,
                                                                                                                                                                                                                                                                           CheckedFunction0<? extends T3> t3Supplier,
                                                                                                                                                                                                                                                                           CheckedFunction0<? extends T4> t4Supplier,
                                                                                                                                                                                                                                                                           CheckedFunction0<? extends T5> t5Supplier,
                                                                                                                                                                                                                                                                           CheckedFunction0<? extends T6> t6Supplier,
                                                                                                                                                                                                                                                                           CheckedFunction0<? extends T7> t7Supplier,
                                                                                                                                                                                                                                                                           CheckedFunction0<? extends T8> t8Supplier)

Creates a Try-with-resources builder that operates on eight AutoCloseable resources.

Type Parameters:

T1 - Type of the 1st resource.

T2 - Type of the 2nd resource.

T3 - Type of the 3rd resource.

T4 - Type of the 4th resource.

T5 - Type of the 5th resource.

T6 - Type of the 6th resource.

T7 - Type of the 7th resource.

T8 - Type of the 8th resource.

Parameters:

t1Supplier - The supplier of the 1st resource.

t2Supplier - The supplier of the 2nd resource.

t3Supplier - The supplier of the 3rd resource.

t4Supplier - The supplier of the 4th resource.

t5Supplier - The supplier of the 5th resource.

t6Supplier - The supplier of the 6th resource.

t7Supplier - The supplier of the 7th resource.

t8Supplier - The supplier of the 8th resource.

Returns:

a new Try.WithResources8 instance.