/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.lang3.exception;

import java.util.List;
import java.util.Set;

import org.apache.commons.lang3.tuple.Pair;


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)

See Also:
ContextedRuntimeException
Since:
3.0/**
 * <p>
 * An exception that provides an easy and safe way to add contextual information.
 * </p><p>
 * 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.
 * </p><p>
 * 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.
 * </p><p>
 * An unchecked version of this exception is provided by ContextedRuntimeException.
 * </p>
 * <p>
 * To use this class write code as follows:
 * </p>
 * <pre>
 *   try {
 *     ...
 *   } catch (Exception e) {
 *     throw new ContextedException("Error posting account transaction", e)
 *          .addContextValue("Account Number", accountNumber)
 *          .addContextValue("Amount Posted", amountPosted)
 *          .addContextValue("Previous Balance", previousBalance)
 *   }
 * }
 * </pre>
 * <p>
 * or improve diagnose data at a higher level:
 * </p>
 * <pre>
 *   try {
 *     ...
 *   } catch (ContextedException e) {
 *     throw e.setContextValue("Transaction Id", transactionId);
 *   } catch (Exception e) {
 *     if (e instanceof ExceptionContext) {
 *       e.setContextValue("Transaction Id", transactionId);
 *     }
 *     throw e;
 *   }
 * }
 * </pre>
 * <p>
 * The output in a printStacktrace() (which often is written to a log) would look something like the following:
 * </p>
 * <pre>
 * 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)
 * </pre>
 *
 * @see ContextedRuntimeException
 * @since 3.0
 */
public class ContextedException extends Exception implements ExceptionContext {

    
The serialization version. /** The serialization version. */
    private static final long serialVersionUID = 20110706L;
    
The context where the data is stored. /** The context where the data is stored. */
    private final ExceptionContext exceptionContext;

    
Instantiates ContextedException without message or cause.

The context information is stored using a default implementation.
/**
     * Instantiates ContextedException without message or cause.
     * <p>
     * The context information is stored using a default implementation.
     */
    public ContextedException() {
        super();
        exceptionContext = new DefaultExceptionContext();
    }

    
Instantiates ContextedException with message, but without cause.

The context information is stored using a default implementation.
Params:
message –  the exception message, may be null/**
     * Instantiates ContextedException with message, but without cause.
     * <p>
     * The context information is stored using a default implementation.
     *
     * @param message  the exception message, may be null
     */
    public ContextedException(final String message) {
        super(message);
        exceptionContext = new DefaultExceptionContext();
    }

    
Instantiates ContextedException with cause, but without message.

The context information is stored using a default implementation.
Params:
cause –  the underlying cause of the exception, may be null/**
     * Instantiates ContextedException with cause, but without message.
     * <p>
     * The context information is stored using a default implementation.
     *
     * @param cause  the underlying cause of the exception, may be null
     */
    public ContextedException(final Throwable cause) {
        super(cause);
        exceptionContext = new DefaultExceptionContext();
    }

    
Instantiates ContextedException with cause and message.

The context information is stored using a default implementation.
Params:
message –  the exception message, may be null
cause –  the underlying cause of the exception, may be null/**
     * Instantiates ContextedException with cause and message.
     * <p>
     * The context information is stored using a default implementation.
     *
     * @param message  the exception message, may be null
     * @param cause  the underlying cause of the exception, may be null
     */
    public ContextedException(final String message, final Throwable cause) {
        super(message, cause);
        exceptionContext = new DefaultExceptionContext();
    }

    
Instantiates ContextedException with cause, message, and ExceptionContext.
Params:
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/**
     * Instantiates ContextedException with cause, message, and ExceptionContext.
     *
     * @param message  the exception message, may be null
     * @param cause  the underlying cause of the exception, may be null
     * @param context  the context used to store the additional information, null uses default implementation
     */
    public ContextedException(final String message, final Throwable cause, ExceptionContext context) {
        super(message, cause);
        if (context == null) {
            context = new DefaultExceptionContext();
        }
        exceptionContext = context;
    }

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

Params:
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/**
     * 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.
     * <p>
     * Note: This exception is only serializable if the object added is serializable.
     * </p>
     *
     * @param label  a textual label associated with information, {@code null} not recommended
     * @param value  information needed to understand exception, may be {@code null}
     * @return {@code this}, for method chaining, not {@code null}
     */
    @Override
    public ContextedException addContextValue(final String label, final Object value) {
        exceptionContext.addContextValue(label, value);
        return this;
    }

    
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.

Params:
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/**
     * 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.
     * <p>
     * Note: This exception is only serializable if the object added as value is serializable.
     * </p>
     *
     * @param label  a textual label associated with information, {@code null} not recommended
     * @param value  information needed to understand exception, may be {@code null}
     * @return {@code this}, for method chaining, not {@code null}
     */
    @Override
    public ContextedException setContextValue(final String label, final Object value) {
        exceptionContext.setContextValue(label, value);
        return this;
    }

    
{@inheritDoc}
/**
     * {@inheritDoc}
     */
    @Override
    public List<Object> getContextValues(final String label) {
        return this.exceptionContext.getContextValues(label);
    }

    
{@inheritDoc}
/**
     * {@inheritDoc}
     */
    @Override
    public Object getFirstContextValue(final String label) {
        return this.exceptionContext.getFirstContextValue(label);
    }

    
{@inheritDoc}
/**
     * {@inheritDoc}
     */
    @Override
    public List<Pair<String, Object>> getContextEntries() {
        return this.exceptionContext.getContextEntries();
    }

    
{@inheritDoc}
/**
     * {@inheritDoc}
     */
    @Override
    public Set<String> getContextLabels() {
        return exceptionContext.getContextLabels();
    }

    
Provides the message explaining the exception, including the contextual data.
See Also:
getMessage.getMessage()
Returns:
the message, never null/**
     * Provides the message explaining the exception, including the contextual data.
     *
     * @see java.lang.Throwable#getMessage()
     * @return the message, never null
     */
    @Override
    public String getMessage(){
        return getFormattedExceptionMessage(super.getMessage());
    }

    
Provides the message explaining the exception without the contextual data.
See Also:
getMessage.getMessage()
Returns:
the message
Since:
3.0.1/**
     * Provides the message explaining the exception without the contextual data.
     *
     * @see java.lang.Throwable#getMessage()
     * @return the message
     * @since 3.0.1
     */
    public String getRawMessage() {
        return super.getMessage();
    }

    
{@inheritDoc}
/**
     * {@inheritDoc}
     */
    @Override
    public String getFormattedExceptionMessage(final String baseMessage) {
        return exceptionContext.getFormattedExceptionMessage(baseMessage);
    }
}