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> 052 * <p> 053 * or improve diagnose data at a higher level: 054 * </p> 055 * <pre> 056 * try { 057 * ... 058 * } catch (ContextedException 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.ContextedException: 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.ContextedExceptionTest.testAddValue(ContextedExceptionTest.java:88) 081 * ..... (rest of trace) 082 * </pre> 083 * 084 * @see ContextedRuntimeException 085 * @since 3.0 086 */ 087public class ContextedException extends Exception 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 ContextedException without message or cause. 096 * <p> 097 * The context information is stored using a default implementation. 098 */ 099 public ContextedException() { 100 exceptionContext = new DefaultExceptionContext(); 101 } 102 103 /** 104 * Instantiates ContextedException with message, but without cause. 105 * <p> 106 * The context information is stored using a default implementation. 107 * 108 * @param message the exception message, may be null 109 */ 110 public ContextedException(final String message) { 111 super(message); 112 exceptionContext = new DefaultExceptionContext(); 113 } 114 115 /** 116 * Instantiates ContextedException with cause, but without message. 117 * <p> 118 * The context information is stored using a default implementation. 119 * 120 * @param cause the underlying cause of the exception, may be null 121 */ 122 public ContextedException(final Throwable cause) { 123 super(cause); 124 exceptionContext = new DefaultExceptionContext(); 125 } 126 127 /** 128 * Instantiates ContextedException with cause and message. 129 * <p> 130 * The context information is stored using a default implementation. 131 * 132 * @param message the exception message, may be null 133 * @param cause the underlying cause of the exception, may be null 134 */ 135 public ContextedException(final String message, final Throwable cause) { 136 super(message, cause); 137 exceptionContext = new DefaultExceptionContext(); 138 } 139 140 /** 141 * Instantiates ContextedException with cause, message, and ExceptionContext. 142 * 143 * @param message the exception message, may be null 144 * @param cause the underlying cause of the exception, may be null 145 * @param context the context used to store the additional information, null uses default implementation 146 */ 147 public ContextedException(final String message, final Throwable cause, ExceptionContext context) { 148 super(message, cause); 149 if (context == null) { 150 context = new DefaultExceptionContext(); 151 } 152 exceptionContext = context; 153 } 154 155 //----------------------------------------------------------------------- 156 /** 157 * Adds information helpful to a developer in diagnosing and correcting the problem. 158 * For the information to be meaningful, the value passed should have a reasonable 159 * toString() implementation. 160 * Different values can be added with the same label multiple times. 161 * <p> 162 * Note: This exception is only serializable if the object added is serializable. 163 * </p> 164 * 165 * @param label a textual label associated with information, {@code null} not recommended 166 * @param value information needed to understand exception, may be {@code null} 167 * @return {@code this}, for method chaining, not {@code null} 168 */ 169 @Override 170 public ContextedException addContextValue(final String label, final Object value) { 171 exceptionContext.addContextValue(label, value); 172 return this; 173 } 174 175 /** 176 * Sets information helpful to a developer in diagnosing and correcting the problem. 177 * For the information to be meaningful, the value passed should have a reasonable 178 * toString() implementation. 179 * Any existing values with the same labels are removed before the new one is added. 180 * <p> 181 * Note: This exception is only serializable if the object added as value is serializable. 182 * </p> 183 * 184 * @param label a textual label associated with information, {@code null} not recommended 185 * @param value information needed to understand exception, may be {@code null} 186 * @return {@code this}, for method chaining, not {@code null} 187 */ 188 @Override 189 public ContextedException setContextValue(final String label, final Object value) { 190 exceptionContext.setContextValue(label, value); 191 return this; 192 } 193 194 /** 195 * {@inheritDoc} 196 */ 197 @Override 198 public List<Object> getContextValues(final String label) { 199 return this.exceptionContext.getContextValues(label); 200 } 201 202 /** 203 * {@inheritDoc} 204 */ 205 @Override 206 public Object getFirstContextValue(final String label) { 207 return this.exceptionContext.getFirstContextValue(label); 208 } 209 210 /** 211 * {@inheritDoc} 212 */ 213 @Override 214 public List<Pair<String, Object>> getContextEntries() { 215 return this.exceptionContext.getContextEntries(); 216 } 217 218 /** 219 * {@inheritDoc} 220 */ 221 @Override 222 public Set<String> getContextLabels() { 223 return exceptionContext.getContextLabels(); 224 } 225 226 /** 227 * Provides the message explaining the exception, including the contextual data. 228 * 229 * @see java.lang.Throwable#getMessage() 230 * @return the message, never null 231 */ 232 @Override 233 public String getMessage() { 234 return getFormattedExceptionMessage(super.getMessage()); 235 } 236 237 /** 238 * Provides the message explaining the exception without the contextual data. 239 * 240 * @see java.lang.Throwable#getMessage() 241 * @return the message 242 * @since 3.0.1 243 */ 244 public String getRawMessage() { 245 return super.getMessage(); 246 } 247 248 /** 249 * {@inheritDoc} 250 */ 251 @Override 252 public String getFormattedExceptionMessage(final String baseMessage) { 253 return exceptionContext.getFormattedExceptionMessage(baseMessage); 254 } 255}