An exception trace itself is often insufficient to provide rapid diagnosis of the issue. Frequently what is needed is a select few pieces of local contextual data. Providing this data is tricky however, due to concerns over formatting and nulls.
The contexted exception approach allows the exception to be created together with a list of context label-value pairs. This additional information is automatically included in the message and printed stack trace.
An unchecked version of this exception is provided by ContextedRuntimeException.
To use this class write code as follows:
try {
...
} catch (Exception e) {
throw new ContextedException("Error posting account transaction", e)
.addContextValue("Account Number", accountNumber)
.addContextValue("Amount Posted", amountPosted)
.addContextValue("Previous Balance", previousBalance);
}
}
or improve diagnose data at a higher level:
try {
...
} catch (ContextedException e) {
throw e.setContextValue("Transaction Id", transactionId);
} catch (Exception e) {
if (e instanceof ExceptionContext) {
e.setContextValue("Transaction Id", transactionId);
}
throw e;
}
}
The output in a printStacktrace() (which often is written to a log) would look something like the following:
org.apache.commons.lang3.exception.ContextedException: java.lang.Exception: Error posting account transaction Exception Context: [1:Account Number=null] [2:Amount Posted=100.00] [3:Previous Balance=-2.17] [4:Transaction Id=94ef1d15-d443-46c4-822b-637f26244899] --------------------------------- at org.apache.commons.lang3.exception.ContextedExceptionTest.testAddValue(ContextedExceptionTest.java:88) ..... (rest of trace)
ContextedRuntimeException
| Modifier and Type | Field and Description |
|---|---|
| private final ExceptionContext | exceptionContext
The context where the data is stored. |
| private static final long | serialVersionUID
The serialization version.
|
| Access | Constructor and Description |
|---|---|
| public | |
| public | ContextedException(final String
the exception message, may be null message)Instantiates ContextedException with message, but without cause. |
| public | ContextedException(final String
the exception message, may be null message, final Throwable the underlying cause of the exception, may be null cause)Instantiates ContextedException with cause and message. |
| public | ContextedException(final String
the exception message, may be null message, final Throwable the underlying cause of the exception, may be null cause, ExceptionContext the context used to store the additional information, null uses default implementation context)Instantiates ContextedException with cause, message, and ExceptionContext. |
| public | ContextedException(final Throwable
the underlying cause of the exception, may be null cause)Instantiates ContextedException with cause, but without message. |
| Modifier and Type | Method and Description |
|---|---|
| public ContextedException | Returns: this, for method chaining, not nulla textual label associated with information, label, final Object null not recommendedinformation needed to understand exception, may be value)nullImplements org. Adds information helpful to a developer in diagnosing and correcting the problem. |
| public List | getContextEntries()
Implements org. Gets the full list of label-value pairs defined in the contextual data. |
| public Set | getContextLabels()
Implements org. Gets the full set of labels defined in the contextual data. |
| public List | getContextValues(final String label)
Implements org. Gets all the contextual data values associated with the label. |
| public Object | getFirstContextValue(final String label)
Implements org. Gets the first available contextual data value associated with the label. |
| public String | getFormattedExceptionMessage(final String baseMessage)
Implements org. Gets the contextualized error message based on a base message. |
| public String | Returns: the message, never nullOverrides java. Provides the message explaining the exception, including the contextual data. |
| public String | Returns: the messageProvides the message explaining the exception without the contextual data. |
| public ContextedException | Returns: this, for method chaining, not nulla textual label associated with information, label, final Object null not recommendedinformation needed to understand exception, may be value)nullImplements org. Sets information helpful to a developer in diagnosing and correcting the problem. |
| exceptionContext | back to summary |
|---|---|
| private final ExceptionContext exceptionContext The context where the data is stored. | |
| serialVersionUID | back to summary |
|---|---|
| private static final long serialVersionUID Hides java. The serialization version. | |
| ContextedException | back to summary |
|---|---|
| public ContextedException() Instantiates ContextedException without message or cause. The context information is stored using a default implementation. | |
| ContextedException | back to summary |
|---|---|
| public ContextedException(final String message) Instantiates ContextedException with message, but without cause. The context information is stored using a default implementation.
| |
| ContextedException | back to summary |
|---|---|
| public ContextedException(final String message, final Throwable cause) Instantiates ContextedException with cause and message. The context information is stored using a default implementation. | |
| ContextedException | back to summary |
|---|---|
| public ContextedException(final String message, final Throwable cause, ExceptionContext context) Instantiates ContextedException with cause, message, and ExceptionContext.
| |
| ContextedException | back to summary |
|---|---|
| public ContextedException(final Throwable cause) Instantiates ContextedException with cause, but without message. The context information is stored using a default implementation.
| |
| addContextValue | back to summary |
|---|---|
| public ContextedException addContextValue(final String label, final Object value) Implements org. Adds information helpful to a developer in diagnosing and correcting the problem. For the information to be meaningful, the value passed should have a reasonable toString() implementation. Different values can be added with the same label multiple times. Note This exception is only serializable if the object added is serializable.
| |
| getContextEntries | back to summary |
|---|---|
| public List Implements org. Doc from org. Gets the full list of label-value pairs defined in the contextual data.
| |
| getContextLabels | back to summary |
|---|---|
| public Set Implements org. Doc from org. Gets the full set of labels defined in the contextual data.
| |
| getContextValues | back to summary |
|---|---|
| public List Implements org. Doc from org. Gets all the contextual data values associated with the label.
| |
| getFirstContextValue | back to summary |
|---|---|
| public Object getFirstContextValue(final String label) Implements org. Doc from org. Gets the first available contextual data value associated with the label.
| |
| getFormattedExceptionMessage | back to summary |
|---|---|
| public String getFormattedExceptionMessage(final String baseMessage) Implements org. Doc from org. Gets the contextualized error message based on a base message. This will add the context label-value pairs to the message.
| |
| getMessage | back to summary |
|---|---|
| public String getMessage() Overrides java. Provides the message explaining the exception, including the contextual data.
| |
| getRawMessage | back to summary |
|---|---|
| public String getRawMessage() Provides the message explaining the exception without the contextual data.
| |
| setContextValue | back to summary |
|---|---|
| public ContextedException setContextValue(final String label, final Object value) Implements org. Sets information helpful to a developer in diagnosing and correcting the problem. For the information to be meaningful, the value passed should have a reasonable toString() implementation. Any existing values with the same labels are removed before the new one is added. Note This exception is only serializable if the object added as value is serializable.
| |