Jax-rs / Jersey how to customize error handling?

Understanding error handling nuances

Embracing WebApplicationException

WebApplicationException can be extended for crafting an exception with a custom status code and message:

public class YourFriendly404Exception extends WebApplicationException {
    public YourFriendly404Exception(String message) {
        super(Response.status(Response.Status.NOT_FOUND)
                      .entity(message)
                      .type(MediaType.TEXT_PLAIN)
                      .build());
    }
}


Throw YourFriendly404Exception in your method whenever you want a 404 with a custom plain text message.

Creating tailored response entities

For elaborate scenarios, ErrorResponse is the way. Think of it as a rescue boat for stranded response entities.

@XmlRootElement
public class ErrorResponse {
    private int code;
    private String message;
    // Getters and setters omitted for brevity
}


Return this sharpened ErrorResponse in your ExceptionMapper:

return Response.status(errorCode)
               .entity(new ErrorResponse(errorCode, errorMessage))
               .type(MediaType.APPLICATION_JSON)
               .build();


The power of our Provider Exception Mappers

Use the imprint @Provider to register ExceptionMappers ready for the rescue of specific exceptions.

@Provider
public class SpecificExceptionMapper implements ExceptionMapper<SpecificException> {
    // A method called toResponse - Now, that's original!
}


Context and headers - A narrative of its own

To provide more context, include headers to your responses:

return Response.status(Response.Status.INTERNAL_SERVER_ERROR)
               .header("X-Custom-Error", "Chaos reigns supreme!")
               .entity(new ErrorResponse())
               .type(MediaType.APPLICATION_JSON)
               .build();


Your headers are the silent narrators of extensive error tales. Just don't let them spill any secrets!

The art of weaving your error handling strategies

Mastering error handling is both a science and an art. Here's to unveiling your inner Van Gogh.

Custom-made error handling strategies

Different strokes for different folks - I mean errors. Handle NotFoundException for a 404 with a difference:

@Provider
public class NotFoundMapper implements ExceptionMapper<NotFoundException> {
    @Override
    public Response toResponse(NotFoundException exception) {
        // Custom response for 404. Not found but well responded!
    }
}


Similarly, unsurprisingly, RESTful APIs don't appreciate BAD PARAMETER jokes:

@Provider
public class BadParamJokeExceptionMapper implements ExceptionMapper<ParamException> {
    @Override
    public Response toResponse(ParamException exception) {
        // Inform the client that his parameter joke was bad - in good humor!
    }
}


Personalized exception handling

Had enough of general exceptions? Go personal with @Path:

@Path("/date/{dateString}")
public class DateResource {
    @GET
    public Response getDate(@PathParam("dateString") String dateString) {
        try {
            Date date = new SimpleDateFormat("yyyy-MM-dd").parse(dateString);
            // Happy date conversion folks!
        } catch (ParseException e) {
            throw new CustomDateFormatException("Dude, yyyy-MM-dd, How hard can it be!");
        }
    }
}


Logging - The chronicling chat logs

Use logger to navigate the labyrinth of exceptions:

@Provider
public class GlobalExceptionMapper implements ExceptionMapper<Throwable> {
    @Override
    public Response toResponse(Throwable exception) {
        Logger.log(exception); // Trust me, log is your friend.
        // Return generic error response while enjoying a fresh cup of java!
    }
}


Just remember - don't spill too much tea in the log!

Advanced error handling - Recipe for peace

As our journey nears conclusion, here's one final recipe for a flavorful error handling experience:

• Create ExceptionMappers, both generic and specific.
• Define an ErrorResponse class for a more expressive response body.
• Go fancy by extending existing exceptions or create your own.
• Don't forget to register the mappers using @Provider.
• Logging is important - but remember to not say too much!
• Make use of headers for minutiae or nagging details.
• Never underestimate the power of the humble, yet precise media types.

Parameter parsing with precision

To make your API more efficient and your code cleaner, refactor parameter parsing and handling:

class DateParamConverter implements ParamConverter<Date> {
    public Date fromString(String value) {
        // Converts user's date preference into a good old java date.
    }
    // We hope you enjoyed the time travel!
}


Register a ParamConverterProvider to apply this class across your app.