Map standard and custom exceptions to a http response body containing problem details as specified in RFC-9457 (formerly RFC-7807).
Most things work out of the box: the type and title fields are derived from the exception class name; the detail field is the message of the exception; the instance field is a random UUID URN that is also logged together with the complete stack trace.
These defaults and the status code can be overridden with annotations.
Getting a consistent error response format for a REST API is a common problem and allows clients to handle specific business errors. Getting some generic HTML response is not helpful. There is a standard for this type of details about an error: RFC-9457. And this library provides a simple way to map exceptions to this format.
Spec & API
This has been proposed to and rejected by several existing specs:
The API in the api module looks quite stable. Some first ideas for a full spec follow below. It’s yet far from complete, but it’s a start:
MUST application/problem+json, application/problem+xml; SHOULD any, e.g. +yaml
SHOULD render text/html
map also @Valid REST params
logging: 4xx = DEBUG, 5xx = ERROR; configurable?
order of extensions is alphabetic (which is better for tests than random)
multiple extensions with the same name: undefined behavior
JAXB can’t unmarshal a subclass with the same type and namespace
Security considerations: nothing dangerous in problem details (i.e. exception message); stack-trace in logs
TODO scan client classpath for @Type annotated exceptions (and document this in the spec and the annotation)
TODO inherited annotations
TODO cause annotations
TODO type factory, e.g. URL to OpenAPI
TODO instance factory, e.g. URL to the logging system filtering on an UUID
Dummy-Impl [ri]
It’s called ri, but it’s actually only a POC, and it’s incomplete. See the README for details.
Test
The test module runs integration tests by using JEE Testcontainers, i.e. it can be configured to start different Docker containers with various JEE application servers. By default, it starts a Wildfly.
testcontainer-running
As the containers don’t yet implement the API by themselves, the dummy implementation ri is hard-wired in the tests for now.
Wildfly
Default mvn or explicitly mvn -Djee-testcontainer=wildfly
needs tag for jdk11 support
needs dependencies on slf4j-api and slf4j-jdk14
TomEE
mvn -Djee-testcontainer=tomee
3 tests fail, because this version of TomEE (9.0.20 / 8.0.0-M3) doesn’t write the problem detail response entity in some cases for some reason:
StandardExceptionMappingIT.shouldMapWebApplicationExceptionWithoutEntityButMessage
StandardExceptionMappingIT.shouldMapWebApplicationExceptionWithoutEntityOrMessage
ValidationFailedExceptionMappingIT.shouldMapValidationFailedException
Payara
mvn -Djee-testcontainer=payara -Pwith-slf4j
fails due to lack of jdk11 support of the payara image.
needs dependencies on slf4j-api and slf4j-jdk14
Spring
We build for JDK 11 and the Jakarta EE 10 APIs. The current versions of Spring Boot don’t support this combination. But you can still use the older com.github.t1:problem-details-api:1.0.10, which was based on Jakarta EE 8.
Add an option to configure the mapping of some built-in exceptions, e.g. org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException to status code 503 Service Unavailable.
We use Jakarta JSON Binding to deserialize an exception (with their extensions). This worked well with JDK 11, but in JDK 17, it fails with a jakarta.json.bind.JsonbException: Internal error: Unable to make field private java.lang.Throwable java.lang.Throwable.cause accessible: module java.base does not "opens java.lang" to unnamed module.
I'd like to build the project for jaxrs but did not manage to do so. I came across the issue, that the master branch relies on a class of the sandbox api, which is not there. The class ResponseStatus does not exist. So how could this project be build? I started to migrate to javax.ws.rs.core.Response.Status and have all files in my own project.
So I wanted to ask, what the current status of this project is? Is it supposed to be that way or am I doing something wrong?