Class Try<A>

java.lang.Object
io.atlassian.fugue.Try<A>
All Implemented Interfaces:
Serializable, Iterable<A>
Direct Known Subclasses:
Try.Delayed, Try.Failure, Try.Success
public abstract class Try<A> extends Object implements Serializable, Iterable<A>
A Try represents a computation that may either throw an exception or return a value. A Try will either be Success wrapping a value or Failure which wraps an exception.

This class is similar to Either, but is explicit about having a success and failure case. Unless method level javadoc says otherwise, methods will not automatically catch exceptions thrown by function arguments. In particular map(Function) will not catch automatically catch thrown exceptions, instead you should use Checked.lift(Checked.Function) to to make the function explicitly return a Try and the use flatMap(Function).

Note that since 4.7.0, all API methods describe whether or not they will result in a Delayed Try being evaluated. In addition to this, any action to Serialize a Delayed Try will result in it being evaluated, and the underlying Try Success or Failure result being serialized.

Since:
4.4.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    Try.Delayed<A>
     
    private static final class 
    Try.Failure<A>
     
    private static final class 
    Try.Success<A>
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final long
    serialVersionUID
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Try()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static <A> Try<A>
    delayed(Supplier<Try<A>> supplier)
    Creates a delayed Try, which will return either a Failure or a Success when evaluated.
    static <A> Try<A>
    failure(Exception e)
    Creates a new failure
    abstract Try<A>
    filterOrElse(Predicate<? super A> p, Supplier<Exception> orElseSupplier)
    Return a Success if this is a Success and the contained values satisfies the given predicate.
    abstract <B> Try<B>
    flatMap(Function<? super A, Try<B>> f)
    Binds the given function across the success value if it is one.
    static <A> Try<A>
    flatten(Try<Try<A>> t)
    Reduces a nested Try by a single level
    abstract <B> B
    fold(Function<? super Exception, B> failureF, Function<A,B> successF)
    Applies the function to the wrapped value, applying failureF it this is a Failure and successF if this is a Success.
    abstract void
    forEach(Consumer<? super A> action)
    Perform the given Consumer (side-effect) for the success if success value.
    abstract A
    getOrElse(Supplier<A> s)
    Returns the contained value if this is a success otherwise call the supplier and return its value.
    abstract boolean
    isFailure()
    Returns true if this failure, otherwise false
    abstract boolean
    isSuccess()
    Returns true if this success, otherwise false
    final Iterator<A>
    iterator()
    Return an iterator for this type.
    abstract <B> Try<B>
    map(Function<? super A, ? extends B> f)
    Maps the given function to the value from this `Success` or returns this unchanged if a `Failure`.
    final Try<A>
    orElse(Try<? extends A> orElse)
    If this is a success, return the same success.
    abstract Try<A>
    orElse(Supplier<? extends Try<? extends A>> orElse)
    If this is a success, return the same success.
    abstract <X extends Exception>
    Try<A>
    recover(Class<X> exceptionType, Function<? super X, A> f)
    Applies the given function `f` if this is a `Failure` with certain exception type otherwise leaves this unchanged.
    abstract Try<A>
    recover(Function<? super Exception, A> f)
    Applies the given function `f` if this is a `Failure` otherwise this unchanged if a 'Success'.
    abstract <X extends Exception>
    Try<A>
    recoverWith(Class<X> exceptionType, Function<? super X, Try<A>> f)
    Binds the given function across certain exception type if it is one, otherwise this unchanged.
    abstract Try<A>
    recoverWith(Function<? super Exception, Try<A>> f)
    Binds the given function across the failure value if it is one, otherwise this unchanged if a 'Success'.
    static <A> Try<Iterable<A>>
    sequence(Iterable<Try<A>> trys)
    Returns a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
    static <T,A,R> Try<R>
    sequence(Iterable<Try<T>> trys, Collector<T,A,R> collector)
    Returns a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
    static <A> Try<A>
    successful(A value)
    Creates a new Success
    abstract Either<Exception, A>
    toEither()
    Convert this Try to an Either, becoming a left if this is a failure and a right if this is a success.
    abstract Option<A>
    toOption()
    Convert this Try to an Option.
    abstract Optional<A>
    toOptional()
    Create a Optional from this try.
    abstract Stream<A>
    toStream()
    Create a Stream from this try.

    Methods inherited from class Object

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

    Methods inherited from interface Iterable

    spliterator

  • Field Details

  • Constructor Details

    • Try

      public Try()

  • Method Details

    • failure

      public static <A> Try<A> failure(Exception e)
      Creates a new failure
      Type Parameters:
      A - the success type
      Parameters:
      e - an exception to wrap, must not be null.
      Returns:
      a new Failure wrapping e.

    • successful

      public static <A> Try<A> successful(A value)
      Creates a new Success
      Type Parameters:
      A - the wrapped value type
      Parameters:
      value - a value to wrap, must not be null
      Returns:
      a new Success wrapping v

    • delayed

      public static <A> Try<A> delayed(Supplier<Try<A>> supplier)
      Creates a delayed Try, which will return either a Failure or a Success when evaluated. The supplier is called only once, no matter how many times the returned delayed Try is evaluated.
      Type Parameters:
      A - the wrapped value type
      Parameters:
      supplier - a supplier that returns a Try of A.
      Returns:
      a new Delayed Try wrapping the supplier.

    • sequence

      public static <A> Try<Iterable<A>> sequence(Iterable<Try<A>> trys)
      Returns a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
      Type Parameters:
      A - The success type
      Parameters:
      trys - an iterable of try values
      Returns:
      a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure

    • sequence

      public static <T,A,R> Try<R> sequence(Iterable<Try<T>> trys, Collector<T,A,R> collector)
      Returns a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
      Type Parameters:
      T - The success type
      A - The intermediate accumulator type
      R - The result type
      Parameters:
      trys - an iterable of try values
      collector - result collector
      Returns:
      a success wrapping all of the values if all of the arguments were a success, otherwise this returns the first failure
      Since:
      4.6.0

    • flatten

      public static <A> Try<A> flatten(Try<Try<A>> t)
      Reduces a nested Try by a single level
      Type Parameters:
      A - The success type
      Parameters:
      t - A nested Try
      Returns:
      The flattened try

    • isFailure

      public abstract boolean isFailure()
      Returns true if this failure, otherwise false

      Note that for delayed(Supplier) this is an evaluating operation.

      Returns:
      true if this failure, otherwise false

    • isSuccess

      public abstract boolean isSuccess()
      Returns true if this success, otherwise false

      Note that for delayed(Supplier) this is an evaluating operation.

      Returns:
      true if this success, otherwise false

    • flatMap

      public abstract <B> Try<B> flatMap(Function<? super A, Try<B>> f)
      Binds the given function across the success value if it is one.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Type Parameters:
      B - result type
      Parameters:
      f - the function to bind.
      Returns:
      A new Try value after binding with the function applied if this is a Success, otherwise returns this if this is a `Failure`.

    • map

      public abstract <B> Try<B> map(Function<? super A, ? extends B> f)
      Maps the given function to the value from this `Success` or returns this unchanged if a `Failure`.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Type Parameters:
      B - result type
      Parameters:
      f - the function to apply
      Returns:
      `f` applied to the `Success`, otherwise returns this if this is a `Failure`.

    • recover

      public abstract Try<A> recover(Function<? super Exception, A> f)
      Applies the given function `f` if this is a `Failure` otherwise this unchanged if a 'Success'. This is like map for the failure.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Parameters:
      f - the function to apply
      Returns:
      `f` applied to the `Failure`, otherwise returns this if this is a `Success`.

    • recover

      public abstract <X extends Exception> Try<A> recover(Class<X> exceptionType, Function<? super X, A> f)
      Applies the given function `f` if this is a `Failure` with certain exception type otherwise leaves this unchanged. This is like map for exceptions types.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Type Parameters:
      X - exception type
      Parameters:
      exceptionType - exception class
      f - the function to apply
      Returns:
      `f` applied to the `Failure`, otherwise returns this if this is a `Success` or the exception does not match the exception type.

    • recoverWith

      public abstract Try<A> recoverWith(Function<? super Exception, Try<A>> f)
      Binds the given function across the failure value if it is one, otherwise this unchanged if a 'Success'. This is like flatmap for the failure.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Parameters:
      f - the function to bind.
      Returns:
      A new Try value after binding with the function applied if this is a `Failure`, otherwise returns this if this is a `Success`.

    • recoverWith

      public abstract <X extends Exception> Try<A> recoverWith(Class<X> exceptionType, Function<? super X, Try<A>> f)
      Binds the given function across certain exception type if it is one, otherwise this unchanged. This is like flatmap for exceptions types.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Type Parameters:
      X - exception type
      Parameters:
      exceptionType - exception class
      f - the function to apply
      Returns:
      A new Try value after binding with the function applied if this is a `Failure`, otherwise returns this if this is a `Success` or the exception does not match the exception type.

    • getOrElse

      public abstract A getOrElse(Supplier<A> s)
      Returns the contained value if this is a success otherwise call the supplier and return its value.

      Note that for delayed(Supplier) this is an evaluating operation.

      Parameters:
      s - called if this is a failure
      Returns:
      the wrapped value or the value from the Supplier

    • orElse

      public final Try<A> orElse(Try<? extends A> orElse)
      If this is a success, return the same success. Otherwise, return orElse.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Parameters:
      orElse - try to return if this is failure
      Returns:
      this or orElse
      Since:
      4.7

    • orElse

      public abstract Try<A> orElse(Supplier<? extends Try<? extends A>> orElse)
      If this is a success, return the same success. Otherwise, return value supplied by orElse.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Parameters:
      orElse - try to return if this is failure
      Returns:
      this or orElse
      Since:
      4.7

    • filterOrElse

      public abstract Try<A> filterOrElse(Predicate<? super A> p, Supplier<Exception> orElseSupplier)
      Return a Success if this is a Success and the contained values satisfies the given predicate.

      If this is a Success but the predicate is not satisfied, return a Failure with the value provided by the orElseSupplier.

      Return a Failure if this a Failure with the contained value.

      Note that for delayed(Supplier) this is not an evaluating operation.

      Parameters:
      p - The predicate function to test on the right contained value.
      orElseSupplier - The supplier to execute when is a success, and predicate is unsatisfied
      Returns:
      a new Try that will be either the existing success/failure or a failure with result of orElseSupplier
      Since:
      4.7.0

    • fold

      public abstract <B> B fold(Function<? super Exception, B> failureF, Function<A,B> successF)
      Applies the function to the wrapped value, applying failureF it this is a Failure and successF if this is a Success.

      Note that for delayed(Supplier) this is an evaluating operation.

      Type Parameters:
      B - the destination type
      Parameters:
      failureF - the function to apply if this is a Failure
      successF - the function to apply if this is a Success
      Returns:
      the result of the applied function

    • toEither

      public abstract Either<Exception, A> toEither()
      Convert this Try to an Either, becoming a left if this is a failure and a right if this is a success.

      Note that for delayed(Supplier) this is an evaluating operation.

      Returns:
      this value wrapped in right if a success, and the exception wrapped in a left if a failure.

    • toOption

      public abstract Option<A> toOption()
      Convert this Try to an Option. Returns Some with a value if it is a success, otherwise None.

      Note that for delayed(Supplier) this is an evaluating operation.

      Returns:
      The success's value in Some if it exists, otherwise None

    • toOptional

      public abstract Optional<A> toOptional()
      Create a Optional from this try.

      Note that for delayed(Supplier) this is an evaluating operation.

      Returns:
      Optional.of(Object) with the value if success, Optional.empty() if failure.
      Since:
      4.7

    • toStream

      public abstract Stream<A> toStream()
      Create a Stream from this try.

      Note that for delayed(Supplier) this is an evaluating operation.

      Returns:
      Stream.of(Object) with the value if success, Stream.empty() if failure.
      Since:
      4.7

    • forEach

      public abstract void forEach(Consumer<? super A> action)
      Perform the given Consumer (side-effect) for the success if success value.

      Note that for delayed(Supplier) this is an evaluating operation.

      Specified by:
      forEach in interface Iterable<A>
      Parameters:
      action - the Consumer to apply on the success value
      Since:
      4.7

    • iterator

      public final Iterator<A> iterator()
      Return an iterator for this type. This will be an empty iterator for the failure isFailure() case, and a iterator of a single value for the success isSuccess() case.

      Note that for delayed(Supplier) this is an evaluating operation.

      Specified by:
      iterator in interface Iterable<A>
      Returns:
      an iterator over the contained value if success, or an empty one otherwise.
      Since:
      4.7.1