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