001: /*
002: * TokenizerException.java: Generic exception used by the Tokenizer interface
003: *
004: * Copyright (C) 2001 Heiko Blau
005: *
006: * This file belongs to the JTopas Library.
007: * JTopas 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 JTopas. 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.jtopas;
032:
033: //------------------------------------------------------------------------------
034: // Imports
035: //
036: import de.susebox.java.lang.ThrowableList;
037: import de.susebox.java.lang.ThrowableMessageFormatter;
038:
039: //------------------------------------------------------------------------------
040: // TokenizerException - definition
041: //
042:
043: /**<p>
044: * Wrapper exception for all the problems that may occur while parsing. There
045: * are IOExceptions, SQLExceptions etc. that can all happen when a {@link Tokenizer}
046: * tries to extract the next token.
047: *</p><p>
048: * The class supports formats and format arguments beside the usual plain
049: * throwable message string.
050: *</p>
051: *
052: * @author Heiko Blau
053: */
054: public class TokenizerException extends Exception implements
055: ThrowableList {
056: //---------------------------------------------------------------------------
057: // methods of the ThrowableList interface
058: //
059:
060: /**
061: * Retrieving the cause of a <code>Throwable</code>. This is the method introduced
062: * with JDK 1.4. It replaces the older {@link #nextThrowable}.
063: *
064: * @return the cause of this <code>Throwable</code>
065: * @see java.lang.Throwable#getCause
066: */
067: public Throwable getCause() {
068: return _next;
069: }
070:
071: /**
072: * Method to traverse the list of {@link java.lang.Throwable}.
073: * See {@link ThrowableList#nextThrowable} for details.
074: *
075: * @return the "earlier" throwable
076: * @deprecated use the JDK 1.4 call {@link #getCause} instead
077: */
078: public Throwable nextThrowable() {
079: return getCause();
080: }
081:
082: /**
083: * Check if <code>this</code> is only a throwable that wraps the real one. See
084: * {@link ThrowableList#isWrapper} for details.
085: *
086: * @return <code>true</code> if this is a wrapper throwable,
087: * <code>false</code> otherwise
088: */
089: public boolean isWrapper() {
090: return _isWrapper;
091: }
092:
093: /**
094: * Getting the format string of a throwable message. This can also be the
095: * message itself if there are no arguments.
096: *
097: * @return the format string being used by {@link java.text.MessageFormat}
098: * @see #getArguments
099: */
100: public String getFormat() {
101: return super .getMessage();
102: }
103:
104: /**
105: * Retrieving the arguments for message formats. These arguments are used by
106: * the {@link java.text.MessageFormat#format} call.
107: *
108: * @return the arguments for a message format
109: * @see #getFormat
110: */
111: public Object[] getArguments() {
112: return _args;
113: }
114:
115: //---------------------------------------------------------------------------
116: // constructors
117: //
118:
119: /**
120: * This constructor takes a simple message string like ordinary Java
121: * {@link java.lang.Throwable} classes. This is the most convenient form to
122: * construct an <code>ThrowableList</code> throwable.
123: *
124: * @param msg message for this <code>Throwable</code> instance
125: */
126: public TokenizerException(String msg) {
127: this (null, msg, null);
128: }
129:
130: /**
131: * This constructor should be used for wrapping another throwable. While reading
132: * data an IOException may occur, but the {@link Tokenizer} interface requires a
133: * <code>TokenizerException</code>. Simply use:
134: *<blockquote><pre>
135: * try {
136: * ...
137: * } catch (IOException ex) {
138: * throw new TokenizerException(ex);
139: * }
140: *</pre></blockquote>
141: *
142: * @param ex the throwable to wrap
143: */
144: public TokenizerException(Throwable ex) {
145: this (ex, null, null);
146: }
147:
148: /**
149: * If one likes to add ones own information to an throwable, this constructor is
150: * the easiest way to do so. By using such an approach a throwable trace with useful
151: * additional informations (which file could be found, what username is unknown)
152: * can be realized:
153: *<blockquote><pre>
154: * try {
155: * ...
156: * } catch (IOException ex) {
157: * throw new TokenizerException(ex, "while tokenizing " + path);
158: * }
159: *</pre></blockquote>
160: *
161: * @param ex the inner throwable
162: * @param msg throwable message
163: */
164: public TokenizerException(Throwable ex, String msg) {
165: this (ex, msg, null);
166: }
167:
168: /**
169: * This constructor takes a format string and its arguments. The format string
170: * must have a form that can be used by {@link java.text.MessageFormat} methods.
171: * That means:
172: *<blockquote><pre>
173: * java.text.Message.format(fmt, args)
174: *</pre></blockquote>
175: * is similar to
176: *<blockquote><pre>
177: * new TokenizerException(fmt, args).getMessage();
178: *</pre></blockquote>
179: *
180: * @param fmt throwable message
181: * @param args arguments for the given format string
182: */
183: public TokenizerException(String fmt, Object[] args) {
184: this (null, fmt, args);
185: }
186:
187: /**
188: * This is the most complex way to construct a <CODE>TokenizerException</CODE>.
189: * An inner throwable is accompanied by a format string and its arguments.
190: * Use this constructor in language-sensitive contexts or for formalized messages.
191: * The meaning of the parameters is explained in the other constructors.
192: *
193: * @param ex the inner throwable
194: * @param fmt throwable message
195: * @param args arguments for the given format string
196: */
197: public TokenizerException(Throwable ex, String fmt, Object[] args) {
198: super (fmt);
199:
200: if (ex != null && fmt == null) {
201: _isWrapper = true;
202: } else {
203: _isWrapper = false;
204: }
205: _next = ex;
206: _args = args;
207: }
208:
209: //---------------------------------------------------------------------------
210: // overridden methods
211: //
212:
213: /**
214: * Implementation of the standard {@link java.lang.Throwable#getMessage} method. It
215: * delegates the call to the central
216: * {@link de.susebox.java.lang.ThrowableMessageFormatter#getMessage} method.
217: *
218: * @return the formatted throwable message
219: * @see de.susebox.java.lang.ThrowableMessageFormatter
220: */
221: public String getMessage() {
222: return ThrowableMessageFormatter.getMessage(this );
223: }
224:
225: //---------------------------------------------------------------------------
226: // members
227: //
228:
229: /**
230: * the parameters to be used when formatting the throwable message
231: */
232: protected Object[] _args = null;
233:
234: /**
235: * The wrapped, nested of next throwable.
236: */
237: protected Throwable _next = null;
238:
239: /**
240: * If <code>true</code> this is only a wrapper throwable with the real one
241: * being returned by {@link #nextThrowable}, <code>false</code> for standalone,
242: * nested or subsequent exceptions
243: */
244: protected boolean _isWrapper = false;
245: }
|