KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > susebox > java > io > ExtIOException


1 /*
2  * ExtIOException.java: Extended standard exception for stacks
3  *
4  * Copyright (C) 2001 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.io;
32
33 //------------------------------------------------------------------------------
34 // Imports
35 //
36 import java.io.IOException JavaDoc;
37
38 import de.susebox.java.lang.ThrowableList;
39 import de.susebox.java.lang.ThrowableMessageFormatter;
40
41
42 //------------------------------------------------------------------------------
43 // ExtIOException - definition
44 //
45
46 /**
47  * Implementation of the {@link ThrowableList} interface for the JDK exception
48  * {@link java.io.IOException}.
49  *
50  * @version 1.00, 2001/06/26
51  * @author Heiko Blau
52  */
53 public class ExtIOException
54   extends IOException JavaDoc
55   implements ThrowableList
56 {
57   //---------------------------------------------------------------------------
58 // methods of the ThrowableList interface
59 //
60
61   /**
62    * Retrieving the cause of a <code>Throwable</code>. This is the method introduced
63    * with JDK 1.4. It replaces the older {@link #nextThrowable}.
64    *
65    * @return the cause of this <code>Throwable</code>
66    * @see java.lang.Throwable#getCause
67    */
68   public Throwable JavaDoc getCause() {
69     return _next;
70   }
71   
72   /**
73    * Method to traverse the list of {@link java.lang.Throwable}.
74    * See {@link ThrowableList#nextThrowable} for details.
75    *
76    * @return the "earlier" throwable
77    * @deprecated use the JDK 1.4 call {@link #getCause} instead
78    */
79   public Throwable JavaDoc nextThrowable() {
80     return getCause();
81   }
82
83   /**
84    * Check if <code>this</code> is only a throwable that wraps the real one. See
85    * {@link ThrowableList#isWrapper} for details.
86    *
87    * @return <code>true</code> if this is a wrapper throwable,
88    * <code>false</code> otherwise
89    */
90   public boolean isWrapper() {
91     return _isWrapper;
92   }
93   
94   /**
95    * Getting the format string of a throwable message. This can also be the
96    * message itself if there are no arguments.
97    *
98    * @return the format string being used by {@link java.text.MessageFormat}
99    * @see #getArguments
100    */
101   public String JavaDoc getFormat() {
102     return super.getMessage();
103   }
104   
105   /**
106    * Retrieving the arguments for message formats. These arguments are used by
107    * the {@link java.text.MessageFormat#format} call.
108    *
109    * @return the arguments for a message format
110    * @see #getFormat
111    */
112   public Object JavaDoc[] getArguments() {
113     return _args;
114   }
115   
116
117   //---------------------------------------------------------------------------
118 // constructors
119 //
120
121   /**
122    * This constructor should be used for wrapping another exception. While reading
123    * data an IOException may occur, but a certain interface requires a
124    * <code>java.sql.SQLException<code>. Simply use:
125    *<blockquote><pre>
126    * try {
127    * ...
128    * } catch (SQLException ex) {
129    * throw new ExtIOException(ex);
130    * }
131    *</pre></blockquote>
132    *
133    * @param ex the exception to wrap
134    */
135     public ExtIOException(Throwable JavaDoc ex) {
136         this(ex, null, null);
137     }
138
139   /**
140    * If one likes to add ones own information to an exception, this constructor is
141    * the easiest way to do so. By using such an approach a exception trace with useful
142    * additional informations (which file could be found, what username is unknown)
143    * can be realized:
144    *<blockquote><pre>
145    * try {
146    * ...
147    * } catch (SQLException ex) {
148    * throw new ExtIOException(ex, "while connecting to " + url);
149    * }
150    *</pre></blockquote>
151    *
152    * @param ex the inner exception
153    * @param msg exception message
154    */
155     public ExtIOException(Throwable JavaDoc ex, String JavaDoc msg) {
156         this(ex, msg, null);
157     }
158
159   /**
160    * This constructor takes a format string and its arguments. The format string
161    * must have a form that can be used by {@link java.text.MessageFormat} methods.
162    * That means:
163    *<blockquote><pre>
164    * java.text.Message.format(fmt, args)
165    *</pre></blockquote>
166    * is similar to
167    *<blockquote><pre>
168    * new MyException(fmt, args).getMessage();
169    *</pre></blockquote>
170    *
171    * @param fmt exception message
172    * @param args arguments for the given format string
173    */
174     public ExtIOException(String JavaDoc fmt, Object JavaDoc[] args) {
175     this(null, fmt, args);
176     }
177   
178   /**
179    * This is the most complex way to construct an <CODE>ThrowableList</CODE>-
180    * Throwable.<br>
181    * An inner exception is accompanied by a format string and its arguments.
182    * Use this constructor in language-sensitive contexts or for formalized messages.
183    * The meaning of the parameters is explained in the other constructors.
184    *
185    * @param ex the inner exception
186    * @param fmt exception message
187    * @param args arguments for the given format string
188    */
189     public ExtIOException(Throwable JavaDoc ex, String JavaDoc fmt, Object JavaDoc[] args) {
190     super(fmt);
191    
192     if (ex != null && fmt == null) {
193       _isWrapper = true;
194     } else {
195       _isWrapper = false;
196     }
197     _next = ex;
198     _args = args;
199     }
200
201
202   //---------------------------------------------------------------------------
203 // overridden methods
204 //
205
206   /**
207    * Implementation of the standard {@link java.lang.Throwable#getMessage} method. It
208    * delegates the call to the central
209    * {@link de.susebox.java.lang.ThrowableMessageFormatter#getMessage} method.
210    *
211    * @return the formatted exception message
212    * @see de.susebox.java.lang.ThrowableMessageFormatter
213    */
214     public String JavaDoc getMessage() {
215     return ThrowableMessageFormatter.getMessage(this);
216     }
217
218   
219   //---------------------------------------------------------------------------
220 // members
221 //
222
223   /**
224    * the parameters to be used when formatting the exception message
225    */
226   protected Object JavaDoc[] _args = null;
227
228   /**
229    * The wrapped, nested of next exception.
230    */
231   protected Throwable JavaDoc _next = null;
232   
233   /**
234    * If <code>true</code> this is only a wrapper exception with the real one
235    * being returned by {@link #nextThrowable}, <code>false</code> for standalone,
236    * nested or subsequent exceptions
237    */
238   protected boolean _isWrapper = false;
239 }
240
Popular Tags