View Javadoc

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