src/main/java/org/apache/commons/lang3/exception/ContextedException.java - platform/external/apache-commons-lang - Git at Google

 /*
  * 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;

 /**
  * <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. */
     private static final long serialVersionUID = 20110706L;
     /** The context where the data is stored. */
     private final ExceptionContext exceptionContext;

     /**
      * 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.
      * <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.
      * <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.
      * <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.
      *
      * @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.
      * <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.
      * <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}
      */
     @Override
     public List<Object> getContextValues(final String label) {
         return this.exceptionContext.getContextValues(label);
     }

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

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

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

     /**
      * 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 java.lang.Throwable#getMessage()
      * @return the message
      * @since 3.0.1
      */
     public String getRawMessage() {
         return super.getMessage();
     }

     /**
      * {@inheritDoc}
      */
     @Override
     public String getFormattedExceptionMessage(final String baseMessage) {
         return exceptionContext.getFormattedExceptionMessage(baseMessage);
     }
 }
	/*
	* 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;

	/**
	* <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. */
	private static final long serialVersionUID = 20110706L;
	/** The context where the data is stored. */
	private final ExceptionContext exceptionContext;

	/**
	* 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.
	* <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.
	* <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.
	* <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.
	*
	* @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.
	* <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.
	* <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}
	*/
	@Override
	public List<Object> getContextValues(final String label) {
	return this.exceptionContext.getContextValues(label);
	}

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

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

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

	/**
	* 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 java.lang.Throwable#getMessage()
	* @return the message
	* @since 3.0.1
	*/
	public String getRawMessage() {
	return super.getMessage();
	}

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