com.io7m.junreachable 4.0.0 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:
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>4.0.0</version>
</dependency>
All
io7m.com
packages use Semantic Versioning
, 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:
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:
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:
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:
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.