Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.lang3.exception
Class ContextedException

    java.lang.Object
      java.lang.Throwable
          java.lang.Exception
              org.apache.commons.lang3.exception.ContextedException

All Implemented Interfaces:
  Serializable, ExceptionContext

    public class ContextedException

extends 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 map of context values. 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)
              .addValue("accountNumber", accountNumber)
              .addValue("amountPosted", amountPosted)
              .addValue("previousBalance", previousBalance)
       }
     }

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:
      [accountNumber=null]
      [amountPosted=100.00]
      [previousBalance=-2.17]

      ---------------------------------
      at org.apache.commons.lang3.exception.ContextedExceptionTest.testAddValue(ContextedExceptionTest.java:88)
      ..... (rest of trace)

Since:
  3.0
Author:
  Apache Software Foundation, D. Ashmore
See Also:
  `ContextedRuntimeException`, Serialized Form

Constructor Summary
`ContextedException()` Instantiates ContextedException without message or cause.
`ContextedException(String message)` Instantiates ContextedException with message, but without cause.
`ContextedException(String message, Throwable cause)` Instantiates ContextedException with cause and message.
`ContextedException(String message, Throwable cause, ExceptionContext context)` Instantiates ContextedException with cause, message, and ExceptionContext.
`ContextedException(Throwable cause)` Instantiates ContextedException with cause, but without message.

Method Summary
`ContextedException` | `addValue(String label, Object value)` Adds information helpful to a developer in diagnosing and correcting the problem.
`String` | `getFormattedExceptionMessage(String baseMessage)` Implementors provide the given base message with context label/value item information appended.
`Set<String>` | `getLabelSet()` Retrieves the labels defined in the contextual data.
`String` | `getMessage()` Provides the message explaining the exception, including the contextual data.
`Object` | `getValue(String label)` Retrieves a contextual data value associated with the label.
`ContextedException` | `replaceValue(String label, Object value)` Replaces information helpful to a developer in diagnosing and correcting the problem.

Methods inherited from class java.lang.Throwable
`fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, 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(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(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(String message,
                              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(String message,
                              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

### addValue

    public ContextedException addValue(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. If the added label is already available, the label is appended with an index.

  Note: This exception is only serializable if the object added is serializable.

  Specified by:
    `addValue` 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

### replaceValue

    public ContextedException replaceValue(String label,
                                           Object value)

  Replaces 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. If the replaced label does not yet exist, it is simply added.

  Note: This exception is only serializable if the object added is serializable.

  Specified by:
    `replaceValue` 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

### getValue

    public Object getValue(String label)

  Retrieves a contextual data value associated with the label.

  Specified by:
    `getValue` in interface `ExceptionContext`
  Parameters:
    `label` - the label to get the contextual value for, may be null
  Returns:
    the contextual value associated with the label, may be null

### getLabelSet

    public Set<String> getLabelSet()

  Retrieves the labels defined in the contextual data.

  Specified by:
    `getLabelSet` in interface `ExceptionContext`
  Returns:
    the set of labels, never 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()`

### getFormattedExceptionMessage

    public String getFormattedExceptionMessage(String baseMessage)

  Implementors provide the given base message with context label/value item information appended.

  Specified by:
    `getFormattedExceptionMessage` in interface `ExceptionContext`
  Parameters:
    `baseMessage` - the base exception message without context information appended
  Returns:
    the exception message with context information appended, never null

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2010 The Apache Software Foundation. All Rights Reserved.