Class Try<A>

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  Try.Failure<A>  
      private static class  Try.Success<A>  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Try()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      Try<A> catchError​(Fn1<? super java.lang.Throwable,​? extends Monad<A,​Try<?>>> recoveryFn)
      Catch any thrown errors inside the Monad and resume normal operations.
      Try<A> catching​(Fn1<? super java.lang.Throwable,​? extends java.lang.Boolean> predicate, Fn1<? super java.lang.Throwable,​? extends A> recoveryFn)
      Catch any thrown T satisfying predicate and map it to a success value.
      <S extends java.lang.Throwable>
      Try<A>
      catching​(java.lang.Class<S> throwableType, Fn1<? super S,​? extends A> recoveryFn)
      Catch any instance of throwableType 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​(java.lang.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.
      java.lang.Throwable forfeit​(Fn1<? super A,​? extends java.lang.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 java.lang.Throwable>
      A
      orThrow()
      If this is a success value, return it.
      abstract <T extends java.lang.Throwable>
      A
      orThrow​(Fn1<? super java.lang.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 java.lang.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​(java.lang.Throwable throwable)
      Throw an error value of type E into the monad.
      Either<java.lang.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 java.lang.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 java.lang.AutoCloseable,​B extends java.lang.AutoCloseable,​C extends java.lang.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 java.lang.AutoCloseable,​B extends java.lang.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 java.lang.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.functor.Functor

        coerce
    • Constructor Detail

      • Try

        private Try()
    • Method Detail

      • catching

        public final <S extends java.lang.Throwable> Try<A> catching​(java.lang.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 java.lang.Throwable,​? extends java.lang.Boolean> predicate,
                                     Fn1<? super java.lang.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 java.lang.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 java.lang.Throwable forfeit​(Fn1<? super A,​? extends java.lang.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 java.lang.Throwable> A orThrow()
                                                        throws T extends java.lang.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 java.lang.Throwable
      • orThrow

        public abstract <T extends java.lang.Throwable> A orThrow​(Fn1<? super java.lang.Throwable,​? extends T> fn)
                                                           throws T extends java.lang.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 java.lang.Throwable
      • toEither

        public final Either<java.lang.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 java.lang.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​(java.lang.Throwable throwable)
        Throw an error value of type E into the monad.
        Specified by:
        throwError in interface MonadError<java.lang.Throwable,​A,​Try<?>>
        Parameters:
        throwable - the error type
        Returns:
        the monad
      • catchError

        public Try<A> catchError​(Fn1<? super java.lang.Throwable,​? extends Monad<A,​Try<?>>> recoveryFn)
        Catch any thrown errors inside the Monad and resume normal operations.
        Specified by:
        catchError in interface MonadError<java.lang.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<java.lang.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<java.lang.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<java.lang.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<java.lang.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<java.lang.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<java.lang.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<java.lang.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
      • 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​(java.lang.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 java.lang.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 java.lang.AutoCloseable,​B extends java.lang.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 java.lang.AutoCloseable,​B extends java.lang.AutoCloseable,​C extends java.lang.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