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

Package org.apache.commons.lang3.exception

# Interface ExceptionContext

All Known Implementing Classes:
  `ContextedException`, `ContextedRuntimeException`, `DefaultExceptionContext`

public interface ExceptionContext
Allows the storage and retrieval of contextual information based on label-value pairs for exceptions.

Implementations are expected to manage the pairs in a list-style collection that keeps the pairs in the sequence of their addition.

Since:
  3.0
See Also:
  - `ContextedException`
  - `ContextedRuntimeException`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ExceptionContext`
  `addContextValue(String label, Object value)`
  Adds a contextual label-value pair into this context.
  `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.
  `ExceptionContext`
  `setContextValue(String label, Object value)`
  Sets a contextual label-value pair into this context.

- ## Method Details

  - ### addContextValue

    ExceptionContext addContextValue(String label, Object value)
    Adds a contextual label-value pair into this context.

    The pair will be added to the context, independently of an already existing pair with the same label.

    Parameters:
      `label` - the label of the item to add, `null` not recommended
      `value` - the value of item to add, may be `null`
    Returns:
      `this`, for method chaining, not `null`

  - ### getContextEntries

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

  - ### getContextLabels

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

  - ### getContextValues

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

  - ### getFirstContextValue

    Object getFirstContextValue(String label)
    Retrieves the first available contextual data value associated with the label.
    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

    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.
    Parameters:
      `baseMessage` - the base exception message without context information appended
    Returns:
      the exception message with context information appended, not `null`

  - ### setContextValue

    ExceptionContext setContextValue(String label, Object value)
    Sets a contextual label-value pair into this context.

    The pair will be added normally, but any existing label-value pair with the same label is removed from the context.

    Parameters:
      `label` - the label of the item to add, `null` not recommended
      `value` - the value of item to add, may be `null`
    Returns:
      `this`, for method chaining, not `null`