Coverage Report

Coverage Report - org.apache.commons.lang3.exception.ContextedException

Classes in this File

Line Coverage

Branch Coverage

Complexity

ContextedException

100%

29/29

100%

2/2

1.071

 /*
  * 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> or improve diagnose data at a higher level:
  * <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><p>
  * The output in a printStacktrace() (which often is written to a log) would look something like the following:
  * <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>
  * </p>
  * 
  * @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);
     }
 }

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> or improve diagnose data at a higher level:
52		* <pre>
53		* try {
54		* ...
55		* } catch (ContextedException e) {
56		* throw e.setContextValue("Transaction Id", transactionId);
57		* } catch (Exception e) {
58		* if (e instanceof ExceptionContext) {
59		* e.setContextValue("Transaction Id", transactionId);
60		* }
61		* throw e;
62		* }
63		* }
64		* </pre>
65		* </p><p>
66		* The output in a printStacktrace() (which often is written to a log) would look something like the following:
67		* <pre>
68		* org.apache.commons.lang3.exception.ContextedException: java.lang.Exception: Error posting account transaction
69		* Exception Context:
70		* [1:Account Number=null]
71		* [2:Amount Posted=100.00]
72		* [3:Previous Balance=-2.17]
73		* [4:Transaction Id=94ef1d15-d443-46c4-822b-637f26244899]
74		*
75		* ---------------------------------
76		* at org.apache.commons.lang3.exception.ContextedExceptionTest.testAddValue(ContextedExceptionTest.java:88)
77		* ..... (rest of trace)
78		* </pre>
79		* </p>
80		*
81		* @see ContextedRuntimeException
82		* @since 3.0
83		*/
84	82	public class ContextedException extends Exception implements ExceptionContext {
85
86		/** The serialization version. */
87		private static final long serialVersionUID = 20110706L;
88		/** The context where the data is stored. */
89		private final ExceptionContext exceptionContext;
90
91		/**
92		* Instantiates ContextedException without message or cause.
93		* <p>
94		* The context information is stored using a default implementation.
95		*/
96		public ContextedException() {
97	1	super();
98	1	exceptionContext = new DefaultExceptionContext();
99	1	}
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	1	super(message);
110	1	exceptionContext = new DefaultExceptionContext();
111	1	}
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	15	super(cause);
122	15	exceptionContext = new DefaultExceptionContext();
123	15	}
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	1	super(message, cause);
135	1	exceptionContext = new DefaultExceptionContext();
136	1	}
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	4	super(message, cause);
147	4	if (context == null) {
148	1	context = new DefaultExceptionContext();
149		}
150	4	exceptionContext = context;
151	4	}
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	81	exceptionContext.addContextValue(label, value);
170	81	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	6	exceptionContext.setContextValue(label, value);
189	6	return this;
190		}
191
192		/**
193		* {@inheritDoc}
194		*/
195		@Override
196		public List<Object> getContextValues(final String label) {
197	2	return this.exceptionContext.getContextValues(label);
198		}
199
200		/**
201		* {@inheritDoc}
202		*/
203		@Override
204		public Object getFirstContextValue(final String label) {
205	9	return this.exceptionContext.getFirstContextValue(label);
206		}
207
208		/**
209		* {@inheritDoc}
210		*/
211		@Override
212		public List<Pair<String, Object>> getContextEntries() {
213	7	return this.exceptionContext.getContextEntries();
214		}
215
216		/**
217		* {@inheritDoc}
218		*/
219		@Override
220		public Set<String> getContextLabels() {
221	13	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	11	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	3	return super.getMessage();
244		}
245
246		/**
247		* {@inheritDoc}
248		*/
249		@Override
250		public String getFormattedExceptionMessage(final String baseMessage) {
251	17	return exceptionContext.getFormattedExceptionMessage(baseMessage);
252		}
253		}