Package io.atlassian.fugue

Class Try<A>

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<A>
    Direct Known Subclasses:
    Try.Delayed, Try.Failure, Try.Success
    public abstract class Try<A>
extends java.lang.Object
implements java.io.Serializable, java.lang.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(io.atlassian.fugue.Checked.Function<A, B, E>) 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:
    Serialized Form

    • Nested Class Summary

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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static long serialVersionUID  

    • Constructor Summary

      Constructors 
      Constructor Description
      Try()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      static <A> Try<A> delayed​(java.util.function.Supplier<Try<A>> supplier)
      Creates a delayed Try, which will return either a Failure or a Success when evaluated.
      static <A> Try<A> failure​(java.lang.Exception e)
      Creates a new failure
      abstract Try<A> filterOrElse​(java.util.function.Predicate<? super A> p, java.util.function.Supplier<java.lang.Exception> orElseSupplier)
      Return a Success if this is a Success and the contained values satisfies the given predicate.
      abstract <B> Try<B> flatMap​(java.util.function.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​(java.util.function.Function<? super java.lang.Exception,​B> failureF, java.util.function.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​(java.util.function.Consumer<? super A> action)
      Perform the given Consumer (side-effect) for the success if success value.
      abstract A getOrElse​(java.util.function.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
      java.util.Iterator<A> iterator()
      Return an iterator for this type.
      abstract <B> Try<B> map​(java.util.function.Function<? super A,​? extends B> f)
      Maps the given function to the value from this `Success` or returns this unchanged if a `Failure`.
      Try<A> orElse​(Try<? extends A> orElse)
      If this is a success, return the same success.
      abstract Try<A> orElse​(java.util.function.Supplier<? extends Try<? extends A>> orElse)
      If this is a success, return the same success.
      abstract <X extends java.lang.Exception>
      Try<A>      		 recover​(java.lang.Class<X> exceptionType, java.util.function.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​(java.util.function.Function<? super java.lang.Exception,​A> f)
      Applies the given function `f` if this is a `Failure` otherwise this unchanged if a 'Success'.
      abstract <X extends java.lang.Exception>
      Try<A>      		 recoverWith​(java.lang.Class<X> exceptionType, java.util.function.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​(java.util.function.Function<? super java.lang.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<java.lang.Iterable<A>> sequence​(java.lang.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​(java.lang.Iterable<Try<T>> trys, java.util.stream.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<java.lang.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 java.util.Optional<A> toOptional()
      Create a Optional from this try.
      abstract java.util.stream.Stream<A> toStream()
      Create a Stream from this try.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.lang.Iterable

        spliterator

    • Constructor Detail

      • Try

        public Try()

    • Method Detail

      • failure

        public static <A> Try<A> failure​(java.lang.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​(java.util.function.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<java.lang.Iterable<A>> sequence​(java.lang.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​(java.lang.Iterable<Try<T>> trys,
                                                  java.util.stream.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​(java.util.function.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​(java.util.function.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​(java.util.function.Function<? super java.lang.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 java.lang.Exception> Try<A> recover​(java.lang.Class<X> exceptionType,
                                                               java.util.function.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​(java.util.function.Function<? super java.lang.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 java.lang.Exception> Try<A> recoverWith​(java.lang.Class<X> exceptionType,
                                                                   java.util.function.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​(java.util.function.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​(java.util.function.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​(java.util.function.Predicate<? super A> p,
                                    java.util.function.Supplier<java.lang.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​(java.util.function.Function<? super java.lang.Exception,​B> failureF,
                           java.util.function.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<java.lang.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 java.util.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 java.util.stream.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​(java.util.function.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 java.lang.Iterable<A>
        Parameters:
        action - the Consumer to apply on the success value
        Since:
        4.7

      • iterator

        public final java.util.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 java.lang.Iterable<A>
        Returns:
        an iterator over the contained value if success, or an empty one otherwise.
        Since:
        4.7.1