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  ;
9   import java.io.PrintWriter  ;
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   {
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   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   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   message, Throwable   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   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   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   initCause(Throwable   cause) {
128         if (this.cause != this) {
129             throw new IllegalStateException  ("Can't overwrite cause");
130         }
131         if (cause == this) {
132             throw new IllegalArgumentException  ("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   stream) {
155         synchronized (stream) {
156             super.printStackTrace(stream);
157             Throwable   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   writer) {
173         synchronized (writer) {
174             super.printStackTrace(writer);
175             Throwable   ourCause = getCause();
176             if (ourCause != null) {
177                 writer.println();
178                 writer.println("Caused by:");
179                 ourCause.printStackTrace(writer);
180             }
181         }
182     }
183 
184 }
185
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags