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, JaxrsNotAuthorizedException, JaxrsNotFoundException, JaxrsValidationException

public class JaxrsException
extends RuntimeException

Represents a JAX-RS 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:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
JaxrsException(String message)	New instance with given message and default status code.
JaxrsException(String message, int statusCode)	New instance with given message and status code.
JaxrsException(String message, Throwable cause)	New instance with given message and cause.
JaxrsException(String message, Throwable cause, int statusCode)	New instance with given message, cause, and status code.
JaxrsException(Throwable cause)	New instance with given cause.
JaxrsException(Throwable cause, int statusCode)	New instance with given cause and status code.
JaxrsException(List<ErrorMessage> errors, Integer statusCode)	New "aggregate" instance with given list of ErrorMessage objects.
JaxrsException(List<JaxrsException> exceptions)	New "aggregate" instance with given list of JaxrsException objects.
JaxrsException(ErrorMessage error)	New instance with given ErrorMessage.
JaxrsException(ErrorMessage error, Throwable cause)	New instance with given ErrorMessage and Throwable.

Method Summary

Modifier and Type	Method	Description
static JaxrsException	buildJaxrsException(Throwable throwable)	Static factory to construct a new instance from the given Throwable.
static int	getErrorCode(Throwable throwable)	Determine an "appropriate" HTTP status code for the given Throwable.
List<ErrorMessage>	getErrors()
Map<String,Object>	getOtherData()
int	getRollUpStatus()	Calculates an overall status code as the "roll up" of the status codes in the ErrorMessage objects contained in this exception.
int	getStatusCode()
protected void	setErrors(List<ErrorMessage> errorMessages)	Change the ErrorMessage objects contained in this exception.
void	setOtherData(Map<String,Object> newDataToAppend)	Appends the entries contained in the given map to the existing otherData.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

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 be given to represent all the errors. The message of this exception is take 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 Detail

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 sub-class 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()

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