    001package org.apache.turbine.util;
    002
    003
    004/*
    005 * Licensed to the Apache Software Foundation (ASF) under one
    006 * or more contributor license agreements.  See the NOTICE file
    007 * distributed with this work for additional information
    008 * regarding copyright ownership.  The ASF licenses this file
    009 * to you under the Apache License, Version 2.0 (the
    010 * "License"); you may not use this file except in compliance
    011 * with the License.  You may obtain a copy of the License at
    012 *
    013 *   http://www.apache.org/licenses/LICENSE-2.0
    014 *
    015 * Unless required by applicable law or agreed to in writing,
    016 * software distributed under the License is distributed on an
    017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    018 * KIND, either express or implied.  See the License for the
    019 * specific language governing permissions and limitations
    020 * under the License.
    021 */
    022
    023
    024/**
    025 * The base class of all exceptions thrown by Turbine.
    026 *
    027 * It is intended to ease the debugging by carrying on the information
    028 * about the exception which was caught and provoked throwing the
    029 * current exception. Catching and rethrowing may occur multiple
    030 * times, and provided that all exceptions except the first one
    031 * are descendands of <code>TurbineException</code>, when the
    032 * exception is finally printed out using any of the <code>
    033 * printStackTrace()</code> methods, the stacktrace will contain
    034 * the information about all exceptions thrown and caught on
    035 * the way.
    036 * <p> Running the following program
    037 * <p><blockquote><pre>
    038 *  1 import org.apache.turbine.util.TurbineException;
    039 *  2
    040 *  3 public class Test {
    041 *  4     public static void main( String[] args ) {
    042 *  5         try {
    043 *  6             a();
    044 *  7         } catch(Exception e) {
    045 *  8             e.printStackTrace();
    046 *  9         }
    047 * 10      }
    048 * 11
    049 * 12      public static void a() throws TurbineException {
    050 * 13          try {
    051 * 14              b();
    052 * 15          } catch(Exception e) {
    053 * 16              throw new TurbineException("foo", e);
    054 * 17          }
    055 * 18      }
    056 * 19
    057 * 20      public static void b() throws TurbineException {
    058 * 21          try {
    059 * 22              c();
    060 * 23          } catch(Exception e) {
    061 * 24              throw new TurbineException("bar", e);
    062 * 25          }
    063 * 26      }
    064 * 27
    065 * 28      public static void c() throws TurbineException {
    066 * 29          throw new Exception("baz");
    067 * 30      }
    068 * 31 }
    069 * </pre></blockquote>
    070 * <p>Yields the following stacktrace:
    071 * <p><blockquote><pre>
    072 * java.lang.Exception: baz: bar: foo
    073 *    at Test.c(Test.java:29)
    074 *    at Test.b(Test.java:22)
    075 * rethrown as TurbineException: bar
    076 *    at Test.b(Test.java:24)
    077 *    at Test.a(Test.java:14)
    078 * rethrown as TurbineException: foo
    079 *    at Test.a(Test.java:16)
    080 *    at Test.main(Test.java:6)
    081 * </pre></blockquote><br>
    082 *
    083 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
    084 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
    085 * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
    086 */
    087public class TurbineException extends Exception
    088{
    089    /** Serial version */
    090    private static final long serialVersionUID = 6287570348053189763L;
    091
    092    /**
    093     * Constructs a new <code>TurbineException</code> without specified
    094     * detail message.
    095     */
    096    public TurbineException()
    097    {
    098        super();
    099    }
    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}