Try

The Try type represents a value of one of two possible types (a disjoint union) of Success or Failure .

Factory methods Try#success(Object) and Try#failure(Throwable) correspond to the two possible values.

Follows the Railway Pattern , that is, once failed, stays failed.

API

Try.java
interface Try<T> {
  Try<T> empty()     (1)
  Try<T> call(Callable<T> callable)
  Try<Void> run(ThrowingRunnable runnable)
  Success<T> success(T value)
  Failure<T> failure(Throwable throwable)
  boolean isSuccess()
  boolean isFailure()
  Optional<T> getValue()     (2)
  Optional<Throwable> getFailure()     (3)
  Try<T> ifSuccess(ThrowingConsumer<Optional<T>> valueConsumer)     (4)
  Try<T> ifSuccessAsNullable(ThrowingConsumer<T> valueConsumer)     (5)
  Try<T> ifFailure(ThrowingConsumer<Throwable> exceptionConsumer)     (6)
  Try<T> ifFailureFail()     (7)
  Try<T> ifAbsentFail()     (8)
  Try<R> mapSuccess(ThrowingFunction<Optional<T>, R> successMapper)     (9)
  Try<R> mapSuccessAsNullable(ThrowingFunction<T, R> successMapper)     (10)
  Try<R> mapSuccessWhenPresent(ThrowingFunction<T, R> successMapper)     (11)
  Try<T> mapFailure(ThrowingFunction<Throwable, Throwable> failureMapper)     (12)
  Try<T> mapFailureToSuccess(ThrowingFunction<Throwable, T> recoveryMapper)     (13)
  Try<T> mapEmptyToFailure()     (14)
  Either<L, R> mapToEither(ThrowingFunction<Throwable, L> failureMapper, ThrowingFunction<Optional<T>, R> successMapper)     (15)
  Try<R> flatMapSuccess(ThrowingFunction<Optional<T>, Try<R>> successMapper)     (16)
  Try<R> flatMapSuccessAsNullable(ThrowingFunction<T, Try<R>> successMapper)     (17)
  Try<R> flatMapSuccessWhenPresent(ThrowingFunction<T, Try<R>> successMapper)     (18)
  Try<T> accept(ThrowingConsumer<Throwable> failureConsumer, ThrowingConsumer<Optional<T>> successConsumer)     (19)
  R fold(ThrowingFunction<Throwable, R> failureMapper, ThrowingFunction<Optional<T>, R> successMapper)     (20)
  Try<R> thenCall(Callable<R> callable)     (21)
  Try<Void> thenRun(ThrowingRunnable runnable)     (22)
  Try<R> then(Callable<? extends Try<R>> next)     (23)
  Try<T> orCall(Callable<T> fallback)     (24)
  T valueAsNullableElseFail()     (25)
  T valueAsNonNullElseFail()     (26)
}
1 empty()

success case with no value
2 getValue()

Optionally returns the contained value based on presence, that is, if this is a Success and the value is not null .
3 getFailure()

Optionally returns the contained failure based on presence, that is, if this is a Failure .
4 ifSuccess(ThrowingConsumer)

If this is a Success , peeks into the value wrapped in an Optional .
5 ifSuccessAsNullable(ThrowingConsumer)

If this is a Success peeks into the (null-able) value .
6 ifFailure(ThrowingConsumer)

If this is a Failure , peeks into the failure .
7 ifFailureFail()

Throws the contained failure if any.
8 ifAbsentFail()

Throws NoSuchElementException if value is null .
9 mapSuccess(ThrowingFunction)

If this is a Success , maps this Try to another, by calling the successMapper with the value wrapped by an Optional . Otherwise if this is a Failure , acts as identity operator, though implementations may return a new instance.
10 mapSuccessAsNullable(ThrowingFunction)

If this is a Success , maps this Try to another, by calling the successMapper with the value (which may be null). Otherwise if this is a Failure , acts as identity operator, though implementations may return a new instance.
11 mapSuccessWhenPresent(ThrowingFunction)

If this Try holds a non-null value (and hence is also a Success ), maps this Try to another, by calling the successMapper with the value (which is non-null). Otherwise acts as identity operator, that is, either stay an empty Success or stay a Failure , though implementations may return a new instance.
12 mapFailure(ThrowingFunction)

If this is a Failure , maps this Try to another. Otherwise if this is a Success acts as identity operator, though implementations may return a new instance.
13 mapFailureToSuccess(ThrowingFunction)

If this is a Failure , recovers to a Success . Otherwise if this is a Success acts as identity operator, though implementations may return a new instance.
14 mapEmptyToFailure()

Maps this Try to Failure if this is a Success with an empty value . Otherwise acts as identity operator, though implementations may return a new instance.
15 mapToEither(ThrowingFunction, ThrowingFunction)

Maps this Try to Either using according mapping function successMapper or failureMapper .
16 flatMapSuccess(ThrowingFunction)

Variant of #mapSuccess(ThrowingFunction) , utilizing a different successMapper, one that returns a Try .
17 flatMapSuccessAsNullable(ThrowingFunction)

Variant of #mapSuccessAsNullable(ThrowingFunction) , utilizing a different successMapper, one that returns a Try .
18 flatMapSuccessWhenPresent(ThrowingFunction)

Variant of #mapSuccessWhenPresent(ThrowingFunction) , utilizing a different successMapper, one that returns a Try .
19 accept(ThrowingConsumer, ThrowingConsumer)

