A
- the possibly successful expression resultpublic abstract class Try<A> extends Object implements MonadError<Throwable,A,Try<?>>, MonadRec<A,Try<?>>, Traversable<A,Try<?>>, CoProduct2<Throwable,A,Try<A>>
Monad
of the evaluation outcome of an expression that might throw. Try/catch/finally semantics map to
trying
/catching
/ensuring
, respectively.Either
Modifier and Type | Method and Description |
---|---|
Try<A> |
catchError(Fn1<? super Throwable,? extends Monad<A,Try<?>>> recoveryFn)
|
<S extends Throwable> |
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> |
orThrow()
If this is a success value, return it.
|
abstract <T extends Throwable> |
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()
|
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>> |
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)
|
static Try<Unit> |
trying(SideEffect sideEffect)
|
static <A extends AutoCloseable,B extends AutoCloseable,C extends AutoCloseable,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> |
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> |
withResources(Fn0<? extends A> fn0,
Fn1<? super A,? extends Try<? extends B>> fn)
Given a
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.
|
public final <S extends Throwable> Try<A> catching(Class<S> throwableType, Fn1<? super S,? extends A> recoveryFn)
throwableType
and map it to a success value.public final Try<A> catching(Fn1<? super Throwable,? extends Boolean> predicate, Fn1<? super Throwable,? extends A> recoveryFn)
T
satisfying predicate
and map it to a success value.public final Try<A> ensuring(SideEffect sideEffect)
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.
public final A recover(Fn1<? super Throwable,? extends A> fn)
Throwable
to fn
and
return the result.fn
- the function mapping the potential Throwable
T
to A
public final Throwable forfeit(Fn1<? super A,? extends Throwable> fn)
fn
and return
the result.fn
- the function mapping the potential A
to T
public final <T extends Throwable> A orThrow() throws T extends Throwable
T
- a declarable exception type used for catching checked exceptionsT
- anything that the call site may want to explicitly catch or indicate could be thrownT extends Throwable
public abstract <T extends Throwable> A orThrow(Fn1<? super Throwable,? extends T> fn) throws T extends Throwable
fn
and throw
the result.public final Maybe<A> toMaybe()
Maybe.just(A)
and return it. Otherwise, return Maybe.nothing()
.Maybe
the success valuepublic final Either<Throwable,A> toEither()
Either.right(R)
and return it. Otherwise, return the Throwable
in an Either.left(L)
.public final <L> Either<L,A> toEither(Fn1<? super Throwable,? extends L> fn)
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.public Try<A> throwError(Throwable throwable)
E
into the monad
.throwError
in interface MonadError<Throwable,A,Try<?>>
throwable
- the error typemonad
public Try<A> catchError(Fn1<? super Throwable,? extends Monad<A,Try<?>>> recoveryFn)
catchError
in interface MonadError<Throwable,A,Try<?>>
recoveryFn
- the catch functionMonad
public <B> Try<B> fmap(Fn1<? super A,? extends B> fn)
fmap
in interface Applicative<A,Try<?>>
fmap
in interface Functor<A,Try<?>>
fmap
in interface Monad<A,Try<?>>
fmap
in interface MonadError<Throwable,A,Try<?>>
fmap
in interface MonadRec<A,Try<?>>
fmap
in interface Traversable<A,Try<?>>
B
- the new parameter typefn
- the mapping functionpublic <B> Try<B> flatMap(Fn1<? super A,? extends Monad<B,Try<?>>> f)
flatMap
in interface Monad<A,Try<?>>
flatMap
in interface MonadError<Throwable,A,Try<?>>
flatMap
in interface MonadRec<A,Try<?>>
B
- the resulting monad parameter typef
- the dependent computation over Apublic <B> Try<B> pure(B b)
b
into this applicative functor.pure
in interface Applicative<A,Try<?>>
pure
in interface Monad<A,Try<?>>
pure
in interface MonadError<Throwable,A,Try<?>>
pure
in interface MonadRec<A,Try<?>>
B
- the type of the returned applicative's parameterb
- the valuepublic <B> Try<B> zip(Applicative<Fn1<? super A,? extends B>,Try<?>> appFn)
zip
in interface Applicative<A,Try<?>>
zip
in interface Monad<A,Try<?>>
zip
in interface MonadError<Throwable,A,Try<?>>
zip
in interface MonadRec<A,Try<?>>
B
- the resulting applicative parameter typeappFn
- the other applicative instancepublic <B> Lazy<Try<B>> lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,Try<?>>> lazyAppFn)
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.lazyZip
in interface Applicative<A,Try<?>>
lazyZip
in interface Monad<A,Try<?>>
lazyZip
in interface MonadError<Throwable,A,Try<?>>
lazyZip
in interface MonadRec<A,Try<?>>
B
- the resulting applicative parameter typelazyAppFn
- the lazy other applicative instanceMaybe
,
Either
public <B> Try<B> discardL(Applicative<B,Try<?>> appB)
Applicative
and appB
, discarding this Applicative's
result and returning appB
. This is generally useful for sequentially performing side-effects.discardL
in interface Applicative<A,Try<?>>
discardL
in interface Monad<A,Try<?>>
discardL
in interface MonadError<Throwable,A,Try<?>>
discardL
in interface MonadRec<A,Try<?>>
B
- the type of the returned Applicative's parameterappB
- the other Applicativepublic <B> Try<A> discardR(Applicative<B,Try<?>> appB)
Applicative
and appB
, discarding appB's
result and
returning this Applicative
. This is generally useful for sequentially performing side-effects.discardR
in interface Applicative<A,Try<?>>
discardR
in interface Monad<A,Try<?>>
discardR
in interface MonadError<Throwable,A,Try<?>>
discardR
in interface MonadRec<A,Try<?>>
B
- the type of appB's parameterappB
- the other Applicativepublic <B> Try<B> trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Try<?>>> fn)
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.
trampolineM
in interface MonadRec<A,Try<?>>
B
- the ultimate resulting carrier typefn
- the function to internally trampolineMonadRec
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
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)
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.traverse
in interface Traversable<A,Try<?>>
B
- the resulting element typeApp
- the result applicative typeTravB
- this Traversable instance over BAppTrav
- the full inferred resulting type from the traversalfn
- the function to applypure
- the applicative pure functionpublic static <A> Try<A> success(A a)
A
- the success parameter typea
- the wrapped valuepublic static <A> Try<A> failure(Throwable t)
A
- the success parameter typet
- the Throwable
public static Try<Unit> trying(SideEffect sideEffect)
public static <A extends AutoCloseable,B> Try<B> withResources(Fn0<? extends A> fn0, Fn1<? super A,? extends Try<? extends B>> fn)
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.
A
- the resource typeB
- the function return typefn0
- the resource supplierfn
- the function bodyTry
representing the result of the function's application to the resourcepublic 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)
withResources
that cascades dependent resource
creation via nested calls.A
- the first resource typeB
- the second resource typeC
- the function return typefn0
- the first resource supplierbFn
- the dependent resource functionfn
- the function bodyTry
representing the result of the function's application to the dependent resourcepublic 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)
withResources
that
cascades
two dependent resource creations via nested calls.A
- the first resource typeB
- the second resource typeC
- the final resource typeD
- the function return typefn0
- the first resource supplierbFn
- the second resource functioncFn
- the final resource functionfn
- the function bodyTry
representing the result of the function's application to the final dependent resource