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 /><B STYLE='color:red;'>NOTE:</B> This class extends {@code java.lang.Error} because
012 * it should be used and 'thought-of' in a way similar to a Java {@code assert}-statement.  Such
013 * coding practice is usually restricted to the debugging phase of development, and extra care 
014 * should be taken to ensure that the final version of releasable-code would never be capable of
015 * throwing {@code UnreachableError}, unless some here-to-fore unrecognized constraints are 
016 * reached or broken.
017 * 
018 * <BR /><BR />The build code for the {@code Java HTML '.jar'} makes quite a bit of use of this 
019 * {@code Error}.  It should not be thrown, but when it is, it means the code has to be changed.
020 */
021public class UnreachableError extends Error
022{
023    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
024    public static final long serialVersionUID = 1;
025
026    /** Constructs a {@code UnreachableError} with a <B>pre-defined</B> detail-message. */
027    public UnreachableError()
028    {
029        super(
030            "This code path has reached a point that was theoretically, or thought-to-be " +
031            "unreachable.  This is the fault of the developer of this class or package."
032        );
033    }
034
035    /**
036     * Constructs a new exception with the specified {@code 'cause'} and a <B>pre-defined</B>
037     * 
038     * @param cause The cause (which is saved for later retrieval by the
039     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
040     * cause is nonexistent or unknown.)
041     */
042    public UnreachableError(Throwable cause)
043    {
044        super(
045            "This code path has reached a point that was theoretically, or thought-to-be " +
046            "unreachable.  This is the fault of the developer of this class package.  A cause " +
047            "Throwable has been provided.  Please see this.getCause() for more information.",
048            cause
049        );
050    }
051}