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
 
 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  82
 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  1
         super();
 101  1
         exceptionContext = new DefaultExceptionContext();
 102  1
     }
 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  1
         super(message);
 113  1
         exceptionContext = new DefaultExceptionContext();
 114  1
     }
 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  15
         super(cause);
 125  15
         exceptionContext = new DefaultExceptionContext();
 126  15
     }
 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  1
         super(message, cause);
 138  1
         exceptionContext = new DefaultExceptionContext();
 139  1
     }
 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  4
         super(message, cause);
 150  4
         if (context == null) {
 151  1
             context = new DefaultExceptionContext();
 152  
         }
 153  4
         exceptionContext = context;
 154  4
     }
 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  81
         exceptionContext.addContextValue(label, value);
 173  81
         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  6
         exceptionContext.setContextValue(label, value);
 192  6
         return this;
 193  
     }
 194  
 
 195  
     /**
 196  
      * {@inheritDoc}
 197  
      */
 198  
     @Override
 199  
     public List<Object> getContextValues(final String label) {
 200  2
         return this.exceptionContext.getContextValues(label);
 201  
     }
 202  
 
 203  
     /**
 204  
      * {@inheritDoc}
 205  
      */
 206  
     @Override
 207  
     public Object getFirstContextValue(final String label) {
 208  9
         return this.exceptionContext.getFirstContextValue(label);
 209  
     }
 210  
 
 211  
     /**
 212  
      * {@inheritDoc}
 213  
      */
 214  
     @Override
 215  
     public List<Pair<String, Object>> getContextEntries() {
 216  7
         return this.exceptionContext.getContextEntries();
 217  
     }
 218  
 
 219  
     /**
 220  
      * {@inheritDoc}
 221  
      */
 222  
     @Override
 223  
     public Set<String> getContextLabels() {
 224  13
         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  11
         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  3
         return super.getMessage();
 247  
     }
 248  
 
 249  
     /**
 250  
      * {@inheritDoc}
 251  
      */
 252  
     @Override
 253  
     public String getFormattedExceptionMessage(final String baseMessage) {
 254  17
         return exceptionContext.getFormattedExceptionMessage(baseMessage);
 255  
     }
 256  
 }