Try (Java Scala Utils 1.3 API)

Type Parameters:

T - The type of the value represented by this Try

All Superinterfaces:

Iterable<T>

All Known Implementing Classes:

Failure, Success
```
public interface Try<T>
extends Iterable<T>
```
The 'Try' type represents a computation that may either result in an exception, or return a successfully computed value.
Typical use case is situations where parallel computation takes place resulting in more than one response where it's possible that one or more computations fail.
Though it might not be desirable to raise an exception for failed computations hence the Try acts a place holder for a response that is either failed or successful.
Instances of 'Try', are either an instance of Success or Failure.
Example of usage:
```
 Try<SomeData> getSomeData(SomeInput input) {
     try {
         // readUserFromDB throws if no user exists
         SomeData data = readUserFromDB(input);
         return new Success<>(data);
     } catch (SomeException ex) {
         return new Failure<>(ex);
     }
 }
 
```
A more elaborate way is to provide a checked function provided to the apply(ThrowableFunction0) method.
```
 Try<Integer> resultSuccess = Try.apply(() -> 9 / 3); // results in Success(3)
 Try<Integer> resultFailure = Try.apply(() -> 9 / 0); // results in Failure(ArithmeticException)
 
```
Or let us re-write the first example to use the apply(ThrowableFunction0) method.
```
 Try<SomeData> getSomeData(SomeInput input) {
     // readUserFromDB throws if no user exists
     Try.apply(() -> readUserFromDB(input));
 }
 
```
Since:

1.0

Author:

Peter Nerg

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`static <T> Try<T>`	`apply(T value)` Creates an instance of Try.
`static <T> Try<T>`	`apply(ThrowableFunction0<T> function)` Creates an instance of Try wrapping the result of the provided function.
`default Option<T>`	`asOption()` Returns this `Try` as an `Option`.
`Try<Throwable>`	`failed()` Completes this 'Try' with an exception wrapped in a `Success`.
`<R> Try<R>`	`flatMap(java.util.function.Function<T,Try<R>> function)` Maps the given function to the value from this `Success` or returns `this` if this is a `Failure`.
`T`	`get()` Returns the value from this `Success` or throws the exception if this is a `Failure`.
`T`	`getOrElse(java.util.function.Supplier<T> supplier)` Returns the value from this `Success` or the value provided by the supplier if this is a `Failure`.
`default boolean`	`isFailure()` Returns `true` if the 'Try' is a `Failure`, `false` otherwise.
`boolean`	`isSuccess()` Returns `true` if the 'Try' is a `Success`, `false` otherwise.
`default Iterator<T>`	`iterator()` Returns the Try's value in an `Iterator` if it is a `Success`, or an empty `Iterator` if it is Failure.
`<R> Try<R>`	`map(java.util.function.Function<T,R> function)` Maps the given function to the value from this `Success` or returns `this` if this is a `Failure`.
`Try<T>`	`orElse(java.util.function.Supplier<Try<T>> supplier)` Returns this 'Try' if it's a `Success` or the value provided by the supplier if this is a `Failure`.
`default T`	`orNull()` Returns the value if it is a `Success`, else `null`.
`default java.util.stream.Stream<T>`	`stream()` Returns the Try's value in a Stream if it is a `Success`, or an empty Stream if it is a `Failure`.

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Method Detail
  - apply
```
static <T> Try<T> apply(T value)
```
    Creates an instance of Try.
    If a null or non-throwable value is provided then Success is returned containing the value, else Failure containing the provided throwable.
    
    Type Parameters:
    
    T - The type for the Try
    
    Parameters:
    
    value - The value for this to create a Try
    
    Returns:
    
    The Try instance
  - apply
