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     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
029     * 
030     * <BR /><BR />This will contain the value for {@code minCursor} defined in an {@code HTML Node
031     * Iterator's} settings for the {@code Cursor Bounds}.
032     */
033    public final int minCursor;
034
035    /**
036     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
037     * 
038     * <BR /><BR />This will contain the value for {@code maxCursor} defined in an {@code HTML Node
039     * Iterator's} settings for the {@code Cursor Bounds}.
040     */
041    public final int maxCursor;
042
043    /**
044     * <EMBED CLASS="external-html" DATA-FILE-ID="EXPF">
045     * 
046     * <BR /><BR />This will contain the value for passed to an {@code HNLI Iterator}
047     * <B>'setter'</B> method which was not within the bounds of the supplied
048     * {@code Cursor Boundary Window}.
049     */
050    public final int pos;
051
052    /**
053     * Constructs a new exception with the specified detail message, and the two {@code public,
054     * final} parameters: {@code maxCursor, minCursor} and {@code pos}.
055     * 
056     * @param message the detail message.
057     * 
058     * @param minCursor This was the setting for the {@code Cursor Boundary Window} inside an
059     * instance of {@code HTML Node List Iterator}, when an exception threw.
060     * 
061     * @param maxCursor This was the setting for the {@code Cursor Boundary Window} inside an
062     * instance of {@code HTML Node List Iterator}, when an exception threw.
063     * 
064     * @param pos The position that generated this exception throw.
065     * 
066     * @see #minCursor
067     * @see #maxCursor
068     * @see #pos
069     */
070    public CursorException(String message, int minCursor, int maxCursor, int pos)
071    {
072        super(message);
073        this.minCursor  = minCursor;
074        this.maxCursor  = maxCursor;
075        this.pos        = pos;
076    }
077
078
079    /**
080     * Constructs a new exception with the specified detail message, and the two {@code public,
081     * final} parameters: {@code maxCursor, minCursor} and {@code pos}.
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        this.minCursor  = minCursor;
107        this.maxCursor  = maxCursor;
108        this.pos        = pos;
109    }
110
111    /**
112     * Checks that a supplied position parameter, {@code 'pos'}, is within the bounds of a
113     * given window, and throws an appropriately formatted exception if it is not.
114     * 
115     * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied
116     * to an instance of {@code HTML Node List Iterator}, when an exception threw.
117     * 
118     * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied
119     * to an instance of {@code HTML Node List Iterator}, when an exception threw.
120     * 
121     * @param pos This is the position to be checked against the window bounds.
122     * 
123     * @throws CursorException Throws this exception if the provided position parameter
124     * {@code 'pos'} is not within the supplied {@code Cursor Bounds}.
125     * 
126     * @see #minCursor
127     * @see #maxCursor
128     * @see #pos
129     */
130    public static void check (int minCursor, int maxCursor, int pos)
131    {
132        if ((maxCursor == -1) && (minCursor == -1)) return;
133
134        if (pos < minCursor) throw new CursorException(
135            "This iterator has had a Minimum-Cursor index [" + minCursor + "] set using the " +
136            "restrictCursor(...) method.  Unfortunately, the position passed as a " +
137            "parameter [" + pos + "], is less than this minimum-cursor index.",
138            minCursor, maxCursor, pos
139        );
140
141        if (pos > maxCursor) throw new CursorException(
142            "This iterator has had a Maximum-Cursor index [" + maxCursor + "] set using the " +
143            "restrictCursor(...) method.  Unfortunately, the DotPair 'range' passed as a " +
144            "parameter [" + pos + "], is greater than this maximum-cursor index.",
145            minCursor, maxCursor, pos
146        );
147    }
148
149    /**
150     * Checks that a supplied {@code DotPair} parameter, {@code 'dp'}, is <B>FULLY</B> within the
151     * bounds (READ: <I>both</I> {@code DotPair.start} <I>and</I> {@code DotPair.end}) of a given
152     * window, and throws an appropriately formatted exception if it is not.
153     * 
154     * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied
155     * to an instance of {@code HTML Node List Iterator}, when an exception threw.
156     * 
157     * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied
158     * to an instance of {@code HTML Node List Iterator}, when an exception threw.
159     * 
160     * @param dp This is the sub-list or sub-section to be checked against the window bounds.
161     * It must <I>fully lay within the provided window</I> in order for this method to avoid
162     * throwing the {@code CursorException}.
163     * 
164     * @throws CursorException Throws this exception if the provided position parameter
165     * {@code 'pos'} is not within the supplied {@code Cursor Bounds}.
166     * 
167     * @see #minCursor
168     * @see #maxCursor
169     * @see #pos
170     */
171    public static void check(int minCursor, int maxCursor, DotPair dp)
172    {
173        if ((maxCursor == -1) && (minCursor == -1)) return;
174
175        if (dp.start < minCursor) throw new CursorException(
176            "This iterator has had a Minimum-Cursor index [" + minCursor + "] set using the " +
177            "restrictCursor(...) method.  Unfortunately, the DotPair 'range' " + dp + " passed " +
178            "as a paremter starts before this minimum-cursor index.",
179            minCursor, maxCursor, dp.start
180        );
181
182        if (dp.end > maxCursor) throw new CursorException(
183            "This iterator has had a Maximum-Cursor index [" + maxCursor + "] set using the " +
184            "restrictCursor(...) method.  Unfortunately, the DotPair 'range' " + dp + " passed " +
185            "as a paremter extends past this maximum-cursor index.",
186            minCursor, maxCursor, dp.end
187        );
188    }
189
190    /**
191     * Checks that each an every index-position from a supplied position-array parameter, 
192     * {@code 'posArr'}, is within the bounds of a given window, and throws an appropriately
193     * formatted exception if <I>any of the indices in {@code 'posArr'} are not within
194     * the windows bounds.</I>
195     * 
196     * @param minCursor This is the setting for a {@code Cursor Boundary Window} which was applied
197     * to an instance of {@code HTML Node List Iterator}, when an exception threw.
198     * 
199     * @param maxCursor This is the setting for a {@code Cursor Boundary Window} which was applied
200     * to an instance of {@code HTML Node List Iterator}, when an exception threw.
201     * 
202     * @param posArr This is the {@code int[]} position-array to be checked against the window
203     * bounds.  It value in this array <I>must be within the provided window</I> in order for this
204     * method to avoid throwing the {@code CursorException}.
205     * 
206     * @throws CursorException Throws this exception if the provided position parameter
207     * {@code 'pos'} is not within the supplied {@code Cursor Bounds}.
208     * 
209     * @see #minCursor
210     * @see #maxCursor
211     * @see #pos
212     */
213    public static void check(int minCursor, int maxCursor, int[] posArr)
214    {
215        if ((maxCursor == -1) && (minCursor == -1)) return;
216
217        int pos; // Temp Var
218
219        for (int i=0; i < posArr.length; i++)
220            if ((pos=posArr[i]) < minCursor) throw new CursorException(
221                "This iterator has had a Minimum-Cursor, index [" + minCursor + "] set using " +
222                "the restrictCursor(...) method.  Unfortunately, One of the elements of the " +
223                "indices-list var-args array (parameter 'posArr') contains a Vector-position " +
224                "index [" + pos + "], at varargs-array index [" + i + "] that is less than " +
225                "this Minimum Cursor Vale.", minCursor, maxCursor, pos
226            );
227            else if (pos > maxCursor) throw new CursorException(
228                "This iterator has had a Maximum-Cursor, index [" + maxCursor + "] set using " +
229                "the setCursorBounds(...) method.  Unfortunately, One of the elements of the " +
230                "indices-list var-args array (parameter 'posArr') contains a Vector-position " +
231                "index [" + pos + "], at varargs-array index [" + i + "] that is greater than " +
232                "this Maximum Cursor Vale.", minCursor, maxCursor, pos
233            );
234    }
235}