1 package com.sharkysoft.util;
2
3 /***
4 * Indicates unanticipated execution path.
5 *
6 * <p><b>Details:</b> An <code>UnreachableCodeException</code> may be thrown
7 * whenever an execution path that the programmer has assumed to be unreachable
8 * actually turns out to be reachable. In a perfect world, therefore, this
9 * exception will never be thrown. However, since no programmers (other than
10 * Sharkysoft programmers) are perfect, we have provided this exception class
11 * for you to use wherever you assert that some piece of code is unreachable.
12 * Later, when this exception is finally thrown, you will realize how naive you
13 * were and quickly fix the problem. As embarrassing as it is, however, it is
14 * better to throw an <code>UnreachableCodeException</code> than to do nothing
15 * at all and risk leaving the bug undetected!</p>
16 *
17 * <blockquote>
18 *
19 * <p><b>Example 1:</b></p>
20 *
21 * <p>Your code <code>switch</code>es on the variable <code>vnShape</code>.
22 * You know, in this particular <code>switch</code> statement, that
23 * <var>vnShape</var> can be only one of three values. (Or at least that's
24 * what you <em>think</em> you know!) However, since you are
25 * safety-<wbr>conscious, your code might look like this:</p>
26 *
27 *<blockquote><pre>
28 *int vnEdges;
29 *switch (vnShape)
30 *{
31 *case TRIANGLE:
32 * vnEdges = 3;
33 * break;
34 *case SQUARE:
35 * vnEdges = 4;
36 * break;
37 *case PENTAGON:
38 * vnEdges = 5;
39 * break;
40 *default:
41 * // <i>Because we are only expecting one of the above three</i>
42 * // <i>shapes, we'll be really surprised if we actually get here!</i>
43 * <b>throw new UnreachableCodeException("Surprise, you moron!");</b>
44 *}
45 *return vnEdges;
46 *</pre></blockquote>
47 *
48 * <p>In this example, adding the unreachable <code>default</code> case
49 * accomplishes two good things:</p>
50 *
51 * <ol>
52 * <li>It guarantees that you'll be notified if your assumption is wrong,
53 * and</li>
54 * <li>It allows your code to compile, without the compiler complaining that
55 * <code>vnEdges</code> might not have been initialized. (You see,
56 * compilers just aren't as smart as humans!)</li>
57 * </ol>
58 *
59 * </blockquote>
60 *
61 * <p>As the above example demonstrates, <code>UnreachableCodeException</code>
62 * not only documents your control flow assumptions, but it also helps you to
63 * fool the compiler. Such deception is often necessary in the presence of
64 * unreachable code that the compiler can't guess about.</p>
65 *
66 * <blockquote>
67 *
68 * <p><b>Example 2:</b></p>
69 *
70 * <p>The function <code>foo</code> divides a value by 2 if the value is even,
71 * but terminates the application if the value is odd.</p>
72 *
73 *<blockquote><pre>
74 *int foo(int vn)
75 *{ if (vn % 2 == 0)
76 * return vn / 2;
77 * System.exit (0);
78 * // <i>exit() will never return, but does the compiler know that?</i>
79 * // <i>No! It will innocently complain about needing a return value</i>
80 * // <i>right here.</i>
81 *}
82 *</pre></blockquote>
83 *
84 * <p>Although this code looks correct (because <code>exit</code> never
85 * returns), the compiler will not accept it. This is because the compiler
86 * does not know anything about <code>System.exit</code>'s behavior. Instead,
87 * it stupidly expects <code>exit</code> to return, and therefore complains
88 * about a missing return value for <code>foo</code>.
89 * <code>UnreachableCodeException</code> offers a good solution here.</p>
90 *
91 *<blockquote><pre>
92 *int foo (int vn)
93 *{ if (vn % 2 == 0)
94 * return vn / 2;
95 * System.exit (0);
96 * <b>throw new com.sharkysoft.util.UnreachableCodeException ();</b>
97 *}
98 *</pre></blockquote>
99 *
100 * <p>Now the compiler will now accept our code without complaint. Although
101 * you could have inserted a dummy <code>return</code> statement into the code
102 * -- like many programmers do -- the better approach shown here renders the
103 * code more "self-documenting," and it also guarantees that you'll be
104 * notified if your assumption about the never-<wbr>returning method turns out
105 * to be <code>incorrect</code> (for some strange reason).</p>
106 *
107 * </blockquote>
108 *
109 * @author Sharky
110 */
111 public class UnreachableCodeException extends RuntimeException
112 {
113
114 /***
115 * Initializes without message.
116 *
117 * <p><b>Details:</b> This default constructor initializes a new
118 * <code>UnreachableCodeException</code> without an exception message.</p>
119 */
120 public UnreachableCodeException()
121 {
122 }
123
124 /***
125 * Initializes with message.
126 *
127 * <p><b>Details:</b> This constructor initializes a new
128 * <code>UnreachableCodeException</code> with the given exception detail
129 * message.</p>
130 *
131 * @param isDetail the messsage
132 */
133 public UnreachableCodeException(String isDetail)
134 {
135 super(isDetail);
136 }
137
138 }
139