001package Torello.HTML.NodeSearch;
002
003import java.util.*;
004
005import Torello.Java.ExceptionCheckError;
006
007/**
008 * <CODE>'Text-Comparitor Compare-String Exception'</CODE> is thrown by the argument marshalling
009 * and validity checking code when attempts are made to search HTML-<CODE>Vector's</CODE> using
010 * an invalid input-{@code String[]} parameter.
011 * 
012 * <BR /><BR />This class does some passed-parameter checking for the HTML-Search routines, such
013 * as: {@code FIND, GET, REMOVE, POLL, etc...}  If one is using the class {@link TextComparitor},
014 * it is important to remember that it usually works in coordination with Java's Varargs syntax
015 * which allows anywhere from {@code '0'} to {@code 'n' String's}.
016 * 
017 * <BR /><BR />This class of {@code Exception} will be thrown if any one of them is null, or if
018 * zero arguments were passed to the Varargs syntax.
019 *
020 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=EXPM>
021 */
022public class TCCompareStrException extends IllegalArgumentException
023{
024    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
025    public static final long serialVersionUID = 1;
026
027    /**
028     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF>
029     * 
030     * <BR /><BR />This should contain the list of compare-{@code String's} passed for a parameter
031     * list to a {@code TextComparitor}.
032     */
033    public final Vector<String> compareStrVec;
034
035    /**
036     * <BR /><BR />This field is intended to store the index into the {@code 'compareStrVec'} of
037     * the compare-{@code String} that caused the exception throw in the first place.
038     */
039    public final int i;
040
041    /**
042     * Constructs a new exception with the specified detail message, and the two
043     * {@code public, final} parameters: {@code compareStr} and {@code i}.
044     * 
045     * @param message the detail message.
046     * 
047     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were
048     * passed to a {@code TextComparitor} that may have contained a null value, or was empty. 
049     * 
050     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF_PARAM>
051     * 
052     * @param i This is the index into the {@code 'compareStr'} var-args parameter list that caused
053     * the exception to throw.
054     * 
055     * @see #compareStrVec
056     * @see #i
057     */
058    public TCCompareStrException(String message, String[] compareStr, int i)
059    {
060        super(message);
061
062        if (compareStr == null) throw new ExceptionCheckError
063            ("Parameter 'compareStr' was passed a null reference");
064
065        this.compareStrVec = new Vector<>();
066
067        for (String s : compareStr) this.compareStrVec.add(s);
068
069        this.i = i;
070    }
071
072    /**
073     * Constructs a new exception with the specified detail message, cause-chain throwable, and the
074     * two {@code public, final} parameters: {@code compareStr} and {@code i}.
075     * 
076     * <BR /><BR /><DIV CLASS=JDHint>
077     * <B STYLE='color:red;'>Note:</B> The detail message associated with cause is not
078     * automatically incorporated into this exception's detail message.
079     * </DIV>
080     * 
081     * @param message The detail message (which is saved for later retrieval by the
082     * {@code Throwable.getMessage()} method).
083     * 
084     * @param cause the cause (which is saved for later retrieval by the
085     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
086     * cause is nonexistent or unknown.)
087     * 
088     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were
089     * passed to a {@code TextComparitor} that may have contained a null value, or was empty. 
090     * 
091     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF_PARAM>
092     * 
093     * @param i This is the index into the {@code 'compareStr'} var-args parameter list that caused
094     * the exception to throw.
095     * 
096     * @see #compareStrVec
097     * @see #i
098     */
099    public TCCompareStrException(String message, Throwable cause, String[] compareStr, int i)
100    {
101        super(message, cause);
102
103        if (compareStr == null) throw new ExceptionCheckError
104            ("Parameter 'compareStr' was passed a null reference");
105
106        this.compareStrVec = new Vector<>();
107
108        for (String s : compareStr) this.compareStrVec.add(s);
109
110        this.i = i;
111    }
112
113    /**
114     * This will do a simple test of the compare-{@code String's} to make sure none of them are
115     * null, and that there are at least one {@code String} in the {@code String[] array}.
116     *
117     * <!-- This Explanation has been Copied from Torello.Java.StrCmprException -->
118     * <BR /><BR /><B CLASS=JDDescLabel>Explanation:</B>
119     * 
120     * <BR />It is a subtle issue, but likely better to throw exceptions when one of the Varargs to
121     * a {@code String} comparison is {@code 'null'}.  Since there is likely no general-convention
122     * or agreement on what {@code null} in the presence of {@code logical AND, OR, NOT, XOR, NAND}
123     * really means, throwing a {@code StrCmprException} <I>when even one var-args string-parameter
124     * is {@code 'null'}</I> actually makes the most sense.
125     * 
126     * @param compareStr This should be the {@code var-args} parameter that was passed to a search
127     * method
128     * 
129     * @throws TCCompareStrException If any of the elements of {@code 'compareStr'} is null, or if 
130     * the {@code String[] array} is zero-length.
131     */
132    public static void check(String... compareStr)
133    {
134        if (compareStr == null) throw new NullPointerException
135            ("The compareStr varags parameter, itself, was null.");
136
137        if (compareStr.length == 0) throw new TCCompareStrException(
138            "You have passed zero-arguments to a search-method's var-args String... " +
139            "parameter.  You must pass at least one non-null compare-string",
140            compareStr, 0
141        );
142
143        for (int i=0; i < compareStr.length; i++)
144            if (compareStr[i] == null) throw new TCCompareStrException(
145                "One of the compare-strings passed to a search-method's var-args " +
146                "String... parameter was null.  This is not allowed.",
147                compareStr, i
148            );
149    }
150}