001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.commons.lang;
018:
019: import java.io.PrintStream;
020: import java.io.PrintWriter;
021:
022: import org.apache.commons.lang.exception.Nestable;
023: import org.apache.commons.lang.exception.NestableDelegate;
024:
025: /**
026: * <p>Thrown to indicate that a block of code has not been implemented.
027: * This exception supplements <code>UnsupportedOperationException</code>
028: * by providing a more semantically rich description of the problem.</p>
029: *
030: * <p><code>NotImplementedException</code> represents the case where the
031: * author has yet to implement the logic at this point in the program.
032: * This can act as an exception based TODO tag.
033: * Because this logic might be within a catch block, this exception
034: * suports exception chaining.</p>
035: *
036: * <pre>
037: * public void foo() {
038: * try {
039: * // do something that throws an Exception
040: * } catch (Exception ex) {
041: * // don't know what to do here yet
042: * throw new NotImplementedException("TODO", ex);
043: * }
044: * }
045: * </pre>
046: *
047: * @author Matthew Hawthorne
048: * @author Stephen Colebourne
049: * @since 2.0
050: * @version $Id: NotImplementedException.java 437554 2006-08-28 06:21:41Z bayard $
051: */
052: public class NotImplementedException extends
053: UnsupportedOperationException implements Nestable {
054:
055: private static final String DEFAULT_MESSAGE = "Code is not implemented";
056:
057: /**
058: * Required for serialization support.
059: *
060: * @see java.io.Serializable
061: */
062: private static final long serialVersionUID = -6894122266938754088L;
063:
064: /**
065: * The exception helper to delegate nested exception handling to.
066: */
067: private NestableDelegate delegate = new NestableDelegate(this );
068:
069: /**
070: * Holds the reference to the exception or error that caused
071: * this exception to be thrown.
072: */
073: private Throwable cause;
074:
075: //-----------------------------------------------------------------------
076: /**
077: * Constructs a new <code>NotImplementedException</code> with default message.
078: *
079: * @since 2.1
080: */
081: public NotImplementedException() {
082: super (DEFAULT_MESSAGE);
083: }
084:
085: /**
086: * Constructs a new <code>NotImplementedException</code> with specified
087: * detail message.
088: *
089: * @param msg the error message.
090: */
091: public NotImplementedException(String msg) {
092: super (msg == null ? DEFAULT_MESSAGE : msg);
093: }
094:
095: /**
096: * Constructs a new <code>NotImplementedException</code> with specified
097: * nested <code>Throwable</code> and default message.
098: *
099: * @param cause the exception that caused this exception to be thrown
100: * @since 2.1
101: */
102: public NotImplementedException(Throwable cause) {
103: super (DEFAULT_MESSAGE);
104: this .cause = cause;
105: }
106:
107: /**
108: * Constructs a new <code>NotImplementedException</code> with specified
109: * detail message and nested <code>Throwable</code>.
110: *
111: * @param msg the error message
112: * @param cause the exception that caused this exception to be thrown
113: * @since 2.1
114: */
115: public NotImplementedException(String msg, Throwable cause) {
116: super (msg == null ? DEFAULT_MESSAGE : msg);
117: this .cause = cause;
118: }
119:
120: /**
121: * Constructs a new <code>NotImplementedException</code> referencing the specified class.
122: *
123: * @param clazz
124: * the <code>Class</code> that has not implemented the method
125: */
126: public NotImplementedException(Class clazz) {
127: super (clazz == null ? DEFAULT_MESSAGE : DEFAULT_MESSAGE
128: + " in " + clazz);
129: }
130:
131: // -----------------------------------------------------------------------
132: /**
133: * Gets the root cause of this exception.
134: * @return the root cause of this exception.
135: *
136: * @since 2.1
137: */
138: public Throwable getCause() {
139: return cause;
140: }
141:
142: /**
143: * Gets the combined the error message of this and any nested errors.
144: *
145: * @return the error message
146: * @since 2.1
147: */
148: public String getMessage() {
149: if (super .getMessage() != null) {
150: return super .getMessage();
151: } else if (cause != null) {
152: return cause.toString();
153: } else {
154: return null;
155: }
156: }
157:
158: /**
159: * Returns the error message of the <code>Throwable</code> in the chain
160: * of <code>Throwable</code>s at the specified index, numbered from 0.
161: *
162: * @param index the index of the <code>Throwable</code> in the chain
163: * @return the error message, or null if the <code>Throwable</code> at the
164: * specified index in the chain does not contain a message
165: * @throws IndexOutOfBoundsException if the <code>index</code> argument is
166: * negative or not less than the count of <code>Throwable</code>s in the chain
167: * @since 2.1
168: */
169: public String getMessage(int index) {
170: if (index == 0) {
171: return super .getMessage();
172: }
173: return delegate.getMessage(index);
174: }
175:
176: /**
177: * Returns the error message of this and any nested <code>Throwable</code> objects.
178: * Each throwable returns a message, a null string is included in the array if
179: * there is no message for a particular <code>Throwable</code>.
180: *
181: * @return the error messages
182: * @since 2.1
183: */
184: public String[] getMessages() {
185: return delegate.getMessages();
186: }
187:
188: /**
189: * Returns the <code>Throwable</code> in the chain by index.
190: *
191: * @param index the index to retrieve
192: * @return the <code>Throwable</code>
193: * @throws IndexOutOfBoundsException if the <code>index</code> argument is
194: * negative or not less than the count of <code>Throwable</code>s in the chain
195: * @since 2.1
196: */
197: public Throwable getThrowable(int index) {
198: return delegate.getThrowable(index);
199: }
200:
201: /**
202: * Returns the number of nested <code>Throwable</code>s represented by
203: * this <code>Nestable</code>, including this <code>Nestable</code>.
204: *
205: * @return the throwable count
206: * @since 2.1
207: */
208: public int getThrowableCount() {
209: return delegate.getThrowableCount();
210: }
211:
212: /**
213: * Returns this <code>Nestable</code> and any nested <code>Throwable</code>s
214: * in an array of <code>Throwable</code>s, one element for each
215: * <code>Throwable</code>.
216: *
217: * @return the <code>Throwable</code>s
218: * @since 2.1
219: */
220: public Throwable[] getThrowables() {
221: return delegate.getThrowables();
222: }
223:
224: /**
225: * Returns the index of the first occurrence of the specified type.
226: * If there is no match, <code>-1</code> is returned.
227: *
228: * @param type the type to search for
229: * @return index of the first occurrence of the type in the chain, or -1 if
230: * the type is not found
231: * @since 2.1
232: */
233: public int indexOfThrowable(Class type) {
234: return delegate.indexOfThrowable(type, 0);
235: }
236:
237: /**
238: * Returns the index of the first occurrence of the specified type starting
239: * from the specified index. If there is no match, <code>-1</code> is returned.
240: *
241: * @param type the type to search for
242: * @param fromIndex the index of the starting position in the chain to be searched
243: * @return index of the first occurrence of the type in the chain, or -1 if
244: * the type is not found
245: * @throws IndexOutOfBoundsException if the <code>fromIndex</code> argument
246: * is negative or not less than the count of <code>Throwable</code>s in the chain
247: * @since 2.1
248: */
249: public int indexOfThrowable(Class type, int fromIndex) {
250: return delegate.indexOfThrowable(type, fromIndex);
251: }
252:
253: /**
254: * Prints the stack trace of this exception.
255: * Includes information from the exception, if any, which caused this exception.
256: *
257: * @since 2.1
258: */
259: public void printStackTrace() {
260: delegate.printStackTrace();
261: }
262:
263: /**
264: * Prints the stack trace of this exception to the specified stream.
265: * Includes information from the exception, if any, which caused this exception.
266: *
267: * @param out the stream to write to
268: * @since 2.1
269: */
270: public void printStackTrace(PrintStream out) {
271: delegate.printStackTrace(out);
272: }
273:
274: /**
275: * Prints the stack trace of this exception to the specified writer.
276: * Includes information from the exception, if any, which caused this exception.
277: *
278: * @param out the writer to write to
279: * @since 2.1
280: */
281: public void printStackTrace(PrintWriter out) {
282: delegate.printStackTrace(out);
283: }
284:
285: /**
286: * Prints the stack trace for this exception only (root cause not included)
287: * using the specified writer.
288: *
289: * @param out the writer to write to
290: * @since 2.1
291: */
292: public final void printPartialStackTrace(PrintWriter out) {
293: super.printStackTrace(out);
294: }
295:
296: }
|