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}