001package Torello.HTML;
002
003/**
004 * This throws when attempting to write attributes to a closing {@code TagNode} (because closing
005 * tag's may not have attributes),
006 * 
007 * <BR /><BR />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 * 
014 * <BR /><BR /><B>NOTE:</B> This {@code Exception} differs from
015 * {@link ClosingTagNodeExpectedException} in that here, the user is attempting to perform a
016 * {@link TagNode}-operation on a {@code TagNode} instance that will not allow it.
017 * 
018 * <BR /><BR />In {@code ClosingTagNodeExpectedException}, that {@code Exception} should be thrown
019 * when a user a specified a certain element to be found inside a {@code Vector}, but such a
020 * {@code TagNode} was not found.
021 */
022public class ClosingTagNodeException extends RuntimeException
023{
024    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUIDEX"> */
025    public static final long serialVersionUID = 1;
026
027    /** Constructs a {@code ClosingTagNodeException} with no detail message. */
028    public ClosingTagNodeException()
029    { super(); }
030
031    /**
032     * Constructs a {@code ClosingTagNodeException} with the specified detail message.
033     * @param message the detail message.
034     */
035    public ClosingTagNodeException(String message)
036    { super(message); }
037
038    /**
039     * Constructs a new exception with the specified detail message and cause.
040     * <BR /><BR /><B>NOTE:</B> The detail message associated with cause is not automatically
041     * incorporated in this exception's detail message.
042     * @param message The detail message (which is saved for later retrieval by the
043     * {@code Throwable.getMessage()} method).
044     * @param cause the cause (which is saved for later retrieval by the
045     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
046     * cause is non-existent or unknown.)
047     */
048    public ClosingTagNodeException(String message, Throwable cause)
049    { super(message, cause); }
050
051    /**
052     * Constructs a new exception with the specified cause and a detail message of
053     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
054     * detail message of cause).  This constructor is useful for exceptions that are little more
055     * than wrappers for other throwables.
056     * @param cause The cause (which is saved for later retrieval by the
057     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
058     * cause is non-existent or unknown.)
059     */
060    public ClosingTagNodeException(Throwable cause)
061    { super(cause); }
062
063    /**
064     * Checks the input {@code TagNode} parameter to ensure that it is a 'Closing HTML Element.'  
065     * This can be verified by inspecting the {@code public final boolean 'isClosing'} field.
066     * If the {@code TagNode} input does not represent a 'Closing HTML Element', then this
067     * exception shall throw.
068     * @param tn Any HTML {@code TagNode} element
069     * @throws ClosingTagNodeException This throws if {@code tn.isclosing} is <B>FALSE</B>.  Exits
070     * gracefully otherwise.
071     */
072    public static void check(TagNode tn)
073    {
074        if (! tn.isClosing) return;
075
076        throw new ClosingTagNodeException(
077            "You have attempted to add, modify, delete, or update the inner-tag key-value pair information " +
078            "for this particular HTML Element.  Unfortunately, the value of 'isClosing' for this TagNode is " +
079            "TRUE, and therefore may not possess any attribute key-value pairs at all.  NOTE: The '.tok' " +
080            "field for this TagNode is: [" + tn.tok + "], and the '.str' field is: [" + tn.str + "]"
081        );
082    }
083}