001package Torello.Java; 002 003import java.util.Vector; 004 005/** 006 * Throws when a Method's (or Constructor's) integer-valued parameter <I>(often for parameters that 007 * are actually named <CODE>'n'</CODE>, representing a 'count' of some form or fasion)</I> does not 008 * adhere to some of those Method's expectations or requirements. 009 * 010 * This exception is used, extensively, by the classes {@link StrIndexOf} and {@link StrTokIndexOf} 011 * inside all methods where an integer parameter {@code 'n'} is required. (These methods all have 012 * names that begin with the three letters {@code 'nth'}). If an inappropriate value for 013 * {@code 'n'} is passed - <I>for instance a negative value</I> - then this exception will throw. 014 * The value of {@code 'n'} refers to the nth-instance of a substring or character, and thusly, 015 * negative-values are meaningless. 016 * 017 * <BR /><BR />This exception is also used in the {@code package HTML.NodeSearch}, for the exact 018 * same purpose, but applied to HTML {@code Vector} match-counts, rather than sub-{@code String} 019 * match-counts. 020 */ 021public class NException extends IndexOutOfBoundsException 022{ 023 /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */ 024 public static final long serialVersionUID = 1; 025 026 /** Constructs an {@code NException} with no detail message. */ 027 public NException() 028 { super(); } 029 030 /** 031 * Constructs an {@code NException} with the specified detail message. 032 * @param message the detail message. 033 */ 034 public NException(String message) 035 { super(message); } 036 037 /** 038 * Constructs a new exception with the specified detail {@code 'message'} and 039 * {@code 'cause'}. 040 * 041 * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B> 042 * 043 * <BR /><BR />The detail message associated with cause is not automatically incorporated into 044 * this exception's detail message. 045 * 046 * @param message The detail message (which is saved for later retrieval by th 047 * {@code Throwable.getMessage()} method). 048 * 049 * @param cause the cause (which is saved for later retrieval by the 050 * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the 051 * cause is nonexistent or unknown.) 052 */ 053 public NException(String message, Throwable cause) 054 { super(message); initCause(cause); } 055 056 /** 057 * Constructs a new exception with the specified {@code 'cause'} and a detail message of 058 * {@code (cause==null ? null : cause.toString())} (which typically contains the class 059 * and detail message of cause). This constructor is useful for exceptions that are little 060 * more than wrappers for other throwables. 061 * 062 * @param cause The cause (which is saved for later retrieval by the 063 * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the 064 * cause is nonexistent or unknown.) 065 */ 066 public NException(Throwable cause) 067 { super(); initCause(cause); } 068 069 /** 070 * Constructs a new NException with an argument indicating the value of {@code 'n'} was the 071 * problem for a message. This is the internally used constructor. 072 * 073 * @param n This is just the value of {@code 'n'} that was passed, and caused the exception. 074 */ 075 public NException(int n) 076 { 077 super( 078 "The value of n [" + n + "] you have passed is not allowed. It must be " + 079 "a positive integer, and less than the compare string length." 080 ); 081 } 082 083 /** 084 * This will check a value of of parameter {@code 'n'} against a {@code java.lang.String}, for 085 * the purposes of {@code String}-Comparison Routines. 086 * 087 * @param n This is the value of {@code 'n'} to check 088 * 089 * @param s This parameter is the {@code String} against which the index-of operation is being 090 * performed. 091 * 092 * @throws NException if {@code 'n'} is less than {@code 1}, or greater than the length of the 093 * {@code String}. 094 */ 095 public static void check(int n, String s) 096 { 097 if (n < 1) throw new NException(n); 098 099 if (n > s.length()) throw new NException( 100 "The value passed to parameter 'n' [" + n + "] is greater than the compare-string length " + 101 "[" + s.length() + "]" 102 ); 103 } 104 105 /** 106 * This will check a value of of parameter {@code 'n'} against a {@code Vector}, for the 107 * purposes of {@code Vector}-Search Routines. 108 * 109 * @param n This is the value of {@code 'n'} to check 110 * 111 * @param v This parameter is the {@code Vector} against which the index-of operation is being 112 * performed. 113 * 114 * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES> 115 * 116 * @throws NException if {@code 'n'} is less than {@code 1}, or greater than the size of the 117 * {@code Vector}. 118 */ 119 public static void check(int n, Vector<?> v) 120 { 121 if (n < 1) throw new NException(n); 122 123 if (n > v.size()) throw new NException( 124 "The value passed to parameter 'n' [" + n + "] is greater than the vector size " + 125 "[" + v.size() + "]" 126 ); 127 } 128 129 /** 130 * This will check a value of of parameter {@code 'n'} to ensure that it is a positive-Integer 131 * (greater-than zero). 132 * 133 * @param n This is the value of {@code n} to check 134 * 135 * @throws NException if {@code 'n'} is less than {@code 1}. 136 */ 137 public static void check(int n) 138 { 139 if (n < 0) throw new NException( 140 "A negative value has been passed to parameter 'n' [" + n + "], but " + 141 "this is not allowed here." 142 ); 143 144 if (n == 0) throw new NException 145 ("Zero was passed to parameter 'n', but this is not allowed here."); 146 } 147 148}