Version 4


    Purpose of the article is to show how to handle exception in RESTEasy.



    RESTEasy provides such a exception handling mechanism which simplifies the exception handling process. RESTEasy ExceptionMappers are custom, application provided, components that can catch thrown application exceptions and write specific HTTP responses. The are classes annotated with @Provider and that implement this interface.


    When an application exception is thrown it will be caught by the JAX-RS runtime. JAX-RS will then scan registered ExceptionMappers to see which one support marshalling the exception type thrown.


    How to Do?

    High-Level Steps

    • Implements ExceptionMapper
    • Register ExceptionMapper in the web.xml
    • Create JAXB model class for the response (Optional)
    • Create RESTEasy method
    • WebService Output




    Create a exception handler/mapper to marshal the exception.


    package com.nuwan.poc.wsmodule.exception;
     * User: Nuwan.N.Bandara 
    public class DefaultExceptionHandler implements ExceptionMapper<Exception> {
        public Response toResponse(Exception e) {        
            // For simplicity I am preparing error xml by hand.
            // Ideally we should create an ErrorResponse class to hold the error info.
            StringBuilder response = new StringBuilder("<response>");
            response.append("<message>" + e.getMessage() + "</message>");
            return Response.serverError().entity(response.toString()).type(MediaType.APPLICATION_XML).build();



    Register the DefaultExceptionHandler in your web.xml





    Create JAXB model class for marshalling POJO to XML to produce the response. (This is optional)


    package com.nuwan.poc.wsmodule.model; 
    import javax.xml.bind.annotation.XmlRootElement;
    import javax.xml.bind.annotation.XmlAttribute;
    import javax.xml.bind.annotation.XmlElement;
    import java.util.Date;
     * User: Nuwan.N.Bandara
    public class Response {
        private long id;
        private String status;
        private String message;
        public long getId() {
            return (new Date()).getTime();
        public void setId(long id) {
   = id;
        public String getStatus() {
            return status;
        public void setStatus(String status) {
            this.status = status;
        public String getMessage() {
            return message;
        public void setMessage(String message) {
            this.message = message;



    Here's the RESTEasy web service method implementation. When method receives value 0, code hit the catch block and throws an ArithmeticException. Which is a type of an Exception that we have already handled in DefaultExceptionHandler class.


        public Response testWebService(int value) throws Exception {
            Response response = new Response();
            try {
                if((100 / value) > 0) {
                    response.setMessage("Greater Than Zero");
                else {
                    response.setMessage("Less Than Zero");
            catch (ArithmeticException e) {
                throw new ArithmeticException("Division by zero!");
            return response;



    Output of the web service would look like this;


    Successful response output. Response class generates this XML.


      <message>Greater Than Zero</message> 


    Error response output. DefaultExceptionHandler toResponse() generates this XML.


      <message>Division by zero!</message>