com.io7m.junreachable 2.1.1 Documentation
Package Information
Orientation
Overview
The com.io7m.junreachable package implements a set of exception types for unambiguously marking code that is supposed to be unreachable (but that the compiler cannot prove is unreachable).
Installation
Source compilation
The project can be compiled and installed with Maven:
$ mvn -C clean install
Maven
Regular releases are made to the Central Repository, so it's possible to use the com.io7m.junreachable package in your projects with the following Maven dependency:
<dependency>
  <groupId>com.io7m.junreachable</groupId>
  <artifactId>com.io7m.junreachable-core</artifactId>
  <version>2.1.1</version>
</dependency>
All io7m.com packages use Semantic Versioning [0], which implies that it is always safe to use version ranges with an exclusive upper bound equal to the next major version - the API of the package will not change in a backwards-incompatible manner before the next major version.
Platform Specific Issues
There are currently no known platform-specific issues.
License
All files distributed with the com.io7m.junreachable package are placed under the following license:
Copyright © 2014 <code@io7m.com> http://io7m.com

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
        
Usage
Exceptions
Unreachable
The Java compiler typically cannot detect unreachable cases in, for example, switch statements:
enum T
{
  A,
  B,
  C
}

int f(
  final T t)
{
  assert t != null;

  switch (t) {
    case A:
    {
      return 1;
    }
    case B:
    {
      return 2;
    }
    case C:
    {
      return 3;
    }
  }
}
The function f will fail to compile due to a missing return statement; even though all possible cases of T are handled, the compiler is not sufficiently intelligent to determine this. Naive developers might try to add a default case, but this makes the code fragile with respect to modification; if someone adds an extra value to T, the code silently becomes incorrect. The correct course of action is to explicitly mark the unreachable code with an exception that unambiguously states the intention:
enum T
{
  A,
  B,
  C
}

int f(
  final T t)
{
  assert t != null;

  switch (t) {
    case A:
    {
      return 1;
    }
    case B:
    {
      return 2;
    }
    case C:
    {
      return 3;
    }
  }

  throw new UnreachableCodeException();
}
The code now compiles. The code is robust in the face of later modification of T. Anyone reading the code understands that the original writer expected the code to be unreachable. Anyone running the code and somehow managing to reach the unreachable section is greeted with an unambiguous exception that states that a bug has been discovered (and the stack trace will indicate exactly where this happened).
Unimplemented code
Most Java development environments will automatically produce empty method stubs when the programmer attempts to implement an interface. The generated methods typically look something like:
@Override void someInterfaceMethod()
{
  // TODO: Auto-generated method stub
}
The programmer doesn't always have a complete implementation ready immediately, and unfortunately nothing stops anyone from running the as-yet unimplemented methods. The correct course of action is to explicitly mark this unimplemented code with an exception type that unambiguously states the nature of the code:
@Override void someInterfaceMethod()
{
  // TODO: Auto-generated method stub
  throw new UnimplementedCodeException();
}
Discovering unimplemented code is now as simple as searching for uses of UnimplementedCodeException in the codebase. Anyone managing to execute unimplemented code will be greeted with an exception that states exactly which code is unimplemented. Most development environments can be instructed to automatically generate code that throws UnimplementedCodeException exceptions as in the above example.
API Reference
Javadoc
API documentation for the package is provided via the included Javadoc.