001package Torello.Java;
002
003import java.util.Vector;
004
005/**
006 * <CODE>StrCmprException - Documentation.</CODE><BR /><BR />
007 * This class does some passed-parameter checking for the {@code class StrCmpr}.
008 * <BR /><BR /><EMBED CLASS="external-html" DATA-FILE-ID="EXPM">
009 */
010public class StrCmprException extends IllegalArgumentException
011{
012    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUIDEX">  */
013    public static final long serialVersionUID = 1;
014
015    /**
016     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
017     * 
018     * <BR /><BR />This should contain the list of compare-{@code String's} passed for a parameter
019     * list to {@code class StrCmpr}.
020     */
021    public final Vector<String> compareStrVec;
022
023    /** 
024     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
025     * 
026     * <BR /><BR />This field is intended to store the index into the {@code compareStrVec} of
027     * the compare-{@code String} that caused the exception throw in the first place.
028     */
029    public final int i;
030
031    /**
032     * Constructs a new exception with the specified detail {@code 'message'}, and the two
033     * {@code public, final} parameters: {@code compareStr} and {@code i}.
034     * 
035     * @param message This should be a well-formatted message informing the user what has occurred.
036     * 
037     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were 
038     * passed to the {@code class StrCmpr} methods that may have contained a null value, or was
039     * empty. It is important not to pass null for this parameter, because checking the input to an
040     * exception's constructor is not very wise... "Exceptions about Exceptions" is usually
041     * unintelligible to a programmer.
042     * 
043     * @param i This is the index into the {@code compareStr} var-args parameter list that caused
044     * the exception to throw.
045     * 
046     * @see #compareStrVec
047     * @see #i
048     */
049    public StrCmprException(String message, String[] compareStr, int i)
050    {
051        super(message);
052        this.compareStrVec = new Vector<>();
053        for (String s : compareStr) this.compareStrVec.add(s);
054        this.i = i;
055    }
056
057    /**
058     * Constructs a new exception with the specified detail {@code 'message'}, cause-chain
059     * {@code Throwable}, and the two {@code public, final} parameters: {@code compareStr} and
060     * {@code i}.
061     * 
062     * @param message This should be a well-formatted message informing the user what has occurred.
063     * 
064     * @param cause This is sometimes used to "chain" exceptions in multi-threaded or heavily
065     * I/O related code.
066     * 
067     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were
068     * passed to a {@code class StrCmpr} method that may have contained a null value, or was empty.
069     * It is important not to pass null for this parameter, because checking the input to an
070     * exception's constructor is not very wise... "Exceptions about Exceptions" is usually
071     * unintelligible to a programmer.
072     * 
073     * @param i This is the index into the {@code 'compareStr'} var-args parameter list that cause
074     * the exception to throw.
075     * 
076     * @see #compareStrVec
077     * @see #i
078     */
079    public StrCmprException(String message, Throwable cause, String[] compareStr, int i)
080    {
081        super(message, cause);
082        this.compareStrVec = new Vector<>();
083        for (String s : compareStr) this.compareStrVec.add(s);
084        this.i = i;
085    }
086
087    /**
088     * This will do a simple test of the compare-{@code String's} to make sure none of them are
089     * null, and that there are at least one {@code String} in the {@code array}.
090     *
091     * <BR /><BR /><B><SPAN STYLE="color: red;">REASON</B></SPAN> It is a subtle issue, but likely
092     * better to throw exceptions when one of the {@code var-args} to a {@code String} comparison
093     * is {@code 'null'}  Java asserts, generally that two null's do not equal each-other, although
094     * testing if a reference is {@code 'null'} (obviously) is fine.  Generally, the concept that a
095     * {@code String}-comparing-loop would just "skip" null compare-{@code String's} <I>may seem
096     * all right, unfortunately</I> there is a difference between the way a {@code String}-compare
097     * {@code 'AND,'} a {@code String}-compare {@code 'OR,'} vs. a {@code String}-compare
098     * {@code 'XOR'} should behave.  Since there is likely no general-convention or agreement on
099     * what {@code null} in the presence of {@code logical AND, OR, NOT, XOR, NAND} really means,
100     * throwing a {@code StrCmprException} <I>when even one var-args string-parameter is
101     * {@code 'null'}</I> actually makes the most sense.
102     * 
103     * @param compareStr This should be the {@code var-args String[]} array-parameter that was
104     * passed to a search method
105     * 
106     * @throws TCCompareStrException If any of the elements of {@code compareStr} are null, or if
107     * the array is zero-length.
108     */
109    public static void check(String[] compareStr)
110    {
111        if (compareStr == null) throw new NullPointerException
112            ("The compareStr varags parameter, itself, was null.");
113
114        if (compareStr.length == 0) throw new StrCmprException(
115            "You have passed zero-arguments to a StrCmpr method's var-args String... parameter.  " + 
116            "You must pass at least one non-null compare-string",
117            compareStr, 0
118        );
119
120        for (int i=0; i < compareStr.length; i++)
121            if (compareStr[i] == null) throw new StrCmprException(
122                "One of the compare-strings passed to a search-method's var-args String... parameter " +
123                "was null.  This is not allowed.",
124                compareStr, i
125            );
126    }
127}