package Torello.HTML;

import java.util.regex.*;

import Torello.HTML.HelperPackages.TagNode.AttrRegEx;

/**
 * This occurs whenever a parameter specifies an Inner-Tag
 * <B STYLE="color: red;">"Key-Value Pair"</B> (which, in this package, are <I>also known
 * as</I> Attribute-<B STYLE="color: red;">Value</B> Pairs) that contain inappropriate characters
 * inside the {@code key-String}.
 *
 * <BR /><BR /><B CLASS=JDDescLabel>Reg-Ex Rules:</B>
 * 
 * <BR />All matching HTML Element Attributes must have attribute-<B STYLE="color: red;">names</B>
 * (inner-tags) whose nomenclature conforms to this regular-expression: {@code [A-Za-z][\w-]+}.
 * 
 * <BR /><BR />All this says is that attribute-<B STYLE="color: red;">names</B> <I>must begin with
 * an alphabetic character</I>, and then the characters that follow must be "regular-expression"
 * {@code word-characters '\w'}.
 * 
 * <BR /><BR />In a regular-expression, the characters that match a {@code \w} include the letters
 * {@code A-Z}, the (lower-case) letters {@code a-z}, the digits {@code 0-9}, and the underscore
 * {@code '_'}.  The minus-sign {@code '-'} may also be used in an
 * attribute-<B STYLE="color: red;">name</B><I> (it just may not be the first character used in an
 * attribute-<B STYLE="color: red;">name</B>)</I>.
 *
 * <DIV CLASS="EXAMPLE">{@code 
 *  <IMG SRC="http://example.com/pic.jpg">
 *  <DIV data-id="this is example data">
 * }</DIV>
 * 
 * <BR />For the above two examples, both the {@code 'SRC'} attribute-name (key-name) and the
 * {@code 'data-id'} key-<B STYLE="color: red;">name</B> are legitimately named.  No exceptions
 * would be thrown if a programmer initiated a search using a string to look for an inner-tag that
 * was named {@code 'src'} nor would there be problems using a string named {@code 'data-id'} to
 * look for the <B STYLE="color: red;">value</B> of {@code data-id} above.
 *
 * <DIV CLASS=EXAMPLE>{@code 
 * Properties p = new java.util.Properties();
 * p.put("My Attribute Value", "data 1");
 * p.put("123Attribute", "data 2");
 * p.put("SpecialChars!@#$%", "data 3");
 * TagNode tn = new TagNode("DIV", p, SD.DoubleQuotes, false);
 * }</DIV>
 * <BR />An {@code InnerTagKeyException} would be generated <I>for all three cases!</I>  Each of
 * the above inner-tag <B STYLE="color: red;">key-value pairs</B> have
 * key-<B STYLE="color: red;">names</B> with illegal characters.
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>Specifically:</B>
 * 
 * <BR /><BR /><UL CLASS=JDUL>
 * <LI>Attribute-Value Pair 1: The key-<B STYLE="color: red;">name</B> contains a space.</LI>
 * <LI>Attribute-Value Pair 2: The key-<B STYLE="color: red;">name</B> begins with a number.</LI>
 * 
 * <LI> Attribute-Value Pair 3: The key-<B STYLE="color: red;">name</B> has invalid,
 *      non-alpha-numeric
 *      characters!
 *      </LI>
 * 
 * </UL>
 * 
 * <BR />If a search were made using an inner-tag (attribute-<B STYLE="color: red;">name</B>)using
 * a {@code String} that did not meet these criteria, an {@code InnerTagKeyException} would be
 * thrown.
 *
 */
public class InnerTagKeyException extends IllegalArgumentException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */
    public static final long serialVersionUID = 1;

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

    /**
     * Constructs an {@code InnerTagKeyException} with the specified detail message.
     * @param message the detail message.
     */
    public InnerTagKeyException(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 nonexistent or unknown).
     */
    public InnerTagKeyException(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 nonexistent or unknown.)
     */
    public InnerTagKeyException(Throwable cause)
    { super(cause); }

    /**
     * This verifies that any Java-{@code String} that is intended to be use as an inner-tag
     * conforms to the right rules.  If a problem is found, then an {@code InnerTagKeyException} or
     * {@code NullPointerException} is thrown.
     * 
     * @param keys One or many HTML-Inner-Tag to be checked for use as an HTML-Attribute
     * <B STYLE="color: red;">name</B>
     * 
     * @throws InnerTagKeyException If any {@code String} does not match the {@code CHECK_KEY}
     * Regular-Expression {@code Pattern}.
     * 
     * @throws NullPointerException If any of the attributes / inner-tag
     * <B STYLE="color: red;">keys</B> passed are null.
     */
    public static void check(String... keys)
    {
        for (String key : keys)

            if (key == null) throw new NullPointerException(
                "You have passed a null as an Attribute-Name (also known as an " +
                "'InnerTag-Key Name'), but this is not allowed."
            );

            else if (! AttrRegEx.ATTRIBUTE_KEY_REGEX.matcher(key).find())
                throw new InnerTagKeyException
                    ("Inner-tag key has invalid characters: [" + key + ']');
    }

    /**
     * This method is <B>identical</B> to the <B>{@code public static void check(key);}</B>, except
     * it allows the programmer to add the <B STYLE="color: red;">key-value pair</B> to the 
     * Exception's error message.  No change to the code is present, except the exception's error
     * message.
     * 
     * @param key Any HTML-Inner-Tag <B STYLE="color: red;">name</B>to be checked for use as an
     * HTML-Attribute
     * 
     * @param value This is the <B STYLE="color: red;">value</B> taken by this
     * <B STYLE="color: red;">key</B>, it is included for error-logging only, but it is not
     * checked.
     * 
     * @throws InnerTagKeyException If this class does not match the {@code CHECK_KEY} 
     * Regular-Expression {@code Pattern}, than it throws.
     */
    public static void check(String key, String value)
    {
        if (key == null) throw new NullPointerException(
            "You have passed a null as an Attribute-Name (also known as an 'InnerTag-Key Name'), " +
            "but this is not allowed."
        );

        if (! AttrRegEx.ATTRIBUTE_KEY_REGEX.matcher(key).find()) 
            throw new InnerTagKeyException(
                "The specified inner-tag key has invalid characters: [" + key + "]\n" +
                "For Key-Value Pair: [" + key + ", " + value + "]"
            );
    }
}