View Javadoc

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