package Torello.HTML.NodeSearch;

import Torello.HTML.HTMLTags;

/**
 * An Inclusive-Exception indicates that a user has tried to perform an "Inclusive Search" on
 * an HTML Tag that cannot have sub-nodes or descendant-nodes.  The most common examples of
 * inclusive search parameters for HTML tags would be the HTML elements: {@code DIV, P, SPAN, A,
 * TABLE, H1..H6}.
 * 
 * <BR /><BR />These are the HTML elements whose primary purpose is to "surround" a block of
 * HTML or, a some plain-text (in the case of the "anchor element" {@code <A HREF="...">}).
 * An inclusive search does just what one might think would be good to do with "container" 
 * HTML elements, it captures each and every {@code HTMLNode} between the opening and closing HTML
 * {@code TagNode's}.
 *
 * <BR /><BR /><B CLASS=JDDescLabel>Inclusive Java-Script Similarity:</B>
 * 
 * <DIV CLASS="SNIP">{@code
 * var divElement = document.getElementById("article-container");
 * var articleHTML = divElement.innerHTML;
 * }</DIV>
 *
 * <BR /><B>The above two lines of "Java-Script," above, would loosely "translate" to the
 * following java-code below:</B>
 * 
 * <BR /><DIV CLASS="SNIP">{@code
 * Vector<HTMLNode> article = InnerTagGetInclusive.first
 *      (some_page, "div", "class", val -> val.equals("article-container"));
 * 
 * String articleAsStr = Util.pageToString(article);
 * }</DIV>
 *
 * <BR /><BR />Examples of "Inclusive Search" that would cause a
 * {@code throw new InclusiveException(message)} would be using the "Inclusive Methods" in this
 * Node-Search Package - <I>and naming any of the following HTML Elements:</I>
 * 
 * <BR /><UL CLASS=JDUL>
 * <LI>{@code <BR>}             </LI>
 * <LI>{@code <IMG SRC="...">}  </LI>
 * <LI>{@code <HR>}             </LI>
 * <LI>{@code <META ...>}       </LI>
 * <LI>{@code <INPUT ID="...">} </LI>
 * </UL>
 *
 * <BR /><I>Each of the previously listed HTML elements <B>only have an opening tag version, 
 * they never need to be closed!</B></I>  An {@code InclusiveException} is generated if an 
 * attempt is made to find an opening-closing pair when there may not be one, according to the 
 * HTML specifications.  These are sometimes called "stand-alone" or "empty" HTML elements.
 * They are also often called "self-closing" tags.
 */
public class InclusiveException extends IllegalArgumentException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
    public static final long serialVersionUID = 1;

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

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

    /**
     * Constructs a new exception with the specified detail message and cause.
     * 
     * <BR /><BR /><DIV CLASS=JDHint>
     * <B STYLE='color:red;'>Note:</B> The detail message associated with cause is not
     * automatically incorporated into this exception's detail message.
     * </DIV>
     * 
     * @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 InclusiveException(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 InclusiveException(Throwable cause)
    { super(cause); }

    /**
     * Checks either one, or a list, of html-tags (same as the {@code TagNode.tok}) to make sure
     * they are not "singleton" (sometimes called <B>{@code 'empty' HTML elements}</B>.  If the
     * parameter(s) are empty/singleton HTML elements, this method will automatically throw an
     * {@code InclusiveException}.
     * 
     * @param htmlTags This may be any Java {@code String} (or {@code String's}), but only
     * Java-{@code String's} that are found to be valid HTML 4 or 5 tags will be accepted. 
     * 
     * <BR /><BR /><B>NOTE:</B> The {@code String...} (var-args) syntax means multiple tags may be
     * tested.  If one is found to be invalid, an {@code InclusiveEception} is immediately thrown.
     * 
     * @throws InclusiveException
     * @see HTMLTags#isSingleton(String)
     */
    public static void check(String... htmlTags)
    {
        for (String tok : htmlTags)
            if (tok != null) if (HTMLTags.isSingleton(tok)) throw new InclusiveException (
                "The HTML Element '" + tok + "' may not have an inclusive search performed " +
                "with it, because it is a singleton HTML element."
            );
    }
}