001package Torello.Browser.JsonAST;
002
003/**
004 * This error is used in place of the common {@code 'UnreachableError'}.  The code in the AST
005 * parsing routines can sometimes be suspiciously difficult to debug, when an error sets in.
006 * The first use of this {@code Throwable} is going to be in preventing a certain aspect of 
007 * the {@link PPR#CTAS()} and {@link PPR#CTAB()} fields from being improperly initialized.
008 * 
009 * <BR /><BR />
010 * In that example &amp; usage, there is currently no way for the relevant fields, which are
011 * the {@code 'ctas'} and {@code 'ctab'} fields, to be improperly initialized.  However, explaining
012 * what could go wrong is somewhat difficult, and salient ennough to let go of the commonly used
013 * {@code 'UnreachableError'}, and instead dedicate this specially tailored error message instead.
014 * 
015 * <BR /><BR />
016 * This is literally because breaking code can sometimes be completely unnoticed and invisble.
017 * Please review the class {@link PPR} to understand what can go wrong when initializing the 
018 * {@code 'ctas'} and {@code 'ctab'} fields.
019 * 
020 * <BR /><BR /><DIV CLASS=JDHint>
021 * Almost instantly, after using this error, I noticed other places where this throwable could
022 * be used to signify other internal errors.  It is not just being used for the CTAS / CTAB issues.
023 * </DIV>
024 */
025public class LinkingStateError extends Error
026{
027    
028    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
029    public static final long serialVersionUID = 1;
030
031    /** Constructs an {@code 'LinkingStateError'} with no detail message. */
032    public LinkingStateError()
033    { super(); }
034
035    /**
036     * Constructs an {@code 'LinkingStateError'} with the specified detail message.
037     * @param message the detail message.
038     */
039    public LinkingStateError(String message)
040    { super(message); }
041
042    /**
043     * Constructs a new error with the specified detail {@code 'message'} and 
044     * {@code 'cause'}.
045     * 
046     * <BR /><BR /><DIV CLASS=JDHint>
047     * <B STYLE='color:red;'>Note:</B> The detail message associated with cause is not
048     * automatically incorporated into this exception's detail message.
049     * </DIV>
050     * 
051     * @param message The detail message (which is saved for later retrieval by th
052     * {@code Throwable.getMessage()} method).
053     * 
054     * @param cause the cause (which is saved for later retrieval by the
055     * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the
056     * cause is nonexistent or unknown.)
057     */
058    public LinkingStateError(String message, Throwable cause)
059    { super(message); initCause(cause); }
060
061    /**
062     * Constructs a new error with the specified {@code 'cause'} and a detail message of
063     * {@code (cause==null ? null : cause.toString())} (which typically contains the class
064     * and detail message of cause).  This constructor is useful for errors that are little
065     * more than wrappers for other throwables.
066     * 
067     * @param cause The cause (which is saved for later retrieval by the
068     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
069     * cause is nonexistent or unknown.)
070     */
071    public LinkingStateError(Throwable cause)
072    { super(); initCause(cause); }   
073}