com.jnape.palatable.lambda.adt

## Class Try<A>

- java.lang.Object
- - com.jnape.palatable.lambda.adt.Try<A>

- Type Parameters:
    `A` - the possibly successful expression result
  All Implemented Interfaces:
    CoProduct2<Throwable,A,Try<A>>, Applicative<A,Try<?>>, Functor<A,Try<?>>, Monad<A,Try<?>>, MonadError<Throwable,A,Try<?>>, MonadRec<A,Try<?>>, Traversable<A,Try<?>>

      public abstract class Try<A>
      extends Object
      implements MonadError<Throwable,A,Try<?>>, MonadRec<A,Try<?>>, Traversable<A,Try<?>>, CoProduct2<Throwable,A,Try<A>>

  A `Monad` of the evaluation outcome of an expression that might throw. Try/catch/finally semantics map to `trying`/`catching`/`ensuring`, respectively.
  See Also:
    `Either`

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Try<A>` | `catchError(Fn1<? super Throwable,? extends Monad<A,Try<?>>> recoveryFn)` Catch any `thrown` errors inside the `Monad` and resume normal operations.
    `<S extends Throwable> Try<A>` | `catching(Class<S> throwableType, Fn1<? super S,? extends A> recoveryFn)` Catch any instance of `throwableType` and map it to a success value.
    `Try<A>` | `catching(Fn1<? super Throwable,? extends Boolean> predicate, Fn1<? super Throwable,? extends A> recoveryFn)` Catch any thrown `T` satisfying `predicate` and map it to a success value.
    `<B> Try<B>` | `discardL(Applicative<B,Try<?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `<B> Try<A>` | `discardR(Applicative<B,Try<?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `Try<A>` | `ensuring(SideEffect sideEffect)` Run the provided runnable regardless of whether this is a success or a failure (the `Try` analog to `finally`.
    `static <A> Try<A>` | `failure(Throwable t)` Static factory method for creating a failure value.
    `<B> Try<B>` | `flatMap(Fn1<? super A,? extends Monad<B,Try<?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `<B> Try<B>` | `fmap(Fn1<? super A,? extends B> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `Throwable` | `forfeit(Fn1<? super A,? extends Throwable> fn)` If this is a failure, return the wrapped value.
    `<B> Lazy<Try<B>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,Try<?>>> lazyAppFn)` Given a `lazy` instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
    `<T extends Throwable> A` | `orThrow()` If this is a success value, return it.
    `abstract <T extends Throwable> A` | `orThrow(Fn1<? super Throwable,? extends T> fn)` If this is a success value, return it.
    `<B> Try<B>` | `pure(B b)` Lift the value `b` into this applicative functor.
    `static Pure<Try<?>>` | `pureTry()` The canonical `Pure` instance for `Try`.
    `A` | `recover(Fn1<? super Throwable,? extends A> fn)` If this is a success, return the wrapped value.
    `static <A> Try<A>` | `success(A a)` Static factory method for creating a success value.
    `Try<A>` | `throwError(Throwable throwable)` Throw an error value of type `E` into the `monad`.
    `Either<Throwable,A>` | `toEither()` If this is a success, wrap the value in a `Either.right(R)` and return it.
    `<L> Either<L,A>` | `toEither(Fn1<? super Throwable,? extends L> fn)` If this is a success, wrap the value in a `Either.right(R)` and return it.
    `Maybe<A>` | `toMaybe()` If this is a success, wrap the value in a `Maybe.just(A)` and return it.
    `<B> Try<B>` | `trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Try<?>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `<B,App extends Applicative<?,App>,TravB extends Traversable<B,Try<?>>,AppTrav extends Applicative<TravB,App>> AppTrav` | `traverse(Fn1<? super A,? extends Applicative<B,App>> fn, Fn1<? super TravB,? extends AppTrav> pure)` Apply `fn` to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
    `static <A> Try<A>` | `trying(Fn0<? extends A> supplier)` Execute `supplier`, returning a success `A` or a failure of the thrown `Throwable`.
    `static Try<Unit>` | `trying(SideEffect sideEffect)` Execute `runnable`, returning a success `Unit` or a failure of the thrown `Throwable`.
    `static <A extends AutoCloseable,B extends AutoCloseable,C extends AutoCloseable,D> Try<D>` | `withResources(Fn0<? extends A> fn0, Fn1<? super A,? extends B> bFn, Fn1<? super B,? extends C> cFn, Fn1<? super C,? extends Try<? extends D>> fn)` Convenience overload of `withResources` that cascades two dependent resource creations via nested calls.
    `static <A extends AutoCloseable,B extends AutoCloseable,C> Try<C>` | `withResources(Fn0<? extends A> fn0, Fn1<? super A,? extends B> bFn, Fn1<? super B,? extends Try<? extends C>> fn)` Convenience overload of `withResources` that cascades dependent resource creation via nested calls.
    `static <A extends AutoCloseable,B> Try<B>` | `withResources(Fn0<? extends A> fn0, Fn1<? super A,? extends Try<? extends B>> fn)` Given a ``Fn0`<`AutoCloseable`>` `aSupplier` and an `Fn1` `fn`, apply `fn` to the result of `aSupplier`, ensuring that the result has its `close` method invoked, regardless of the outcome.
    `<B> Try<B>` | `zip(Applicative<Fn1<? super A,? extends B>,Try<?>> appFn)` Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface com.jnape.palatable.lambda.monad.Monad

      `join`

    - ### Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

      `coerce`

    - ### Methods inherited from interface com.jnape.palatable.lambda.adt.coproduct.CoProduct2

      `diverge, embed, invert, match, project, projectA, projectB`

- - ### Method Detail

    - #### catching

          public final <S extends Throwable> Try<A> catching(Class<S> throwableType,
                                                             Fn1<? super S,? extends A> recoveryFn)

      Catch any instance of `throwableType` and map it to a success value.
      Type Parameters:
        `S` - the `Throwable` (sub)type
      Parameters:
        `throwableType` - the `Throwable` (sub)type to be caught
        `recoveryFn` - the function mapping the `Throwable` to the result
      Returns:
        a new `Try` instance around either the original successful result or the mapped result

    - #### catching

          public final Try<A> catching(Fn1<? super Throwable,? extends Boolean> predicate,
                                       Fn1<? super Throwable,? extends A> recoveryFn)

      Catch any thrown `T` satisfying `predicate` and map it to a success value.
      Parameters:
        `predicate` - the predicate
        `recoveryFn` - the function mapping the `Throwable` to the result
      Returns:
        a new `Try` instance around either the original successful result or the mapped result

    - #### ensuring

          public final Try<A> ensuring(SideEffect sideEffect)

      Run the provided runnable regardless of whether this is a success or a failure (the `Try` analog to `finally`.

      If the runnable runs successfully, the result is preserved as is. If the runnable itself throws, and the result was a success, the result becomes a failure over the newly-thrown `Throwable`. If the result was a failure over some `Throwable` `t1`, and the runnable throws a new `Throwable` `t2`, the result is a failure over `t1` with `t2` added to `t1` as a suppressed exception.

      Parameters:
        `sideEffect` - the runnable block of code to execute
      Returns:
        the same `Try` instance if runnable completes successfully; otherwise, a `Try` conforming to rules above

    - #### recover

          public final A recover(Fn1<? super Throwable,? extends A> fn)

      If this is a success, return the wrapped value. Otherwise, apply the `Throwable` to `fn` and return the result.
      Parameters:
        `fn` - the function mapping the potential `Throwable` `T` to `A`
      Returns:
        a success value

    - #### forfeit

          public final Throwable forfeit(Fn1<? super A,? extends Throwable> fn)

      If this is a failure, return the wrapped value. Otherwise, apply the success value to `fn` and return the result.
      Parameters:
        `fn` - the function mapping the potential `A` to `T`
      Returns:
        a failure value

    - #### orThrow

          public final <T extends Throwable> A orThrow()
                                                throws T extends Throwable

      If this is a success value, return it. Otherwise, rethrow the captured failure.
      Type Parameters:
        `T` - a declarable exception type used for catching checked exceptions
      Returns:
        possibly the success value
      Throws:
        `T` - anything that the call site may want to explicitly catch or indicate could be thrown
        `T extends Throwable`

    - #### orThrow

          public abstract <T extends Throwable> A orThrow(Fn1<? super Throwable,? extends T> fn)
                                                   throws T extends Throwable

      If this is a success value, return it. Otherwise, transform the captured failure with `fn` and throw the result.
      Type Parameters:
        `T` - the type of the thrown `Throwable`
      Parameters:
        `fn` - the `Throwable` transformation
      Returns:
        possibly the success value
      Throws:
        `T` - the transformation output
        `T extends Throwable`

    - #### toMaybe

          public final Maybe<A> toMaybe()

      If this is a success, wrap the value in a `Maybe.just(A)` and return it. Otherwise, return `Maybe.nothing()`.
      Returns:
        `Maybe` the success value

    - #### toEither

          public final Either<Throwable,A> toEither()

      If this is a success, wrap the value in a `Either.right(R)` and return it. Otherwise, return the `Throwable` in an `Either.left(L)`.
      Returns:
        `Either` the success value or the `Throwable`

    - #### toEither

          public final <L> Either<L,A> toEither(Fn1<? super Throwable,? extends L> fn)

      If this is a success, wrap the value in a `Either.right(R)` and return it. Otherwise, apply the mapping function to the failure `Throwable`, re-wrap it in an `Either.left(L)`, and return it.
      Type Parameters:
        `L` - the `Either` left parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        `Either` the success value or the mapped left value

    - #### throwError

          public Try<A> throwError(Throwable throwable)

      Throw an error value of type `E` into the `monad`.
      Specified by:
        `throwError` in interface `MonadError<Throwable,A,Try<?>>`
      Parameters:
        `throwable` - the error type
      Returns:
        the `monad`

    - #### catchError

          public Try<A> catchError(Fn1<? super Throwable,? extends Monad<A,Try<?>>> recoveryFn)

      Catch any `thrown` errors inside the `Monad` and resume normal operations.
      Specified by:
        `catchError` in interface `MonadError<Throwable,A,Try<?>>`
      Parameters:
        `recoveryFn` - the catch function
      Returns:
        the recovered `Monad`

    - #### fmap

          public <B> Try<B> fmap(Fn1<? super A,? extends B> fn)

      Covariantly transmute this functor's parameter using the given mapping function. Generally this method is specialized to return an instance of the class implementing Functor.
      Specified by:
        `fmap` in interface `Applicative<A,Try<?>>`
      Specified by:
        `fmap` in interface `Functor<A,Try<?>>`
      Specified by:
        `fmap` in interface `Monad<A,Try<?>>`
      Specified by:
        `fmap` in interface `MonadError<Throwable,A,Try<?>>`
      Specified by:
        `fmap` in interface `MonadRec<A,Try<?>>`
      Specified by:
        `fmap` in interface `Traversable<A,Try<?>>`
      Type Parameters:
        `B` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### flatMap

          public <B> Try<B> flatMap(Fn1<? super A,? extends Monad<B,Try<?>>> f)

      Chain dependent computations that may continue or short-circuit based on previous results.
      Specified by:
        `flatMap` in interface `Monad<A,Try<?>>`
      Specified by:
        `flatMap` in interface `MonadError<Throwable,A,Try<?>>`
      Specified by:
        `flatMap` in interface `MonadRec<A,Try<?>>`
      Type Parameters:
        `B` - the resulting monad parameter type
      Parameters:
        `f` - the dependent computation over A
      Returns:
        the new monad instance

    - #### pure

          public <B> Try<B> pure(B b)

      Lift the value `b` into this applicative functor.
      Specified by:
        `pure` in interface `Applicative<A,Try<?>>`
      Specified by:
        `pure` in interface `Monad<A,Try<?>>`
      Specified by:
        `pure` in interface `MonadError<Throwable,A,Try<?>>`
      Specified by:
        `pure` in interface `MonadRec<A,Try<?>>`
      Type Parameters:
        `B` - the type of the returned applicative's parameter
      Parameters:
        `b` - the value
      Returns:
        an instance of this applicative over b

    - #### zip

          public <B> Try<B> zip(Applicative<Fn1<? super A,? extends B>,Try<?>> appFn)

      Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
      Specified by:
        `zip` in interface `Applicative<A,Try<?>>`
      Specified by:
        `zip` in interface `Monad<A,Try<?>>`
      Specified by:
        `zip` in interface `MonadError<Throwable,A,Try<?>>`
      Specified by:
        `zip` in interface `MonadRec<A,Try<?>>`
      Type Parameters:
        `B` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

          public <B> Lazy<Try<B>> lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,Try<?>>> lazyAppFn)

      Given a `lazy` instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports. This is useful for applicatives that support lazy evaluation and early termination.
      Specified by:
        `lazyZip` in interface `Applicative<A,Try<?>>`
      Specified by:
        `lazyZip` in interface `Monad<A,Try<?>>`
      Specified by:
        `lazyZip` in interface `MonadError<Throwable,A,Try<?>>`
      Specified by:
        `lazyZip` in interface `MonadRec<A,Try<?>>`
      Type Parameters:
        `B` - the resulting applicative parameter type
      Parameters:
        `lazyAppFn` - the lazy other applicative instance
      Returns:
        the mapped applicative
      See Also:
        `Maybe`, `Either`

    - #### discardL

          public <B> Try<B> discardL(Applicative<B,Try<?>> appB)

      Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`. This is generally useful for sequentially performing side-effects.
      Specified by:
        `discardL` in interface `Applicative<A,Try<?>>`
      Specified by:
        `discardL` in interface `Monad<A,Try<?>>`
      Specified by:
        `discardL` in interface `MonadError<Throwable,A,Try<?>>`
      Specified by:
        `discardL` in interface `MonadRec<A,Try<?>>`
      Type Parameters:
        `B` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

          public <B> Try<A> discardR(Applicative<B,Try<?>> appB)

      Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`. This is generally useful for sequentially performing side-effects.
      Specified by:
        `discardR` in interface `Applicative<A,Try<?>>`
      Specified by:
        `discardR` in interface `Monad<A,Try<?>>`
      Specified by:
        `discardR` in interface `MonadError<Throwable,A,Try<?>>`
      Specified by:
        `discardR` in interface `MonadRec<A,Try<?>>`
      Type Parameters:
        `B` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### trampolineM

          public <B> Try<B> trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Try<?>>> fn)

      Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.

      Stack-safety depends on implementations guaranteeing that the growth of the call stack is a constant factor independent of the number of invocations of the operation. For various examples of how this can be achieved in stereotypical circumstances, see the referenced types.

      Specified by:
        `trampolineM` in interface `MonadRec<A,Try<?>>`
      Type Parameters:
        `B` - the ultimate resulting carrier type
      Parameters:
        `fn` - the function to internally trampoline
      Returns:
        the trampolined `MonadRec`
      See Also:
        `for a basic implementation`, `for a {@link CoProduct2 coproduct} implementation`, `for an implementation leveraging an already stack-safe {@link Monad#flatMap(Fn1)}`, `for a {@link MonadT monad transformer} implementation`

    - #### traverse

          public <B,App extends Applicative<?,App>,TravB extends Traversable<B,Try<?>>,AppTrav extends Applicative<TravB,App>> AppTrav traverse(Fn1<? super A,? extends Applicative<B,App>> fn,
                                                                                                                                                Fn1<? super TravB,? extends AppTrav> pure)

      Apply `fn` to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
      Specified by:
        `traverse` in interface `Traversable<A,Try<?>>`
      Type Parameters:
        `B` - the resulting element type
        `App` - the result applicative type
        `TravB` - this Traversable instance over B
        `AppTrav` - the full inferred resulting type from the traversal
      Parameters:
        `fn` - the function to apply
        `pure` - the applicative pure function
      Returns:
        the traversed Traversable, wrapped inside an applicative

    - #### success

          public static <A> Try<A> success(A a)

      Static factory method for creating a success value.
      Type Parameters:
        `A` - the success parameter type
      Parameters:
        `a` - the wrapped value
      Returns:
        a success value of a

    - #### failure

          public static <A> Try<A> failure(Throwable t)

      Static factory method for creating a failure value.
      Type Parameters:
        `A` - the success parameter type
      Parameters:
        `t` - the `Throwable`
      Returns:
        a failure value of t

    - #### trying

          public static <A> Try<A> trying(Fn0<? extends A> supplier)

      Execute `supplier`, returning a success `A` or a failure of the thrown `Throwable`.
      Type Parameters:
        `A` - the possible success type
      Parameters:
        `supplier` - the supplier
      Returns:
        a new `Try` around either a successful A result or the thrown `Throwable`

    - #### trying

          public static Try<Unit> trying(SideEffect sideEffect)

      Execute `runnable`, returning a success `Unit` or a failure of the thrown `Throwable`.
      Parameters:
        `sideEffect` - the runnable
      Returns:
        a new `Try` around either a successful `Unit` result or the thrown `Throwable`

    - #### withResources

          public static <A extends AutoCloseable,B> Try<B> withResources(Fn0<? extends A> fn0,
                                                                         Fn1<? super A,? extends Try<? extends B>> fn)

      Given a ``Fn0`<`AutoCloseable`>` `aSupplier` and an `Fn1` `fn`, apply `fn` to the result of `aSupplier`, ensuring that the result has its `close` method invoked, regardless of the outcome.

      If the resource creation process throws, the function body throws, or the `close method` throws, the result is a failure. If both the function body and the `close method` throw, the result is a failure over the function body `Throwable` with the `close method` `Throwable` added as a `suppressed` `Throwable`. If only the `close method` throws, the result is a failure over that `Throwable`.

      Note that `withResources` calls can be nested, in which case all of the above specified exception handling applies, where closing the previously created resource is considered part of the body of the next `withResources` calls, and `Throwables` are considered suppressed in the same manner. Additionally, `close methods` are invoked in the inverse order of resource creation.

      This is `Try`'s equivalent of try-with-resources, introduced in Java 7.

      Type Parameters:
        `A` - the resource type
        `B` - the function return type
      Parameters:
        `fn0` - the resource supplier
        `fn` - the function body
      Returns:
        a `Try` representing the result of the function's application to the resource

    - #### withResources

          public static <A extends AutoCloseable,B extends AutoCloseable,C> Try<C> withResources(Fn0<? extends A> fn0,
                                                                                                 Fn1<? super A,? extends B> bFn,
                                                                                                 Fn1<? super B,? extends Try<? extends C>> fn)

      Convenience overload of `withResources` that cascades dependent resource creation via nested calls.
      Type Parameters:
        `A` - the first resource type
        `B` - the second resource type
        `C` - the function return type
      Parameters:
        `fn0` - the first resource supplier
        `bFn` - the dependent resource function
        `fn` - the function body
      Returns:
        a `Try` representing the result of the function's application to the dependent resource

    - #### withResources

          public static <A extends AutoCloseable,B extends AutoCloseable,C extends AutoCloseable,D> Try<D> withResources(Fn0<? extends A> fn0,
                                                                                                                         Fn1<? super A,? extends B> bFn,
                                                                                                                         Fn1<? super B,? extends C> cFn,
                                                                                                                         Fn1<? super C,? extends Try<? extends D>> fn)

      Convenience overload of `withResources` that cascades two dependent resource creations via nested calls.
      Type Parameters:
        `A` - the first resource type
        `B` - the second resource type
        `C` - the final resource type
        `D` - the function return type
      Parameters:
        `fn0` - the first resource supplier
        `bFn` - the second resource function
        `cFn` - the final resource function
        `fn` - the function body
      Returns:
        a `Try` representing the result of the function's application to the final dependent resource

    - #### pureTry

          public static Pure<Try<?>> pureTry()

      The canonical `Pure` instance for `Try`.
      Returns:
        the `Pure` instance