Package org.kiwiproject.jaxrs.exception

Class JaxrsException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
org.kiwiproject.jaxrs.exception.JaxrsException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
JaxrsBadRequestException, JaxrsConflictException, JaxrsForbiddenException, JaxrsInternalServerErrorException, JaxrsNotAuthorizedException, JaxrsNotFoundException, JaxrsValidationException
public class JaxrsException extends RuntimeException
Represents a Jakarta REST exception that uses the Kiwi ErrorMessage to describe the errors causing this exception.

This class is concrete but also can be subclassed to represent specific HTTP status error codes.

See Also:

  • Constructor Details

    • JaxrsException

      public JaxrsException(Throwable cause)
      New instance with given cause.
      Parameters:
      cause - the cause of this exception

    • JaxrsException

      public JaxrsException(String message)
      New instance with given message and default status code.
      Parameters:
      message - the message for this exception

    • JaxrsException

      public JaxrsException(String message, int statusCode)
      New instance with given message and status code.
      Parameters:
      message - the message for this exception
      statusCode - the status code for this exception

    • JaxrsException

      public JaxrsException(String message, Throwable cause)
      New instance with given message and cause.
      Parameters:
      message - the message for this exception
      cause - the cause of this exception

    • JaxrsException

      public JaxrsException(String message, Throwable cause, int statusCode)
      New instance with given message, cause, and status code.
      Parameters:
      message - the message for this exception
      cause - the cause of this exception
      statusCode - the status code for this exception

    • JaxrsException

      public JaxrsException(ErrorMessage error)
      New instance with given ErrorMessage.
      Parameters:
      error - the ErrorMessage cause of this exception

    • JaxrsException

      public JaxrsException(Throwable cause, int statusCode)
      New instance with given cause and status code.
      Parameters:
      cause - the cause of this exception
      statusCode - the status code for this exception

    • JaxrsException

      public JaxrsException(ErrorMessage error, Throwable cause)
      New instance with given ErrorMessage and Throwable.
      Parameters:
      error - the ErrorMessage cause of this exception
      cause - the cause of this exception

    • JaxrsException

      public JaxrsException(List<ErrorMessage> errors, @Nullable Integer statusCode)
      New "aggregate" instance with given list of ErrorMessage objects. The statusCode can be null if a "rolled up" overall status is desired, or an explicit code be given to represent all the errors. The message of this exception is taken from the first ErrorMessage.
      Parameters:
      errors - a list containing multiple ErrorMessages as the underlying cause of this exception
      statusCode - the overall status code to use, or null (overall status will be rolled up as max of all the ErrorMessage objects)

    • JaxrsException

      public JaxrsException(List<JaxrsException> exceptions)
      New "aggregate" instance with given list of JaxrsException objects.
      Parameters:
      exceptions - the JaxrsException objects that caused this exception

  • Method Details

    • buildJaxrsException

      public static JaxrsException buildJaxrsException(Throwable throwable)
      Static factory to construct a new instance from the given Throwable.
      Parameters:
      throwable - the cause to use for the JaxrsException
      Returns:
      new JaxrsException instance

    • getErrors

      public List<ErrorMessage> getErrors()
      Returns:
      an unmodifiable list of ErrorMessages

    • setErrors

      protected final void setErrors(List<ErrorMessage> errorMessages)
      Change the ErrorMessage objects contained in this exception.

      NOTE: If the given errorMessages is null or empty, it is ignored in order to prevent clearing out all errors.

      Parameters:
      errorMessages - the new ErrorMessages to set
      Implementation Note:
      This is final because it is used in some subclass constructors. It is a big no-no to call overridable methods in constructors. It can cause very strange behavior like NPEs. Also see Effective Java (3rd Edition) Item #19 "Design and document for inheritance or else prohibit it" and Sonar rule java:S1699 "Constructors should only call non-overridable methods".

    • getStatusCode

      public int getStatusCode()
      Returns:
      the overall status or a "roll up" status if there are multiple errors
      See Also:

    • getRollUpStatus

      public int getRollUpStatus()
      Calculates an overall status code as the "roll up" of the status codes in the ErrorMessage objects contained in this exception.

      If there are no ErrorMessage objects a default status code is returned. If there is exactly one ErrorMessage, then its status code is returned.

      If there are multiple ErrorMessage objects, and they all have the same status code, then the overall status is just that status code.

      Last, if there are multiple ErrorMessage objects, and some have different status codes, then the overall status is calculated to be the base status code (e.g. 400) of the highest error family (e.g. 4xx). For example, if there are multiple 4xx errors then the overall status is considered as the base of the 4xx series, or 400. Or if there are both 4xx and 5xx errors, the overall status is 500 (the base of the 5xx series). This is obviously a lossy "algorithm" and is meant as an overall indication of the error family. Inspection of all contained errors is required to fully determine the causes.

      Returns:
      the "rolled up" status code

    • getOtherData

      public Map<String,Object> getOtherData()
      Returns:
      an unmodifiable map of additional data about this exception

    • setOtherData

      public void setOtherData(Map<String,Object> newDataToAppend)
      Appends the entries contained in the given map to the existing otherData. Or, if the given map is null or empty, clears the existing otherData (but will never set it to null).

      NOTE: If the given map contains a key named "errors", it will be ignored when the JaxrsExceptionMapper creates the response, because "errors" is reserved for the list of ErrorMessage objects.

      Parameters:
      newDataToAppend - map containing additional data
      API Note:
      This method is poorly named, but since we have existing code that uses it, we don't plan to change it. Whenever Jakarta EE 9 is released, we will look into a re-design of this class and package.

    • getErrorCode

      public static int getErrorCode(Throwable throwable)
      Determine an "appropriate" HTTP status code for the given Throwable.
      Parameters:
      throwable - the Throwable to inspect
      Returns:
      an HTTP error status code