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 * A runtime 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 * A checked version of this exception is provided by ContextedException.
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 ContextedRuntimeException("Error posting account transaction", e)
046 *          .addContextValue("Account Number", accountNumber)
047 *          .addContextValue("Amount Posted", amountPosted)
048 *          .addContextValue("Previous Balance", previousBalance)
049 *   }
050 * }
051 * </pre>
052 * <p>
053 * or improve diagnose data at a higher level:
054 * </p>
055 * <pre>
056 *   try {
057 *     ...
058 *   } catch (ContextedRuntimeException e) {
059 *     throw e.setContextValue("Transaction Id", transactionId);
060 *   } catch (Exception e) {
061 *     if (e instanceof ExceptionContext) {
062 *       e.setContextValue("Transaction Id", transactionId);
063 *     }
064 *     throw e;
065 *   }
066 * }
067 * </pre>
068 * <p>
069 * The output in a printStacktrace() (which often is written to a log) would look something like the following:
070 * </p>
071 * <pre>
072 * org.apache.commons.lang3.exception.ContextedRuntimeException: java.lang.Exception: Error posting account transaction
073 *  Exception Context:
074 *  [1:Account Number=null]
075 *  [2:Amount Posted=100.00]
076 *  [3:Previous Balance=-2.17]
077 *  [4:Transaction Id=94ef1d15-d443-46c4-822b-637f26244899]
078 *
079 *  ---------------------------------
080 *  at org.apache.commons.lang3.exception.ContextedRuntimeExceptionTest.testAddValue(ContextedExceptionTest.java:88)
081 *  ..... (rest of trace)
082 * </pre>
083 * 
084 * @see ContextedException
085 * @since 3.0
086 */
087public class ContextedRuntimeException extends RuntimeException implements ExceptionContext {
088
089    /** The serialization version. */
090    private static final long serialVersionUID = 20110706L;
091    /** The context where the data is stored. */
092    private final ExceptionContext exceptionContext;
093
094    /**
095     * Instantiates ContextedRuntimeException without message or cause.
096     * <p>
097     * The context information is stored using a default implementation.
098     */
099    public ContextedRuntimeException() {
100        super();
101        exceptionContext = new DefaultExceptionContext();
102    }
103
104    /**
105     * Instantiates ContextedRuntimeException 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 ContextedRuntimeException(final String message) {
112        super(message);
113        exceptionContext = new DefaultExceptionContext();
114    }
115
116    /**
117     * Instantiates ContextedRuntimeException 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 ContextedRuntimeException(final Throwable cause) {
124        super(cause);
125        exceptionContext = new DefaultExceptionContext();
126    }
127
128    /**
129     * Instantiates ContextedRuntimeException 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 ContextedRuntimeException(final String message, final Throwable cause) {
137        super(message, cause);
138        exceptionContext = new DefaultExceptionContext();
139    }
140
141    /**
142     * Instantiates ContextedRuntimeException 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 ContextedRuntimeException(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 ContextedRuntimeException 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 ContextedRuntimeException 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
257}