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 * @param message The detail message (which is saved for later retrieval by the 079 * {@code Throwable.getMessage()} method). 080 * 081 * @param cause the cause (which is saved for later retrieval by the 082 * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the 083 * cause is nonexistent or unknown). 084 * 085 * @param minCursor This was the setting for the {@code Cursor Boundary Window} inside an 086 * instance of {@code HTML Node List Iterator}, when an exception threw. 087 * 088 * @param maxCursor This was the setting for the {@code Cursor Boundary Window} inside an 089 * instance of {@code HTML Node List Iterator}, when an exception threw. 090 * 091 * @param pos The position that generated this exception throw. 092 * 093 * @see #minCursor 094 * @see #maxCursor 095 * @see #pos 096 */ 097 public CursorException 098 (String message, Throwable cause, int minCursor, int maxCursor, int pos) 099 { 100 super(message); 101 102 this.minCursor = minCursor; 103 this.maxCursor = maxCursor; 104 this.pos = pos; 105 } 106 107 /** 108 * Checks that a supplied position parameter, {@code 'pos'}, is within the bounds of a 109 * given window, and throws an appropriately formatted exception if it is not. 110 * 111 * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied 112 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 113 * 114 * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied 115 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 116 * 117 * @param pos This is the position to be checked against the window bounds. 118 * 119 * @throws CursorException Throws this exception if the provided position parameter 120 * {@code 'pos'} is not within the supplied {@code Cursor Bounds}. 121 * 122 * @see #minCursor 123 * @see #maxCursor 124 * @see #pos 125 */ 126 public static void check (int minCursor, int maxCursor, int pos) 127 { 128 if ((maxCursor == -1) && (minCursor == -1)) return; 129 130 if (pos < minCursor) throw new CursorException( 131 "This iterator has had a Minimum-Cursor index [" + minCursor + "] set using the " + 132 "restrictCursor(...) method. Unfortunately, the position passed as a " + 133 "parameter [" + pos + "], is less than this minimum-cursor index.", 134 minCursor, maxCursor, pos 135 ); 136 137 if (pos > maxCursor) throw new CursorException( 138 "This iterator has had a Maximum-Cursor index [" + maxCursor + "] set using the " + 139 "restrictCursor(...) method. Unfortunately, the DotPair 'range' passed as a " + 140 "parameter [" + pos + "], is greater than this maximum-cursor index.", 141 minCursor, maxCursor, pos 142 ); 143 } 144 145 /** 146 * Checks that a supplied {@code DotPair} parameter, {@code 'dp'}, is <B>FULLY</B> within the 147 * bounds (READ: <I>both</I> {@code DotPair.start} <I>and</I> {@code DotPair.end}) of a given 148 * window, and throws an appropriately formatted exception if it is not. 149 * 150 * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied 151 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 152 * 153 * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied 154 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 155 * 156 * @param dp This is the sub-list or sub-section to be checked against the window bounds. 157 * It must <I>fully lay within the provided window</I> in order for this method to avoid 158 * throwing the {@code CursorException}. 159 * 160 * @throws CursorException Throws this exception if the provided position parameter 161 * {@code 'pos'} is not within the supplied {@code Cursor Bounds}. 162 * 163 * @see #minCursor 164 * @see #maxCursor 165 * @see #pos 166 */ 167 public static void check(int minCursor, int maxCursor, DotPair dp) 168 { 169 if ((maxCursor == -1) && (minCursor == -1)) return; 170 171 if (dp.start < minCursor) throw new CursorException( 172 "This iterator has had a Minimum-Cursor index [" + minCursor + "] set using the " + 173 "restrictCursor(...) method. Unfortunately, the DotPair 'range' " + dp + " passed " + 174 "as a paremter starts before this minimum-cursor index.", 175 minCursor, maxCursor, dp.start 176 ); 177 178 if (dp.end > maxCursor) throw new CursorException( 179 "This iterator has had a Maximum-Cursor index [" + maxCursor + "] set using the " + 180 "restrictCursor(...) method. Unfortunately, the DotPair 'range' " + dp + " passed " + 181 "as a paremter extends past this maximum-cursor index.", 182 minCursor, maxCursor, dp.end 183 ); 184 } 185 186 /** 187 * Checks that each an every index-position from a supplied position-array parameter, 188 * {@code 'posArr'}, is within the bounds of a given window, and throws an appropriately 189 * formatted exception if <I>any of the indices in {@code 'posArr'} are not within 190 * the windows bounds.</I> 191 * 192 * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied 193 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 194 * 195 * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied 196 * to an instance of {@code HTML Node List Iterator}, when an exception threw. 197 * 198 * @param posArr This is the {@code int[]} position-array to be checked against the window 199 * bounds. It value in this array <I>must be within the provided window</I> in order for this 200 * method to avoid throwing the {@code CursorException}. 201 * 202 * @throws CursorException Throws this exception if the provided position parameter 203 * {@code 'pos'} is not within the supplied {@code Cursor Bounds}. 204 * 205 * @see #minCursor 206 * @see #maxCursor 207 * @see #pos 208 */ 209 public static void check(int minCursor, int maxCursor, int[] posArr) 210 { 211 if ((maxCursor == -1) && (minCursor == -1)) return; 212 213 int pos; // Temp Var 214 215 for (int i=0; i < posArr.length; i++) 216 if ((pos=posArr[i]) < minCursor) throw new CursorException( 217 "This iterator has had a Minimum-Cursor, index [" + minCursor + "] set using " + 218 "the restrictCursor(...) method. Unfortunately, One of the elements of the " + 219 "indices-list var-args array (parameter 'posArr') contains a Vector-position " + 220 "index [" + pos + "], at varargs-array index [" + i + "] that is less than " + 221 "this Minimum Cursor Vale.", minCursor, maxCursor, pos 222 ); 223 else if (pos > maxCursor) throw new CursorException( 224 "This iterator has had a Maximum-Cursor, index [" + maxCursor + "] set using " + 225 "the setCursorBounds(...) method. Unfortunately, One of the elements of the " + 226 "indices-list var-args array (parameter 'posArr') contains a Vector-position " + 227 "index [" + pos + "], at varargs-array index [" + i + "] that is greater than " + 228 "this Maximum Cursor Vale.", minCursor, maxCursor, pos 229 ); 230 } 231}