Introduce common exception types into the API to allow for more precise reactions to errors.

Author: io7m

net.adoptopenjdk.v3.api/src/main/java/net/adoptopenjdk/v3/api/AOV3Exception.java

@@ -0,0 +1,65 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.adoptopenjdk.v3.api;
+
+import java.util.Objects;
+
+/**
+ * The base type of exceptions raised by the API.
+ */
+
+public class AOV3Exception extends Exception
+{
+  /**
+   * Construct an exception.
+   *
+   * @param message The message
+   */
+
+  public AOV3Exception(
+    final String message)
+  {
+    super(Objects.requireNonNull(message, "message"));
+  }
+
+  /**
+   * Construct an exception.
+   *
+   * @param cause   The cause
+   * @param message The message
+   */
+
+  public AOV3Exception(
+    final String message,
+    final Throwable cause)
+  {
+    super(
+      Objects.requireNonNull(message, "message"),
+      Objects.requireNonNull(cause, "cause")
+    );
+  }
+
+  /**
+   * Construct an exception.
+   *
+   * @param cause The cause
+   */
+
+  public AOV3Exception(
+    final Throwable cause)
+  {
+    super(Objects.requireNonNull(cause, "cause"));
+  }
+}

net.adoptopenjdk.v3.api/src/main/java/net/adoptopenjdk/v3/api/AOV3ExceptionHTTPRequestFailed.java

@@ -0,0 +1,82 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.adoptopenjdk.v3.api;
+
+import java.net.URI;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * An HTTP request failed because the server returned some sort of error.
+ */
+
+public final class AOV3ExceptionHTTPRequestFailed extends AOV3Exception
+{
+  private final int statusCode;
+  private final Map<String, List<String>> headers;
+  private final URI uri;
+
+  /**
+   * Construct an exception.
+   *
+   * @param inStatusCode The HTTP status code
+   * @param inUri        The URI of the request
+   * @param inMessage    The error message
+   * @param inHeaders    The response headers
+   */
+
+  public AOV3ExceptionHTTPRequestFailed(
+    final int inStatusCode,
+    final URI inUri,
+    final String inMessage,
+    final Map<String, List<String>> inHeaders)
+  {
+    super(inMessage);
+    this.statusCode =
+      inStatusCode;
+    this.uri =
+      Objects.requireNonNull(inUri, "uri");
+    this.headers =
+      Objects.requireNonNull(inHeaders, "headers");
+  }
+
+  /**
+   * @return The URI of the request
+   */
+
+  public URI uri()
+  {
+    return this.uri;
+  }
+
+  /**
+   * @return The HTTP status code
+   */
+
+  public int statusCode()
+  {
+    return this.statusCode;
+  }
+
+  /**
+   * @return The response headers
+   */
+
+  public Map<String, List<String>> headers()
+  {
+    return this.headers;
+  }
+}

net.adoptopenjdk.v3.api/src/main/java/net/adoptopenjdk/v3/api/AOV3ExceptionHTTPRequestIOFailed.java

@@ -0,0 +1,52 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.adoptopenjdk.v3.api;
+
+import java.net.URI;
+import java.util.Objects;
+
+/**
+ * An HTTP request due to an I/O error.
+ */
+
+public final class AOV3ExceptionHTTPRequestIOFailed extends AOV3Exception
+{
+  private final URI uri;
+
+  /**
+   * Construct an exception.
+   *
+   * @param inUri The request URI
+   * @param cause The cause of the error
+   */
+
+  public AOV3ExceptionHTTPRequestIOFailed(
+    final URI inUri,
+    final Throwable cause)
+  {
+    super(cause);
+    this.uri =
+      Objects.requireNonNull(inUri, "uri");
+  }
+
+  /**
+   * @return The request URI
+   */
+
+  public URI uri()
+  {
+    return this.uri;
+  }
+}

net.adoptopenjdk.v3.api/src/main/java/net/adoptopenjdk/v3/api/AOV3ExceptionParseFailed.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.adoptopenjdk.v3.api;
+
+/**
+ * An exception caused by a parse error.
+ */
+
+public final class AOV3ExceptionParseFailed extends AOV3Exception
+{
+  /**
+   * Construct an exception.
+   *
+   * @param cause The cause of the exception
+   */
+
+  public AOV3ExceptionParseFailed(
+    final Throwable cause)
+  {
+    super(cause);
+  }
+}

net.adoptopenjdk.v3.api/src/main/java/net/adoptopenjdk/v3/api/AOV3RequestType.java

@@ -14,8 +14,6 @@
 
 package net.adoptopenjdk.v3.api;
 
-import java.io.IOException;
-
 /**
  * An executable request. Requests can be created once and re-executed an
  * arbitrary number of times.
@@ -30,10 +28,10 @@ public interface AOV3RequestType<T>
    *
    * @return The received data
    *
-   * @throws IOException          On I/O errors
+   * @throws AOV3Exception        On errors
    * @throws InterruptedException If the thread hosting the operation was interrupted
    */
 
   T execute()
-    throws IOException, InterruptedException;
+    throws AOV3Exception, InterruptedException;
 }

net.adoptopenjdk.v3.tests/pom.xml

@@ -34,6 +34,10 @@
       <version>${project.version}</version>
     </dependency>
 
+    <dependency>
+      <groupId>commons-io</groupId>
+      <artifactId>commons-io</artifactId>
+    </dependency>
     <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>

net.adoptopenjdk.v3.tests/src/test/java/net/adoptopenjdk/v3/tests/AOV3ClientsTest.java

@@ -15,6 +15,7 @@
 package net.adoptopenjdk.v3.tests;
 
 import net.adoptopenjdk.v3.api.AOV3Error;
+import net.adoptopenjdk.v3.api.AOV3ExceptionHTTPRequestFailed;
 import net.adoptopenjdk.v3.api.AOV3ReleaseKind;
 import net.adoptopenjdk.v3.vanilla.AOV3Clients;
 import net.adoptopenjdk.v3.vanilla.AOV3Messages;
@@ -95,7 +96,7 @@ public void testRequestFailure0()
 
     try (var client = clients.createClient()) {
       final var exception =
-        Assertions.assertThrows(IOException.class, () -> {
+        Assertions.assertThrows(AOV3ExceptionHTTPRequestFailed.class, () -> {
           client.assetsForRelease(
             this::logError,
             BigInteger.ZERO,
@@ -113,7 +114,14 @@ public void testRequestFailure0()
           ).execute();
         });
 
-      Assertions.assertTrue(exception.getMessage().contains("500"));
+      Assertions.assertEquals(
+        500,
+        exception.statusCode()
+      );
+      Assertions.assertEquals(
+        "urn:test",
+        exception.uri().toString()
+      );
     }
   }
 }