UnreachableCodeException
Keywords: com.sharkysoft.util.UnreachableCodeException class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| sharkysoft.com
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `switch`es 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| sharkysoft.com
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 1997-2004 Sharkysoft (sharkysoft.com). All rights reserved.