KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > lang > exception > NestableException


1 /*
2  * Copyright 2002-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.lang.exception;
17
18 import java.io.PrintStream JavaDoc;
19 import java.io.PrintWriter JavaDoc;
20
21 /**
22  * The base class of all exceptions which can contain other exceptions.
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 descendants of <code>NestedException</code>, when the
29  * exception is finally printed out using any of the <code>
30  * printStackTrace()</code> methods, the stack trace 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.commons.lang.exception.NestableException;
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 Exception {
47  * 13 try {
48  * 14 b();
49  * 15 } catch(Exception e) {
50  * 16 throw new NestableException("foo", e);
51  * 17 }
52  * 18 }
53  * 19
54  * 20 public static void b() throws Exception {
55  * 21 try {
56  * 22 c();
57  * 23 } catch(Exception e) {
58  * 24 throw new NestableException("bar", e);
59  * 25 }
60  * 26 }
61  * 27
62  * 28 public static void c() throws Exception {
63  * 29 throw new Exception("baz");
64  * 30 }
65  * 31 }
66  * </pre></blockquote>
67  * <p>Yields the following stack trace:
68  * <p><blockquote><pre>
69  * org.apache.commons.lang.exception.NestableException: foo
70  * at Test.a(Test.java:16)
71  * at Test.main(Test.java:6)
72  * Caused by: org.apache.commons.lang.exception.NestableException: bar
73  * at Test.b(Test.java:24)
74  * at Test.a(Test.java:14)
75  * ... 1 more
76  * Caused by: java.lang.Exception: baz
77  * at Test.c(Test.java:29)
78  * at Test.b(Test.java:22)
79  * ... 2 more
80  * </pre></blockquote><br>
81  *
82  * @author <a HREF="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
83  * @author <a HREF="mailto:dlr@collab.net">Daniel Rall</a>
84  * @author <a HREF="mailto:knielsen@apache.org">Kasper Nielsen</a>
85  * @author <a HREF="mailto:steven@caswell.name">Steven Caswell</a>
86  * @since 1.0
87  * @version $Id: NestableException.java 161243 2005-04-14 04:30:28Z ggregory $
88  */
89 public class NestableException extends Exception JavaDoc implements Nestable {
90     
91     /**
92      * The helper instance which contains much of the code which we
93      * delegate to.
94      */
95     protected NestableDelegate delegate = new NestableDelegate(this);
96
97     /**
98      * Holds the reference to the exception or error that caused
99      * this exception to be thrown.
100      */
101     private Throwable JavaDoc cause = null;
102
103     /**
104      * Constructs a new <code>NestableException</code> without specified
105      * detail message.
106      */
107     public NestableException() {
108         super();
109     }
110
111     /**
112      * Constructs a new <code>NestableException</code> with specified
113      * detail message.
114      *
115      * @param msg The error message.
116      */
117     public NestableException(String JavaDoc msg) {
118         super(msg);
119     }
120
121     /**
122      * Constructs a new <code>NestableException</code> with specified
123      * nested <code>Throwable</code>.
124      *
125      * @param cause the exception or error that caused this exception to be
126      * thrown
127      */
128     public NestableException(Throwable JavaDoc cause) {
129         super();
130         this.cause = cause;
131     }
132
133     /**
134      * Constructs a new <code>NestableException</code> with specified
135      * detail message and nested <code>Throwable</code>.
136      *
137      * @param msg the error message
138      * @param cause the exception or error that caused this exception to be
139      * thrown
140      */
141     public NestableException(String JavaDoc msg, Throwable JavaDoc cause) {
142         super(msg);
143         this.cause = cause;
144     }
145
146     public Throwable JavaDoc getCause() {
147         return cause;
148     }
149
150     /**
151      * Returns the detail message string of this throwable. If it was
152      * created with a null message, returns the following:
153      * (cause==null ? null : cause.toString()).
154      *
155      * @return String message string of the throwable
156      */
157     public String JavaDoc getMessage() {
158         if (super.getMessage() != null) {
159             return super.getMessage();
160         } else if (cause != null) {
161             return cause.toString();
162         } else {
163             return null;
164         }
165     }
166
167     public String JavaDoc getMessage(int index) {
168         if (index == 0) {
169             return super.getMessage();
170         } else {
171             return delegate.getMessage(index);
172         }
173     }
174
175     public String JavaDoc[] getMessages() {
176         return delegate.getMessages();
177     }
178
179     public Throwable JavaDoc getThrowable(int index) {
180         return delegate.getThrowable(index);
181     }
182
183     public int getThrowableCount() {
184         return delegate.getThrowableCount();
185     }
186
187     public Throwable JavaDoc[] getThrowables() {
188         return delegate.getThrowables();
189     }
190
191     public int indexOfThrowable(Class JavaDoc type) {
192         return delegate.indexOfThrowable(type, 0);
193     }
194
195     public int indexOfThrowable(Class JavaDoc type, int fromIndex) {
196         return delegate.indexOfThrowable(type, fromIndex);
197     }
198
199     public void printStackTrace() {
200         delegate.printStackTrace();
201     }
202
203     public void printStackTrace(PrintStream JavaDoc out) {
204         delegate.printStackTrace(out);
205     }
206
207     public void printStackTrace(PrintWriter JavaDoc out) {
208         delegate.printStackTrace(out);
209     }
210
211     public final void printPartialStackTrace(PrintWriter JavaDoc out) {
212         super.printStackTrace(out);
213     }
214
215 }
216
Popular Tags