KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > logicalcobwebs > proxool > ProxoolException


1 /*
2  * This software is released under a licence similar to the Apache Software Licence.
3  * See org.logicalcobwebs.proxool.package.html for details.
4  * The latest version is available at http://proxool.sourceforge.net
5  */

6 package org.logicalcobwebs.proxool;
7
8 import java.io.PrintStream JavaDoc;
9 import java.io.PrintWriter JavaDoc;
10
11 /**
12   * Proxool exception class that emulates the behaviour of the new cause
13   * facility in jdk 1.4. It is also known as the <i>chained
14   * exception</i> facility, as the cause can, itself, have a cause, and so on,
15   * leading to a "chain" of exceptions, each caused by another.
16   *
17   * <p>A cause can be associated with a throwable in two ways: via a
18   * constructor that takes the cause as an argument, or via the
19   * {@link #initCause(Throwable)} method. New throwable classes that
20   * wish to allow causes to be associated with them should provide constructors
21   * that take a cause and delegate (perhaps indirectly) to one of the
22   * <tt>Throwable</tt> constructors that takes a cause.
23   *
24  * @version $Revision: 1.2 $, $Date: 2003/03/03 11:11:58 $
25  * @author Christian Nedregaard (christian_nedregaard@email.com)
26  * @author $Author: billhorsman $ (current maintainer)
27  * @since Proxool 0.6
28  */

29 public class ProxoolException extends Exception JavaDoc {
30     /**
31      * The throwable that caused this ProxoolException to get thrown, or null if this
32      * ProxoolException was not caused by another throwable, or if the causative
33      * throwable is unknown.
34      */

35     private Throwable JavaDoc cause = this;
36
37     /**
38      * Constructs a new instance with <code>null</code> as its detail message.
39      * The cause is not initialized, and may subsequently be initialized by a
40      * call to {@link #initCause}.
41      */

42     public ProxoolException() {
43         super();
44     }
45
46     /**
47      * Constructs a new instance with the specified detail message. The
48      * cause is not initialized, and may subsequently be initialized by
49      * a call to {@link #initCause}.
50      *
51      * @param message the detail message. The detail message is saved for
52      * later retrieval by the {@link #getMessage()} method.
53      */

54     public ProxoolException(String JavaDoc message) {
55         super(message);
56     }
57
58     /**
59      * Constructs a new instance with the specified detail message and cause.
60      *
61      * <p>Note that the detail message associated with
62      * <code>cause</code> is <i>not</i> automatically incorporated in
63      * this throwable's detail message.
64      *
65      * @param message the detail message (which is saved for later retrieval
66      * by the {@link #getMessage()} method).
67      * @param cause the cause (which is saved for later retrieval by the
68      * {@link #getCause()} method). (A <tt>null</tt> value is
69      * permitted, and indicates that the cause is nonexistent or
70      * unknown.)
71      */

72     public ProxoolException(String JavaDoc message, Throwable JavaDoc cause) {
73         this(message);
74         this.cause = cause;
75     }
76
77     /**
78      * Constructs a new throwable with the specified cause and a detail
79      * message of <tt>(cause==null ? null : cause.toString())</tt> (which
80      * typically contains the class and detail message of <tt>cause</tt>).
81      * This constructor is useful for throwables that are little more than
82      * wrappers for other throwables.
83      *
84      * @param cause the cause (which is saved for later retrieval by the
85      * {@link #getCause()} method). (A <tt>null</tt> value is
86      * permitted, and indicates that the cause is nonexistent or
87      * unknown.)
88      */

89     public ProxoolException(Throwable JavaDoc cause) {
90         this(cause == null ? null : cause.toString());
91         this.cause = cause;
92     }
93
94     /**
95      * Returns the cause of this exception or <code>null</code> if the
96      * cause is nonexistent or unknown. (The cause is the throwable that
97      * caused this exception to get thrown.)
98      *
99      * <p>This implementation returns the cause that was supplied via one of
100      * the constructors requiring a <tt>Throwable</tt>, or that was set after
101      * creation with the {@link #initCause(Throwable)} method.
102      *
103      * @return the cause of this throwable or <code>null</code> if the
104      * cause is nonexistent or unknown.
105      */

106     public Throwable JavaDoc getCause() {
107         return (cause == this ? null : cause);
108     }
109
110     /**
111      * Initializes the <i>cause</i> of this exception to the specified value.
112      * (The cause is the throwable that caused this exception to get thrown.)
113      *
114      * <p>This method can be called at most once. It is generally called from
115      * within the constructor, or immediately after creating the
116      * throwable. If this throwable was created
117      * with {@link #ProxoolException(Throwable)} or
118      * {@link #ProxoolException(String,Throwable)}, this method cannot be called
119      * even once.
120      *
121      * @param cause the cause (which is saved for later retrieval by the
122      * {@link #getCause()} method). (A <tt>null</tt> value is
123      * permitted, and indicates that the cause is nonexistent or
124      * unknown.)
125      * @return a reference to this <code>ProxoolException</code> instance.
126      */

127     public synchronized Throwable JavaDoc initCause(Throwable JavaDoc cause) {
128         if (this.cause != this) {
129             throw new IllegalStateException JavaDoc("Can't overwrite cause");
130         }
131         if (cause == this) {
132             throw new IllegalArgumentException JavaDoc("Self-causation not permitted");
133         }
134         this.cause = cause;
135         return this;
136     }
137
138     /**
139      * Prints this ProxoolException and its backtrace to the
140      * standard error stream.
141      *
142      * The backtrace for a ProxoolException with an initialized, non-null cause
143      * should generally include the backtrace for the cause.
144      */

145     public void printStackTrace() {
146         printStackTrace(System.err);
147     }
148
149     /**
150      * Prints this ProxoolException and its backtrace to the specified print stream.
151      *
152      * @param stream <code>PrintStream</code> to use for output
153      */

154     public void printStackTrace(PrintStream JavaDoc stream) {
155         synchronized (stream) {
156             super.printStackTrace(stream);
157             Throwable JavaDoc ourCause = getCause();
158             if (ourCause != null) {
159                 stream.println();
160                 stream.println("Caused by:");
161                 ourCause.printStackTrace(stream);
162             }
163         }
164     }
165
166     /**
167      * Prints this ProxoolException and its backtrace to the specified
168      * print writer.
169      *
170      * @param writer <code>PrintWriter</code> to use for output
171      */

172     public void printStackTrace(PrintWriter JavaDoc writer) {
173         synchronized (writer) {
174             super.printStackTrace(writer);
175             Throwable JavaDoc ourCause = getCause();
176             if (ourCause != null) {
177                 writer.println();
178                 writer.println("Caused by:");
179                 ourCause.printStackTrace(writer);
180             }
181         }
182     }
183
184 }
185
Popular Tags