001package Torello.HTML.NodeSearch; 002 003import Torello.HTML.DotPair; 004 005/** 006 * This exception is thrown when attempts to violate a <CODE><B>Cursor Boundary Window 007 * Contract</B></CODE> <I>(possibly rendering the window invalid)</I> are made inside any of the 008 * methods exported by the <CODE>AbstractHNLI, HNLI</CODE> or <CODE>HNLIInclusive</CODE> iterators. 009 * 010 * <BR /><BR />A {@code Cursor Bounds Window} is created for a given {@code HTML Node List Iterator 011 * (HNLI, or HNLIInclusive} by invoking the method {@code restrictCursor(...)}. When such a 012 * bounding limit is set for an {@code HNLI}, the returned {@code Iterator}-matches that lay 013 * outside these limits shall be ignored <I>(cannot be returned)</I> by the {@code Iterator}. 014 * 015 * <BR /><BR />Internally, the {@code Iterator} code easily avoids returning such user-requested 016 * out-of-bounds matches. <B><I>However</I></B>, if any of the {@code HNLI} "setter" methods 017 * attempt to set a portion of the vectorized-html that is not within the bounds that were set 018 * by the programmer, this exception shall throw. 019 * 020 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=EXPM> 021 */ 022public class CursorException extends IllegalArgumentException 023{ 024 /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */ 025 public static final long serialVersionUID = 1; 026 027 /** 028 * This will contain the value for {@code minCursor} defined in an {@code HTML Node 029 * Iterator's} settings for the {@code Cursor Bounds}. 030 */ 031 public final int minCursor; 032 033 /** 034 * This will contain the value for {@code maxCursor} defined in an {@code HTML Node 035 * Iterator's} settings for the {@code Cursor Bounds}. 036 */ 037 public final int maxCursor; 038 039 /** 040 * This will contain the value for passed to an {@code HNLI Iterator} 041 * <B>'setter'</B> method which was not within the bounds of the supplied 042 * {@code Cursor Boundary Window}. 043 */ 044 public final int pos; 045 046 /** 047 * Constructs a new exception with the specified detail message, and the two {@code public, 048 * final} parameters: {@code maxCursor, minCursor} and {@code pos}. 049 * 050 * @param message the detail message. 051 * 052 * @param minCursor This was the setting for the {@code Cursor Boundary Window} inside an 053 * instance of {@code HTML Node List Iterator}, when an exception threw. 054 * 055 * @param maxCursor This was the setting for the {@code Cursor Boundary Window} inside an 056 * instance of {@code HTML Node List Iterator}, when an exception threw. 057 * 058 * @param pos The position that generated this exception throw. 059 * 060 * @see #minCursor 061 * @see #maxCursor 062 * @see #pos 063 */ 064 public CursorException(String message, int minCursor, int maxCursor, int pos) 065 { 066 super(message); 067 068 this.minCursor = minCursor; 069 this.maxCursor = maxCursor; 070 this.pos = pos; 071 } 072 073 074 /** 075 * Constructs a new exception with the specified detail message, and the two {@code public, 076 * final} parameters: {@code maxCursor, minCursor} and {@code pos}. 077 * 078 * <BR /><BR /><DIV CLASS=JDHint> 079 * <B STYLE='color:red;'>Note:</B> The detail message associated with cause is not 080 * automatically incorporated into this exception's detail message. 081 * </DIV> 082 * 083 * @param message The detail message (which is saved for later retrieval by the 084 * {@code Throwable.getMessage()} method). 085 * 086 * @param cause the cause (which is saved for later retrieval by the 087 * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the 088 * cause is nonexistent or unknown). 089 * 090 * @param minCursor This was the setting for the {@code Cursor Boundary Window} inside an 091 * instance of {@code HTML Node List Iterator}, when an exception threw. 092 * 093 * @param maxCursor This was the setting for the {@code Cursor Boundary Window} inside an 094 * instance of {@code HTML Node List Iterator}, when an exception threw. 095 * 096 * @param pos The position that generated this exception throw. 097 * 098 * @see #minCursor 099 * @see #maxCursor 100 * @see #pos 101 */ 102 public CursorException 103 (String message, Throwable cause, int minCursor, int maxCursor, int pos) 104 { 105 super(message); 106 107 this.minCursor = minCursor; 108 this.maxCursor = maxCursor; 109 this.pos = pos; 110 } 111 112 /** 113 * Checks that a supplied position parameter, {@code 'pos'}, is within the bounds of a 114 * given window, and throws an appropriately formatted exception if it is not. 115 * 116 * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied 117 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 118 * 119 * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied 120 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 121 * 122 * @param pos This is the position to be checked against the window bounds. 123 * 124 * @throws CursorException Throws this exception if the provided position parameter 125 * {@code 'pos'} is not within the supplied {@code Cursor Bounds}. 126 * 127 * @see #minCursor 128 * @see #maxCursor 129 * @see #pos 130 */ 131 public static void check (int minCursor, int maxCursor, int pos) 132 { 133 if ((maxCursor == -1) && (minCursor == -1)) return; 134 135 if (pos < minCursor) throw new CursorException( 136 "This iterator has had a Minimum-Cursor index [" + minCursor + "] set using the " + 137 "restrictCursor(...) method. Unfortunately, the position passed as a " + 138 "parameter [" + pos + "], is less than this minimum-cursor index.", 139 minCursor, maxCursor, pos 140 ); 141 142 if (pos > maxCursor) throw new CursorException( 143 "This iterator has had a Maximum-Cursor index [" + maxCursor + "] set using the " + 144 "restrictCursor(...) method. Unfortunately, the DotPair 'range' passed as a " + 145 "parameter [" + pos + "], is greater than this maximum-cursor index.", 146 minCursor, maxCursor, pos 147 ); 148 } 149 150 /** 151 * Checks that a supplied {@code DotPair} parameter, {@code 'dp'}, is <B>FULLY</B> within the 152 * bounds (READ: <I>both</I> {@code DotPair.start} <I>and</I> {@code DotPair.end}) of a given 153 * window, and throws an appropriately formatted exception if it is not. 154 * 155 * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied 156 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 157 * 158 * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied 159 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 160 * 161 * @param dp This is the sub-list or sub-section to be checked against the window bounds. 162 * It must <I>fully lay within the provided window</I> in order for this method to avoid 163 * throwing the {@code CursorException}. 164 * 165 * @throws CursorException Throws this exception if the provided position parameter 166 * {@code 'pos'} is not within the supplied {@code Cursor Bounds}. 167 * 168 * @see #minCursor 169 * @see #maxCursor 170 * @see #pos 171 */ 172 public static void check(int minCursor, int maxCursor, DotPair dp) 173 { 174 if ((maxCursor == -1) && (minCursor == -1)) return; 175 176 if (dp.start < minCursor) throw new CursorException( 177 "This iterator has had a Minimum-Cursor index [" + minCursor + "] set using the " + 178 "restrictCursor(...) method. Unfortunately, the DotPair 'range' " + dp + " passed " + 179 "as a paremter starts before this minimum-cursor index.", 180 minCursor, maxCursor, dp.start 181 ); 182 183 if (dp.end > maxCursor) throw new CursorException( 184 "This iterator has had a Maximum-Cursor index [" + maxCursor + "] set using the " + 185 "restrictCursor(...) method. Unfortunately, the DotPair 'range' " + dp + " passed " + 186 "as a paremter extends past this maximum-cursor index.", 187 minCursor, maxCursor, dp.end 188 ); 189 } 190 191 /** 192 * Checks that each an every index-position from a supplied position-array parameter, 193 * {@code 'posArr'}, is within the bounds of a given window, and throws an appropriately 194 * formatted exception if <I>any of the indices in {@code 'posArr'} are not within 195 * the windows bounds.</I> 196 * 197 * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied 198 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 199 * 200 * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied 201 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 202 * 203 * @param posArr This is the {@code int[]} position-array to be checked against the window 204 * bounds. It value in this array <I>must be within the provided window</I> in order for this 205 * method to avoid throwing the {@code CursorException}. 206 * 207 * @throws CursorException Throws this exception if the provided position parameter 208 * {@code 'pos'} is not within the supplied {@code Cursor Bounds}. 209 * 210 * @see #minCursor 211 * @see #maxCursor 212 * @see #pos 213 */ 214 public static void check(int minCursor, int maxCursor, int[] posArr) 215 { 216 if ((maxCursor == -1) && (minCursor == -1)) return; 217 218 int pos; // Temp Var 219 220 for (int i=0; i < posArr.length; i++) 221 if ((pos=posArr[i]) < minCursor) throw new CursorException( 222 "This iterator has had a Minimum-Cursor, index [" + minCursor + "] set using " + 223 "the restrictCursor(...) method. Unfortunately, One of the elements of the " + 224 "indices-list var-args array (parameter 'posArr') contains a Vector-position " + 225 "index [" + pos + "], at varargs-array index [" + i + "] that is less than " + 226 "this Minimum Cursor Vale.", minCursor, maxCursor, pos 227 ); 228 else if (pos > maxCursor) throw new CursorException( 229 "This iterator has had a Maximum-Cursor, index [" + maxCursor + "] set using " + 230 "the setCursorBounds(...) method. Unfortunately, One of the elements of the " + 231 "indices-list var-args array (parameter 'posArr') contains a Vector-position " + 232 "index [" + pos + "], at varargs-array index [" + i + "] that is greater than " + 233 "this Maximum Cursor Vale.", minCursor, maxCursor, pos 234 ); 235 } 236}