KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > susebox > jtopas > TokenizerException


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