Try (Functional Extensions Library 4.7.1 API)

java.lang.Object
- io.atlassian.fugue.Try<A>

All Implemented Interfaces:

Serializable, Iterable<A>
```
public abstract class Try<A>
extends Object
implements Serializable, Iterable<A>
```
A Try represents a computation that may either throw an exception or return a value. A Try will either be Success wrapping a value or Failure which wraps an exception.
This class is similar to Either, but is explicit about having a success and failure case. Unless method level javadoc says otherwise, methods will not automatically catch exceptions thrown by function arguments. In particular map(Function) will not catch automatically catch thrown exceptions, instead you should use Checked.lift(io.atlassian.fugue.Checked.Function<A, B, E>) to to make the function explicitly return a Try and the use flatMap(Function).
Note that since 4.7.0, all API methods describe whether or not they will result in a Delayed Try being evaluated. In addition to this, any action to Serialize a Delayed Try will result in it being evaluated, and the underlying Try Success or Failure result being serialized.

Since:

4.4.0

See Also:

Serialized Form

Constructor Summary

Constructors
Constructor and Description

Try()

Constructors
Constructor and Description
`Try()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static <A> Try<A>`	`delayed(Supplier<Try<A>> supplier)` Creates a delayed Try, which will return either a Failure or a Success when evaluated.
`static <A> Try<A>`	`failure(Exception e)` Creates a new failure
`abstract Try<A>`	`filterOrElse(Predicate<? super A> p, Supplier<Exception> orElseSupplier)` Return a `Success` if this is a `Success` and the contained values satisfies the given predicate.
`abstract <B> Try<B>`	`flatMap(Function<? super A,Try<B>> f)` Binds the given function across the success value if it is one.
`static <A> Try<A>`	`flatten(Try<Try<A>> t)` Reduces a nested Try by a single level
`abstract <B> B`	`fold(Function<? super Exception,B> failureF, Function<A,B> successF)` Applies the function to the wrapped value, applying failureF it this is a Failure and successF if this is a Success.
`abstract void`	`forEach(Consumer<? super A> action)` Perform the given `Consumer` (side-effect) for the success `if success` value.
`abstract A`	`getOrElse(Supplier<A> s)` Returns the contained value if this is a success otherwise call the supplier and return its value.
`abstract boolean`	`isFailure()` Returns `true` if this failure, otherwise `false`
`abstract boolean`	`isSuccess()` Returns `true` if this success, otherwise `false`
`Iterator<A>`	`iterator()` Return an iterator for this type.
`abstract <B> Try<B>`	`map(Function<? super A,? extends B> f)` Maps the given function to the value from this `Success` or returns this unchanged if a `Failure`.
`abstract Try<A>`	`orElse(Supplier<? extends Try<? extends A>> orElse)` If this is a success, return the same success.
`Try<A>`	`orElse(Try<? extends A> orElse)` If this is a success, return the same success.
`abstract <X extends Exception> Try<A>`	`recover(Class<X> exceptionType, Function<? super X,A> f)` Applies the given function `f` if this is a `Failure` with certain exception type otherwise leaves this unchanged.
`abstract Try<A>`	`recover(Function<? super Exception,A> f)` Applies the given function `f` if this is a `Failure` otherwise this unchanged if a 'Success'.
`abstract <X extends Exception> Try<A>`	`recoverWith(Class<X> exceptionType, Function<? super X,Try<A>> f)` Binds the given function across certain exception type if it is one, otherwise this unchanged.
`abstract Try<A>`	`recoverWith(Function<? super Exception,Try<A>> f)` Binds the given function across the failure value if it is one, otherwise this unchanged if a 'Success'.
`static <A> Try<Iterable<A>>`	`sequence(Iterable<Try<A>> trys)` Returns a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
`static <T,A,R> Try<R>`	`sequence(Iterable<Try<T>> trys, Collector<T,A,R> collector)` Returns a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
`static <A> Try<A>`	`successful(A value)` Creates a new Success
`abstract Either<Exception,A>`	`toEither()` Convert this Try to an `Either`, becoming a left if this is a failure and a right if this is a success.
`abstract Option<A>`	`toOption()` Convert this Try to an Option.
`abstract Optional<A>`	`toOptional()` Create a `Optional` from this try.
`abstract Stream<A>`	`toStream()` Create a `Stream` from this try.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable
spliterator

- Constructor Detail
 - Try
```
public Try()
```
- Method Detail
 - failure
