Class Try<V extends @Nullable Object>

java.lang.Object
org.junit.platform.commons.function.Try<V>
@API(status=MAINTAINED, since="1.4") public abstract class Try<V extends @Nullable Object> extends Object
A container object which may either contain a nullable value in case of success or an exception in case of failure.

Instances of this class should be returned by methods instead of Optional when callers might want to report the exception via logging or by wrapping it in another exception at a later point in time, e.g. via getOrThrow(Function).

Moreover, it makes it particularly convenient to attach follow-up actions should the Try have been successful (cf. andThen(java.util.function.Function<V, org.junit.platform.commons.function.Try<U>>) and andThenTry(org.junit.platform.commons.function.Try.Transformer<V, U>)) or fallback actions should it not have been (cf. orElse(java.util.function.Supplier<org.junit.platform.commons.function.Try<V>>) and orElseTry(java.util.concurrent.Callable<V>)).

Since:
1.4

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    Try.Transformer<S extends @Nullable Object, T extends @Nullable Object>
    A transformer for values of type S to type T.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract <U> Try<U>
    andThen(Function<V,Try<U>> function)
    If this Try is a success, apply the supplied function to its value and return the resulting Try; if this Try is a failure, do nothing.
    abstract <U> Try<U>
    andThenTry(Try.Transformer<V,U> transformer)
    If this Try is a success, apply the supplied transformer to its value and return a new successful or failed Try depending on the transformer's outcome; if this Try is a failure, do nothing.
    static <V extends @Nullable Object>
    Try<V>
    call(Callable<V> action)
    Call the supplied Callable and return a successful Try that contains the returned value or, in case an exception was thrown, a failed Try that contains the exception.
    static <V> Try<V>
    failure(Exception cause)
    Convert the supplied exception into a failed Try.
    abstract V
    get()
    If this Try is a success, get the contained value; if this Try is a failure, throw the contained exception.
    final @NonNull V
    getNonNull()
    If this Try is a success, get the contained value; if this Try is a failure, throw the contained exception.
    final <E extends Exception>
    @NonNull V
    getNonNullOrThrow(Function<@Nullable Exception, E> exceptionTransformer)
    If this Try is a success, get the contained value; if this Try is a failure, call the supplied Function with the contained exception and throw the resulting Exception.
    abstract <E extends Exception>
    V
    getOrThrow(Function<? super Exception, E> exceptionTransformer)
    If this Try is a success, get the contained value; if this Try is a failure, call the supplied Function with the contained exception and throw the resulting Exception.
    abstract Try<V>
    ifFailure(Consumer<Exception> causeConsumer)
    If this Try is a failure, call the supplied Consumer with the contained exception; otherwise, do nothing.
    abstract Try<V>
    ifSuccess(Consumer<V> valueConsumer)
    If this Try is a success, call the supplied Consumer with the contained value; otherwise, do nothing.
    abstract Try<V>
    orElse(Supplier<Try<V>> supplier)
    If this Try is a failure, call the supplied supplier and return the resulting Try; if this Try is a success, do nothing.
    abstract Try<V>
    orElseTry(Callable<V> action)
    If this Try is a failure, call the supplied action and return a new successful or failed Try depending on the action's outcome; if this Try is a success, do nothing.
    static <V extends @Nullable Object>
    Try<V>
    success(V value)
    Convert the supplied value into a succeeded Try.
    abstract Optional<V>
    toOptional()
    If this Try is a failure, return an empty Optional; if this Try is a success, wrap the contained value using Optional.ofNullable(Object).

    Methods inherited from class java.lang.Object

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

  • Method Details

    • call

      public static <V extends @Nullable Object> Try<V> call(Callable<V> action)
      Call the supplied Callable and return a successful Try that contains the returned value or, in case an exception was thrown, a failed Try that contains the exception.
      Parameters:
      action - the action to try; must not be null
      Returns:
      a succeeded or failed Try depending on the outcome of the supplied action; never null
      See Also:

    • success

      public static <V extends @Nullable Object> Try<V> success(V value)
      Convert the supplied value into a succeeded Try.
      Parameters:
      value - the value to wrap; potentially null
      Returns:
      a succeeded Try that contains the supplied value; never null

    • failure

      public static <V> Try<V> failure(Exception cause)
      Convert the supplied exception into a failed Try.
      Parameters:
      cause - the exception to wrap; must not be null
      Returns:
      a failed Try that contains the supplied value; never null

    • andThenTry

      public abstract <U> Try<U> andThenTry(Try.Transformer<V,U> transformer)
      If this Try is a success, apply the supplied transformer to its value and return a new successful or failed Try depending on the transformer's outcome; if this Try is a failure, do nothing.
      Parameters:
      transformer - the transformer to try; must not be null
      Returns:
      a succeeded or failed Try; never null

    • andThen

      public abstract <U> Try<U> andThen(Function<V,Try<U>> function)
      If this Try is a success, apply the supplied function to its value and return the resulting Try; if this Try is a failure, do nothing.
      Parameters:
      function - the function to apply; must not be null
      Returns:
      a succeeded or failed Try; never null

    • orElseTry

      public abstract Try<V> orElseTry(Callable<V> action)
      If this Try is a failure, call the supplied action and return a new successful or failed Try depending on the action's outcome; if this Try is a success, do nothing.
      Parameters:
      action - the action to try; must not be null
      Returns:
      a succeeded or failed Try; never null

    • orElse

      public abstract Try<V> orElse(Supplier<Try<V>> supplier)
      If this Try is a failure, call the supplied supplier and return the resulting Try; if this Try is a success, do nothing.
      Parameters:
      supplier - the supplier to call; must not be null
      Returns:
      a succeeded or failed Try; never null

    • get

      public abstract V get() throws Exception
      If this Try is a success, get the contained value; if this Try is a failure, throw the contained exception.
      Returns:
      the contained value, if available; potentially null
      Throws:
      Exception - if this Try is a failure

    • getNonNull

      @API(status=EXPERIMENTAL, since="6.0") public final @NonNull V getNonNull() throws Exception
      If this Try is a success, get the contained value; if this Try is a failure, throw the contained exception.
      Returns:
      the contained value, if available
      Throws:
      Exception - if this Try is a failure or the contained value is null
      Since:
      6.0

    • getOrThrow

      public abstract <E extends Exception> V getOrThrow(Function<? super Exception, E> exceptionTransformer) throws E
      If this Try is a success, get the contained value; if this Try is a failure, call the supplied Function with the contained exception and throw the resulting Exception.
      Parameters:
      exceptionTransformer - the transformer to be called with the contained exception, if available; must not be null
      Returns:
      the contained value, if available
      Throws:
      E - if this Try is a failure

    • getNonNullOrThrow

      @API(status=EXPERIMENTAL, since="6.0") public final <E extends Exception> @NonNull V getNonNullOrThrow(Function<@Nullable Exception, E> exceptionTransformer) throws E
      If this Try is a success, get the contained value; if this Try is a failure, call the supplied Function with the contained exception and throw the resulting Exception.
      Parameters:
      exceptionTransformer - the transformer to be called with the contained exception, if available; must not be null
      Returns:
      the contained value, if available and not null
      Throws:
      E - if this Try is a failure or the contained value is null

    • ifSuccess

      public abstract Try<V> ifSuccess(Consumer<V> valueConsumer)
      If this Try is a success, call the supplied Consumer with the contained value; otherwise, do nothing.
      Parameters:
      valueConsumer - the consumer to be called with the contained value, if available; must not be null
      Returns:
      the same Try for method chaining

    • ifFailure

      public abstract Try<V> ifFailure(Consumer<Exception> causeConsumer)
      If this Try is a failure, call the supplied Consumer with the contained exception; otherwise, do nothing.
      Parameters:
      causeConsumer - the consumer to be called with the contained exception, if available; must not be null
      Returns:
      the same Try for method chaining

    • toOptional

      public abstract Optional<V> toOptional()
      If this Try is a failure, return an empty Optional; if this Try is a success, wrap the contained value using Optional.ofNullable(Object).
      Returns:
      an Optional; never null but potentially empty