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