Class 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
Monad
of the evaluation outcome of an expression that might throw. Try/catch/finally semantics map to
trying
/catching
/ensuring
, respectively.- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
private static final class
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptioncatching
(Fn1<? super Throwable, ? extends Boolean> predicate, Fn1<? super Throwable, ? extends A> recoveryFn) Catch any thrownT
satisfyingpredicate
and map it to a success value.Catch any instance ofthrowableType
and map it to a success value.<B> Try
<B> discardL
(Applicative<B, Try<?>> appB) Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
.discardR
(Applicative<B, Try<?>> appB) Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
.ensuring
(SideEffect sideEffect) Run the provided runnable regardless of whether this is a success or a failure (theTry
analog tofinally
.static <A> Try
<A> Static factory method for creating a failure value.<B> Try
<B> Chain dependent computations that may continue or short-circuit based on previous results.<B> Try
<B> Covariantly transmute this functor's parameter using the given mapping function.final Throwable
If this is a failure, return the wrapped value.Given alazy
instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.orThrow()
If this is a success value, return it.If this is a success value, return it.<B> Try
<B> pure
(B b) Lift the valueb
into this applicative functor.pureTry()
final A
If this is a success, return the wrapped value.static <A> Try
<A> success
(A a) Static factory method for creating a success value.throwError
(Throwable throwable) Throw an error value of typeE
into themonad
.toEither()
If this is a success, wrap the value in aEither.right(R)
and return it.If this is a success, wrap the value in aEither.right(R)
and return it.toMaybe()
If this is a success, wrap the value in aMaybe.just(A)
and return it.<B> Try
<B> trampolineM
(Fn1<? super A, ? extends MonadRec<RecursiveResult<A, B>, Try<?>>> fn) Given some operation yielding aRecursiveResult
inside thisMonadRec
, internally trampoline the operation until it yields atermination
instruction.<B,
App extends Applicative<?, App>, TravB extends Traversable<B, Try<?>>, AppTrav extends Applicative<TravB, App>>
AppTravtraverse
(Fn1<? super A, ? extends Applicative<B, App>> fn, Fn1<? super TravB, ? extends AppTrav> pure) Applyfn
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
(SideEffect sideEffect) 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 ofwithResources
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 ofwithResources
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 aFn0
<AutoCloseable
>aSupplier
and anFn1
fn
, applyfn
to the result ofaSupplier
, ensuring that the result has itsclose
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
-
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 ofthrowableType
and map it to a success value. -
catching
public final Try<A> catching(Fn1<? super Throwable, ? extends Boolean> predicate, Fn1<? super Throwable, ? extends A> recoveryFn) Catch any thrownT
satisfyingpredicate
and map it to a success value. -
ensuring
Run the provided runnable regardless of whether this is a success or a failure (theTry
analog tofinally
.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 someThrowable
t1
, and the runnable throws a newThrowable
t2
, the result is a failure overt1
witht2
added tot1
as a suppressed exception. -
recover
If this is a success, return the wrapped value. Otherwise, apply theThrowable
tofn
and return the result.- Parameters:
fn
- the function mapping the potentialThrowable
T
toA
- Returns:
- a success value
-
forfeit
If this is a failure, return the wrapped value. Otherwise, apply the success value tofn
and return the result.- Parameters:
fn
- the function mapping the potentialA
toT
- Returns:
- a failure value
-
orThrow
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
If this is a success value, return it. Otherwise, transform the captured failure withfn
and throw the result. -
toMaybe
If this is a success, wrap the value in aMaybe.just(A)
and return it. Otherwise, returnMaybe.nothing()
.- Returns:
Maybe
the success value
-
toEither
If this is a success, wrap the value in aEither.right(R)
and return it. Otherwise, return theThrowable
in anEither.left(L)
. -
toEither
If this is a success, wrap the value in aEither.right(R)
and return it. Otherwise, apply the mapping function to the failureThrowable
, re-wrap it in anEither.left(L)
, and return it. -
throwError
Throw an error value of typeE
into themonad
.- Specified by:
throwError
in interfaceMonadError<Throwable,
A, Try<?>> - Parameters:
throwable
- the error type- Returns:
- the
monad
-
catchError
- Specified by:
catchError
in interfaceMonadError<Throwable,
A, Try<?>> - Parameters:
recoveryFn
- the catch function- Returns:
- the recovered
Monad
-
fmap
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 interfaceApplicative<A,
Try<?>> - Specified by:
fmap
in interfaceFunctor<A,
Try<?>> - Specified by:
fmap
in interfaceMonad<A,
Try<?>> - Specified by:
fmap
in interfaceMonadError<Throwable,
A, Try<?>> - Specified by:
fmap
in interfaceMonadRec<A,
Try<?>> - Specified by:
fmap
in interfaceTraversable<A,
Try<?>> - Type Parameters:
B
- the new parameter type- Parameters:
fn
- the mapping function- Returns:
- a functor over B (the new parameter type)
-
flatMap
Chain dependent computations that may continue or short-circuit based on previous results.- Specified by:
flatMap
in interfaceMonad<A,
Try<?>> - Specified by:
flatMap
in interfaceMonadError<Throwable,
A, Try<?>> - Specified by:
flatMap
in interfaceMonadRec<A,
Try<?>> - Type Parameters:
B
- the resulting monad parameter type- Parameters:
f
- the dependent computation over A- Returns:
- the new monad instance
-
pure
Lift the valueb
into this applicative functor.- Specified by:
pure
in interfaceApplicative<A,
Try<?>> - Specified by:
pure
in interfaceMonad<A,
Try<?>> - Specified by:
pure
in interfaceMonadError<Throwable,
A, Try<?>> - Specified by:
pure
in interfaceMonadRec<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
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 interfaceApplicative<A,
Try<?>> - Specified by:
zip
in interfaceMonad<A,
Try<?>> - Specified by:
zip
in interfaceMonadError<Throwable,
A, Try<?>> - Specified by:
zip
in interfaceMonadRec<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 alazy
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 interfaceApplicative<A,
Try<?>> - Specified by:
lazyZip
in interfaceMonad<A,
Try<?>> - Specified by:
lazyZip
in interfaceMonadError<Throwable,
A, Try<?>> - Specified by:
lazyZip
in interfaceMonadRec<A,
Try<?>> - Type Parameters:
B
- the resulting applicative parameter type- Parameters:
lazyAppFn
- the lazy other applicative instance- Returns:
- the mapped applicative
- See Also:
-
discardL
Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
. This is generally useful for sequentially performing side-effects.- Specified by:
discardL
in interfaceApplicative<A,
Try<?>> - Specified by:
discardL
in interfaceMonad<A,
Try<?>> - Specified by:
discardL
in interfaceMonadError<Throwable,
A, Try<?>> - Specified by:
discardL
in interfaceMonadRec<A,
Try<?>> - Type Parameters:
B
- the type of the returned Applicative's parameter- Parameters:
appB
- the other Applicative- Returns:
- appB
-
discardR
Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
. This is generally useful for sequentially performing side-effects.- Specified by:
discardR
in interfaceApplicative<A,
Try<?>> - Specified by:
discardR
in interfaceMonad<A,
Try<?>> - Specified by:
discardR
in interfaceMonadError<Throwable,
A, Try<?>> - Specified by:
discardR
in interfaceMonadRec<A,
Try<?>> - Type Parameters:
B
- the type of appB's parameter- Parameters:
appB
- the other Applicative- Returns:
- this Applicative
-
trampolineM
Given some operation yielding aRecursiveResult
inside thisMonadRec
, internally trampoline the operation until it yields atermination
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 interfaceMonadRec<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<?, AppTrav traverseApp>, TravB extends Traversable<B, Try<?>>, AppTrav extends Applicative<TravB, App>> (Fn1<? super A, ? extends Applicative<B, App>> fn, Fn1<? super TravB, ? extends AppTrav> pure) Applyfn
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 interfaceTraversable<A,
Try<?>> - Type Parameters:
B
- the resulting element typeApp
- the result applicative typeTravB
- this Traversable instance over BAppTrav
- the full inferred resulting type from the traversal- Parameters:
fn
- the function to applypure
- the applicative pure function- Returns:
- the traversed Traversable, wrapped inside an applicative
-
success
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
Static factory method for creating a failure value.- Type Parameters:
A
- the success parameter type- Parameters:
t
- theThrowable
- Returns:
- a failure value of t
-
trying
-
trying
-
withResources
public static <A extends AutoCloseable,B> Try<B> withResources(Fn0<? extends A> fn0, Fn1<? super A, ? extends Try<? extends B>> fn) Given aFn0
<AutoCloseable
>aSupplier
and anFn1
fn
, applyfn
to the result ofaSupplier
, ensuring that the result has itsclose
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 theclose method
throw, the result is a failure over the function bodyThrowable
with theclose method
Throwable
added as asuppressed
Throwable
. If only theclose method
throws, the result is a failure over thatThrowable
.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 nextwithResources
calls, andThrowables
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 typeB
- the function return type- Parameters:
fn0
- the resource supplierfn
- 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, Try<C> withResourcesC> (Fn0<? extends A> fn0, Fn1<? super A, ? extends B> bFn, Fn1<? super B, ? extends Try<? extends C>> fn) Convenience overload ofwithResources
that cascades dependent resource creation via nested calls.- Type Parameters:
A
- the first resource typeB
- the second resource typeC
- the function return type- Parameters:
fn0
- the first resource supplierbFn
- the dependent resource functionfn
- 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, Try<D> withResourcesC extends AutoCloseable, D> (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 ofwithResources
that cascades two dependent resource creations via nested calls.- Type Parameters:
A
- the first resource typeB
- the second resource typeC
- the final resource typeD
- the function return type- Parameters:
fn0
- the first resource supplierbFn
- the second resource functioncFn
- the final resource functionfn
- the function body- Returns:
- a
Try
representing the result of the function's application to the final dependent resource
-
pureTry
- Returns:
- the
Pure
instance
-