1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
package Torello.Java;

import java.util.Vector;

/**
 * <CODE>StrCmprException - Documentation.</CODE><BR /><BR />
 * This class does some passed-parameter checking for the {@code class StrCmpr}.
 * <BR /><BR /><EMBED CLASS="external-html" DATA-FILE-ID="EXPM">
 */
public class StrCmprException extends IllegalArgumentException
{
    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUIDEX">  */
    public static final long serialVersionUID = 1;

    /**
     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
     * 
     * <BR /><BR />This should contain the list of compare-{@code String's} passed for a parameter
     * list to {@code class StrCmpr}.
     */
    public final Vector<String> compareStrVec;

    /** 
     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
     * 
     * <BR /><BR />This field is intended to store the index into the {@code compareStrVec} of
     * the compare-{@code String} that caused the exception throw in the first place.
     */
    public final int i;

    /**
     * Constructs a new exception with the specified detail {@code 'message'}, and the two
     * {@code public, final} parameters: {@code compareStr} and {@code i}.
     * 
     * @param message This should be a well-formatted message informing the user what has occurred.
     * 
     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were 
     * passed to the {@code class StrCmpr} methods that may have contained a null value, or was
     * empty. It is important not to pass null for this parameter, because checking the input to an
     * exception's constructor is not very wise... "Exceptions about Exceptions" is usually
     * unintelligible to a programmer.
     * 
     * @param i This is the index into the {@code compareStr} var-args parameter list that caused
     * the exception to throw.
     * 
     * @see #compareStrVec
     * @see #i
     */
    public StrCmprException(String message, String[] compareStr, int i)
    {
        super(message);
        this.compareStrVec = new Vector<>();
        for (String s : compareStr) this.compareStrVec.add(s);
        this.i = i;
    }

    /**
     * Constructs a new exception with the specified detail {@code 'message'}, cause-chain
     * {@code Throwable}, and the two {@code public, final} parameters: {@code compareStr} and
     * {@code i}.
     * 
     * @param message This should be a well-formatted message informing the user what has occurred.
     * 
     * @param cause This is sometimes used to "chain" exceptions in multi-threaded or heavily
     * I/O related code.
     * 
     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were
     * passed to a {@code class StrCmpr} method that may have contained a null value, or was empty.
     * It is important not to pass null for this parameter, because checking the input to an
     * exception's constructor is not very wise... "Exceptions about Exceptions" is usually
     * unintelligible to a programmer.
     * 
     * @param i This is the index into the {@code 'compareStr'} var-args parameter list that cause
     * the exception to throw.
     * 
     * @see #compareStrVec
     * @see #i
     */
    public StrCmprException(String message, Throwable cause, String[] compareStr, int i)
    {
        super(message, cause);
        this.compareStrVec = new Vector<>();
        for (String s : compareStr) this.compareStrVec.add(s);
        this.i = i;
    }

    /**
     * This will do a simple test of the compare-{@code String's} to make sure none of them are
     * null, and that there are at least one {@code String} in the {@code array}.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">REASON</B></SPAN> It is a subtle issue, but likely
     * better to throw exceptions when one of the {@code var-args} to a {@code String} comparison
     * is {@code 'null'}  Java asserts, generally that two null's do not equal each-other, although
     * testing if a reference is {@code 'null'} (obviously) is fine.  Generally, the concept that a
     * {@code String}-comparing-loop would just "skip" null compare-{@code String's} <I>may seem
     * all right, unfortunately</I> there is a difference between the way a {@code String}-compare
     * {@code 'AND,'} a {@code String}-compare {@code 'OR,'} vs. a {@code String}-compare
     * {@code 'XOR'} should behave.  Since there is likely no general-convention or agreement on
     * what {@code null} in the presence of {@code logical AND, OR, NOT, XOR, NAND} really means,
     * throwing a {@code StrCmprException} <I>when even one var-args string-parameter is
     * {@code 'null'}</I> actually makes the most sense.
     * 
     * @param compareStr This should be the {@code var-args String[]} array-parameter that was
     * passed to a search method
     * 
     * @throws TCCompareStrException If any of the elements of {@code compareStr} are null, or if
     * the array is zero-length.
     */
    public static void check(String[] compareStr)
    {
        if (compareStr == null) throw new NullPointerException
            ("The compareStr varags parameter, itself, was null.");

        if (compareStr.length == 0) throw new StrCmprException(
            "You have passed zero-arguments to a StrCmpr method's var-args String... parameter.  " + 
            "You must pass at least one non-null compare-string",
            compareStr, 0
        );

        for (int i=0; i < compareStr.length; i++)
            if (compareStr[i] == null) throw new StrCmprException(
                "One of the compare-strings passed to a search-method's var-args String... parameter " +
                "was null.  This is not allowed.",
                compareStr, i
            );
    }
}