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}