public class ContextedException extends Exception implements ExceptionContext
An exception that provides an easy and safe way to add contextual information.
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
,
Serialized FormConstructor and Description |
---|
ContextedException()
Instantiates ContextedException without message or cause.
|
ContextedException(String message)
Instantiates ContextedException with message, but without cause.
|
ContextedException(String message,
Throwable cause)
Instantiates ContextedException with cause and message.
|
ContextedException(String message,
Throwable cause,
ExceptionContext context)
Instantiates ContextedException with cause, message, and ExceptionContext.
|
ContextedException(Throwable cause)
Instantiates ContextedException with cause, but without message.
|
Modifier and Type | Method and Description |
---|---|
ContextedException |
addContextValue(String label,
Object value)
Adds information helpful to a developer in diagnosing and correcting the problem.
|
List<Pair<String,Object>> |
getContextEntries()
Retrieves the full list of label-value pairs defined in the contextual data.
|
Set<String> |
getContextLabels()
Retrieves the full set of labels defined in the contextual data.
|
List<Object> |
getContextValues(String label)
Retrieves all the contextual data values associated with the label.
|
Object |
getFirstContextValue(String label)
Retrieves the first available contextual data value associated with the label.
|
String |
getFormattedExceptionMessage(String baseMessage)
Gets the contextualized error message based on a base message.
|
String |
getMessage()
Provides the message explaining the exception, including the contextual data.
|
String |
getRawMessage()
Provides the message explaining the exception without the contextual data.
|
ContextedException |
setContextValue(String label,
Object value)
Sets information helpful to a developer in diagnosing and correcting the problem.
|
addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
public ContextedException()
The context information is stored using a default implementation.
public ContextedException(String message)
The context information is stored using a default implementation.
message
- the exception message, may be nullpublic ContextedException(Throwable cause)
The context information is stored using a default implementation.
cause
- the underlying cause of the exception, may be nullpublic ContextedException(String message, Throwable cause)
The context information is stored using a default implementation.
message
- the exception message, may be nullcause
- the underlying cause of the exception, may be nullpublic ContextedException(String message, Throwable cause, ExceptionContext context)
message
- the exception message, may be nullcause
- the underlying cause of the exception, may be nullcontext
- the context used to store the additional information, null uses default implementationpublic ContextedException addContextValue(String label, Object value)
Note: This exception is only serializable if the object added is serializable.
addContextValue
in interface ExceptionContext
label
- a textual label associated with information, null
not recommendedvalue
- information needed to understand exception, may be null
this
, for method chaining, not null
public ContextedException setContextValue(String label, Object value)
Note: This exception is only serializable if the object added as value is serializable.
setContextValue
in interface ExceptionContext
label
- a textual label associated with information, null
not recommendedvalue
- information needed to understand exception, may be null
this
, for method chaining, not null
public List<Object> getContextValues(String label)
getContextValues
in interface ExceptionContext
label
- the label to get the contextual values for, may be null
null
public Object getFirstContextValue(String label)
getFirstContextValue
in interface ExceptionContext
label
- the label to get the contextual value for, may be null
null
public List<Pair<String,Object>> getContextEntries()
getContextEntries
in interface ExceptionContext
null
public Set<String> getContextLabels()
getContextLabels
in interface ExceptionContext
null
public String getMessage()
getMessage
in class Throwable
Throwable.getMessage()
public String getRawMessage()
Throwable.getMessage()
public String getFormattedExceptionMessage(String baseMessage)
getFormattedExceptionMessage
in interface ExceptionContext
baseMessage
- the base exception message without context information appendednull
Copyright © 2001–2014 The Apache Software Foundation. All rights reserved.