Package org.apache.commons.lang3.exception

Class ContextedException

  • All Implemented Interfaces:
    java.io.Serializable, ExceptionContext
    public class ContextedException
extends java.lang.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)
    Since:
    3.0
    See Also:
    ContextedRuntimeException, Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      ContextedException()
      Instantiates ContextedException without message or cause.
      ContextedException​(java.lang.String message)
      Instantiates ContextedException with message, but without cause.
      ContextedException​(java.lang.String message, java.lang.Throwable cause)
      Instantiates ContextedException with cause and message.
      ContextedException​(java.lang.String message, java.lang.Throwable cause, ExceptionContext context)
      Instantiates ContextedException with cause, message, and ExceptionContext.
      ContextedException​(java.lang.Throwable cause)
      Instantiates ContextedException with cause, but without message.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      ContextedException addContextValue​(java.lang.String label, java.lang.Object value)
      Adds information helpful to a developer in diagnosing and correcting the problem.
      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.
      java.lang.String getMessage()
      Provides the message explaining the exception, including the contextual data.
      java.lang.String getRawMessage()
      Provides the message explaining the exception without the contextual data.
      ContextedException setContextValue​(java.lang.String label, java.lang.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

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • ContextedException

        public ContextedException()
        Instantiates ContextedException without message or cause.

        The context information is stored using a default implementation.

      • ContextedException

        public ContextedException​(java.lang.String message)
        Instantiates ContextedException with message, but without cause.

        The context information is stored using a default implementation.

        Parameters:
        message - the exception message, may be null

      • ContextedException

        public ContextedException​(java.lang.Throwable cause)
        Instantiates ContextedException 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

      • ContextedException

        public ContextedException​(java.lang.String message,
                          java.lang.Throwable cause)
        Instantiates ContextedException 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

      • ContextedException

        public ContextedException​(java.lang.String message,
                          java.lang.Throwable cause,
                          ExceptionContext context)
        Instantiates ContextedException 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

    • Method Detail

      • addContextValue

        public ContextedException addContextValue​(java.lang.String label,
                                          java.lang.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

      • setContextValue

        public ContextedException setContextValue​(java.lang.String label,
                                          java.lang.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

      • getContextValues

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

      • getContextEntries

        public java.util.List<Pair<java.lang.String,​java.lang.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 java.util.Set<java.lang.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

      • getMessage

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

      • getRawMessage

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

      • getFormattedExceptionMessage

        public 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.
        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