001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 * 
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 * 
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3.exception;
018
019import java.util.List;
020import java.util.Set;
021
022import org.apache.commons.lang3.tuple.Pair;
023
024/**
025 * <p>
026 * An exception that provides an easy and safe way to add contextual information.
027 * </p><p>
028 * An exception trace itself is often insufficient to provide rapid diagnosis of the issue.
029 * Frequently what is needed is a select few pieces of local contextual data.
030 * Providing this data is tricky however, due to concerns over formatting and nulls.
031 * </p><p>
032 * The contexted exception approach allows the exception to be created together with a
033 * list of context label-value pairs. This additional information is automatically included in
034 * the message and printed stack trace.
035 * </p><p>
036 * An unchecked version of this exception is provided by ContextedRuntimeException.
037 * </p>
038 * <p>
039 * To use this class write code as follows:
040 * </p>
041 * <pre>
042 *   try {
043 *     ...
044 *   } catch (Exception e) {
045 *     throw new ContextedException("Error posting account transaction", e)
046 *          .addContextValue("Account Number", accountNumber)
047 *          .addContextValue("Amount Posted", amountPosted)
048 *          .addContextValue("Previous Balance", previousBalance)
049 *   }
050 * }
051 * </pre> or improve diagnose data at a higher level:
052 * <pre>
053 *   try {
054 *     ...
055 *   } catch (ContextedException e) {
056 *     throw e.setContextValue("Transaction Id", transactionId);
057 *   } catch (Exception e) {
058 *     if (e instanceof ExceptionContext) {
059 *       e.setContextValue("Transaction Id", transactionId);
060 *     }
061 *     throw e;
062 *   }
063 * }
064 * </pre>
065 * </p><p>
066 * The output in a printStacktrace() (which often is written to a log) would look something like the following:
067 * <pre>
068 * org.apache.commons.lang3.exception.ContextedException: java.lang.Exception: Error posting account transaction
069 *  Exception Context:
070 *  [1:Account Number=null]
071 *  [2:Amount Posted=100.00]
072 *  [3:Previous Balance=-2.17]
073 *  [4:Transaction Id=94ef1d15-d443-46c4-822b-637f26244899]
074 *
075 *  ---------------------------------
076 *  at org.apache.commons.lang3.exception.ContextedExceptionTest.testAddValue(ContextedExceptionTest.java:88)
077 *  ..... (rest of trace)
078 * </pre>
079 * </p>
080 * 
081 * @see ContextedRuntimeException
082 * @since 3.0
083 */
084public class ContextedException extends Exception implements ExceptionContext {
085
086    /** The serialization version. */
087    private static final long serialVersionUID = 20110706L;
088    /** The context where the data is stored. */
089    private final ExceptionContext exceptionContext;
090
091    /**
092     * Instantiates ContextedException without message or cause.
093     * <p>
094     * The context information is stored using a default implementation.
095     */
096    public ContextedException() {
097        super();
098        exceptionContext = new DefaultExceptionContext();
099    }
100
101    /**
102     * Instantiates ContextedException with message, but without cause.
103     * <p>
104     * The context information is stored using a default implementation.
105     * 
106     * @param message  the exception message, may be null
107     */
108    public ContextedException(final String message) {
109        super(message);
110        exceptionContext = new DefaultExceptionContext();
111    }
112
113    /**
114     * Instantiates ContextedException with cause, but without message.
115     * <p>
116     * The context information is stored using a default implementation.
117     * 
118     * @param cause  the underlying cause of the exception, may be null
119     */
120    public ContextedException(final Throwable cause) {
121        super(cause);
122        exceptionContext = new DefaultExceptionContext();
123    }
124
125    /**
126     * Instantiates ContextedException with cause and message.
127     * <p>
128     * The context information is stored using a default implementation.
129     * 
130     * @param message  the exception message, may be null
131     * @param cause  the underlying cause of the exception, may be null
132     */
133    public ContextedException(final String message, final Throwable cause) {
134        super(message, cause);
135        exceptionContext = new DefaultExceptionContext();
136    }
137
138    /**
139     * Instantiates ContextedException with cause, message, and ExceptionContext.
140     * 
141     * @param message  the exception message, may be null
142     * @param cause  the underlying cause of the exception, may be null
143     * @param context  the context used to store the additional information, null uses default implementation
144     */
145    public ContextedException(final String message, final Throwable cause, ExceptionContext context) {
146        super(message, cause);
147        if (context == null) {
148            context = new DefaultExceptionContext();
149        }
150        exceptionContext = context;
151    }
152
153    //-----------------------------------------------------------------------
154    /**
155     * Adds information helpful to a developer in diagnosing and correcting the problem.
156     * For the information to be meaningful, the value passed should have a reasonable
157     * toString() implementation.
158     * Different values can be added with the same label multiple times.
159     * <p>
160     * Note: This exception is only serializable if the object added is serializable.
161     * </p>
162     * 
163     * @param label  a textual label associated with information, {@code null} not recommended
164     * @param value  information needed to understand exception, may be {@code null}
165     * @return {@code this}, for method chaining, not {@code null}
166     */
167    @Override
168    public ContextedException addContextValue(final String label, final Object value) {        
169        exceptionContext.addContextValue(label, value);
170        return this;
171    }
172
173    /**
174     * Sets information helpful to a developer in diagnosing and correcting the problem.
175     * For the information to be meaningful, the value passed should have a reasonable
176     * toString() implementation.
177     * Any existing values with the same labels are removed before the new one is added.
178     * <p>
179     * Note: This exception is only serializable if the object added as value is serializable.
180     * </p>
181     * 
182     * @param label  a textual label associated with information, {@code null} not recommended
183     * @param value  information needed to understand exception, may be {@code null}
184     * @return {@code this}, for method chaining, not {@code null}
185     */
186    @Override
187    public ContextedException setContextValue(final String label, final Object value) {        
188        exceptionContext.setContextValue(label, value);
189        return this;
190    }
191
192    /**
193     * {@inheritDoc}
194     */
195    @Override
196    public List<Object> getContextValues(final String label) {
197        return this.exceptionContext.getContextValues(label);
198    }
199
200    /**
201     * {@inheritDoc}
202     */
203    @Override
204    public Object getFirstContextValue(final String label) {
205        return this.exceptionContext.getFirstContextValue(label);
206    }
207
208    /**
209     * {@inheritDoc}
210     */
211    @Override
212    public List<Pair<String, Object>> getContextEntries() {
213        return this.exceptionContext.getContextEntries();
214    }
215
216    /**
217     * {@inheritDoc}
218     */
219    @Override
220    public Set<String> getContextLabels() {
221        return exceptionContext.getContextLabels();
222    }
223
224    /**
225     * Provides the message explaining the exception, including the contextual data.
226     * 
227     * @see java.lang.Throwable#getMessage()
228     * @return the message, never null
229     */
230    @Override
231    public String getMessage(){
232        return getFormattedExceptionMessage(super.getMessage());
233    }
234
235    /**
236     * Provides the message explaining the exception without the contextual data.
237     * 
238     * @see java.lang.Throwable#getMessage()
239     * @return the message
240     * @since 3.0.1
241     */
242    public String getRawMessage() {
243        return super.getMessage();
244    }
245
246    /**
247     * {@inheritDoc}
248     */
249    @Override
250    public String getFormattedExceptionMessage(final String baseMessage) {
251        return exceptionContext.getFormattedExceptionMessage(baseMessage);
252    }
253}