KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > susebox > java > lang > ThrowableList


1 /*
2  * ThrowableList.java: Interface for throwable stacks
3  *
4  * Copyright (C) 2002 Heiko Blau
5  *
6  * This file belongs to the Susebox Java Core Library (Susebox JCL).
7  * The Susebox JCL is free software; you can redistribute it and/or modify it
8  * under the terms of the GNU Lesser General Public License as published by the
9  * Free Software Foundation; either version 2.1 of the License, or (at your
10  * option) any later version.
11  *
12  * This software is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE.
15  * See the GNU Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public License along
18  * with the Susebox JCL. If not, write to the
19  *
20  * Free Software Foundation, Inc.
21  * 59 Temple Place, Suite 330,
22  * Boston, MA 02111-1307
23  * USA
24  *
25  * or check the Internet: http://www.fsf.org
26  *
27  * Contact:
28  * email: heiko@susebox.de
29  */
30
31 package de.susebox.java.lang;
32
33 //------------------------------------------------------------------------------
34 // Imports
35 //
36
37 /*-->
38 import de.susebox.java.lang.ThrowableList;
39 import de.susebox.java.lang.ThrowableMessageFormatter;
40 -->*/
41
42
43 //------------------------------------------------------------------------------
44 // Interface ThrowableList
45 //
46
47 /**<p>
48  * This interface should be implemented by classes derived from {@link java.lang.Throwable}
49  * that may contain a stacked, additional or wrapped throwable.
50  *</p><p>
51  * Such cases are common when
52  *<ul><li>
53  * a method implements a certain interface method that allows for a specific
54  * throwable like IOException, but the method itself may encounter a different
55  * throwable type like SQLException (wrapped throwable)
56  *</li><li>
57  * one application layer catches an throwable only to add its specific
58  * information in form of another throwable (throwable stack, nested throwable
59  * like in SQLException or MessagingException).
60  *</li></ul>
61  *</p><p>
62  * We provide the expected code in block comments starting with --&gt;, terminated
63  * by --&gt;. Note that the provided code also includes a new implementation of
64  * the base class method {@link java.lang.Throwable#getMessage} using the text
65  * formatting capabilities of {@link java.text.MessageFormat}.
66  *<p></p>
67  * <strong>Note:</strong> This interface replaces the formerly used <code>ExceptionList</code>
68  * interface.
69  *<p></p>
70  * <strong>Note:</strong> With JDK 1.4, the <i>chained exception facility</i>
71  * is available, that implements a Throwable stack (or list of causes) already
72  * in {@link java.lang.Throwable}. Still, the notion of a wrapped exception and
73  * the delayed formatting is a reason for this interface.
74  *</p>
75  *
76  * @version 1.00, 2001/06/26
77  * @author Heiko Blau
78  */
79 public interface ThrowableList {
80   
81   /**
82    * Retrieving the cause of a <code>Throwable</code>. This is the method introduced
83    * with JDK 1.4. It replaces the older {@link #nextThrowable}.
84    *
85    * @return the cause of this <code>Throwable</code>
86    * @see java.lang.Throwable#getCause
87    */
88   public Throwable JavaDoc getCause();
89   
90   /**
91    * Method to traverse the throwable list. By convention, <code>nextThrowable</code>>
92    * returns the "earlier" throwable. By walking down the throwable list one gets the
93    * the following meaning:
94    *<br>
95    * this happened because nextThrowable happened because nextThrowable happened...
96    *<br>
97    * The next throwable has usually one of the following meaning:
98    *<br><ul><li>
99    * It is the "real" throwable. An interface implementation might be allowed to
100    * throw only <code>IOException</code>, but actually has to pass on a
101    * <code>SQLException</code>. That could be done by wrapping the <code>SQLException</code>
102    * into the <code>IOException</code>.
103    *</li><li>
104    * The next throwable is "deeper" cause of this one (often called a nested
105    * throwable). A file couldn't be read in the first place and therefore not be
106    * attached to a mail. Both this throwable and the one nested inside have their
107    * own message.
108    *</li></li>
109    * There are more than one basic throwable to be propagated. A simple parser
110    * might return all syntax errors in one throwable list.
111    *</li></ul>
112    *
113    * @return the "earlier" throwable
114    * @deprecated use the JDK 1.4 call {@link #getCause} instead
115    */
116   public Throwable JavaDoc nextThrowable();
117   /*-->
118   {
119     return _next;
120   }
121   -->*/
122   
123   
124   /**
125    * Check if <code>this</code> is only a throwable that wraps the real one. This
126    * might be nessecary to pass an throwable incompatible to a method declaration.
127    *
128    * @return <code>true</code> if this is a wrapper throwable,
129    * <code>false</code> otherwise
130    */
131   public boolean isWrapper();
132   /*-->
133   {
134     return _isWrapper;
135   }
136   -->*/
137   
138   /**
139    * Getting the format string of a throwable message. This can also be the
140    * message itself if there are no arguments.
141    *
142    * @return the format string being used by {@link java.text.MessageFormat}
143    * @see #getArguments
144    */
145   public String JavaDoc getFormat();
146   /*-->
147   {
148     return super.getMessage();
149   }
150   -->*/
151   
152   /**
153    * Retrieving the arguments for message formats. These arguments are used by
154    * the {@link java.text.MessageFormat#format} call.
155    *
156    * @return the arguments for a message format
157    * @see #getFormat
158    */
159   public Object JavaDoc[] getArguments();
160   /*-->
161   {
162     return _args;
163   }
164   -->*/
165   
166   
167   //---------------------------------------------------------------------------
168 // implementation code templates
169 //
170
171   /**
172    * This constructor takes a simple message string like ordinary Java
173    * {@link java.lang.Throwable} classes. This is the most convenient form to
174    * construct an <code>ThrowableList</code> throwable.
175    *
176    * @param msg message for this <code>Throwable</code> instance
177    */
178   /*-->
179   public <<WHICH>>Throwable(String msg) {
180     this(null, msg, null);
181   }
182   -->*/
183   
184   /**
185    * This constructor should be used for wrapping another {@link java.lang.Throwable}.
186    * While reading data an <code>IOException</code> may occur, but a certain interface
187    * requires a <code>SQLException</code>. Simply use:
188    *<blockquote><pre>
189    * try {
190    * ...
191    * } catch (NullPointerException ex) {
192    * throw new ExtNoSuchMethodException(ex);
193    * }
194    *</pre></blockquote>
195    *
196    * @param trowable the <code>Throwable</code> to wrap
197    */
198   /*-->
199   public <<WHICH>>Throwable(Throwable throwable) {
200     this(throwable, null, null);
201   }
202   -->*/
203   
204   /**
205    * If one likes to add ones own information to an throwable, this constructor is
206    * the easiest way to do so. By using such an approach a throwable trace with useful
207    * additional informations (which file could be found, what username is unknown)
208    * can be realized:
209    *<blockquote><pre>
210    * try {
211    * ...
212    * } catch (SQLException ex) {
213    * throw new MyException(ex, "while connecting to " + url);
214    * }
215    *</pre></blockquote>
216    *
217    * @param throwable the inner throwable
218    * @param msg throwable message
219    */
220   /*-->
221   public <<WHICH>>Throwable(Throwable throwable, String msg) {
222     this(throwable, msg, null);
223   }
224   -->*/
225   
226   /**
227    * This constructor takes a format string and its arguments. The format string
228    * must have a form that can be used by {@link java.text.MessageFormat} methods.
229    * That means:
230    *<blockquote><pre>
231    * java.text.Message.format(fmt, args)
232    *</pre></blockquote>
233    * is similar to
234    *<blockquote><pre>
235    * new MyException(fmt, args).getMessage();
236    *</pre></blockquote>
237    *
238    * @param fmt throwable message format
239    * @param args arguments for the given format string
240    */
241   /*-->
242   public <<WHICH>>Throwable(String fmt, Object[] args) {
243     this(null, msg, args);
244   }
245   -->*/
246   
247   /**
248    * This is the most complex way to construct an <code>ThrowableList</code>-
249    * Throwable.<br>
250    * An inner throwable is accompanied by a format string and its arguments.
251    * Use this constructor in language-sensitive contexts or for formalized messages.
252    * The meaning of the parameters is explained in the other constructors.
253    *
254    * @param throwable the inner throwable
255    * @param fmt throwable message
256    * @param args arguments for the given format string
257    */
258   /*-->
259   public <<WHICH>>Throwable(Throwable throwable, String fmt, Object[] args) {
260     super(fmt);
261    
262     if (throwable != null && fmt == null) {
263       _isWrapper = true;
264     } else {
265       _isWrapper = false;
266     }
267     _next = throwable;
268     _args = args;
269   }
270   -->
271    
272   /**
273    * Implementation of the standard {@link java.lang.Throwable#getMessage} method to
274    * meet the requirements of formats and format arguments as well as wrapper
275    * exceptions.<br>
276    * If this is a wrapper throwable then the <code>getMessage</code> of the wrapped
277    * throwable is returned.<br>
278    * If this is not a wrapper throwable: if no arguments were given in the
279    * constructor then the format parameter is taken as the formatted message itself.
280    * Otherwise it is treated like the patter for the {@link java.text.MessageFormat#format}
281    * method.
282    *
283    * @return the formatted throwable message
284    * @see java.text.MessageFormat
285    */
286   /*-->
287   public String getMessage() {
288     return ThrowableMessageFormatter.getMessage(this);
289   }
290   -->*/
291   
292   
293   //---------------------------------------------------------------------------
294 // members
295 //
296 /**
297    * the parameters to be used when formatting the throwable message
298    */
299   /*-->
300   protected Object[] _args = null;
301   -->*/
302   
303   /**
304    * The wrapped, nested of next throwable.
305    */
306   /*-->
307   protected Throwable _next = null;
308   -->*/
309
310   /**
311    * If <code>true</code> this is only a wrapper throwable with the real one
312    * being returned by {@link #nextThrowable}, <code>false</code> for standalone,
313    * nested or subsequent exceptions
314    */
315   /*-->
316   protected boolean _isWrapper = false;
317   -->*/
318 }
319
Popular Tags