001package Torello.HTML;
002
003/**
004 * Used when an invalid, non-HTML, tag or token has been passed to a method.
005 * 
006 * <BR /><BR />For instance, if a programmer accidentally passes the characters {@code 'DVI'},
007 * instead of {@code 'DIV'}, to a method that accepts HTML tokens / tags, then this exception
008 * would throw.
009 */
010public class HTMLTokException extends IllegalArgumentException
011{
012    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */
013    public static final long serialVersionUID = 1;
014
015    /** Constructs an {@code HTMLTokException} with no detail message. */
016    public HTMLTokException()
017    { super(); }
018
019    /**
020     * Constructs an {@code HTMLTokException} with the specified detail message.
021     * @param message the detail message.
022     */
023    public HTMLTokException(String message)
024    { super(message); }
025
026    /**
027     * Constructs a new exception with the specified detail message and cause.
028     *
029     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
030     * 
031     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
032     * this exception's detail message.
033     * 
034     * @param message The detail message (which is saved for later retrieval by the
035     * {@code Throwable.getMessage()} method).
036     *
037     * @param cause the cause (which is saved for later retrieval by the 
038     * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the
039     * cause is non-existent or unknown.)
040     */
041    public HTMLTokException(String message, Throwable cause)
042    { super(message, cause); }
043
044    /**
045     * Constructs a new exception with the specified cause and a detail message of
046     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
047     * detail message of cause).  This constructor is useful for exceptions that are little more
048     * than wrappers for other throwables.
049     *
050     * @param cause The cause (which is saved for later retrieval by the
051     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
052     * cause is nonexistent or unknown.)
053     */
054    public HTMLTokException(Throwable cause)
055    { super(cause); }
056  
057    /**
058     * This just checks if the passed HTML tok(s) is a valid HTML-element, for instance:
059     * {@code img, div, p, a, b, h1, h2, h3} etc...
060     *
061     * <BR /><BR />It throws an HTMLTokException if an "invalid-{@code String}" is passed.
062     *
063     * @param htmlTags This may be any Java String (or strings), but only Java-String's that are
064     * found to be valid HTML 4 or 5 tags will be accepted.
065     * 
066     * <BR /><BR /><B>NOTE:</B> Obviously, the '...' notation means multiple tags may be tested.
067     * If one is found invalid, an exception is immediately thrown.
068     * 
069     * @throws HTMLTokException if the value passed in the tok parameter is not found in the
070     * {@code HTMLTags.isTag(tok);} hashtable.
071     */
072    public static void check(String... htmlTags)
073    {
074        if (htmlTags.length == 0)
075            throw new HTMLTokException
076                ("You have passed zero arguments to the variable-length parameter 'htmlTags'");
077
078        else if (htmlTags.length == 1)
079        {
080            if (htmlTags[0] == null)
081                throw new NullPointerException(
082                    "You have passed null for the value of HTML Tag/Token here, " +
083                    "but this is not allowed."
084                );
085
086            if (! HTMLTags.isTag(htmlTags[0])) throw new HTMLTokException
087                ("The HTML-Element provided isn't valid!  tok = [" + htmlTags[0] + "]");
088        }
089
090        else
091        {
092            String tok;
093            for (int i=0; i < htmlTags.length; i++)
094
095                if ((tok = htmlTags[i]) == null)
096                    throw new NullPointerException(
097                        "You have passed multiple HTML Tokens, but one of them was null " +
098                        "(param #" + i + ").  This is not allowed"
099                     );
100
101                else if (! HTMLTags.isTag(tok))
102                    throw new HTMLTokException(
103                        "You have passed multiple HTML Tokens, but one of them isn't valid! " +
104                        "(param #" + i + "),  tok = [" + tok + "]"
105                    );
106        }
107    }
108}