```
public static <A> Try<A> failure(Exception e)
```
 Creates a new failure
 
 Type Parameters:
 
 A - the success type
 
 Parameters:
 
 e - an exception to wrap, must not be null.
 
 Returns:
 
 a new Failure wrapping e.
 - successful
```
public static <A> Try<A> successful(A value)
```
 Creates a new Success
 
 Type Parameters:
 
 A - the wrapped value type
 
 Parameters:
 
 value - a value to wrap, must not be null
 
 Returns:
 
 a new Success wrapping v
 - delayed
```
public static <A> Try<A> delayed(Supplier<Try<A>> supplier)
```
 Creates a delayed Try, which will return either a Failure or a Success when evaluated. The supplier is called only once, no matter how many times the returned delayed Try is evaluated.
 
 Type Parameters:
 
 A - the wrapped value type
 
 Parameters:
 
 supplier - a supplier that returns a Try of A.
 
 Returns:
 
 a new Delayed Try wrapping the supplier.
 - sequence
```
public static <A> Try<Iterable<A>> sequence(Iterable<Try<A>> trys)
```
 Returns a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
 
 Type Parameters:
 
 A - The success type
 
 Parameters:
 
 trys - an iterable of try values
 
 Returns:
 
 a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
 - sequence
```
public static <T,A,R> Try<R> sequence(Iterable<Try<T>> trys,
 Collector<T,A,R> collector)
```
 Returns a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
 
 Type Parameters:
 
 T - The success type
 
 A - The intermediate accumulator type
 
 R - The result type
 
 Parameters:
 
 trys - an iterable of try values
 
 collector - result collector
 
 Returns:
 
 a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
 
 Since:
 
 4.6.0
 - flatten
```
public static <A> Try<A> flatten(Try<Try<A>> t)
```
 Reduces a nested Try by a single level
 
 Type Parameters:
 
 A - The success type
 
 Parameters:
 
 t - A nested Try
 
 Returns:
 
 The flattened try
 - isFailure
```
public abstract boolean isFailure()
```
 Returns true if this failure, otherwise false
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Returns:
 
 true if this failure, otherwise false
 - isSuccess
```
public abstract boolean isSuccess()
```
 Returns true if this success, otherwise false
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Returns:
 
 true if this success, otherwise false
 - flatMap
```
public abstract  Try flatMap(Function<? super A,Try> f)
```
 Binds the given function across the success value if it is one.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Type Parameters:
 
 B - result type
 
 Parameters:
 
 f - the function to bind.
 
 Returns:
 
 A new Try value after binding with the function applied if this is a Success, otherwise returns this if this is a `Failure`.
 - map
```
public abstract  Try map(Function<? super A,? extends B> f)
```
 Maps the given function to the value from this `Success` or returns this unchanged if a `Failure`.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Type Parameters:
 
 B - result type
 
 Parameters:
 
 f - the function to apply
 
 Returns:
 
 `f` applied to the `Success`, otherwise returns this if this is a `Failure`.
 - recover
```
public abstract Try<A> recover(Function<? super Exception,A> f)
```
 Applies the given function `f` if this is a `Failure` otherwise this unchanged if a 'Success'. This is like map for the failure.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Parameters:
 
 f - the function to apply
 
 Returns:
 
 `f` applied to the `Failure`, otherwise returns this if this is a `Success`.
 - recover
```
public abstract <X extends Exception> Try<A> recover(Class<X> exceptionType,
 Function<? super X,A> f)
```
 Applies the given function `f` if this is a `Failure` with certain exception type otherwise leaves this unchanged. This is like map for exceptions types.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Type Parameters:
 
 X - exception type
 
 Parameters:
 
 exceptionType - exception class
 
 f - the function to apply
 
 Returns:
 
 `f` applied to the `Failure`, otherwise returns this if this is a `Success` or the exception does not match the exception type.
 - recoverWith
```
public abstract Try<A> recoverWith(Function<? super Exception,Try<A>> f)
```
 Binds the given function across the failure value if it is one, otherwise this unchanged if a 'Success'. This is like flatmap for the failure.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Parameters:
 
 f - the function to bind.
 
 Returns:
 
 A new Try value after binding with the function applied if this is a `Failure`, otherwise returns this if this is a `Success`.
 - recoverWith