Either consumes the success or the failure.
20 fold(ThrowingFunction, ThrowingFunction)

Maps the contained value or failure to a new value of type R using according mapping function successMapper or failureMapper .
21 thenCall(Callable)

If this is a Success , maps it to a new Try based on given Callable . Otherwise if its a Failure , acts as identity operator.
22 thenRun(ThrowingRunnable)

If this is a Success , maps it to a new Try based on given ThrowingRunnable . Otherwise if this is a Failure , acts as identity operator.
23 then(Callable)

If this is a Success , maps it to a new Try based on given Supplier . Otherwise if this is a Failure , acts as identity operator.
24 orCall(Callable)

If this is a Failure , maps it to a new Try based on given Callable . Otherwise if this is a Success , acts as identity operator.
25 valueAsNullableElseFail()

If this is a Failure throws the contained failure, otherwise if this is a Success , returns the success value as null-able.
26 valueAsNonNullElseFail()

If this is a Failure throws the contained failure, otherwise if this is a Success , either returns the success value if it is NOT null or throws a NoSuchElementException .

Members

empty()

success case with no value

getValue()

Optionally returns the contained value based on presence, that is, if this is a Success and the value is not null .

getFailure()

Optionally returns the contained failure based on presence, that is, if this is a Failure .

ifSuccess(ThrowingConsumer)

If this is a Success , peeks into the value wrapped in an Optional .

If given valueConsumer throws an exception, a failed Try is returned.

ifSuccessAsNullable(ThrowingConsumer)

If this is a Success peeks into the (null-able) value .

If given valueConsumer throws an exception, a failed Try is returned.

ifFailure(ThrowingConsumer)

If this is a Failure , peeks into the failure .

If given exceptionConsumer throws an exception, a failed Try is returned.

ifFailureFail()

Throws the contained failure if any.

ifAbsentFail()

Throws NoSuchElementException if value is null .

mapSuccess(ThrowingFunction)

If this is a Success , maps this Try to another, by calling the successMapper with the value wrapped by an Optional . Otherwise if this is a Failure , acts as identity operator, though implementations may return a new instance.

If given successMapper throws an exception, a failed Try is returned.

mapSuccessAsNullable(ThrowingFunction)

If this is a Success , maps this Try to another, by calling the successMapper with the value (which may be null). Otherwise if this is a Failure , acts as identity operator, though implementations may return a new instance.

If given successMapper throws an exception, a failed Try is returned.

mapSuccessWhenPresent(ThrowingFunction)

If this Try holds a non-null value (and hence is also a Success ), maps this Try to another, by calling the successMapper with the value (which is non-null). Otherwise acts as identity operator, that is, either stay an empty Success or stay a Failure , though implementations may return a new instance.

If given successMapper throws an exception, a failed Try is returned.

mapFailure(ThrowingFunction)

If this is a Failure , maps this Try to another. Otherwise if this is a Success acts as identity operator, though implementations may return a new instance.

If given failureMapper throws an exception, a failed Try is returned (hiding the original failure).

mapFailureToSuccess(ThrowingFunction)

If this is a Failure , recovers to a Success . Otherwise if this is a Success acts as identity operator, though implementations may return a new instance.

If given recoveryMapper throws an exception, a failed Try is returned.

mapEmptyToFailure()

Maps this Try to Failure if this is a Success with an empty value . Otherwise acts as identity operator, though implementations may return a new instance.

mapToEither(ThrowingFunction, ThrowingFunction)

Maps this Try to Either using according mapping function successMapper or failureMapper .

Any exceptions thrown by given failureMapper or successMapper are propagated without catching.

flatMapSuccess(ThrowingFunction)

Variant of #mapSuccess(ThrowingFunction) , utilizing a different successMapper, one that returns a Try .

flatMapSuccessAsNullable(ThrowingFunction)

Variant of #mapSuccessAsNullable(ThrowingFunction) , utilizing a different successMapper, one that returns a Try .

flatMapSuccessWhenPresent(ThrowingFunction)

Variant of #mapSuccessWhenPresent(ThrowingFunction) , utilizing a different successMapper, one that returns a Try .

accept(ThrowingConsumer, ThrowingConsumer)

Either consumes the success or the failure.

However, if any of given failureConsumer or successConsumer throws an exception, a failed Try is returned.

fold(ThrowingFunction, ThrowingFunction)

Maps the contained value or failure to a new value of type R using according mapping function successMapper or failureMapper .

Any exceptions thrown by given failureMapper or successMapper are propagated without catching.

thenCall(Callable)

If this is a Success , maps it to a new Try based on given Callable . Otherwise if its a Failure , acts as identity operator.

thenRun(ThrowingRunnable)

If this is a Success , maps it to a new Try based on given ThrowingRunnable . Otherwise if this is a Failure , acts as identity operator.

then(Callable)

If this is a Success , maps it to a new Try based on given Supplier . Otherwise if this is a Failure , acts as identity operator.

orCall(Callable)

If this is a Failure , maps it to a new Try based on given Callable . Otherwise if this is a Success , acts as identity operator.

valueAsNullableElseFail()

If this is a Failure throws the contained failure, otherwise if this is a Success , returns the success value as null-able.

valueAsNonNullElseFail()

If this is a Failure throws the contained failure, otherwise if this is a Success , either returns the success value if it is NOT null or throws a NoSuchElementException .