001package Torello.HTML.NodeSearch;
002
003import Torello.HTML.DotPair;
004import java.util.Vector;
005
006/**
007 * An exception thrown by the {@code HNLI} & {@code HNLIInclusive} iterators when, in the
008 * processes of modifying or reading the contents of the most recent {@code Iterator}-Match, a
009 * location is specified that's out of the bounds of the {@code Vector} itself.
010 * 
011 * <BR /><BR /><B CLASS=JDDescLabel>Using this Exception:</B>
012 * 
013 * <BR />The use of this exception differs slightly from that of the {@link CursorException}, with
014 * the primary difference being that a failed cursor-operation resulting in an invalid-cursor is
015 * not identical to an "Out of Bounds" exception for that iterator <I>(when the
016 * <CODE>Iterator</CODE>, itself, might not have even had a cursor set by the user!)</I>.
017 * 
018 * @see HNLIInclusive
019 * @see HNLI
020 */
021public class IteratorOutOfBoundsException extends IndexOutOfBoundsException
022{
023    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
024    public static final long serialVersionUID = 1;
025
026    /** Constructs an {@code IteratorOutOfBoundsException} with no detail message. */
027    public IteratorOutOfBoundsException()
028    { super(); }
029
030    /**
031     * Constructs an {@code IteratorOutOfBoundsException} with the specified detail message.
032     * 
033     * @param message the detail message.
034     */
035    public IteratorOutOfBoundsException(String message)
036    { super(message); }
037
038    /**
039     * This method provides a consistently formatted error message when this exception is thrown by
040     * the {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} classes.  Mostly, like
041     * standard {@code Vector} operations, if the {@code int 'pos'} parameter that was passed is
042     * negative or past the end of the {@code Vector}, an {@code IndexOutOfBoundsException} will be
043     * thrown.
044     * 
045     * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by
046     * an {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} class.
047     * 
048     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
049     * 
050     * @param pos This is the position that has been attempted to index that {@code Vector}.
051     * 
052     * @throws IteratorOutOfBoundsException This will throw if the value passed to parameter 
053     * {@code 'pos'} is negative, or greater than the size of the {@code Vector} parameter 
054     * {@code 'v'}.
055     * 
056     * @see HNLI
057     * @see HNLIInclusive
058     */
059    public static void check(Vector<?> v, int pos)
060    {
061        if (pos < 0) throw new IteratorOutOfBoundsException(
062            "An attempt was made to reference the internal-state vector with a negative " +
063            "index-value: [" + pos + "]"
064        );
065
066        if (pos >= v.size()) throw new IteratorOutOfBoundsException(
067            "An attempt was made to reference the internal-state vector with an index that " +
068            "is past the end of the Vector.  The attempted operation was made using " +
069            "index [" + pos + "], but the internal-state vector has " +
070            "vector.size() [" + v.size() + "]."
071        );
072    }
073
074    /**
075     * This method provides a consistently formatted error message for this exception.  This is
076     * used by the {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} classes.  Mostly,
077     * like standard {@code Vector} operations, if the {@code DotPair 'dp'} provided is not
078     * consistent with the dimensions of the input html-{@code Vector}, then an
079     * {@code IndexOutOfBoundsException} will be thrown.
080     * 
081     * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by
082     * an {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} class.
083     * 
084     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
085     * 
086     * @param dp This is the sub-section, or sub-list of the {@code Vector} that is being checked.
087     * 
088     * @throws IteratorOutOfBoundsException This will throw if the value passed to parameter
089     * {@code 'dp'} is negative, or greater than the size of {@code Vector} parameter
090     * {@code 'v'}.
091     * 
092     * @see HNLI
093     * @see HNLIInclusive
094     */
095    public static void check(Vector<?> v, DotPair dp)
096    {
097        if (dp.end >= v.size()) throw new IteratorOutOfBoundsException(
098            "An attempt was made to reference the internal-state vector with an index that " +
099            "is past the end of the Vector.  The attempted operation was made using " +
100            "DotPair " + dp.toString() + ", but the internal-state vector has " +
101            "vector.size() [" + v.size() + "]."
102        );
103    }
104
105    /**
106     * This method provides a consistently formatted error message when this exception is thrown by
107     * the {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} classes.  Mostly, like
108     * standard {@code Vector} operations, if any of the index-positions that are referenced by the
109     * {@code int[] posArr} parameter are negative or past the end of the {@code Vector}, an
110     * {@code IndexOutOfBoundsException} will be thrown.
111     * 
112     * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by
113     * an {@code HNLI} &amp; {@code HNLIInclusive} {@code Iterator} class.
114     * 
115     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
116     * 
117     * @param posArr This is the {@code array} of position-indices into {@code Vector} parameter 
118     * {@code 'v'} that have been requested to update or for replacement.
119     * 
120     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</B></SPAN> In the code that invokes this
121     * method, the {@code int[]} position-{@code array} passed to parameter {@code 'posArr'} will
122     * <B><I>ALWAYS</I></B> have been sorted before being received here.  As such, only the first
123     * and last elements of this array are actually check for validity.  If this {@code array} is
124     * not sorted, then the check performed by this method will be thoroughly insufficient.
125     * 
126     * @throws IteratorOutOfBoundsException This will throw if any of the the values passed to
127     * parameter {@code 'posArr'} are negative, or greater than the size of {@code Vector} 
128     * parameter {@code 'v'}.
129     * 
130     * @see HNLI
131     * @see HNLIInclusive
132     */
133    public static void check(Vector<?> v, int[] posArr)
134    {
135        if (posArr[0] < 0) throw new IteratorOutOfBoundsException(
136                "An attempt was made to reference the internal-state vector with a " +
137                "negative index-value.  The smallest (most-negative) value " +
138                "passed to the vector-index integer-array was [" + posArr[0] + "]."
139            );
140        if (posArr[posArr.length-1] >= v.size()) throw new IteratorOutOfBoundsException(
141                "An attempt was made to reference the internal-state vector with a " +
142                "location that is past the end of the Vector.  The largest value passed to " +
143                "the vector-index integer-array was [" + posArr[posArr.length-1] + "].  " +
144                "The internal-state vector has vector.size() [" + v.size() + "]."
145            );
146    }
147}