1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25 package com.sharkysoft.util;
26
27 /***
28 * Indicates an unfinished execution path.
29 *
30 * <p><b>Details:</b> A <code>NotImplementedException</code> is thrown when a
31 * method is called, a case invoked, or a feature is requested that has not yet
32 * been implemented. This class is the extreme programmer's best friend; it
33 * allows the developer to compile and execute half-<wbr>baked code while
34 * minimizing the risk of forgetting to finish it later. More importantly, this
35 * class allows you to completely design a class without implementing any of it.
36 * To do this, simply include the statement</p>
37 *
38 * <blockquote><code>
39 * throw new NotImplementedException();
40 * </blockquote></ul>
41 *
42 * <p>in any method or execution path that you'd like to finish later. The
43 * compiler will let you compile the code without forcing you to insert dummy
44 * return values or "TO<!-- fool IDE -->DO" comments that you might forget about later.</p>
45 *
46 * <blockquote>
47 *
48 * <p><b>Example 1:</b></p>
49 *
50 * <!-- The arrangement of the asterisks has special significance in javadoc
51 * comments. Please ask Sharky for details if you are curious. -->
52 *
53 <pre>
54 *if (bReadyToRock)
55 *{ do_stuff();
56 * do_more_stuff();
57 *}
58 *else
59 * throw new NotImplementedException();
60 </pre>
61 *
62 * </blockquote>
63 *
64 * <p>In Example 1, a single execution path has been left unimplemented because
65 * the programmer is not yet concerned about it. He'll get to it later, and if
66 * he forget's he'll be reminded when it's needed.</p>
67 *
68 * <blockquote>
69 *
70 * <p><b>Example 2:</b></p>
71 *
72 <pre>
73 *public static float[] findPolynomialRoots(Polynomial ipPolynomial)
74 *{ // I'm putting this declaration here so that the rest of my code will
75 * // compile, but I'll implement the body later or ask my partner to do
76 * // it.
77 * throw new NotImplementedException();
78 *}
79 </pre>
80 *
81 * </blockquote>
82 *
83 * <p>In Example 2, a method is stubbed out because the developer knows he's
84 * going to need it, but he doesn't want to focus on its implementation right
85 * now. In situations like this, you may be tempted to stub out the method and
86 * return a dummy value, such as <code>null</code> or 0. Don't! Doing so is
87 * asking for trouble! You might forget about it and wind up with a
88 * difficult-<wbr>to-<wbr>trace bug! Just use
89 * <code>NotImplementedException</code> instead, and rest confident that the JVM
90 * will remind you if your forgotten method ever gets executed. In fact, you
91 * won't just be reminded, but you'll also be pointed to the class, method, and
92 * line number!</p>
93 *
94 * <blockquote>
95 *
96 * <p><b>Example 3:</b></p>
97 *
98 <pre>
99 *public void actionPerformed(ActionEvent ipEvent)
100 *{ // We're safe doing nothing for now, but eventually we'll need to
101 * // implement this.
102 * NotImplementedException.trace("warning: button response not implemented");
103 *}
104 </pre>
105 *
106 * </blockquote>
107 *
108 * <p>In Example 3, a button's action event handler has not yet been
109 * implemented. At this stage in the application development, however, the
110 * programmer has decided that this is a problem. Rather than stopping the show
111 * with an exception, the developer has decided to simply let
112 * <code>NotImplementedException</code> issue a reminder that the handler has
113 * not yet been implemented.</p>
114 *
115 * <p>Before deploying the final build of an application, the developer should
116 * search all source files for instances of the identifier
117 * "<code>NotImplementedException</code>" to be sure that application is indeed
118 * complete.</p>
119 *
120 * @since 1997
121 * @version 1999.04.19
122 */
123 public class NotImplementedException extends RuntimeException
124 {
125
126 /***
127 * Initializes without detail.
128 *
129 * <p><b>Details:</b> This default constructor initializes a new
130 * <code>NotImplementedException</code> without a detail message.</p>
131 */
132 public NotImplementedException()
133 {
134 super();
135 }
136
137 /***
138 * Initializes with detail.
139 *
140 * <p><b>Details:</b> This constructor initializes a new
141 * <code>NotImplementedException</code> with the given detail message.</p>
142 *
143 * @param isDetail the messsage
144 */
145 public NotImplementedException(String isDetail)
146 {
147 super(isDetail);
148 }
149
150 /***
151 * Prints stack trace of unimplemented execution path.
152 *
153 * <p><b>Details:</b> <code>trace</code> instantiates a new
154 * <code>NotImplementedException</code> without throwing it, and then outputs
155 * its stack trace to <code>System.err</code>. This is useful for tracking
156 * unfinished code paths which must be allowed to operate, albeit temporarily,
157 * in their unfinished state. The provided detail message is included in the
158 * stack trace.</p>
159 *
160 * @param isDetail detail message
161 * @see #trace()
162 * @since 1999.06.04
163 */
164 public static void trace(String isDetail)
165 {
166 new NotImplementedException(isDetail).printStackTrace();
167 }
168
169 /***
170 * Prints stack trace of unimplemented execution path.
171 *
172 * <p><b>Details:</b> <code>trace()</code> is the same as
173 * <code>trace(String)</code>, except that no detail message is used.</p>
174 *
175 * @see #trace(String)
176 * @since 1999.06.04
177 */
178 public static void trace()
179 {
180 new NotImplementedException().printStackTrace();
181 }
182
183 }
184