```
public abstract <X extends Exception> Try<A> recoverWith(Class<X> exceptionType,
 Function<? super X,Try<A>> f)
```
 Binds the given function across certain exception type if it is one, otherwise this unchanged. This is like flatmap for exceptions types.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Type Parameters:
 
 X - exception type
 
 Parameters:
 
 exceptionType - exception class
 
 f - the function to apply
 
 Returns:
 
 A new Try value after binding with the function applied if this is a `Failure`, otherwise returns this if this is a `Success` or the exception does not match the exception type.
 - getOrElse
```
public abstract A getOrElse(Supplier<A> s)
```
 Returns the contained value if this is a success otherwise call the supplier and return its value.
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Parameters:
 
 s - called if this is a failure
 
 Returns:
 
 the wrapped value or the value from the Supplier
 - orElse
```
public final Try<A> orElse(Try<? extends A> orElse)
```
 If this is a success, return the same success. Otherwise, return orElse.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Parameters:
 
 orElse - try to return if this is failure
 
 Returns:
 
 this or orElse
 
 Since:
 
 4.7
 - orElse
```
public abstract Try<A> orElse(Supplier<? extends Try<? extends A>> orElse)
```
 If this is a success, return the same success. Otherwise, return value supplied by orElse.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Parameters:
 
 orElse - try to return if this is failure
 
 Returns:
 
 this or orElse
 
 Since:
 
 4.7
 - filterOrElse
```
public abstract Try<A> filterOrElse(Predicate<? super A> p,
 Supplier<Exception> orElseSupplier)
```
 Return a Success if this is a Success and the contained values satisfies the given predicate.
 If this is a Success but the predicate is not satisfied, return a Failure with the value provided by the orElseSupplier.
 Return a Failure if this a Failure with the contained value.
 Note that for delayed(Supplier) this is not an evaluating operation.
 
 Parameters:
 
 p - The predicate function to test on the right contained value.
 
 orElseSupplier - The supplier to execute when is a success, and predicate is unsatisfied
 
 Returns:
 
 a new Try that will be either the existing success/failure or a failure with result of orElseSupplier
 
 Since:
 
 4.7.0
 - fold
```
public abstract  B fold(Function<? super Exception,B> failureF,
 Function<A,B> successF)
```
 Applies the function to the wrapped value, applying failureF it this is a Failure and successF if this is a Success.
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Type Parameters:
 
 B - the destination type
 
 Parameters:
 
 failureF - the function to apply if this is a Failure
 
 successF - the function to apply if this is a Success
 
 Returns:
 
 the result of the applied function
 - toEither
```
public abstract Either<Exception,A> toEither()
```
 Convert this Try to an Either, becoming a left if this is a failure and a right if this is a success.
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Returns:
 
 this value wrapped in right if a success, and the exception wrapped in a left if a failure.
 - toOption
```
public abstract Option<A> toOption()
```
 Convert this Try to an Option. Returns Some with a value if it is a success, otherwise None.
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Returns:
 
 The success's value in Some if it exists, otherwise None
 - toOptional
```
public abstract Optional<A> toOptional()
```
 Create a Optional from this try.
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Returns:
 
 Optional.of(Object) with the value if success, Optional.empty() if failure.
 
 Since:
 
 4.7
 - toStream
```
public abstract Stream<A> toStream()
```
 Create a Stream from this try.
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Returns:
 
 Stream.of(Object) with the value if success, Stream.empty() if failure.
 
 Since:
 
 4.7
 - forEach
```
public abstract void forEach(Consumer<? super A> action)
```
 Perform the given Consumer (side-effect) for the success if success value.
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Specified by:
 
 forEach in interface Iterable<A>
 
 Parameters:
 
 action - the Consumer to apply on the success value
 
 Since:
 
 4.7
 - iterator
```
public final Iterator<A> iterator()
```
 Return an iterator for this type. This will be an empty iterator for the failure isFailure() case, and a iterator of a single value for the success isSuccess() case.
 Note that for delayed(Supplier) this is an evaluating operation.
 
 Specified by:
 
 iterator in interface Iterable<A>
 
 Returns:
 
 an iterator over the contained value if success, or an empty one otherwise.
 
 Since:
 
 4.7.1

Class Try<A>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

Try

Method Detail

failure

successful

delayed

sequence

sequence

flatten

isFailure

isSuccess

flatMap

map

recover

recover

recoverWith

recoverWith

getOrElse

orElse

orElse

filterOrElse

fold

toEither

toOption

toOptional

toStream

forEach

iterator