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}