View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.exception;
18  
19  import java.util.List;
20  import java.util.Set;
21  
22  import org.apache.commons.lang3.tuple.Pair;
23  
24  /**
25   * <p>
26   * An exception that provides an easy and safe way to add contextual information.
27   * </p><p>
28   * An exception trace itself is often insufficient to provide rapid diagnosis of the issue.
29   * Frequently what is needed is a select few pieces of local contextual data.
30   * Providing this data is tricky however, due to concerns over formatting and nulls.
31   * </p><p>
32   * The contexted exception approach allows the exception to be created together with a
33   * list of context label-value pairs. This additional information is automatically included in
34   * the message and printed stack trace.
35   * </p><p>
36   * An unchecked version of this exception is provided by ContextedRuntimeException.
37   * </p>
38   * <p>
39   * To use this class write code as follows:
40   * </p>
41   * <pre>
42   *   try {
43   *     ...
44   *   } catch (Exception e) {
45   *     throw new ContextedException("Error posting account transaction", e)
46   *          .addContextValue("Account Number", accountNumber)
47   *          .addContextValue("Amount Posted", amountPosted)
48   *          .addContextValue("Previous Balance", previousBalance)
49   *   }
50   * }
51   * </pre>
52   * <p>
53   * or improve diagnose data at a higher level:
54   * </p>
55   * <pre>
56   *   try {
57   *     ...
58   *   } catch (ContextedException e) {
59   *     throw e.setContextValue("Transaction Id", transactionId);
60   *   } catch (Exception e) {
61   *     if (e instanceof ExceptionContext) {
62   *       e.setContextValue("Transaction Id", transactionId);
63   *     }
64   *     throw e;
65   *   }
66   * }
67   * </pre>
68   * <p>
69   * The output in a printStacktrace() (which often is written to a log) would look something like the following:
70   * </p>
71   * <pre>
72   * org.apache.commons.lang3.exception.ContextedException: java.lang.Exception: Error posting account transaction
73   *  Exception Context:
74   *  [1:Account Number=null]
75   *  [2:Amount Posted=100.00]
76   *  [3:Previous Balance=-2.17]
77   *  [4:Transaction Id=94ef1d15-d443-46c4-822b-637f26244899]
78   *
79   *  ---------------------------------
80   *  at org.apache.commons.lang3.exception.ContextedExceptionTest.testAddValue(ContextedExceptionTest.java:88)
81   *  ..... (rest of trace)
82   * </pre>
83   * 
84   * @see ContextedRuntimeException
85   * @since 3.0
86   */
87  public class ContextedException extends Exception implements ExceptionContext {
88  
89      /** The serialization version. */
90      private static final long serialVersionUID = 20110706L;
91      /** The context where the data is stored. */
92      private final ExceptionContext exceptionContext;
93  
94      /**
95       * Instantiates ContextedException without message or cause.
96       * <p>
97       * The context information is stored using a default implementation.
98       */
99      public ContextedException() {
100         super();
101         exceptionContext = new DefaultExceptionContext();
102     }
103 
104     /**
105      * Instantiates ContextedException with message, but without cause.
106      * <p>
107      * The context information is stored using a default implementation.
108      * 
109      * @param message  the exception message, may be null
110      */
111     public ContextedException(final String message) {
112         super(message);
113         exceptionContext = new DefaultExceptionContext();
114     }
115 
116     /**
117      * Instantiates ContextedException with cause, but without message.
118      * <p>
119      * The context information is stored using a default implementation.
120      * 
121      * @param cause  the underlying cause of the exception, may be null
122      */
123     public ContextedException(final Throwable cause) {
124         super(cause);
125         exceptionContext = new DefaultExceptionContext();
126     }
127 
128     /**
129      * Instantiates ContextedException with cause and message.
130      * <p>
131      * The context information is stored using a default implementation.
132      * 
133      * @param message  the exception message, may be null
134      * @param cause  the underlying cause of the exception, may be null
135      */
136     public ContextedException(final String message, final Throwable cause) {
137         super(message, cause);
138         exceptionContext = new DefaultExceptionContext();
139     }
140 
141     /**
142      * Instantiates ContextedException with cause, message, and ExceptionContext.
143      * 
144      * @param message  the exception message, may be null
145      * @param cause  the underlying cause of the exception, may be null
146      * @param context  the context used to store the additional information, null uses default implementation
147      */
148     public ContextedException(final String message, final Throwable cause, ExceptionContext context) {
149         super(message, cause);
150         if (context == null) {
151             context = new DefaultExceptionContext();
152         }
153         exceptionContext = context;
154     }
155 
156     //-----------------------------------------------------------------------
157     /**
158      * Adds information helpful to a developer in diagnosing and correcting the problem.
159      * For the information to be meaningful, the value passed should have a reasonable
160      * toString() implementation.
161      * Different values can be added with the same label multiple times.
162      * <p>
163      * Note: This exception is only serializable if the object added is serializable.
164      * </p>
165      * 
166      * @param label  a textual label associated with information, {@code null} not recommended
167      * @param value  information needed to understand exception, may be {@code null}
168      * @return {@code this}, for method chaining, not {@code null}
169      */
170     @Override
171     public ContextedException addContextValue(final String label, final Object value) {        
172         exceptionContext.addContextValue(label, value);
173         return this;
174     }
175 
176     /**
177      * Sets information helpful to a developer in diagnosing and correcting the problem.
178      * For the information to be meaningful, the value passed should have a reasonable
179      * toString() implementation.
180      * Any existing values with the same labels are removed before the new one is added.
181      * <p>
182      * Note: This exception is only serializable if the object added as value is serializable.
183      * </p>
184      * 
185      * @param label  a textual label associated with information, {@code null} not recommended
186      * @param value  information needed to understand exception, may be {@code null}
187      * @return {@code this}, for method chaining, not {@code null}
188      */
189     @Override
190     public ContextedException setContextValue(final String label, final Object value) {        
191         exceptionContext.setContextValue(label, value);
192         return this;
193     }
194 
195     /**
196      * {@inheritDoc}
197      */
198     @Override
199     public List<Object> getContextValues(final String label) {
200         return this.exceptionContext.getContextValues(label);
201     }
202 
203     /**
204      * {@inheritDoc}
205      */
206     @Override
207     public Object getFirstContextValue(final String label) {
208         return this.exceptionContext.getFirstContextValue(label);
209     }
210 
211     /**
212      * {@inheritDoc}
213      */
214     @Override
215     public List<Pair<String, Object>> getContextEntries() {
216         return this.exceptionContext.getContextEntries();
217     }
218 
219     /**
220      * {@inheritDoc}
221      */
222     @Override
223     public Set<String> getContextLabels() {
224         return exceptionContext.getContextLabels();
225     }
226 
227     /**
228      * Provides the message explaining the exception, including the contextual data.
229      * 
230      * @see java.lang.Throwable#getMessage()
231      * @return the message, never null
232      */
233     @Override
234     public String getMessage(){
235         return getFormattedExceptionMessage(super.getMessage());
236     }
237 
238     /**
239      * Provides the message explaining the exception without the contextual data.
240      * 
241      * @see java.lang.Throwable#getMessage()
242      * @return the message
243      * @since 3.0.1
244      */
245     public String getRawMessage() {
246         return super.getMessage();
247     }
248 
249     /**
250      * {@inheritDoc}
251      */
252     @Override
253     public String getFormattedExceptionMessage(final String baseMessage) {
254         return exceptionContext.getFormattedExceptionMessage(baseMessage);
255     }
256 }