1 package org.apache.turbine.util; 2 3 4 /* 5 * Licensed to the Apache Software Foundation (ASF) under one 6 * or more contributor license agreements. See the NOTICE file 7 * distributed with this work for additional information 8 * regarding copyright ownership. The ASF licenses this file 9 * to you under the Apache License, Version 2.0 (the 10 * "License"); you may not use this file except in compliance 11 * with the License. You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, 16 * software distributed under the License is distributed on an 17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 18 * KIND, either express or implied. See the License for the 19 * specific language governing permissions and limitations 20 * under the License. 21 */ 22 23 24 /** 25 * The base class of all exceptions thrown by Turbine. 26 * 27 * <p> 28 * It is intended to ease the debugging by carrying on the information 29 * about the exception which was caught and provoked throwing the 30 * current exception. Catching and rethrowing may occur multiple 31 * times, and provided that all exceptions except the first one 32 * are descendands of <code>TurbineException</code>, when the 33 * exception is finally printed out using any of the <code> 34 * printStackTrace()</code> methods, the stacktrace will contain 35 * the information about all exceptions thrown and caught on the way. 36 * </p> 37 * 38 * <p> Running the following program </p> 39 * 40 * <pre> 41 * 1 import org.apache.turbine.util.TurbineException; 42 * 2 43 * 3 public class Test { 44 * 4 public static void main( String[] args ) { 45 * 5 try { 46 * 6 a(); 47 * 7 } catch(Exception e) { 48 * 8 e.printStackTrace(); 49 * 9 } 50 * 10 } 51 * 11 52 * 12 public static void a() throws TurbineException { 53 * 13 try { 54 * 14 b(); 55 * 15 } catch(Exception e) { 56 * 16 throw new TurbineException("foo", e); 57 * 17 } 58 * 18 } 59 * 19 60 * 20 public static void b() throws TurbineException { 61 * 21 try { 62 * 22 c(); 63 * 23 } catch(Exception e) { 64 * 24 throw new TurbineException("bar", e); 65 * 25 } 66 * 26 } 67 * 27 68 * 28 public static void c() throws TurbineException { 69 * 29 throw new Exception("baz"); 70 * 30 } 71 * 31 } 72 * </pre> 73 * 74 * <p>Yields the following stacktrace: </p> 75 * 76 * <pre> 77 * java.lang.Exception: baz: bar: foo 78 * at Test.c(Test.java:29) 79 * at Test.b(Test.java:22) 80 * rethrown as TurbineException: bar 81 * at Test.b(Test.java:24) 82 * at Test.a(Test.java:14) 83 * rethrown as TurbineException: foo 84 * at Test.a(Test.java:16) 85 * at Test.main(Test.java:6) 86 * </pre> 87 * 88 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a> 89 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a> 90 * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a> 91 */ 92 public class TurbineException extends Exception 93 { 94 /** Serial version */ 95 private static final long serialVersionUID = 6287570348053189763L; 96 97 /** 98 * Constructs a new <code>TurbineException</code> without specified 99 * detail message. 100 */ 101 public TurbineException() 102 { 103 super(); 104 } 105 106 /** 107 * Constructs a new <code>TurbineException</code> with specified 108 * detail message. 109 * 110 * @param msg The error message. 111 */ 112 public TurbineException(String msg) 113 { 114 super(msg); 115 } 116 117 /** 118 * Constructs a new <code>TurbineException</code> with specified 119 * nested <code>Throwable</code>. 120 * 121 * @param nested The exception or error that caused this exception 122 * to be thrown. 123 */ 124 public TurbineException(Throwable nested) 125 { 126 super(nested); 127 } 128 129 /** 130 * Constructs a new <code>TurbineException</code> with specified 131 * detail message and nested <code>Throwable</code>. 132 * 133 * @param msg The error message. 134 * @param nested The exception or error that caused this exception 135 * to be thrown. 136 */ 137 public TurbineException(String msg, Throwable nested) 138 { 139 super(msg, nested); 140 } 141 }