KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > lang > NotImplementedException


1 /*
2  * Copyright 2002-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.lang;
17
18 import java.io.PrintStream JavaDoc;
19 import java.io.PrintWriter JavaDoc;
20
21 import org.apache.commons.lang.exception.Nestable;
22 import org.apache.commons.lang.exception.NestableDelegate;
23
24 /**
25  * <p>Thrown to indicate that a block of code has not been implemented.
26  * This exception supplements <code>UnsupportedOperationException</code>
27  * by providing a more semantically rich description of the problem.</p>
28  *
29  * <p><code>NotImplementedException</code> represents the case where the
30  * author has yet to implement the logic at this point in the program.
31  * This can act as an exception based TODO tag.
32  * Because this logic might be within a catch block, this exception
33  * suports exception chaining.</p>
34  *
35  * <pre>
36  * public void foo() {
37  * try {
38  * // do something that throws an Exception
39  * } catch (Exception ex) {
40  * // don't know what to do here yet
41  * throw new NotImplementedException("TODO", ex);
42  * }
43  * }
44  * </pre>
45  *
46  * @author Matthew Hawthorne
47  * @author Stephen Colebourne
48  * @since 2.0
49  * @version $Id: NotImplementedException.java 161243 2005-04-14 04:30:28Z ggregory $
50  */
51 public class NotImplementedException
52         extends UnsupportedOperationException JavaDoc implements Nestable {
53
54     /**
55      * The exception helper to delegate nested exception handling to.
56      */
57     private NestableDelegate delegate = new NestableDelegate(this);
58
59     /**
60      * Holds the reference to the exception or error that caused
61      * this exception to be thrown.
62      */
63     private Throwable JavaDoc cause;
64
65     //-----------------------------------------------------------------------
66 /**
67      * Constructs a new <code>NotImplementedException</code> with default message.
68      *
69      * @since 2.1
70      */
71     public NotImplementedException() {
72         super("Code is not implemented");
73     }
74
75     /**
76      * Constructs a new <code>NotImplementedException</code> with specified
77      * detail message.
78      *
79      * @param msg the error message.
80      */
81     public NotImplementedException(String JavaDoc msg) {
82         super(msg == null ? "Code is not implemented" : msg);
83     }
84
85     /**
86      * Constructs a new <code>NotImplementedException</code> with specified
87      * nested <code>Throwable</code> and default message.
88      *
89      * @param cause the exception that caused this exception to be thrown
90      * @since 2.1
91      */
92     public NotImplementedException(Throwable JavaDoc cause) {
93         super("Code is not implemented");
94         this.cause = cause;
95     }
96
97     /**
98      * Constructs a new <code>NotImplementedException</code> with specified
99      * detail message and nested <code>Throwable</code>.
100      *
101      * @param msg the error message
102      * @param cause the exception that caused this exception to be thrown
103      * @since 2.1
104      */
105     public NotImplementedException(String JavaDoc msg, Throwable JavaDoc cause) {
106         super(msg == null ? "Code is not implemented" : msg);
107         this.cause = cause;
108     }
109
110     /**
111      * Constructs a new <code>NotImplementedException</code> referencing
112      * the specified class.
113      *
114      * @param clazz the <code>Class</code> that has not implemented the method
115      */
116     public NotImplementedException(Class JavaDoc clazz) {
117         super((clazz == null ?
118                 "Code is not implemented" :
119                 "Code is not implemented in " + clazz));
120     }
121
122     //-----------------------------------------------------------------------
123 /**
124      * Gets the root cause of this exception.
125      * @return the root cause of this exception.
126      *
127      * @since 2.1
128      */
129     public Throwable JavaDoc getCause() {
130         return cause;
131     }
132
133     /**
134      * Gets the combined the error message of this and any nested errors.
135      *
136      * @return the error message
137      * @since 2.1
138      */
139     public String JavaDoc getMessage() {
140         if (super.getMessage() != null) {
141             return super.getMessage();
142         } else if (cause != null) {
143             return cause.toString();
144         } else {
145             return null;
146         }
147     }
148
149     /**
150      * Returns the error message of the <code>Throwable</code> in the chain
151      * of <code>Throwable</code>s at the specified index, numbered from 0.
152      *
153      * @param index the index of the <code>Throwable</code> in the chain
154      * @return the error message, or null if the <code>Throwable</code> at the
155      * specified index in the chain does not contain a message
156      * @throws IndexOutOfBoundsException if the <code>index</code> argument is
157      * negative or not less than the count of <code>Throwable</code>s in the chain
158      * @since 2.1
159      */
160     public String JavaDoc getMessage(int index) {
161         if (index == 0) {
162             return super.getMessage();
163         } else {
164             return delegate.getMessage(index);
165         }
166     }
167
168     /**
169      * Returns the error message of this and any nested <code>Throwable</code> objects.
170      * Each throwable returns a message, a null string is included in the array if
171      * there is no message for a particular <code>Throwable</code>.
172      *
173      * @return the error messages
174      * @since 2.1
175      */
176     public String JavaDoc[] getMessages() {
177         return delegate.getMessages();
178     }
179
180     /**
181      * Returns the <code>Throwable</code> in the chain by index.
182      *
183      * @param index the index to retrieve
184      * @return the <code>Throwable</code>
185      * @throws IndexOutOfBoundsException if the <code>index</code> argument is
186      * negative or not less than the count of <code>Throwable</code>s in the chain
187      * @since 2.1
188      */
189     public Throwable JavaDoc getThrowable(int index) {
190         return delegate.getThrowable(index);
191     }
192
193     /**
194      * Returns the number of nested <code>Throwable</code>s represented by
195      * this <code>Nestable</code>, including this <code>Nestable</code>.
196      *
197      * @return the throwable count
198      * @since 2.1
199      */
200     public int getThrowableCount() {
201         return delegate.getThrowableCount();
202     }
203
204     /**
205      * Returns this <code>Nestable</code> and any nested <code>Throwable</code>s
206      * in an array of <code>Throwable</code>s, one element for each
207      * <code>Throwable</code>.
208      *
209      * @return the <code>Throwable</code>s
210      * @since 2.1
211      */
212     public Throwable JavaDoc[] getThrowables() {
213         return delegate.getThrowables();
214     }
215
216     /**
217      * Returns the index of the first occurrence of the specified type.
218      * If there is no match, <code>-1</code> is returned.
219      *
220      * @param type the type to search for
221      * @return index of the first occurrence of the type in the chain, or -1 if
222      * the type is not found
223      * @since 2.1
224      */
225     public int indexOfThrowable(Class JavaDoc type) {
226         return delegate.indexOfThrowable(type, 0);
227     }
228
229     /**
230      * Returns the index of the first occurrence of the specified type starting
231      * from the specified index. If there is no match, <code>-1</code> is returned.
232      *
233      * @param type the type to search for
234      * @param fromIndex the index of the starting position in the chain to be searched
235      * @return index of the first occurrence of the type in the chain, or -1 if
236      * the type is not found
237      * @throws IndexOutOfBoundsException if the <code>fromIndex</code> argument
238      * is negative or not less than the count of <code>Throwable</code>s in the chain
239      * @since 2.1
240      */
241     public int indexOfThrowable(Class JavaDoc type, int fromIndex) {
242         return delegate.indexOfThrowable(type, fromIndex);
243     }
244
245     /**
246      * Prints the stack trace of this exception.
247      * Includes information from the exception, if any, which caused this exception.
248      *
249      * @since 2.1
250      */
251     public void printStackTrace() {
252         delegate.printStackTrace();
253     }
254
255     /**
256      * Prints the stack trace of this exception to the specified stream.
257      * Includes information from the exception, if any, which caused this exception.
258      *
259      * @param out the stream to write to
260      * @since 2.1
261      */
262     public void printStackTrace(PrintStream JavaDoc out) {
263         delegate.printStackTrace(out);
264     }
265
266     /**
267      * Prints the stack trace of this exception to the specified writer.
268      * Includes information from the exception, if any, which caused this exception.
269      *
270      * @param out the writer to write to
271      * @since 2.1
272      */
273     public void printStackTrace(PrintWriter JavaDoc out) {
274         delegate.printStackTrace(out);
275     }
276
277     /**
278      * Prints the stack trace for this exception only (root cause not included)
279      * using the specified writer.
280      *
281      * @param out the writer to write to
282      * @since 2.1
283      */
284     public final void printPartialStackTrace(PrintWriter JavaDoc out) {
285         super.printStackTrace(out);
286     }
287
288 }
289
Popular Tags