package Torello.HTML;

/**
 * This throws when attempting to write attributes to a closing {@code TagNode} (because closing
 * tag's may not have attributes),
 * 
 * <BR /><BR />Valid HTML does not allow "Inner Tags" or "Attributes" 
 * to be inserted into HTML Elements that begin with the forward-slash (ASCII Character: {@code '/'}).
 * The {@code class TagNode} has quite a few methods that facilitate saving Inner-Tag
 * <B STYLE="color: red;">Key / Value Pairs</B> to the text-{@code String} of a {@code TagNode}.  In
 * cases where one, mistakenly, is attempting to perform such an insert on a closing version of the
 * element, then this exception must throw.
 * 
 * <BR /><BR /><B>NOTE:</B> This {@code Exception} differs from
 * {@link ClosingTagNodeExpectedException} in that here, the user is attempting to perform a
 * {@link TagNode}-operation on a {@code TagNode} instance that will not allow it.
 * 
 * <BR /><BR />In {@code ClosingTagNodeExpectedException}, that {@code Exception} should be thrown
 * when a user a specified a certain element to be found inside a {@code Vector}, but such a
 * {@code TagNode} was not found.
 */
public class ClosingTagNodeException extends RuntimeException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */
    public static final long serialVersionUID = 1;

    /** Constructs a {@code ClosingTagNodeException} with no detail message. */
    public ClosingTagNodeException()
    { super(); }

    /**
     * Constructs a {@code ClosingTagNodeException} with the specified detail message.
     * @param message the detail message.
     */
    public ClosingTagNodeException(String message)
    { super(message); }

    /**
     * Constructs a new exception with the specified detail message and cause.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
     * 
     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
     * this exception's detail message.
     * 
     * @param message The detail message (which is saved for later retrieval by the
     * {@code Throwable.getMessage()} method).
     * 
     * @param cause the cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
     * cause is non-existent or unknown.)
     */
    public ClosingTagNodeException(String message, Throwable cause)
    { super(message, cause); }

    /**
     * Constructs a new exception with the specified cause and a detail message of
     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
     * detail message of cause).  This constructor is useful for exceptions that are little more
     * than wrappers for other throwables.
     * 
     * @param cause The cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
     * cause is non-existent or unknown.)
     */
    public ClosingTagNodeException(Throwable cause)
    { super(cause); }

    /**
     * Checks the input {@code TagNode} parameter to ensure that it is a 'Closing HTML Element.'  
     * This can be verified by inspecting the {@code public final boolean 'isClosing'} field.
     * If the {@code TagNode} input does not represent a 'Closing HTML Element', then this
     * exception shall throw.
     * 
     * @param tn Any HTML {@code TagNode} element
     * 
     * @throws ClosingTagNodeException This throws if {@code tn.isclosing} is {@code FALSE}.  Exits
     * gracefully otherwise.
     */
    public static void check(TagNode tn)
    {
        if (! tn.isClosing) return;

        throw new ClosingTagNodeException(
            "You have attempted to add, modify, delete, or update the inner-tag key-value pair information " +
            "for this particular HTML Element.  Unfortunately, the value of 'isClosing' for this TagNode is " +
            "TRUE, and therefore may not possess any attribute key-value pairs at all.  NOTE: The '.tok' " +
            "field for this TagNode is: [" + tn.tok + "], and the '.str' field is: [" + tn.str + "]"
        );
    }
}