ContextedRuntimeException (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.exception, class: ContextedRuntimeException

Package org.apache.commons.lang3.exception

# Class ContextedRuntimeException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
org.apache.commons.lang3.exception.ContextedRuntimeException

All Implemented Interfaces:
  `Serializable`, `ExceptionContext`

public class ContextedRuntimeException extends RuntimeException implements ExceptionContext
A runtime 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.

A checked version of this exception is provided by ContextedException.

To use this class write code as follows:

       try {
         ...
       } catch (Exception e) {
         throw new ContextedRuntimeException("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 (ContextedRuntimeException 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.ContextedRuntimeException: 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.ContextedRuntimeExceptionTest.testAddValue(ContextedExceptionTest.java:88)
      ..... (rest of trace)

Since:
  3.0
See Also:
  - `ContextedException`
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ContextedRuntimeException()`
  Instantiates ContextedRuntimeException without message or cause.
  `ContextedRuntimeException(String message)`
  Instantiates ContextedRuntimeException with message, but without cause.
  `ContextedRuntimeException(String message, Throwable cause)`
  Instantiates ContextedRuntimeException with cause and message.
  `ContextedRuntimeException(String message, Throwable cause, ExceptionContext context)`
  Instantiates ContextedRuntimeException with cause, message, and ExceptionContext.
  `ContextedRuntimeException(Throwable cause)`
  Instantiates ContextedRuntimeException with cause, but without message.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ContextedRuntimeException`
  `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.
  `ContextedRuntimeException`
  `setContextValue(String label, Object value)`
  Sets information helpful to a developer in diagnosing and correcting the problem.

  ### Methods inherited from class java.lang.Throwable

  `addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, 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 Details

  - ### ContextedRuntimeException

    public ContextedRuntimeException()
    Instantiates ContextedRuntimeException without message or cause.

    The context information is stored using a default implementation.

  - ### ContextedRuntimeException

    public ContextedRuntimeException(String message)
    Instantiates ContextedRuntimeException with message, but without cause.

    The context information is stored using a default implementation.

    Parameters:
      `message` - the exception message, may be null

  - ### ContextedRuntimeException

    public ContextedRuntimeException(String message, Throwable cause)
    Instantiates ContextedRuntimeException with cause and message.

    The context information is stored using a default implementation.

    Parameters:
      `message` - the exception message, may be null
      `cause` - the underlying cause of the exception, may be null

  - ### ContextedRuntimeException

    public ContextedRuntimeException(String message, Throwable cause, ExceptionContext context)
    Instantiates ContextedRuntimeException with cause, message, and ExceptionContext.
    Parameters:
      `message` - the exception message, may be null
      `cause` - the underlying cause of the exception, may be null
      `context` - the context used to store the additional information, null uses default implementation

  - ### ContextedRuntimeException

    public ContextedRuntimeException(Throwable cause)
    Instantiates ContextedRuntimeException with cause, but without message.

    The context information is stored using a default implementation.

    Parameters:
      `cause` - the underlying cause of the exception, may be null

- ## Method Details

  - ### addContextValue

    public ContextedRuntimeException addContextValue(String label, Object value)
    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.

    Specified by:
      `addContextValue` in interface `ExceptionContext`
    Parameters:
      `label` - a textual label associated with information, `null` not recommended
      `value` - information needed to understand exception, may be `null`
    Returns:
      `this`, for method chaining, not `null`

  - ### getContextEntries

    public List<Pair<String,Object>> getContextEntries()
    Retrieves the full list of label-value pairs defined in the contextual data.
    Specified by:
      `getContextEntries` in interface `ExceptionContext`
    Returns:
      the list of pairs, not `null`

  - ### getContextLabels

    public Set<String> getContextLabels()
    Retrieves the full set of labels defined in the contextual data.
    Specified by:
      `getContextLabels` in interface `ExceptionContext`
    Returns:
      the set of labels, not `null`

  - ### getContextValues

    public List<Object> getContextValues(String label)
    Retrieves all the contextual data values associated with the label.
    Specified by:
      `getContextValues` in interface `ExceptionContext`
    Parameters:
      `label` - the label to get the contextual values for, may be `null`
    Returns:
      the contextual values associated with the label, never `null`

  - ### getFirstContextValue

    public Object getFirstContextValue(String label)
    Retrieves the first available contextual data value associated with the label.
    Specified by:
      `getFirstContextValue` in interface `ExceptionContext`
    Parameters:
      `label` - the label to get the contextual value for, may be `null`
    Returns:
      the first contextual value associated with the label, may be `null`

  - ### getFormattedExceptionMessage

    public String getFormattedExceptionMessage(String baseMessage)
    Gets the contextualized error message based on a base message. This will add the context label-value pairs to the message.
    Specified by:
      `getFormattedExceptionMessage` in interface `ExceptionContext`
    Parameters:
      `baseMessage` - the base exception message without context information appended
    Returns:
      the exception message with context information appended, not `null`

  - ### getMessage

    public String getMessage()
    Provides the message explaining the exception, including the contextual data.
    Overrides:
      `getMessage` in class `Throwable`
    Returns:
      the message, never null
    See Also:
      - `Throwable.getMessage()`

  - ### getRawMessage

    public String getRawMessage()
    Provides the message explaining the exception without the contextual data.
    Returns:
      the message
    Since:
      3.0.1
    See Also:
      - `Throwable.getMessage()`

  - ### setContextValue

    public ContextedRuntimeException setContextValue(String label, Object value)
    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.

    Specified by:
      `setContextValue` in interface `ExceptionContext`
    Parameters:
      `label` - a textual label associated with information, `null` not recommended
      `value` - information needed to understand exception, may be `null`
    Returns:
      `this`, for method chaining, not `null`