com.sharkysoft.util
Class UnreachableCodeException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.lang.RuntimeException
              com.sharkysoft.util.UnreachableCodeException

All Implemented Interfaces:

java.io.Serializable

public class UnreachableCodeException

extends java.lang.RuntimeException

Indicates unanticipated execution path.

Details: An UnreachableCodeException may be thrown whenever an execution path that the programmer has assumed to be unreachable actually turns out to be reachable. In a perfect world, therefore, this exception will never be thrown. However, since no programmers (other than Sharkysoft programmers) are perfect, we have provided this exception class for you to use wherever you assert that some piece of code is unreachable. Later, when this exception is finally thrown, you will realize how naive you were and quickly fix the problem. As embarrassing as it is, however, it is better to throw an UnreachableCodeException than to do nothing at all and risk leaving the bug undetected!

Example 1:

Your code switches on the variable vnShape. You know, in this particular switch statement, that vnShape can be only one of three values. (Or at least that's what you think you know!) However, since you are safety-conscious, your code might look like this:

int vnEdges;
switch (vnShape)
{
case TRIANGLE:
  vnEdges = 3;
  break;
case SQUARE:
  vnEdges = 4;
  break;
case PENTAGON:
  vnEdges = 5;
  break;
default:
  // Because we are only expecting one of the above three
  // shapes, we'll be really surprised if we actually get here!
  throw new UnreachableCodeException("Surprise, you moron!");
}
return vnEdges;

In this example, adding the unreachable default case accomplishes two good things:

1. It guarantees that you'll be notified if your assumption is wrong, and
2. It allows your code to compile, without the compiler complaining that vnEdges might not have been initialized. (You see, compilers just aren't as smart as humans!)

As the above example demonstrates, UnreachableCodeException not only documents your control flow assumptions, but it also helps you to fool the compiler. Such deception is often necessary in the presence of unreachable code that the compiler can't guess about.

Example 2:

The function foo divides a value by 2 if the value is even, but terminates the application if the value is odd.

int foo(int vn)
{ if (vn % 2 == 0)
    return vn / 2;
  System.exit (0);
  // exit() will never return, but does the compiler know that?
  // No!  It will innocently complain about needing a return value
  // right here.
}

Although this code looks correct (because exit never returns), the compiler will not accept it. This is because the compiler does not know anything about System.exit's behavior. Instead, it stupidly expects exit to return, and therefore complains about a missing return value for foo. UnreachableCodeException offers a good solution here.

int foo (int vn)
{ if (vn % 2 == 0)
    return vn / 2;
  System.exit (0);
  throw new com.sharkysoft.util.UnreachableCodeException ();
}

Now the compiler will now accept our code without complaint. Although you could have inserted a dummy return statement into the code -- like many programmers do -- the better approach shown here renders the code more "self-documenting," and it also guarantees that you'll be notified if your assumption about the never-returning method turns out to be incorrect (for some strange reason).

Author:

Sharky

See Also:

Serialized Form

Constructor Summary

UnreachableCodeException()
Initializes without message.

UnreachableCodeException(java.lang.String isDetail)
Initializes with message.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnreachableCodeException

public UnreachableCodeException()

Initializes without message.

Details: This default constructor initializes a new UnreachableCodeException without an exception message.

UnreachableCodeException

public UnreachableCodeException(java.lang.String isDetail)

Initializes with message.

Details: This constructor initializes a new UnreachableCodeException with the given exception detail message.

Parameters:

isDetail - the messsage