JCL-402: Low-level client throws enriched exceptions (#1157)

NSeydoux · web-flow · commit 27dde17c131a · 2024-04-23T08:09:10.000Z
`SolidClient` now uses the `throwOnError` body mapper to handle error responses, and provides a custom exception mapper to throw the appropriate specialized exception on HTTP error response. Overall, the behavior of the library doesn't change, the only addition is that the thrown Exception object now has a `ProblemDetails` instance attached to it.
diff --git a/api/src/main/java/com/inrupt/client/ProblemDetails.java b/api/src/main/java/com/inrupt/client/ProblemDetails.java
@@ -34,7 +34,13 @@
  * @see <a href="https://www.rfc-editor.org/rfc/rfc9457">RFC 9457 Problem Details for HTTP APIs</a>
  */
 public class ProblemDetails {
+    /**
+     * The <a href="https://www.rfc-editor.org/rfc/rfc9457">RFC9457</a> default MIME type.
+     */
     public static final String MIME_TYPE = "application/problem+json";
+    /**
+     * The <a href="https://www.rfc-editor.org/rfc/rfc9457">RFC9457</a> default problem type.
+     */
     public static final String DEFAULT_TYPE = "about:blank";
     private final URI type;
     private final String title;
@@ -44,6 +50,15 @@ public class ProblemDetails {
     private static JsonService jsonService;
     private static boolean isJsonServiceInitialized;
 
+    /**
+     * Build a ProblemDetails instance providing the expected fields as described in
+     * <a href="https://www.rfc-editor.org/rfc/rfc9457">RFC9457</a>.
+     * @param type the problem type
+     * @param title the problem title
+     * @param details the problem details
+     * @param status the error response status code
+     * @param instance the problem instance
+     */
     public ProblemDetails(
         final URI type,
         final String title,
@@ -58,22 +73,42 @@ public ProblemDetails(
         this.instance = instance;
     }
 
+    /**
+     * The problem type.
+     * @return the type
+     */
     public URI getType() {
         return this.type;
     };
 
+    /**
+     * The problem title.
+     * @return the title
+     */
     public String getTitle() {
         return this.title;
     };
 
+    /**
+     * The problem details.
+     * @return the details
+     */
     public String getDetails() {
         return this.details;
     };
 
+    /**
+     * The problem status code.
+     * @return the status code
+     */
     public int getStatus() {
         return this.status;
     };
 
+    /**
+     * The problem instance.
+     * @return the instance
+     */
     public URI getInstance() {
         return this.instance;
     };
@@ -82,10 +117,25 @@ public URI getInstance() {
      * This inner class is only ever used for JSON deserialization. Please do not use in any other context.
      */
     public static class Data {
+        /**
+         * The problem type.
+         */
         public URI type;
+        /**
+         * The problem title.
+         */
         public String title;
+        /**
+         * The problem details.
+         */
         public String details;
+        /**
+         * The problem status code.
+         */
         public int status;
+        /**
+         * The problem instance.
+         */
         public URI instance;
     }
 
@@ -104,6 +154,13 @@ private static JsonService getJsonService() {
         return ProblemDetails.jsonService;
     }
 
+    /**
+     * Builds a {@link ProblemDetails} instance from an HTTP error response.
+     * @param statusCode the HTTP error response status code
+     * @param headers the HTTP error response headers
+     * @param body the HTTP error response body
+     * @return a {@link ProblemDetails} instance
+     */
     public static ProblemDetails fromErrorResponse(
             final int statusCode,
             final Headers headers,
diff --git a/api/src/main/java/com/inrupt/client/Response.java b/api/src/main/java/com/inrupt/client/Response.java
@@ -26,8 +26,6 @@
 import java.io.InputStream;
 import java.net.URI;
 import java.nio.ByteBuffer;
-import java.nio.charset.StandardCharsets;
-import java.util.function.Function;
 
 /**
  * An HTTP Response.
@@ -97,6 +95,15 @@ interface ResponseInfo {
         ByteBuffer body();
     }
 
+    /**
+     * Indicates whether a status code reflects a successful HTTP response.
+     * @param statusCode the HTTP response status code
+     * @return true if the status code is in the success range, namely [200, 299].
+     */
+    static boolean isSuccess(final int statusCode) {
+        return statusCode >= 200 && statusCode < 300;
+    }
+
     /**
      * An interface for mapping an HTTP response into a specific Java type.
      * @param <T> the body type
@@ -154,51 +161,6 @@ public static BodyHandler<Void> discarding() {
             return responseInfo -> null;
         }
 
-        /**
-         * Throws on HTTP error using the provided mapper, or apply the provided body handler.
-         * @param handler the body handler to apply on non-error HTTP responses
-         * @param isSuccess a callback determining error cases
-         * @param exceptionMapper the exception mapper
-         * @return the body handler
-         * @param <T> the type of the body handler
-         */
-        public static <T> Response.BodyHandler<T> throwOnError(
-                final Response.BodyHandler<T> handler,
-                final Function<Response.ResponseInfo, Boolean> isSuccess,
-                final Function<Response.ResponseInfo, ClientHttpException> exceptionMapper
-        ) {
-            return responseinfo -> {
-                if (!isSuccess.apply(responseinfo)) {
-                    throw exceptionMapper.apply(responseinfo);
-                }
-                return handler.apply(responseinfo);
-            };
-        }
-
-        /**
-         * Throws on HTTP error, or apply the provided body handler.
-         * @param handler the body handler to apply on non-error HTTP responses
-         * @param isSuccess a callback determining error cases
-         * @return the body handler
-         * @param <T> the type of the body handler
-         */
-        public static <T> Response.BodyHandler<T> throwOnError(
-                final Response.BodyHandler<T> handler,
-                final Function<Response.ResponseInfo, Boolean> isSuccess
-        ) {
-            final Function<Response.ResponseInfo, ClientHttpException> defaultMapper = responseInfo ->
-                new ClientHttpException(
-                    "An HTTP error has been returned, with status code " + responseInfo.statusCode(),
-                    responseInfo.uri(),
-                    responseInfo.statusCode(),
-                    responseInfo.headers(),
-                    new String(responseInfo.body().array(), StandardCharsets.UTF_8)
-                );
-            return throwOnError(handler, isSuccess, defaultMapper);
-        }
-
-
-
         private BodyHandlers() {
             // Prevent instantiation
         }
diff --git a/solid/src/main/java/com/inrupt/client/solid/SolidClient.java b/solid/src/main/java/com/inrupt/client/solid/SolidClient.java
@@ -20,22 +20,14 @@
  */
 package com.inrupt.client.solid;
 
-import static java.nio.charset.StandardCharsets.UTF_8;
-
-import com.inrupt.client.Client;
-import com.inrupt.client.ClientProvider;
-import com.inrupt.client.Headers;
-import com.inrupt.client.RDFSource;
-import com.inrupt.client.Request;
-import com.inrupt.client.Resource;
-import com.inrupt.client.Response;
-import com.inrupt.client.ValidationResult;
+import com.inrupt.client.*;
 import com.inrupt.client.auth.Session;
 
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.URI;
+import java.nio.charset.StandardCharsets;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -131,36 +123,43 @@ public <T extends Resource> CompletionStage<T> read(final URI identifier, final
         headers.firstValue(USER_AGENT).ifPresent(agent -> builder.setHeader(USER_AGENT, agent));
 
         final Request request = builder.build();
-        return client.send(request, Response.BodyHandlers.ofByteArray())
-            .thenApply(response -> {
-                if (response.statusCode() >= ERROR_STATUS) {
-                    throw SolidClientException.handle("Unable to read resource at " + request.uri(), request.uri(),
-                            response.statusCode(), response.headers(), new String(response.body()));
-                } else {
-                    final String contentType = response.headers().firstValue(CONTENT_TYPE)
-                        .orElse("application/octet-stream");
-                    try {
-                        // Check that this is an RDFSoure
-                        if (RDFSource.class.isAssignableFrom(clazz)) {
-                            final Dataset dataset = SolidResourceHandlers.buildDataset(contentType, response.body(),
-                                    request.uri().toString()).orElse(null);
-                            final T obj = construct(request.uri(), clazz, dataset, response.headers());
-                            final ValidationResult res = RDFSource.class.cast(obj).validate();
-                            if (!res.isValid()) {
-                                throw new DataMappingException(
-                                    "Unable to map resource into type: [" + clazz.getSimpleName() + "] ",
-                                     res.getResults());
-                            }
-                            return obj;
-                        // Otherwise, create a non-RDF-bearing resource
-                        } else {
-                            return construct(request.uri(), clazz, contentType,
-                                    new ByteArrayInputStream(response.body()), response.headers());
+        return client.send(
+                request,
+                Response.BodyHandlers.ofByteArray()
+            ).thenApply(response -> {
+                if (!Response.isSuccess(response.statusCode())) {
+                    throw SolidClientException.handle(
+                        "Reading resource failed.",
+                        response.uri(),
+                        response.statusCode(),
+                        response.headers(),
+                        new String(response.body(), StandardCharsets.UTF_8)
+                    );
+                }
+
+                final String contentType = response.headers().firstValue(CONTENT_TYPE)
+                    .orElse("application/octet-stream");
+                try {
+                    // Check that this is an RDFSoure
+                    if (RDFSource.class.isAssignableFrom(clazz)) {
+                        final Dataset dataset = SolidResourceHandlers.buildDataset(contentType, response.body(),
+                                request.uri().toString()).orElse(null);
+                        final T obj = construct(request.uri(), clazz, dataset, response.headers());
+                        final ValidationResult res = RDFSource.class.cast(obj).validate();
+                        if (!res.isValid()) {
+                            throw new DataMappingException(
+                                "Unable to map resource into type: [" + clazz.getSimpleName() + "] ",
+                                 res.getResults());
                         }
-                    } catch (final ReflectiveOperationException ex) {
-                        throw new SolidResourceException("Unable to read resource into type " + clazz.getName(),
-                                ex);
+                        return obj;
+                    // Otherwise, create a non-RDF-bearing resource
+                    } else {
+                        return construct(request.uri(), clazz, contentType,
+                                new ByteArrayInputStream(response.body()), response.headers());
                     }
+                } catch (final ReflectiveOperationException ex) {
+                    throw new SolidResourceException("Unable to read resource into type " + clazz.getName(),
+                            ex);
                 }
             });
     }
@@ -280,13 +279,21 @@ public <T extends Resource> CompletionStage<Void> delete(final T resource, final
         defaultHeaders.firstValue(USER_AGENT).ifPresent(agent -> builder.setHeader(USER_AGENT, agent));
         headers.firstValue(USER_AGENT).ifPresent(agent -> builder.setHeader(USER_AGENT, agent));
 
-        return client.send(builder.build(), Response.BodyHandlers.ofByteArray()).thenApply(res -> {
-            if (isSuccess(res.statusCode())) {
-                return null;
-            } else {
-                throw SolidClientException.handle("Unable to delete resource", resource.getIdentifier(),
-                        res.statusCode(), res.headers(), new String(res.body(), UTF_8));
+
+        return client.send(
+            builder.build(),
+            Response.BodyHandlers.ofByteArray()
+        ).thenApply(response -> {
+            if (!Response.isSuccess(response.statusCode())) {
+                throw SolidClientException.handle(
+                    "Deleting resource failed.",
+                    response.uri(),
+                    response.statusCode(),
+                    response.headers(),
+                    new String(response.body(), StandardCharsets.UTF_8)
+                );
             }
+            return null;
         });
     }
 
@@ -370,9 +377,14 @@ public SolidClient build() {
     <T extends Resource> Function<Response<byte[]>, CompletionStage<T>> handleResponse(final T resource,
             final Headers headers, final String message) {
         return res -> {
-            if (!isSuccess(res.statusCode())) {
-                throw SolidClientException.handle(message, resource.getIdentifier(),
-                        res.statusCode(), res.headers(), new String(res.body(), UTF_8));
+            if (!Response.isSuccess(res.statusCode())) {
+                throw SolidClientException.handle(
+                    message,
+                    resource.getIdentifier(),
+                    res.statusCode(),
+                    res.headers(),
+                    new String(res.body(), StandardCharsets.UTF_8)
+                );
             }
 
             if (!fetchAfterWrite) {
@@ -382,7 +394,6 @@ <T extends Resource> Function<Response<byte[]>, CompletionStage<T>> handleRespon
             @SuppressWarnings("unchecked")
             final Class<T> clazz = (Class<T>) resource.getClass();
             return read(resource.getIdentifier(), headers, clazz);
-
         };
     }
 
@@ -445,10 +456,6 @@ static void decorateHeaders(final Request.Builder builder, final Headers headers
         }
     }
 
-    static boolean isSuccess(final int statusCode) {
-        return statusCode >= 200 && statusCode < 300;
-    }
-
     static Request.BodyPublisher cast(final Resource resource) {
         try {
             return Request.BodyPublishers.ofInputStream(resource.getEntity());
diff --git a/solid/src/test/java/com/inrupt/client/solid/SolidClientTest.java b/solid/src/test/java/com/inrupt/client/solid/SolidClientTest.java
