sdk-common / com.tomtom.online.sdk.common.functional / Try

Try

abstract class Try<T : Any!> : Serializable, MutableIterable<T>

A monadic type representing a result of some computation. It can be a Success or a Failure. Success contains the computed value, Failure contains cause of the computation failure in a form of a Throwable.

Try can be compared to Java's Optional, Scala's Option, Haskell's Maybe as it also allows to model optional values, but it also allows storing the information why the value is not available.

Java doesn't have means to define sealed class hierarchies, due to this limitation Try is an abstract class with a protected constructor. This simulates a sealed hierarchy as Success and Failure are the only possible subclasses.

To create a Success:

Try<String> ts = Try.success("some value");

To create a Failure:

Try<Integer> tf = Try.failure(new Exception("some exception"));

Note: Implementation of this class was made to be extremely familiar for anyone that is used to Scala Try implementation or Vavr.io implementation.

Types

Failure	`class Failure<T : Any!> : Try<T>` Represents a failed computation that resulted in a `Throwable`.
Success	`class Success<T : Any!> : Try<T>` Represents a successful computation that resulted in some returned value.

Constructors

<init>

Try()

Functions

cast	`abstract fun <R : Any!> cast(clazz: Class<R>): Try<R>!` Performs value type cast to provided type if possible.
failure	`open static fun <R : Any!> failure(throwable: Throwable): Try<R>` Creates a `Failure` from the given `Throwable`. This method deliberately allows a null throwable to be passed to conform with rules of monadic design.
filter	`open fun filter(predicate: Predicate<in T>): Try<T>!` Returns a `Failure` if this `Try` represents a failed computation. Returns a `Failure` if the value does not satisfy the predicate or an `Exception` is thrown when testing the predicate. Returns `Success` otherwise. `abstract fun filter(predicate: Predicate<in T>, supplier: Supplier<out Throwable!>): Try<T>!` Returns a `Failure` if this `Try` represents a failed computation. Returns a `Failure` if the value does not satisfy the predicate or an `Exception` is thrown with testing the predicate. Returns `Success` otherwise.
flatMap	`abstract fun <R : Any!> flatMap(function: (in T) -> out Try<out R>!): Try<R>!` Maps success value to a new Try or passes a failure. In case of success function that is passed to this method will be called on the stored value, the resulting Try will be returned by the flatMap method. In case of failure flatMap will not invoke the passed function and just pass the failure again.
get	`abstract fun get(): T` Returns success value or in case of failure throws a `Throwable` wrapped in a `RuntimeException`.
getCause	`abstract fun getCause(): Throwable!` Gets the cause if this is a `Failure` or throws if this is a `Success`.
getChecked	`abstract fun getChecked(): T` Returns `Success` value or in case of `Failure` throws a `Throwable`. This method is deprecated, as checked exceptions are causing issues with how the code is structured, and create issues with code refactoring and restructuring. Please use `Try#get()` instead.
getOrElse	`abstract fun getOrElse(defaultValue: T?): T` Returns success value or in case of failure returns the passed value. `open fun getOrElse(provider: (in Throwable!) -> T): T` Returns `Success` value or in case of `Failure` throws exception that can be built by the given function from the throwable stored in the `Failure`.
getOrElseThrow	`open fun <E : Throwable!> getOrElseThrow(): T` Returns `Success` value or in case of `Failure` throws exception that is stored in the `Failure`. `open fun <E : Throwable!> getOrElseThrow(provider: (in Throwable!) -> E): T` Returns `Success` value or in case of `Failure` throws exception that can be built by the given function from the throwable stored in the `Failure`.
getOrNull	`open fun getOrNull(): T` Returns a `Success` value or in case of `Failure` a null. This method was added to introduce a level of compatibility with APIs that expect `null` values. If it's not needed please use `Try#getOrElse(Object)` instead. Avoid introducing `null` in your code.
ifFailure	`abstract fun ifFailure(action: Consumer1<Throwable!>): Try<T>!` Performs the provided action if the Try represents a failure. Note: If action throws, then this method may throw an Exception.
ifSuccess	`abstract fun ifSuccess(action: Consumer1<in T>): Try<T>!` Performs the provided action if the Try represents a success. Note: If action throws, then this method may throw an Exception.
isFailure	`open fun isFailure(): Boolean` Checks if the `Try` is a `Failure`.
isSuccess	`abstract fun isSuccess(): Boolean` Checks if the `Try` is a `Success`.
iterator	`open fun iterator(): MutableIterator<T>`
map	`abstract fun <R : Any!> map(function: (in T) -> out R): Try<R>!` Maps success value or passes failure. In case of success function that is passed to this method will be called with the stored value, the result of this operation will be assigned to a new Try. In case of failure map will not invoke the passed function and just pass the failure again.
of	`open static fun <R : Any!> of(supplier: Supplier<out R>): Try<R>` Creates a `Try` from a given `Supplier`. The code run by the supplier can throw an `RuntimeException`, this exception will be caught and wrapped by the resulting Try.
ofChecked	`open static fun <R : Any!> ofChecked(supplier: CheckedSupplier<out R>): Try<R>` Creates a `Try` from a given `CheckedSupplier`. The code run by the supplier can throw an `Exception`, this exception will be caught and wrapped by the resulting Try.
ofFailure	`open static fun <R : Any!> ofFailure(supplier: Supplier<out Throwable!>): Try<R>` Creates a `Failure` from a given `Supplier` that returns a `Throwable`.
ofNullable	`open static fun <R : Any!> ofNullable(value: R?): Try<R>` Creates a `Try` from a given value. If the value is null a `Failure` will be created containing information about a `NullPointerException`. `open static fun <R : Any!> ofNullable(value: R?, exception: Exception!): Try<R>` Creates a `Try` from a given value. If the value is null a `Failure` will be created with provided exception.
onBoth	`abstract fun <R : Any!> onBoth(other: Try<out R>, action: Consumer2<in T, in R>): Try<T>` Performs the provided action if both current and other Try represents a success. Note: If action throws, then this method may throw an Exception. `abstract fun <R : Any!> onBoth(otherSupplier: Supplier<Try<R>!>, action: Consumer2<in T, in R>): Try<T>` Performs the provided action if both current and other supplied Try represents a success. Note: If action throws, then this method may throw an Exception.
orElse	`abstract fun orElse(defaultTry: Try<T>): Try<T>!` Returns this Try if it's a Success or the given default argument if this is a Failure. `abstract fun orElse(supplier: Supplier<Try<T>!>): Try<T>!` Returns a `Success` or a value returned by the `Supplier` wrapped in a `Try`.
recover	`abstract fun recover(function: (in Throwable!) -> out T): Try<T>!` Applies the given function if this is a Failure, otherwise returns a `Success` if this is a Success. This is like a `Try#map(Function1)` for an exception.
recoverWith	`abstract fun recoverWith(function: (in Throwable!) -> Try<out T>!): Try<T>!` Applies the given function if this is a Failure, otherwise returns a Success if this is a Success. This is like a `Try#flatMap(Function1)` for an exception.
success	`open static fun <R : Any!> success(value: R): Try<R>` Creates a `Success` from the given value. Please be aware that if the value is null then a null will get stored. If you don't want to store or process a potential null value please use `Try#ofNullable(Object)` instead.
unit	`open static fun <R : Any!> unit(): (R) -> Try<R>!` Returns a function that takes a value and returns a monad of that value. The returned function will always return a `Success` regardless of the passed value (even null!).
when	`open static fun <R : Any!> when(condition: Boolean, value: R): Try<R>` Creates a `Try` from the given `value`. A `Success` is returned if the given `condition` is met, a `Failure` otherwise. `open static fun <R : Any!> when(condition: Boolean, supplier: Supplier<out R>): Try<R>` Lazy equivalent of `Try#when(boolean, Object)`. Creates a `Try` from the value returned by the given `Supplier`. A `Success` is returned if the given `condition` is met, a `Failure` otherwise. `open static fun <R : Any!> when(conditionSupplier: Supplier<Boolean!>, valueSupplier: Supplier<out R>, errorSupplier: Supplier<out Throwable!>): Try<R>!`
zipWith	`abstract fun <R : Any!, S : Any!> zipWith(other: Try<out S>, zipper: (in T, in S) -> out R): Try<R>` Returns an instance of `Try` that contains the result of the specified zipper function applied to the values of both Try instances if both are a Success. If at least one instance is a Failure or the zipper function fails then z Failure is returned.

Inheritors

Failure	`class Failure<T : Any!> : Try<T>` Represents a failed computation that resulted in a `Throwable`.
Success	`class Success<T : Any!> : Try<T>` Represents a successful computation that resulted in some returned value.