001package Torello.Java;
002
003/**
004 * If a code-block that was theoretically unreachable is actually reached, this error is a great
005 * class to make use-of during any debugging-phase of the development-process.  The detail message
006 * in this class may not be configured using the constructors to this class - <I>it is set inside
007 * this class' constructor, and cannot be modified!</I>  It's a pre-defined message, and informs
008 * the reader that the problem that's been encountered is with programing logic itself (and it
009 * needs to be addressed by the progrmmer).
010 *
011 * <BR /><BR /><DIV CLASS=JDHint>
012 * <B STYLE='color:red;'>Note:</B> This class extends {@code java.lang.Error} because it should be
013 * used and 'thought-of' in a way similar to a Java {@code assert}-statement.  Such coding practice
014 * is usually restricted to the debugging phase of development, and extra care should be taken to
015 * ensure that the final version of releasable-code would never be capable of throwing
016 * {@code UnreachableError}, unless some here-to-fore unrecognized constraints are reached or
017 * broken.
018 * </DIV>
019 * 
020 * <BR />The build code for the {@code Java HTML '.jar'} makes quite a bit of use of this 
021 * {@code Error}.  It should not be thrown, but when it is, it means the code has to be changed.
022 */
023public class UnreachableError extends Error
024{
025    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
026    public static final long serialVersionUID = 1;
027
028    /** Constructs a {@code UnreachableError} with a <B>pre-defined</B> detail-message. */
029    public UnreachableError()
030    {
031        super(
032            "This code path has reached a point that was theoretically, or thought-to-be " +
033            "unreachable.  This is the fault of the developer of this class or package."
034        );
035    }
036
037    /**
038     * Constructs a new exception with the specified {@code 'cause'} and a <B>pre-defined</B>
039     * 
040     * @param cause The cause (which is saved for later retrieval by the
041     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
042     * cause is nonexistent or unknown.)
043     */
044    public UnreachableError(Throwable cause)
045    {
046        super(
047            "This code path has reached a point that was theoretically, or thought-to-be " +
048            "unreachable.  This is the fault of the developer of this class package.  A cause " +
049            "Throwable has been provided.  Please see this.getCause() for more information.",
050            cause
051        );
052    }
053}