001: /*
002: * ExtIOException.java: Extended standard exception for stacks
003: *
004: * Copyright (C) 2001 Heiko Blau
005: *
006: * This file belongs to the Susebox Java Core Library (Susebox JCL).
007: * The Susebox JCL is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as published by the
009: * Free Software Foundation; either version 2.1 of the License, or (at your
010: * option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful, but WITHOUT
013: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
014: * FITNESS FOR A PARTICULAR PURPOSE.
015: * See the GNU Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public License along
018: * with the Susebox JCL. If not, write to the
019: *
020: * Free Software Foundation, Inc.
021: * 59 Temple Place, Suite 330,
022: * Boston, MA 02111-1307
023: * USA
024: *
025: * or check the Internet: http://www.fsf.org
026: *
027: * Contact:
028: * email: heiko@susebox.de
029: */
030:
031: package de.susebox.java.io;
032:
033: //------------------------------------------------------------------------------
034: // Imports
035: //
036: import java.io.IOException;
037:
038: import de.susebox.java.lang.ThrowableList;
039: import de.susebox.java.lang.ThrowableMessageFormatter;
040:
041: //------------------------------------------------------------------------------
042: // ExtIOException - definition
043: //
044:
045: /**
046: * Implementation of the {@link ThrowableList} interface for the JDK exception
047: * {@link java.io.IOException}.
048: *
049: * @version 1.00, 2001/06/26
050: * @author Heiko Blau
051: */
052: public class ExtIOException extends IOException implements
053: ThrowableList {
054: //---------------------------------------------------------------------------
055: // methods of the ThrowableList interface
056: //
057:
058: /**
059: * Retrieving the cause of a <code>Throwable</code>. This is the method introduced
060: * with JDK 1.4. It replaces the older {@link #nextThrowable}.
061: *
062: * @return the cause of this <code>Throwable</code>
063: * @see java.lang.Throwable#getCause
064: */
065: public Throwable getCause() {
066: return _next;
067: }
068:
069: /**
070: * Method to traverse the list of {@link java.lang.Throwable}.
071: * See {@link ThrowableList#nextThrowable} for details.
072: *
073: * @return the "earlier" throwable
074: * @deprecated use the JDK 1.4 call {@link #getCause} instead
075: */
076: public Throwable nextThrowable() {
077: return getCause();
078: }
079:
080: /**
081: * Check if <code>this</code> is only a throwable that wraps the real one. See
082: * {@link ThrowableList#isWrapper} for details.
083: *
084: * @return <code>true</code> if this is a wrapper throwable,
085: * <code>false</code> otherwise
086: */
087: public boolean isWrapper() {
088: return _isWrapper;
089: }
090:
091: /**
092: * Getting the format string of a throwable message. This can also be the
093: * message itself if there are no arguments.
094: *
095: * @return the format string being used by {@link java.text.MessageFormat}
096: * @see #getArguments
097: */
098: public String getFormat() {
099: return super .getMessage();
100: }
101:
102: /**
103: * Retrieving the arguments for message formats. These arguments are used by
104: * the {@link java.text.MessageFormat#format} call.
105: *
106: * @return the arguments for a message format
107: * @see #getFormat
108: */
109: public Object[] getArguments() {
110: return _args;
111: }
112:
113: //---------------------------------------------------------------------------
114: // constructors
115: //
116:
117: /**
118: * This constructor should be used for wrapping another exception. While reading
119: * data an IOException may occur, but a certain interface requires a
120: * <code>java.sql.SQLException<code>. Simply use:
121: *<blockquote><pre>
122: * try {
123: * ...
124: * } catch (SQLException ex) {
125: * throw new ExtIOException(ex);
126: * }
127: *</pre></blockquote>
128: *
129: * @param ex the exception to wrap
130: */
131: public ExtIOException(Throwable ex) {
132: this (ex, null, null);
133: }
134:
135: /**
136: * If one likes to add ones own information to an exception, this constructor is
137: * the easiest way to do so. By using such an approach a exception trace with useful
138: * additional informations (which file could be found, what username is unknown)
139: * can be realized:
140: *<blockquote><pre>
141: * try {
142: * ...
143: * } catch (SQLException ex) {
144: * throw new ExtIOException(ex, "while connecting to " + url);
145: * }
146: *</pre></blockquote>
147: *
148: * @param ex the inner exception
149: * @param msg exception message
150: */
151: public ExtIOException(Throwable ex, String msg) {
152: this (ex, msg, null);
153: }
154:
155: /**
156: * This constructor takes a format string and its arguments. The format string
157: * must have a form that can be used by {@link java.text.MessageFormat} methods.
158: * That means:
159: *<blockquote><pre>
160: * java.text.Message.format(fmt, args)
161: *</pre></blockquote>
162: * is similar to
163: *<blockquote><pre>
164: * new MyException(fmt, args).getMessage();
165: *</pre></blockquote>
166: *
167: * @param fmt exception message
168: * @param args arguments for the given format string
169: */
170: public ExtIOException(String fmt, Object[] args) {
171: this (null, fmt, args);
172: }
173:
174: /**
175: * This is the most complex way to construct an <CODE>ThrowableList</CODE>-
176: * Throwable.<br>
177: * An inner exception is accompanied by a format string and its arguments.
178: * Use this constructor in language-sensitive contexts or for formalized messages.
179: * The meaning of the parameters is explained in the other constructors.
180: *
181: * @param ex the inner exception
182: * @param fmt exception message
183: * @param args arguments for the given format string
184: */
185: public ExtIOException(Throwable ex, String fmt, Object[] args) {
186: super (fmt);
187:
188: if (ex != null && fmt == null) {
189: _isWrapper = true;
190: } else {
191: _isWrapper = false;
192: }
193: _next = ex;
194: _args = args;
195: }
196:
197: //---------------------------------------------------------------------------
198: // overridden methods
199: //
200:
201: /**
202: * Implementation of the standard {@link java.lang.Throwable#getMessage} method. It
203: * delegates the call to the central
204: * {@link de.susebox.java.lang.ThrowableMessageFormatter#getMessage} method.
205: *
206: * @return the formatted exception message
207: * @see de.susebox.java.lang.ThrowableMessageFormatter
208: */
209: public String getMessage() {
210: return ThrowableMessageFormatter.getMessage(this );
211: }
212:
213: //---------------------------------------------------------------------------
214: // members
215: //
216:
217: /**
218: * the parameters to be used when formatting the exception message
219: */
220: protected Object[] _args = null;
221:
222: /**
223: * The wrapped, nested of next exception.
224: */
225: protected Throwable _next = null;
226:
227: /**
228: * If <code>true</code> this is only a wrapper exception with the real one
229: * being returned by {@link #nextThrowable}, <code>false</code> for standalone,
230: * nested or subsequent exceptions
231: */
232: protected boolean _isWrapper = false;
233: }
|