```
static <T> Try<T> apply(ThrowableFunction0<T> function)
```
    Creates an instance of Try wrapping the result of the provided function.
    If the function results in a value then Success with the value is returned.
    In case the function raises an exception then Failure is returned containing that exception.
    If null is provided as argument then the apply(Object) is invoked.
    Example simple division by zero results in an exception.
    Try<Integer> resultSuccess = Try.apply(() -> 9 / 3); // results in Success(3) Try<Integer> resultFailure = Try.apply(() -> 9 / 0); // results in Failure(ArithmeticException)
    Type Parameters:
    
    T - The type for the Try
    
    Parameters:
    
    function - The function to render either the value T or raise an exception.
    
    Returns:
    
    The resulting Try instance wrapping what the function resulted in
    
    Since:
    
    1.3
  - isFailure
```
default boolean isFailure()
```
    Returns true if the 'Try' is a Failure, false otherwise.
    
    Returns:
    
    If the Try is a Failure
  - isSuccess
```
boolean isSuccess()
```
    Returns true if the 'Try' is a Success, false otherwise.
    
    Returns:
    
    If the Try is a Success
  - getOrElse
```
T getOrElse(java.util.function.Supplier<T> supplier)
```
    Returns the value from this Success or the value provided by the supplier if this is a Failure.
    
    Parameters:
    
    supplier - The supplier to return the value in case of a Failure
    
    Returns:
    
    The value from the Try or the supplier
  - orNull
```
default T orNull()
```
    Returns the value if it is a Success, else null.
    
    Returns:
    
    The value of the Try or null.
  - orElse
```
Try<T> orElse(java.util.function.Supplier<Try<T>> supplier)
```
    Returns this 'Try' if it's a Success or the value provided by the supplier if this is a Failure.
    
    Parameters:
    
    supplier - The supplier to return the value in case of a Failure
    
    Returns:
    
    This try or the value from the supplier
  - get
```
T get()
throws Throwable
```
    Returns the value from this Success or throws the exception if this is a Failure.
    
    Returns:
    
    The value of the Success
    
    Throws:
    
    Throwable - The Throwable in case of a Failure
  - failed
```
Try<Throwable> failed()
```
    Completes this 'Try' with an exception wrapped in a Success.
    The exception is either the exception that the 'Try' failed with (if a Failure) or an 'UnsupportedOperationException'.
    
    Returns:
    
    The value of the Failure in a Success
  - iterator
```
default Iterator<T> iterator()
```
    Returns the Try's value in an Iterator if it is a Success, or an empty Iterator if it is Failure.
    Should it be a Success containing a null value then the iterator will also be empty.
    
    Specified by:
    
    iterator in interface Iterable<T>
    
    Returns:
    
    The iterator for the Try
  - map
```
<R> Try<R> map(java.util.function.Function<T,R> function)
```
    Maps the given function to the value from this Success or returns this if this is a Failure.
    
    Type Parameters:
    
    R - The type for the return value from the function
    
    Parameters:
    
    function - The function to use
    
    Returns:
    
    The Option containing the mapped value
  - flatMap
```
<R> Try<R> flatMap(java.util.function.Function<T,Try<R>> function)
```
    Maps the given function to the value from this Success or returns this if this is a Failure.
    
    Type Parameters:
    
    R - The type for the return value from the function
    
    Parameters:
    
    function - The function to use
    
    Returns:
    
    The Option containing the mapped value
    
    Since:
    
    1.2
  - stream
```
default java.util.stream.Stream<T> stream()
```
    Returns the Try's value in a Stream if it is a Success, or an empty Stream if it is a Failure.
    Should it be a Success containing a null value then the stream will also be empty.
    
    Returns:
    
    The stream for the Try
  - asOption
```
default Option<T> asOption()
```
    Returns this Try as an Option.
    If it is a Success then the value is wrapped in Some else None is returned.
    Should the Success contain a null value the result will be None as null values are per definition none/nothing.
    
    Returns:
    
    The Option representing this Try

Interface Try<T>

Method Summary

Methods inherited from interface java.lang.Iterable

Method Detail

apply

apply

isFailure

isSuccess

getOrElse

orNull

orElse

get

failed

iterator

map

flatMap

stream

asOption