com.sharkysoft.fig.extra.dev

Class UnreachableCodeException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.sharkysoft.fig.extra.dev.UnreachableCodeException

All Implemented Interfaces:

Serializable

public class UnreachableCodeException
extends 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 shape. You know, in this particular switch statement, that shape 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 edges;
switch (shape)
{
case TRIANGLE:
  edges = 3;
  break;
case SQUARE:
  edges = 4;
  break;
case PENTAGON:
  edges = 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 edges;

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 edges 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 value)
{ if (value % 2 == 0)
    return value / 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 value)
{ 
  if (value % 2 == 0)
    return value / 2;
  System.exit (0);
  throw new 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

Constructors

Constructor and Description
UnreachableCodeException() Initializes without message.
UnreachableCodeException(String iDetail) Initializes with message.
UnreachableCodeException(String iMessage, Throwable iCause) Initializes with detail and cause.
UnreachableCodeException(Throwable iCause) Initializes with cause.

Method Summary

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, 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(String iDetail)

Initializes with message.

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

Parameters:

iDetail - the messsage

UnreachableCodeException

public UnreachableCodeException(String iMessage,
                        Throwable iCause)

Initializes with detail and cause.

Details: This constructor initializes a new instance with the given detail message and wraps the exception that caused the VM to reach the current "unreachable" point.

This constructor may be useful for identifying exceptions that were presumed to be impossible.

Parameters:

iMessage - the message

iCause - the causing exception

UnreachableCodeException

public UnreachableCodeException(Throwable iCause)

Initializes with cause.

Details: This constructor wraps in a new instance the given exception that caused the VM to reach the current "unreachable" point.

This constructor may be useful for identifying exceptions that were presumed to be impossible.

Parameters:

iCause - the causing exception