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<?>>
Direct Known Subclasses:
Try.Failure, Try.Success
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:

  • Constructor Details

    • Try

      private Try()

  • Method Details

    • 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
      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

    • orThrow

      public abstract <T extends Throwable> A orThrow(Fn1<? super Throwable, ? extends T> fn) throws T
      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

    • 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:

    • 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:

    • 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