Package org.jtrim2.concurrent

Class AsyncTasks

java.lang.Object
org.jtrim2.concurrent.AsyncTasks
public final class AsyncTasks extends Object
Defines utility methods to help with asynchronous tasks relying on CompletableFuture or CompletionStage.

  • Method Details

    • expectNoError

      public static <R> R expectNoError(Throwable error)
      Logs the argument as a SEVERE level issue, if it is not null and does not represent cancellation.

      This function is expected to be used with CompletionStage's exceptionally method to log any uncaught error. This is important to do as a last action because otherwise the stack trace of the thrown exception will be lost. That is, the intended use is: 

      
 CompletionStage<?> future = ...;
 future.exceptionally(Tasks::expectNoError);

      This method does not log OperationCanceledException because cancellation is considered as a normal event.

      Type Parameters:
      R - any type
      Parameters:
      error - the error to be logged if not null. This argument can be null, in which case, this method does nothing.
      Returns:
      always null
      See Also:

    • unwrap

      public static Throwable unwrap(Throwable error)
      Returns the actual error represented by the given exception. This method was designed to be used with CompletableFuture in mind. That is, CompletableFuture often wraps exceptions in a CompletionException and this method unwraps that exception and returns the original cause.
      Parameters:
      error - the error to be unwrapped. This argument can be null, in which case the return value is also null.
      Returns:
      the actual exception represented by the given exception. This method only returns null if the given exception was also null.

    • isCanceled

      public static boolean isCanceled(Throwable error)
      Returns true if the given exception represents a cancellation event. This method is can be safely used with the error reported by CompletableFuture whether it is thrown or if the error is provided in a callback.
      Parameters:
      error - the exception to be checked if it represents a cancellation event. This argument can be null, in which case, the return value is false.
      Returns:
      true if the given exception represents a cancellation event, false otherwise

    • isError

      public static boolean isError(Throwable error)
      Returns true if the given exception represents an error event. That is, if the given exception is null or represents cancellation.
      Parameters:
      error - the exception to be checked if it represents an error event. This argument can be null, in which case, the return value is false.
      Returns:
      true if the given exception represents an error event, false otherwise

    • completeForwarder

      public static <V> BiConsumer<V,Throwable> completeForwarder(CompletableFuture<? super V> future)
      Returns a BiConsumer passable to the whenComplete method of CompletionStage completing the passed CompletableFuture. That is, the returned BiConsumer simply calls the complete method with the arguments passed to the returned BiConsumer.
      Type Parameters:
      V - the type of the result of the asynchronous computation
      Parameters:
      future - the future to be completed by the returned BiConsumer. This argument cannot be null.
      Returns:
      a BiConsumer passable to the whenComplete method of CompletionStage completing the passed CompletableFuture. This method never returns null.

    • complete

      public static <V> void complete(V result, Throwable error, CompletableFuture<? super V> future)
      Completes the passed future exceptionally or normally. This method was designed to be called from the whenComplete method of CompletionStage.

      If the passed exception is not null, the passed future is completed exceptionally with the given error. Otherwise, the passed future is completed normally with the given result.

      Type Parameters:
      V - the type of the result of the asynchronous computation
      Parameters:
      result - the result of the asynchronous computation to complete the passed future normally with. This argument can be null, if the asynchronous computation yielded null result, and should be null if the passed error is not null.
      error - the exception to complete the passed future with (if not null. This argument can be null, if the asynchronous computation completed normally. However, if not null, the result argument will be ignored.
      future - the CompletableFuture to be completed. This future will always be completed after this method returns. This argument cannot be null.

    • errorResultHandler

      public static <E extends Throwable> BiConsumer<E,Throwable> errorResultHandler(Consumer<? super Throwable> errorHandler)
      Returns a BiConsumer notifying the passed error handler if any of the arguments of the returned BiConsumer is not null. See handleErrorResult for further explanation.

      The returned BiConsumer was designed to be passable to the whenComplete method of CompletionStage.

      Type Parameters:
      E - the type of the result of the asynchronous computation
      Parameters:
      errorHandler - the handler to be notified in case of an error. This argument cannot be null.
      Returns:
      a BiConsumer notifying the passed error handler if any of the arguments of the returned BiConsumer is not null. This method never returns null.
      See Also:

    • handleErrorResult

      public static void handleErrorResult(Throwable result, Throwable error, Consumer<? super Throwable> errorHandler)
      Calls the given error handler if any of the exception arguments is not null. If none of the exception arguments is null, the result argument is passed and the error argument is added as a suppressed exception. If both argument is null, the handler is not called.

      This method is useful if an asynchronous computation returns a Throwable as a result but may also throw an exception.

      Parameters:
      result - the result exception which takes precedence over the other exception argument. This argument can be null.
      error - the error which will only be (directly) passed to the handler if the result argument is null. This argument can be null.
      errorHandler - the handler to be notified if any of the exception arguments is not null. This argument cannot be null.
      See Also: