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