#327: fix error handling for completable future (#328)

* #324: extended tests to cover default error handler
* #328: improve JavaDoc

Author: hohwille

modules/http-client/src/main/java/com/devonfw/module/httpclient/common/impl/AbstractAsyncServiceHttpClient.java

@@ -50,30 +50,7 @@ protected <R> void doCall(ServiceClientInvocation<S> invocation, Consumer<R> res
     HttpRequest request = createRequest(invocation);
     CompletableFuture<HttpResponse<String>> future = this.client.getHttpClient().sendAsync(request,
         BodyHandlers.ofString());
-    future.thenAccept(response -> handleResponse(response, startTime, invocation, resultHandler));
-  }
-
-  @SuppressWarnings({ "rawtypes", "unchecked" })
-  private void handleResponse(HttpResponse<?> response, long startTime, ServiceClientInvocation<S> invocation,
-      Consumer resultHandler) {
-
-    Throwable error = null;
-    String service = invocation.getServiceDescription(response.uri().toString());
-    try {
-      int statusCode = response.statusCode();
-      if (statusCode >= 400) {
-        error = createError(response, invocation, service);
-        this.errorHandler.accept(error);
-      } else {
-        Object result = createResult(response, invocation);
-        resultHandler.accept(result);
-      }
-    } catch (Throwable t) {
-      this.errorHandler.accept(t);
-      error = t;
-    } finally {
-      ServiceClientPerformanceLogger.log(startTime, service, response.statusCode(), error);
-    }
+    future.thenAccept(response -> handleResponse(response, startTime, invocation, resultHandler, getErrorHandler()));
   }
 
   private Throwable createError(HttpResponse<?> response, ServiceClientInvocation<S> invocation, String service) {
@@ -107,7 +84,8 @@ protected Object handleUnsupportedBody(Object body) {
   /**
    * @param response the received {@link HttpResponse}.
    * @param invocation the {@link ServiceClientInvocation}.
-   * @return the unmarshalled result object from the response body or {@code null} if no body was found or return type is {@code void}.
+   * @return the unmarshalled result object from the response body or {@code null} if no body was found or return type
+   *         is {@code void}.
    * @throws IllegalStateException if the unmarshalling of the result failed.
    * @throws UnsupportedOperationException if the body type is not supported.
    */
@@ -126,27 +104,30 @@ protected <R> CompletableFuture<R> doCall(ServiceClientInvocation<S> invocation)
     HttpRequest request = createRequest(invocation);
     CompletableFuture<HttpResponse<String>> future = this.client.getHttpClient().sendAsync(request,
         BodyHandlers.ofString());
-    return future.thenApplyAsync(response -> handleResponse(response, startTime, invocation));
-
+    return future.thenApplyAsync(
+        response -> handleResponse(response, startTime, invocation, null, ErrorHandlerThrowImmediately.get()));
   }
 
-  @SuppressWarnings({ "rawtypes", "unchecked" })
-  private <R> R handleResponse(HttpResponse<?> response, long startTime, ServiceClientInvocation<S> invocation) {
+  @SuppressWarnings({ "unchecked" })
+  private <R> R handleResponse(HttpResponse<?> response, long startTime, ServiceClientInvocation<S> invocation,
+      Consumer<R> resultHandler, Consumer<Throwable> errorHandler) {
 
     Throwable error = null;
     String service = invocation.getServiceDescription(response.uri().toString());
     try {
       int statusCode = response.statusCode();
       if (statusCode >= 400) {
         error = createError(response, invocation, service);
-        this.errorHandler.accept(error);
+        errorHandler.accept(error);
       } else {
-
-        Object result = createResult(response, invocation);
-        return (R) result;
+        R result = (R) createResult(response, invocation);
+        if (resultHandler != null) {
+          resultHandler.accept(result);
+        }
+        return result;
       }
     } catch (Throwable t) {
-      this.errorHandler.accept(t);
+      errorHandler.accept(t);
       error = t;
     } finally {
       ServiceClientPerformanceLogger.log(startTime, service, response.statusCode(), error);

modules/http-client/src/main/java/com/devonfw/module/httpclient/common/impl/ErrorHandlerThrowImmediately.java

@@ -0,0 +1,32 @@
+package com.devonfw.module.httpclient.common.impl;
+
+import java.util.function.Consumer;
+
+/**
+ * {@link Consumer} used as error-handling to immediately throw received exceptions.
+ *
+ * @since 2020.12.001
+ */
+class ErrorHandlerThrowImmediately implements Consumer<Throwable> {
+
+  private static final ErrorHandlerThrowImmediately INSTANCE = new ErrorHandlerThrowImmediately();
+
+  @Override
+  public void accept(Throwable t) {
+
+    if (t instanceof RuntimeException) {
+      throw (RuntimeException) t;
+    } else {
+      throw new IllegalStateException(t);
+    }
+  }
+
+  /**
+   * @return the singleton instance.
+   */
+  public static ErrorHandlerThrowImmediately get() {
+
+    return INSTANCE;
+  }
+
+}

modules/service/src/main/java/com/devonfw/module/service/common/api/client/AsyncServiceClient.java

@@ -5,7 +5,9 @@
 
 /**
  * An {@link AsyncServiceClient} wraps a {@link #get() service client} allowing to do {@link #call(Object, Consumer)
- * asynchronous calls}. The following code is a simple example how to do an asynchronous service invocation:
+ * asynchronous calls}. Only {@link ServiceClientFactory} is thread-safe but not instances of this interface so please
+ * do not share clients between threads. The following code is a simple example how to do an asynchronous service
+ * invocation:
  *
  * <pre>
  * {@link ServiceClientFactory} factory = getServiceClientFactory();
@@ -39,7 +41,13 @@ public interface AsyncServiceClient<S> {
 
   /**
    * @return the the {@link Consumer} callback {@link Consumer#accept(Object) accepting} a potential exception that
-   *         occurred during sending the request or receiving the response.
+   *         occurred during sending the request or receiving the response. <b>ATTENTION:</b> The error handler is only
+   *         used to report errors for {@link Consumer} usage (via {@link #call(Object, Consumer)} and
+   *         {@link #callVoid(Runnable, Consumer)}). When using {@link CompletableFuture} instead, errors will be
+   *         reported via the {@link CompletableFuture} itself. Please also note that due to design of
+   *         {@link CompletableFuture} the errors (like
+   *         {@link net.sf.mmm.util.exception.api.ServiceInvocationFailedException}) will be wrapped in a
+   *         {@link java.util.concurrent.ExecutionException}.
    */
   Consumer<Throwable> getErrorHandler();
 
@@ -53,23 +61,34 @@ public interface AsyncServiceClient<S> {
    * @param <R> type of the result of the service operation to call.
    * @param result the dummy result returned by the operation invoked on the actual {@link #get() service client}.
    * @param resultHandler the {@link Consumer} callback {@link Consumer#accept(Object) accepting} the actual result
-   *        asynchronously when available.
+   *        asynchronously when available. Errors will reported via {@link #getErrorHandler() errorHandler}.
    */
   <R> void call(R result, Consumer<R> resultHandler);
 
   /**
    * @param serviceInvoker the lambda function calling a void operation on the actual {@link #get() service client} -
    *        e.g. {@code () -> client.get().myVoidFunction()}.
    * @param resultHandler the {@link Consumer} callback {@link Consumer#accept(Object) accepting} the actual result
-   *        asynchronously when available. May be {@code null} for fire and forget.
+   *        asynchronously when available. May be {@code null} for fire and forget. Errors will reported via
+   *        {@link #getErrorHandler() errorHandler}.
    */
   void callVoid(Runnable serviceInvoker, Consumer<Void> resultHandler);
 
   /**
    * @param <R> type of the result of the service operation to call.
    * @param result the dummy result returned by the operation invoked on the actual {@link #get() service client}.
-   * @return a {@link CompletableFuture} to receive the result asynchronously.
+   * @return a {@link CompletableFuture} to receive the result asynchronously. Also errors will reported via this
+   *         {@link CompletableFuture} - see {@link #getErrorHandler()} for details.
    */
   <R> CompletableFuture<R> call(R result);
 
+  /**
+   * @param serviceInvoker the lambda function calling a void operation on the actual {@link #get() service client} -
+   *        e.g. {@code () -> client.get().myVoidFunction()}.
+   * @return a {@link CompletableFuture} to receive the result asynchronously. Also errors will reported via this
+   *         {@link CompletableFuture} - see {@link #getErrorHandler()} for details.
+   * @see #callVoid(Runnable, Consumer)
+   */
+  CompletableFuture<Void> callVoid(Runnable serviceInvoker);
+
 }

modules/service/src/main/java/com/devonfw/module/service/common/api/client/ServiceClientFactory.java

@@ -34,6 +34,9 @@
  * </ul>
  * All these aspects can be configured via spring and customized with own implementations.
  *
+ * <b>ATTENTION:</b> This {@link ServiceClientFactory} is thread-safe. However, the client objects returned by it are
+ * not thread-safe and shall not be reused or shared between threads.
+ *
  * @since 3.0.0
  */
 public interface ServiceClientFactory {

modules/service/src/main/java/com/devonfw/module/service/common/base/client/async/AbstractAsyncServiceClient.java

@@ -28,7 +28,7 @@ public abstract class AbstractAsyncServiceClient<S> implements AsyncServiceClien
   private final ServiceClientStub<S> stub;
 
   /** The {@link #setErrorHandler(Consumer)} */
-  protected Consumer<Throwable> errorHandler;
+  private Consumer<Throwable> errorHandler;
 
   /** The most recent invocation. */
   private ServiceClientInvocation<S> invocation;
@@ -87,6 +87,13 @@ public void callVoid(Runnable serviceInvoker, Consumer<Void> resultHandler) {
     }
   }
 
+  @Override
+  public CompletableFuture<Void> callVoid(Runnable serviceInvoker) {
+
+    serviceInvoker.run();
+    return call(null);
+  }
+
   private ServiceClientInvocation<S> getInvocation() {
 
     this.invocation = this.stub.getInvocation();
@@ -125,19 +132,17 @@ private static int getLength(Object[] parameters) {
     return parameters.length;
   }
 
-  @SuppressWarnings("unchecked")
   @Override
   public <R> CompletableFuture<R> call(R result) {
 
-    ServiceClientInvocation<S> invocation = getInvocation();
-    return doCall(invocation);
+    return doCall(getInvocation());
   }
 
   /**
    * @param <R> type of the return/result type.
-   * @param invocation the {@link ServiceClientInvocation}.
+   * @param serviceInvocation the {@link ServiceClientInvocation}.
    * @return a {@link CompletableFuture} to receive the result asynchronously.
    * @see #call(Object)
    */
-  protected abstract <R> CompletableFuture<R> doCall(ServiceClientInvocation<S> invocation);
+  protected abstract <R> CompletableFuture<R> doCall(ServiceClientInvocation<S> serviceInvocation);
 }