ExceptionContext
Date: 2017-02-08

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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ExceptionContext` | `addContextValue(java.lang.String label, java.lang.Object value)` Adds a contextual label-value pair into this context.
    `java.util.List<Pair<java.lang.String,java.lang.Object>>` | `getContextEntries()` Retrieves the full list of label-value pairs defined in the contextual data.
    `java.util.Set<java.lang.String>` | `getContextLabels()` Retrieves the full set of labels defined in the contextual data.
    `java.util.List<java.lang.Object>` | `getContextValues(java.lang.String label)` Retrieves all the contextual data values associated with the label.
    `java.lang.Object` | `getFirstContextValue(java.lang.String label)` Retrieves the first available contextual data value associated with the label.
    `java.lang.String` | `getFormattedExceptionMessage(java.lang.String baseMessage)` Gets the contextualized error message based on a base message.
    `ExceptionContext` | `setContextValue(java.lang.String label, java.lang.Object value)` Sets a contextual label-value pair into this context.

- - ### Method Detail

    - #### addContextValue

          ExceptionContext addContextValue(java.lang.String label,
                                         java.lang.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`

    - #### setContextValue

          ExceptionContext setContextValue(java.lang.String label,
                                         java.lang.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`

    - #### getContextValues

          java.util.List<java.lang.Object> getContextValues(java.lang.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

          java.lang.Object getFirstContextValue(java.lang.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`

    - #### getContextLabels

          java.util.Set<java.lang.String> getContextLabels()

      Retrieves the full set of labels defined in the contextual data.
      Returns:
        the set of labels, not `null`

    - #### getContextEntries

          java.util.List<Pair<java.lang.String,java.lang.Object>> getContextEntries()

      Retrieves the full list of label-value pairs defined in the contextual data.
      Returns:
        the list of pairs, not `null`

    - #### getFormattedExceptionMessage

          java.lang.String getFormattedExceptionMessage(java.lang.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`