001package Torello.HTML.NodeSearch;
002
003import Torello.HTML.HTMLTags;
004
005/**
006 * An Inclusive-Exception indicates that a user has tried to perform an "Inclusive Search" on
007 * an HTML Tag that cannot have sub-nodes or descendant-nodes.  The most common examples of
008 * inclusive search parameters for HTML tags would be the HTML elements: {@code DIV, P, SPAN, A,
009 * TABLE, H1..H6}.
010 * 
011 * <BR /><BR />These are the HTML elements whose primary purpose is to "surround" a block of
012 * HTML or, a some plain-text (in the case of the "anchor element" {@code <A HREF="...">}).
013 * An inclusive search does just what one might think would be good to do with "container" 
014 * HTML elements, it captures each and every {@code HTMLNode} between the opening and closing HTML
015 * {@code TagNode's}.
016 *
017 * <BR /><BR /><B CLASS=JDDescLabel>Inclusive Java-Script Similarity:</B>
018 * 
019 * <DIV CLASS="SNIP">{@code
020 * var divElement = document.getElementById("article-container");
021 * var articleHTML = divElement.innerHTML;
022 * }</DIV>
023 *
024 * <BR /><B>The above two lines of "Java-Script," above, would loosely "translate" to the
025 * following java-code below:</B>
026 * 
027 * <BR /><DIV CLASS="SNIP">{@code
028 * Vector<HTMLNode> article = InnerTagGetInclusive.first
029 *      (some_page, "div", "class", val -> val.equals("article-container"));
030 * 
031 * String articleAsStr = Util.pageToString(article);
032 * }</DIV>
033 *
034 * <BR /><BR />Examples of "Inclusive Search" that would cause a
035 * {@code throw new InclusiveException(message)} would be using the "Inclusive Methods" in this
036 * Node-Search Package - <I>and naming any of the following HTML Elements:</I>
037 * 
038 * <BR /><UL CLASS=JDUL>
039 * <LI>{@code <BR>}             </LI>
040 * <LI>{@code <IMG SRC="...">}  </LI>
041 * <LI>{@code <HR>}             </LI>
042 * <LI>{@code <META ...>}       </LI>
043 * <LI>{@code <INPUT ID="...">} </LI>
044 * </UL>
045 *
046 * <BR /><I>Each of the previously listed HTML elements <B>only have an opening tag version, 
047 * they never need to be closed!</B></I>  An {@code InclusiveException} is generated if an 
048 * attempt is made to find an opening-closing pair when there may not be one, according to the 
049 * HTML specifications.  These are sometimes called "stand-alone" or "empty" HTML elements.
050 * They are also often called "self-closing" tags.
051 */
052public class InclusiveException extends IllegalArgumentException
053{
054    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
055    public static final long serialVersionUID = 1;
056
057    /** Constructs an {@code InclusiveException} with no detail message. */
058    public InclusiveException()
059    { super(); }
060
061    /**
062     * Constructs an {@code InclusiveException} with the specified detail message.
063     * @param message the detail message.
064     */
065    public InclusiveException(String message)
066    { super(message); }
067
068    /**
069     * Constructs a new exception with the specified detail message and cause.
070     * 
071     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
072     * 
073     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
074     * this exception's detail message.
075     * 
076     * @param message The detail message (which is saved for later retrieval by the
077     * {@code Throwable.getMessage()} method).
078     * 
079     * @param cause the cause (which is saved for later retrieval by the
080     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
081     * cause is nonexistent or unknown.)
082     */
083    public InclusiveException(String message, Throwable cause)
084    { super(message, cause); }
085
086    /**
087     * Constructs a new exception with the specified cause and a detail message of
088     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
089     * detail message of cause).  This constructor is useful for exceptions that are little more
090     * than wrappers for other throwables.
091     * 
092     * @param cause The cause (which is saved for later retrieval by the
093     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
094     * cause is nonexistent or unknown.)
095     */
096    public InclusiveException(Throwable cause)
097    { super(cause); }
098
099    /**
100     * Checks either one, or a list, of html-tags (same as the {@code TagNode.tok}) to make sure
101     * they are not "singleton" (sometimes called <B>{@code 'empty' HTML elements}</B>.  If the
102     * parameter(s) are empty/singleton HTML elements, this method will automatically throw an
103     * {@code InclusiveException}.
104     * 
105     * @param htmlTags This may be any Java {@code String} (or {@code String's}), but only
106     * Java-{@code String's} that are found to be valid HTML 4 or 5 tags will be accepted. 
107     * 
108     * <BR /><BR /><B>NOTE:</B> The {@code String...} (var-args) syntax means multiple tags may be
109     * tested.  If one is found to be invalid, an {@code InclusiveEception} is immediately thrown.
110     * 
111     * @throws InclusiveException
112     * @see HTMLTags#isSingleton(String)
113     */
114    public static void check(String... htmlTags)
115    {
116        for (String tok : htmlTags)
117            if (tok != null) if (HTMLTags.isSingleton(tok)) throw new InclusiveException (
118                "The HTML Element '" + tok + "' may not have an inclusive search performed " +
119                "with it, because it is a singleton HTML element."
120            );
121    }
122}