Merge pull request #18 from bunq/feature/exception-handler

Feature/exception handler

Author: dnl-blkv

.gitignore

@@ -71,3 +71,4 @@ bunq.conf
 context-save-restore-test.conf
 /tmp
 config.properties
+bunq-test.conf

README.md

@@ -172,3 +172,7 @@ API key before running the example!
 ## Running tests
 Information regarding the test cases can be found in the [README.md](./src/test/README.md)
 located in [test](/src/test).
+
+## Exceptions
+The SDK can throw multiple exceptions. For an overview of these exceptions please
+take a look at [EXCEPTIONS.md](./src/main/java/com/bunq/sdk/exception/EXCEPTIONS.md)

src/main/java/com/bunq/sdk/exception/ApiException.java

@@ -1,37 +1,17 @@
 package com.bunq.sdk.exception;
 
-import java.util.List;
-
-/**
- * Exception triggered by API requests failed on the server side.
- */
 public class ApiException extends RuntimeException {
 
-  private static final String GLUE_ERROR_MESSAGES = "\n";
-
   private int responseCode;
-  private List<String> messages;
 
-  /**
-   * @param responseCode The HTTP Response code of the failed request.
-   * @param messages The list of messages related to this exception.
-   */
-  public ApiException(int responseCode, List<String> messages) {
-    super(concatenateMessages(messages));
-    this.responseCode = responseCode;
-    this.messages = messages;
-  }
+  public ApiException(String message, int responseCode) {
+    super(message);
 
-  private static String concatenateMessages(List<String> messages) {
-    return String.join(GLUE_ERROR_MESSAGES, messages);
+    this.responseCode = responseCode;
   }
 
   public int getResponseCode() {
     return responseCode;
   }
 
-  public List<String> getMessages() {
-    return messages;
-  }
-
 }

src/main/java/com/bunq/sdk/exception/BadRequestException.java

@@ -0,0 +1,9 @@
+package com.bunq.sdk.exception;
+
+public class BadRequestException extends ApiException {
+
+  public BadRequestException(String message, int responseCode) {
+    super(message, responseCode);
+  }
+
+}

src/main/java/com/bunq/sdk/exception/EXCEPTIONS.md

@@ -0,0 +1,68 @@
+## Exceptions
+When you make a request via the SDK, there is a chance of request failing
+due to various reasons. When such a failure happens, an exception
+corresponding to the error occurred is thrown.
+
+
+----
+#### Possible Exceptions
+* `BadRequestException` If the request returns with status code `400`
+* `UnauthorizedException` If the request returns with status code `401`
+* `ForbiddenException` If the request returns with status code `403`
+* `NotFoundException` If the request returns with status code `404`
+* `MethodNotAllowedException` If the request returns with status code `405`
+* `TooManyRequestsException` If the request returns with status code `429`
+* `PleaseContactBunqException` If the request returns with status code `500`.
+If you get this exception, please contact us preferably via the support chat in the bunq app.
+* `UnknownApiErrorException` If none of the above mentioned exceptions are thrown,
+this exception will be thrown instead.
+
+For more information regarding these errors, please take a look on the documentation
+page here: https://doc.bunq.com/api/1/page/errors
+
+---
+#### Base exception
+All the exceptions have the same base exception which looks like this:
+```java
+public class ApiException extends RuntimeException {
+  
+  private int responseCode;
+
+  public ApiException(String message, int responseCode) {
+    // Some hidden code    
+  }
+
+  public int getResponseCode() {
+    return responseCode;
+  }
+
+}
+```
+This means that each exception will have a response code and an error message
+related to the specific error returned by API.
+
+---
+#### Exception handling
+Since each API error has a distinct SDK exception type corresponding to it,
+you can catch the exact exceptions you expect 👏.
+
+```java
+import com.bunq.sdk.context.ApiContext;
+import com.bunq.sdk.context.ApiEnvironmentType;
+import com.bunq.sdk.exception.BadRequestException;
+
+class BadRequest {
+  private final String API_KEY = "Some invalid key";
+  private final String DESCRIPTION = "This will throw BadRequestException.";
+  
+  public void main(){
+    try{
+      new ApiContext(ApiEnvironmentType.SANDBOX, this.API_KEY, this.DESCRIPTION);
+    }catch (BadRequestException error){
+      System.out.println(error.getMessage());
+      System.out.println(error.getResponseCode());
+    }
+  }
+  
+}
+```

src/main/java/com/bunq/sdk/exception/ExceptionFactory.java

@@ -0,0 +1,57 @@
+package com.bunq.sdk.exception;
+
+import java.util.List;
+
+public class ExceptionFactory {
+
+  /**
+   * HTTP error response codes constants.
+   */
+  private static final int HTTP_RESPONSE_CODE_BAD_REQUEST = 400;
+  private static final int HTTP_RESPONSE_CODE_UNAUTHORIZED = 401;
+  private static final int HTTP_RESPONSE_CODE_FORBIDDEN = 403;
+  private static final int HTTP_RESPONSE_CODE_NOT_FOUND = 404;
+  private static final int HTTP_RESPONSE_CODE_METHOD_NOT_ALLOWED = 405;
+  private static final int HTTP_RESPONSE_CODE_TOO_MANY_REQUESTS = 429;
+  private static final int HTTP_RESPONSE_CODE_INTERNAL_SERVER_ERROR = 500;
+
+  /**
+   * Some glue to glue the error message together.
+   */
+  private static final String GLUE_ERROR_MESSAGES = "\n";
+
+  /**
+   *
+   * @param responseCode The HTTP response code related to the request.
+   * @param messages  The error message related to the exception that should be thrown.
+   *
+   * @return The exception that belongs to this status code.
+   */
+  public static ApiException createExceptionForResponse(int responseCode, List<String> messages){
+    String error_message = concatenateMessages(messages);
+
+    switch (responseCode) {
+      case HTTP_RESPONSE_CODE_BAD_REQUEST:
+        return new BadRequestException(error_message, responseCode);
+      case HTTP_RESPONSE_CODE_UNAUTHORIZED:
+        return new UnauthorizedException(error_message, responseCode);
+      case HTTP_RESPONSE_CODE_FORBIDDEN:
+        return new UnauthorizedException(error_message, responseCode);
+      case HTTP_RESPONSE_CODE_NOT_FOUND:
+        return new NotFoundException(error_message, responseCode);
+      case HTTP_RESPONSE_CODE_METHOD_NOT_ALLOWED:
+        return new MethodNotAllowedException(error_message, responseCode);
+      case HTTP_RESPONSE_CODE_TOO_MANY_REQUESTS:
+        return new TooManyRequestsException(error_message, responseCode);
+      case HTTP_RESPONSE_CODE_INTERNAL_SERVER_ERROR:
+        return new PleaseContactBunqException(error_message, responseCode);
+      default:
+        return new UnknownApiErrorException(error_message, responseCode);
+    }
+  }
+
+  private static String concatenateMessages(List<String> messages) {
+    return String.join(GLUE_ERROR_MESSAGES, messages);
+  }
+  
+}

src/main/java/com/bunq/sdk/exception/ForbiddenException.java

@@ -0,0 +1,9 @@
+package com.bunq.sdk.exception;
+
+public class ForbiddenException extends ApiException {
+
+  public ForbiddenException(String message, int responseCode) {
+    super(message, responseCode);
+  }
+
+}

src/main/java/com/bunq/sdk/exception/MethodNotAllowedException.java

@@ -0,0 +1,9 @@
+package com.bunq.sdk.exception;
+
+public class MethodNotAllowedException extends ApiException {
+
+  public MethodNotAllowedException(String message, int responseCode) {
+    super(message, responseCode);
+  }
+
+}

src/main/java/com/bunq/sdk/exception/NotFoundException.java

@@ -0,0 +1,9 @@
+package com.bunq.sdk.exception;
+
+public class NotFoundException extends ApiException {
+
+  public NotFoundException(String message, int responseCode) {
+    super(message, responseCode);
+  }
+
+}

src/main/java/com/bunq/sdk/exception/PleaseContactBunqException.java

@@ -0,0 +1,9 @@
+package com.bunq.sdk.exception;
+
+public class PleaseContactBunqException extends ApiException {
+
+  public PleaseContactBunqException(String message, int responseCode) {
+    super(message, responseCode);
+  }
+
+}