1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

package Torello.Java;

/**
 * If a code-block that was theoretically unreachable is actually reached, this error is a great
 * class to make use-of during any debugging-phase of the development-process.  The detail message
 * in this class may not be configured using the constructors to this class - <I>it is set inside
 * this class' constructor, and cannot be modified!</I>  It's a pre-defined message, and informs
 * the reader that the problem that's been encountered is with programing logic itself (and it
 * needs to be addressed by the progrmmer).
 *
 * <BR /><BR /><B STYLE='color:red;'>NOTE:</B> This class extends {@code java.lang.Error} because
 * it should be used and 'thought-of' in a way similar to a Java {@code assert}-statement.  Such
 * coding practice is usually restricted to the debugging phase of development, and extra care 
 * should be taken to ensure that the final version of releasable-code would never be capable of
 * throwing {@code UnreachableError}, unless some here-to-fore unrecognized constraints are 
 * reached or broken.
 * 
 * <BR /><BR />The build code for the {@code Java HTML '.jar'} makes quite a bit of use of this 
 * {@code Error}.  It should not be thrown, but when it is, it means the code has to be changed.
 */
public class UnreachableError extends Error
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
    public static final long serialVersionUID = 1;

    /** Constructs a {@code UnreachableError} with a <B>pre-defined</B> detail-message. */
    public UnreachableError()
    {
        super(
            "This code path has reached a point that was theoretically, or thought-to-be " +
            "unreachable.  This is the fault of the developer of this class or package."
        );
    }

    /**
     * Constructs a new exception with the specified {@code 'cause'} and a <B>pre-defined</B>
     * 
     * @param cause The cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
     * cause is nonexistent or unknown.)
     */
    public UnreachableError(Throwable cause)
    {
        super(
            "This code path has reached a point that was theoretically, or thought-to-be " +
            "unreachable.  This is the fault of the developer of this class package.  A cause " +
            "Throwable has been provided.  Please see this.getCause() for more information.",
            cause
        );
    }
}