Package io.github.oliviercailloux.jaris.exceptions

Interface TryCatchAll<T>

Type Parameters:
T - the type of result possibly kept in the instance.
All Superinterfaces:
TryOptional<T,​Throwable>, io.github.oliviercailloux.jaris.exceptions.TryOptionalImpl.TryVariableCatchInterface<T,​Throwable,​Throwable>
public interface TryCatchAll<T> extends io.github.oliviercailloux.jaris.exceptions.TryOptionalImpl.TryVariableCatchInterface<T,​Throwable,​Throwable>
Represents either a result or a failure and provides operations to deal with cases of successes and of failures in a unified way.

An instance of this class contains either a (non-null) result, in which case it is called a “success”; or a cause of type X (some Exception), in which case it is called a “failure”.

Instances of this type are immutable.

This type provides transformation operations that admit functional operators that can throw throwables. Some of these methods will catch all throwables thrown by such functional operators, while others will propagate any exception thrown to the caller (see the method documentation). This is the only difference between this type and the Try type: the latter catches only checked exceptions instead of all throwables.

It is generally a bad idea to catch throwables that are not exceptions. Unless dealing with a very specific use case (such as checking correctness of some code), please consider using Try instead of TryCatchAll.

When the documentation of a method indicates that it catches checked exceptions thrown by some provided functional interface, it is implicit that if the provided functional interface throws anything that is not a checked exception, then it is not caught, and simply thrown back to the caller.

  • Method Summary

    Modifier and Type
    Method
    Description
    <U,​ V,​ Y extends Exception>
    TryCatchAll<V>
    and​(TryCatchAll<U> t2, Throwing.BiFunction<? super T,​? super U,​? extends V,​Y> merger)
    Returns this failure if this instance is a failure; the provided failure if it is a failure and this instance is a success; and a success containing the merge of the result contained in this instance and the one contained in t2, if they both are successes and merger does not return null.
    <U> TryCatchAll<U>
    andApply​(Throwing.Function<? super T,​? extends U,​? extends Throwable> mapper)
    Returns this failure if this instance is a failure; a failure containing the cause thrown by the given function if it threw a checked exception; a failure containing a NullPointerException as a cause if the provided mapper returned null; or a success containing the result of applying the provided mapper to the result contained in this instance if it is a success and the mapper returned a non-null result.
    TryCatchAll<T>
    andConsume​(Throwing.Consumer<? super T,​?> consumer)
    Returns a failure containing this cause if this instance is a failure, a failure containing the checked exception that the provided consumer threw if it did throw one, and a success containg the result contained in this instance otherwise.
    TryCatchAll<T>
    andRun​(Throwing.Runnable<?> runnable)
    Returns a failure containing this cause if this instance is a failure, a failure containing the checked exception that the provided runnable threw if it did throw one, and a success containg the result contained in this instance if this instance is a success and the provided runnable does not throw.
    static <T> TryCatchAll<T>
    failure​(Throwable cause)
    Returns a failure containing the given cause.
    static <T> TryCatchAll<T>
    get​(Throwing.Supplier<? extends T,​?> supplier)
    Attempts to get and encapsulate a result from the given supplier.
    <W extends Exception>
    TryCatchAll<T>
    or​(Throwing.Supplier<? extends T,​?> supplier, Throwing.BiFunction<? super Throwable,​? super Throwable,​? extends Throwable,​W> exceptionsMerger)
    Returns this instance if it is a success, or merges this instance with the one provided by the supplier.
    static <T> TryCatchAll<T>
    success​(T result)
    Returns a success containing the given result.

    Methods inherited from interface io.github.oliviercailloux.jaris.exceptions.TryOptional

    getCause, getResult, toString

    Methods inherited from interface io.github.oliviercailloux.jaris.exceptions.TryOptionalImpl.TryVariableCatchInterface

    equals, isFailure, isSuccess, map, orConsumeCause, orMapCause, orThrow, orThrow

  • Method Details

    • success

      static <T> TryCatchAll<T> success​(T result)
      Returns a success containing the given result.
      Type Parameters:
      T - the type of result declared to be (and effectively) kept in the instance
      Parameters:
      result - the result to contain
      Returns:
      a success

    • failure

      static <T> TryCatchAll<T> failure​(Throwable cause)
      Returns a failure containing the given cause.
      Type Parameters:
      T - the type of result declared to be (but not effectively) kept in the instance
      Parameters:
      cause - the cause to contain
      Returns:
      a failure

    • get

      static <T> TryCatchAll<T> get​(Throwing.Supplier<? extends T,​?> supplier)
      Attempts to get and encapsulate a result from the given supplier.

      This method returns a failure iff the given supplier throws or returns null.

      Type Parameters:
      T - the type of result declared to be kept in the instance
      Parameters:
      supplier - the supplier to get a result from
      Returns:
      a success containing the result if the supplier returns a result; a failure containing the throwable if the supplier throws

    • andRun

      TryCatchAll<T> andRun​(Throwing.Runnable<?> runnable)
      Returns a failure containing this cause if this instance is a failure, a failure containing the checked exception that the provided runnable threw if it did throw one, and a success containg the result contained in this instance if this instance is a success and the provided runnable does not throw.

      If this instance is a failure, returns this instance without running the provided runnable. Otherwise, if the runnable succeeds (that is, does not throw), returns this instance. Otherwise, if the runnable throws a checked exception, returns a failure containing the cause it threw.

      Specified by:
      andRun in interface io.github.oliviercailloux.jaris.exceptions.TryOptionalImpl.TryVariableCatchInterface<T,​Throwable,​Throwable>
      Parameters:
      runnable - the function to run if this instance is a success
      Returns:
      a success iff this instance is a success and the provided runnable terminated without throwing

    • andConsume

      TryCatchAll<T> andConsume​(Throwing.Consumer<? super T,​?> consumer)
      Returns a failure containing this cause if this instance is a failure, a failure containing the checked exception that the provided consumer threw if it did throw one, and a success containg the result contained in this instance otherwise.

      If this instance is a failure, returns this instance without running the provided consumer. Otherwise, if the consumer succeeds (that is, does not throw), returns this instance. Otherwise, if the consumer throws a checked exception, returns a failure containing the cause it threw.

      Specified by:
      andConsume in interface io.github.oliviercailloux.jaris.exceptions.TryOptionalImpl.TryVariableCatchInterface<T,​Throwable,​Throwable>
      Parameters:
      consumer - the function to run if this instance is a success
      Returns:
      a success iff this instance is a success and the provided consumer terminated without throwing

    • and

      <U,​ V,​ Y extends Exception> TryCatchAll<V> and​(TryCatchAll<U> t2, Throwing.BiFunction<? super T,​? super U,​? extends V,​Y> merger) throws Y
      Returns this failure if this instance is a failure; the provided failure if it is a failure and this instance is a success; and a success containing the merge of the result contained in this instance and the one contained in t2, if they both are successes and merger does not return null.
      Type Parameters:
      U - the type of result that the provided try is declared to contain
      V - the type of result that the returned try will be declared to contain
      Y - a type of exception that the provided merger may throw
      Parameters:
      t2 - the try to consider if this try is a success
      merger - the function invoked to merge the results if both this and the given try are successes
      Returns:
      a success if this instance and the given try are two successes
      Throws:
      Y - if the merger was applied and threw a checked exception
      NullPointerException - if the merger was applied and returned null

    • andApply

      <U> TryCatchAll<U> andApply​(Throwing.Function<? super T,​? extends U,​? extends Throwable> mapper)
      Returns this failure if this instance is a failure; a failure containing the cause thrown by the given function if it threw a checked exception; a failure containing a NullPointerException as a cause if the provided mapper returned null; or a success containing the result of applying the provided mapper to the result contained in this instance if it is a success and the mapper returned a non-null result.

      Equivalent to t.map(r -> TryCatchAll.get(() -> mapper.apply(r)), c -> t).

      Specified by:
      andApply in interface io.github.oliviercailloux.jaris.exceptions.TryOptionalImpl.TryVariableCatchInterface<T,​Throwable,​Throwable>
      Type Parameters:
      U - the type of result that the returned try will be declared to contain
      Parameters:
      mapper - the mapper to apply to the result contained in this instance if it is a success
      Returns:
      a success iff this instance is a success and the provided mapper returns a non-null result

    • or

      <W extends Exception> TryCatchAll<T> or​(Throwing.Supplier<? extends T,​?> supplier, Throwing.BiFunction<? super Throwable,​? super Throwable,​? extends Throwable,​W> exceptionsMerger) throws W
      Returns this instance if it is a success, or merges this instance with the one provided by the supplier.

      Returns this instance if it is a success. Otherwise, attempts to get a result from the given supplier. If this succeeds, that is, if the supplier returns a non-null result, returns a success containing that result. Otherwise, if the supplier throws, merges both throwables using the given exceptionMerger and returns a failure containing that merged cause, provided it is not null. If the supplier returns null, it is treated as if it had thrown a NullPointerException: this method merges the NullPointerException with the cause contained in this instance using the provided exceptionMerger and returns a failure containing that merged cause, provided it is not null.

      Type Parameters:
      W - a type of exception that the provided merger may throw
      Parameters:
      supplier - the supplier that is invoked if this try is a failure
      exceptionsMerger - the function invoked to merge both exceptions if this try is a failure and the given supplier threw a checked exception
      Returns:
      a success if this instance is a success or the given supplier returned a result
      Throws:
      W - iff the merger was applied and threw a checked exception