001package Torello.Java;
002
003import java.util.Vector;
004
005import Torello.HTML.NodeSearch.TCCompareStrException;
006
007/**
008 * An exception that performs a little bit of passed-parameter checking for the class
009 * {@code StrCmpr}.
010 * 
011 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=EXPM>
012 */
013public class StrCmprException extends IllegalArgumentException
014{
015    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
016    public static final long serialVersionUID = 1;
017
018    /**
019     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF>
020     * 
021     * <BR /><BR />This should contain the list of compare-{@code String's} passed for a parameter
022     * list to {@code class StrCmpr}.
023     */
024    public final Vector<String> compareStrVec;
025
026    /** 
027     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF>
028     * 
029     * <BR /><BR />This field is intended to store the index into the {@code compareStrVec} of
030     * the compare-{@code String} that caused the exception throw in the first place.
031     */
032    public final int i;
033
034    /**
035     * Constructs a new exception with the specified detail {@code 'message'}, and the two
036     * {@code public, final} parameters: {@code compareStr} and {@code i}.
037     * 
038     * @param message This should be a well-formatted message informing the user what has occurred.
039     * 
040     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were 
041     * passed to the {@code class StrCmpr} methods that may have contained a null value, or was
042     * empty.
043     * 
044     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF_PARAM>
045     * 
046     * @param i This is the index into the {@code 'compareStr'} var-args parameter list that cause
047     * the exception to throw.  This value must be between {@code 0} and
048     * {@code comparestr.length - 1}, or {@link ExceptionCheckError} will throw.
049     * 
050     * @throws ExceptionCheckError If parameter {@code 'compareStr'} is passed null, or if
051     * parameter {@code 'i'} is not a valid array-index into {@code 'compareStr'}.
052     * 
053     * @see #compareStrVec
054     * @see #i
055     */
056    public StrCmprException(String message, String[] compareStr, int i)
057    {
058        super(message);
059
060        if (compareStr == null) throw new ExceptionCheckError
061            ("StrCmprException constructor parameter 'compareStr' was passed null.");
062
063        if ((i < 0) || (i >= compareStr.length)) throw new ExceptionCheckError(
064            "StrmCmprException constructor parameter 'i' was passed a value that is not within " +
065            "the bounds of the var-args String-array parameter 'comparestr'"
066        );
067
068        this.compareStrVec = new Vector<>();
069        for (String s : compareStr) this.compareStrVec.add(s);
070
071        this.i = i;
072    }
073
074    /**
075     * Constructs a new exception with the specified detail {@code 'message'}, cause-chain
076     * {@code Throwable}, and the two {@code public, final} parameters: {@code compareStr} and
077     * {@code i}.
078     * 
079     * <BR /><BR /><DIV CLASS=JDHint>
080     * <B STYLE='color:red;'>Note:</B> The detail message associated with cause is not
081     * automatically incorporated into this exception's detail message.
082     * </DIV>
083     * 
084     * @param message This should be a well-formatted message informing the user what has occurred.
085     * 
086     * @param cause This is sometimes used to "chain" exceptions in multi-threaded or heavily
087     * I/O related code.
088     * 
089     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were
090     * passed to a {@code class StrCmpr} method that may have contained a null value, or was empty.
091     * 
092     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF_PARAM>
093     * 
094     * @param i This is the index into the {@code 'compareStr'} var-args parameter list that cause
095     * the exception to throw.  This value must be between {@code 0} and
096     * {@code comparestr.length - 1}, or {@link ExceptionCheckError} will throw.
097     * 
098     * @throws ExceptionCheckError If parameter {@code 'compareStr'} is passed null, or if
099     * parameter {@code 'i'} is not a valid array-index into {@code 'compareStr'}.
100     * 
101     * @see #compareStrVec
102     * @see #i
103     */
104    public StrCmprException(String message, Throwable cause, String[] compareStr, int i)
105    {
106        super(message, cause);
107
108        if (compareStr == null) throw new ExceptionCheckError
109            ("StrCmprException constructor parameter 'compareStr' was passed null.");
110
111        if ((i < 0) || (i >= compareStr.length)) throw new ExceptionCheckError(
112            "StrmCmprException constructor parameter 'i' was passed a value that is not within " +
113            "the bounds of the var-args String-array parameter 'comparestr'"
114        );
115
116        this.compareStrVec = new Vector<>();
117        for (String s : compareStr) this.compareStrVec.add(s);
118
119        this.i = i;
120    }
121
122    /**
123     * This will do a simple test of the compare-{@code String's} to make sure none of them are
124     * null, and that there are at least one {@code String} in the {@code array}.
125     *
126     * <BR /><BR /><B CLASS=JDDescLabel>Explanation:</B>
127     * 
128     * <BR />It is a subtle issue, but likely better to throw exceptions when one of the Varargs to
129     * a {@code String} comparison is {@code 'null'}.  Since there is likely no general-convention
130     * or agreement on what {@code null} in the presence of {@code logical AND, OR, NOT, XOR, NAND}
131     * really means, throwing a {@code StrCmprException} <I>when even one var-args string-parameter
132     * is {@code 'null'}</I> actually makes the most sense.
133     * 
134     * @param compareStr This should be the {@code var-args String[]} array-parameter that was
135     * passed to a search method
136     * 
137     * @throws TCCompareStrException If any of the elements of {@code compareStr} are null, or if
138     * the array is zero-length.
139     */
140    public static void check(String[] compareStr)
141    {
142        if (compareStr == null) throw new NullPointerException
143            ("The compareStr varags parameter, itself, was null.");
144
145        if (compareStr.length == 0) throw new StrCmprException(
146            "You have passed zero-arguments to a StrCmpr method's var-args String... parameter.  " + 
147            "You must pass at least one non-null compare-string",
148            compareStr, 0
149        );
150
151        for (int i=0; i < compareStr.length; i++)
152            if (compareStr[i] == null) throw new StrCmprException(
153                "One of the compare-strings passed to a search-method's var-args String... parameter " +
154                "was null.  This is not allowed.",
155                compareStr, i
156            );
157    }
158}