001package Torello.HTML;
002
003/**
004 * <CODE>ClosingTagNodeException - Documentation.</CODE><BR /><BR />
005 * 
006 * This method is used to indicate that a programmer is trying to write attributes to a
007 * closing-version of a {@code TagNode}.  Valid HTML does not allow "Inner Tags" or "Attributes" 
008 * to be inserted into HTML Elements that begin with the forward-slash (ASCII Character: {@code '/'}).
009 * The {@code class TagNode} has quite a few methods that facilitate saving Inner-Tag
010 * <B STYLE="color: red;">Key / Value Pairs</B> to the text-{@code String} of a {@code TagNode}.  In
011 * cases where one, mistakenly, is attempting to perform such an insert on a closing version of the
012 * element, then this exception must throw.
013 */
014public class ClosingTagNodeException extends RuntimeException
015{
016    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUIDEX"> */
017    public static final long serialVersionUID = 1;
018
019    /** Constructs a {@code ClosingTagNodeException} with no detail message. */
020    public ClosingTagNodeException()
021    { super(); }
022
023    /**
024     * Constructs a {@code ClosingTagNodeException} with the specified detail message.
025     * @param message the detail message.
026     */
027    public ClosingTagNodeException(String message)
028    { super(message); }
029
030    /**
031     * Constructs a new exception with the specified detail message and cause.
032     * <BR /><BR /><B>NOTE:</B> The detail message associated with cause is not automatically
033     * incorporated in this exception's detail message.
034     * @param message The detail message (which is saved for later retrieval by the
035     * {@code Throwable.getMessage()} method).
036     * @param cause the cause (which is saved for later retrieval by the
037     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
038     * cause is non-existent or unknown.)
039     */
040    public ClosingTagNodeException(String message, Throwable cause)
041    { super(message, cause); }
042
043    /**
044     * Constructs a new exception with the specified cause and a detail message of
045     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
046     * detail message of cause).  This constructor is useful for exceptions that are little more
047     * than wrappers for other throwables.
048     * @param cause The cause (which is saved for later retrieval by the
049     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
050     * cause is non-existent or unknown.)
051     */
052    public ClosingTagNodeException(Throwable cause)
053    { super(cause); }
054
055    /**
056     * Checks the input {@code TagNode} parameter to ensure that it is a 'Closing HTML Element.'  
057     * This can be verified by inspecting the {@code public final boolean 'isClosing'} field.
058     * If the {@code TagNode} input does not represent a 'Closing HTML Element', then this
059     * exception shall throw.
060     * @param tn Any HTML {@code TagNode} element
061     * @throws ClosingTagNodeException This throws if {@code tn.isclosing} is <B>FALSE</B>.  Exits
062     * gracefully otherwise.
063     */
064    public static void check(TagNode tn)
065    {
066        if (! tn.isClosing) return;
067
068        throw new ClosingTagNodeException(
069            "You have attempted to add, modify, delete, or update the inner-tag key-value pair information " +
070            "for this particular HTML Element.  Unfortunately, the value of 'isClosing' for this TagNode is " +
071            "TRUE, and therefore may not possess any attribute key-value pairs at all.  NOTE: The '.tok' " +
072            "field for this TagNode is: [" + tn.tok + "], and the '.str' field is: [" + tn.str + "]"
073        );
074    }
075}