JCL-402: Low-level client throws enriched exceptions

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,

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
         }

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());