Exception Handling Section

README.adoc

@@ -198,6 +198,68 @@ include::{common-includes}/devmode-build.adoc[]
 Check out the service that you created at the
 http://localhost:9080/LibertyProject/System/properties[^] URL. 
 
+// =================================================================================================
+// Exception Handling
+// =================================================================================================
+
+== Exception Handling
+
+If a resource doesn't exist or the service experiences an exception, the client will receive either an empty response or an HTML error page respectively.
+A client should not receive either of these.
+Clients should receive JSON responses. 
+
+This will be handled using an `ExceptionMapper` which maps exceptions to responses and builds appropriate JSON payloads. 
+
+[role="code_command hotspot file=0", subs="quotes"]
+----
+#Create the `ErrorResponse` class.#
+`src/main/java/io/openliberty/guides/rest/exceptions/ErrorResponse.java`
+----
+
+ErrorResponse.java
+[source, Java, linenums, role="code_column hide_tags=comment"]
+----
+include::finish/src/main/java/io/openliberty/guides/rest/exceptions/ErrorResponse.java[]
+----
+
+The [hotspot file=0]`ErrorResponse` class will define the JSON contents of our response. 
+It contains fields for the error code and error message. 
+
+[role="code_command hotspot file=1", subs="quotes"]
+----
+#Create the `GenericExceptionMapper` class.#
+`src/main/java/io/openliberty/guides/rest/exceptions/GenericExceptionMapper.java`
+----
+
+GenericExceptionMapper.java
+[source, Java, linenums, role="code_column hide_tags=comment"]
+----
+include::finish/src/main/java/io/openliberty/guides/rest/exceptions/GenericExceptionMapper.java[]
+----
+
+When JAX-RS sees any `Throwable`, it will search for a matching `ExceptionMapper` interface that has been marked with the [hotspot=provider file=1]`@Provider` annotation. 
+It will pass the `Throwable` to the [hotspot=toResponse file=1]`toResponse()` method to construct a response using the [hotspot file=0]`ErrorResponse` class.
+
+The [hotspot file=1]`GenericExceptionMapper` class will be used for any `Throwable` that does not have a more specific `ExceptionMapper` interface implemented. 
+
+[role="code_command hotspot file=2", subs="quotes"]
+----
+#Create the `NotFoundExceptionMapper` class.#
+`src/main/java/io/openliberty/guides/rest/exceptions/NotFoundExceptionMapper.java`
+----
+
+NotFoundExceptionMapper.java
+[source, Java, linenums, role="code_column hide_tags=comment"]
+----
+include::finish/src/main/java/io/openliberty/guides/rest/exceptions/NotFoundExceptionMapper.java[]
+----
+
+The [hotspot file=2]`NotFoundExceptionMapper` class is a more specific implementation of the `ExceptionMapper` interface. 
+The type of the generic inside is now [hotspot=generic file=2]`NotFoundException` instead of `Throwable`.
+It will only map to instances of `NotFoundException` that the application throws. 
+
+See this error by visiting a URL for a resource that doesn't exist such as http://localhost:9080/LibertyProject/System/DoesNotExist[^].
+
 // =================================================================================================
 // Testing the service
 // =================================================================================================

finish/src/main/java/io/openliberty/guides/rest/exceptions/ErrorResponse.java

@@ -0,0 +1,20 @@
+package io.openliberty.guides.rest.exceptions;
+
+public class ErrorResponse {
+    int errorCode;
+    String errorMessage;
+
+    public ErrorResponse(int errorCode, String errorMessage) {
+        super();
+        this.errorCode = errorCode;
+        this.errorMessage = errorMessage;
+    }
+
+    public int getErrorCode() {
+        return this.errorCode;
+    }
+
+    public String getErrorMessage() {
+        return this.errorMessage;
+    }
+}

finish/src/main/java/io/openliberty/guides/rest/exceptions/GenericExceptionMapper.java

@@ -0,0 +1,24 @@
+package io.openliberty.guides.rest.exceptions;
+
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.ext.ExceptionMapper;
+import javax.ws.rs.ext.Provider;
+
+// tag::provider[]
+@Provider
+// end::provider[]
+public class GenericExceptionMapper implements ExceptionMapper<Throwable> {
+
+    // tag::toResponse[]
+    @Override
+    public Response toResponse(Throwable t) {
+        ErrorResponse response = new ErrorResponse(500, t.getMessage());
+        return Response.serverError()
+                       .entity(response)
+                       .type(MediaType.APPLICATION_JSON)
+                       .build();
+    }
+    // end::toResponse[]
+
+}

finish/src/main/java/io/openliberty/guides/rest/exceptions/NotFoundExceptionMapper.java

@@ -0,0 +1,23 @@
+package io.openliberty.guides.rest.exceptions;
+
+import javax.ws.rs.NotFoundException;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.ext.ExceptionMapper;
+import javax.ws.rs.ext.Provider;
+
+@Provider
+// tag::generic[]
+public class NotFoundExceptionMapper implements ExceptionMapper<NotFoundException> {
+// end::generic[]
+
+    @Override
+    public Response toResponse(NotFoundException ex) {
+        ErrorResponse response = new ErrorResponse(404, ex.getMessage());
+        return Response.status(Response.Status.NOT_FOUND)
+                       .entity(response)
+                       .type(MediaType.APPLICATION_JSON)
+                       .build();
+    }
+
+}