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