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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and 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 Detail

    - #### 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`

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.