View Javadoc

1   package org.apache.turbine.util;
2   
3   /*
4    * Copyright 2001-2005 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 278822 2005-09-05 19:53:05Z henning $
84   */
85  public class TurbineException extends NestableException
86  {
87      /*** Serial Version UID */
88      private static final long serialVersionUID = -2978139489274739700L;
89  
90      /***
91       * Constructs a new <code>TurbineException</code> without specified
92       * detail message.
93       */
94      public TurbineException()
95      {
96      }
97  
98      /***
99       * Constructs a new <code>TurbineException</code> with specified
100      * detail message.
101      *
102      * @param msg The error message.
103      */
104     public TurbineException(String msg)
105     {
106         super(msg);
107     }
108 
109     /***
110      * Constructs a new <code>TurbineException</code> with specified
111      * nested <code>Throwable</code>.
112      *
113      * @param nested The exception or error that caused this exception
114      *               to be thrown.
115      */
116     public TurbineException(Throwable nested)
117     {
118         super(nested);
119     }
120 
121     /***
122      * Constructs a new <code>TurbineException</code> with specified
123      * detail message and nested <code>Throwable</code>.
124      *
125      * @param msg    The error message.
126      * @param nested The exception or error that caused this exception
127      *               to be thrown.
128      */
129     public TurbineException(String msg, Throwable nested)
130     {
131         super(msg, nested);
132     }
133 }