Class CursorException

  • All Implemented Interfaces:
    java.io.Serializable
    public class CursorException
extends java.lang.IllegalArgumentException
    CursorException - Documentation.

    This is exception is thrown if code attempts to violate a . A Cursor Bounds Window is created for a given HTML Node List Iterator (HNLI, or HNLIInclusive by invoking the method restrictCursor(...). When such a bounding limit is set for an HNLI, the returned Iterator-matches that lay outside these limits may not be returned by the Iterator.

    Internally, the code easily avoids returning such user-requested out-of-bounds matches. However, if any of the HNLI "setter" methods attempt to set a portion of the vectorized-html that is not within the bounds that were set by the programmer, this exception shall throw.

    This class provides some public final "inspection & convenience" fields which should guarantee to avoid having null values when this Exception is thrown by an internal method. If as a programmer, you intended to extend use of this class, make sure to pass valid-information & valid-data, to the constructors of this class.
    See Also:
    Serialized Form




    • Constructor Summary

      Constructors 
      Constructor
      CursorException​(String message, int minCursor, int maxCursor, int pos)
      CursorException​(String message, Throwable cause, int minCursor, int maxCursor, int pos)

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method
      static void check​(int minCursor, int maxCursor, int pos)
      static void check​(int minCursor, int maxCursor, int[] posArr)
      static void check​(int minCursor, int maxCursor, DotPair dp)

      • Methods inherited from class java.lang.Throwable

        addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • serialVersionUID

        public static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.

        Note that Java's java.lang.Exception and java.lang.Error classes implement the Serializable interface, and a warning-free build expects this field be defined here.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        1
        public static final long serialVersionUID = 1;

      • minCursor

        public final int minCursor
        This field is provided to the user as a matter of convenience. All instantiations of this Exception are guaranteed to enforce and ensure that when an instance of this exception is thrown, the convenience field will not be null. If this package is extended, it is up to the programmer/user to make sure not to leave this field null when using one of these constructors. This constructor will not check whether a convenience field is null or not, when constructing the exception.

        IMPORTANT: All this is really trying to explain is that, when debugging your code, if in the analysis of a particular Exception, that analysis causes another exception throw (like NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - would be an unnecessary source of headache.

        This will contain the value for minCursor defined in an HTML Node Iterator's settings for the Cursor Bounds.
        Code:
        Exact Field Declaration Expression:
        1
        public final int minCursor;

      • maxCursor

        public final int maxCursor
        This field is provided to the user as a matter of convenience. All instantiations of this Exception are guaranteed to enforce and ensure that when an instance of this exception is thrown, the convenience field will not be null. If this package is extended, it is up to the programmer/user to make sure not to leave this field null when using one of these constructors. This constructor will not check whether a convenience field is null or not, when constructing the exception.

        IMPORTANT: All this is really trying to explain is that, when debugging your code, if in the analysis of a particular Exception, that analysis causes another exception throw (like NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - would be an unnecessary source of headache.

        This will contain the value for maxCursor defined in an HTML Node Iterator's settings for the Cursor Bounds.
        Code:
        Exact Field Declaration Expression:
        1
        public final int maxCursor;

      • pos

        public final int pos
        This field is provided to the user as a matter of convenience. All instantiations of this Exception are guaranteed to enforce and ensure that when an instance of this exception is thrown, the convenience field will not be null. If this package is extended, it is up to the programmer/user to make sure not to leave this field null when using one of these constructors. This constructor will not check whether a convenience field is null or not, when constructing the exception.

        IMPORTANT: All this is really trying to explain is that, when debugging your code, if in the analysis of a particular Exception, that analysis causes another exception throw (like NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - would be an unnecessary source of headache.

        This will contain the value for passed to an HNLI Iterator 'setter' method which was not within the bounds of the supplied Cursor Boundary Window.
        Code:
        Exact Field Declaration Expression:
        1
        public final int pos;

    • Constructor Detail

      • CursorException

        public CursorException​(java.lang.String message,
                       int minCursor,
                       int maxCursor,
                       int pos)
        Constructs a new exception with the specified detail message, and the two public, final parameters: maxCursor, minCursor and pos.
        Parameters:
        message - the detail message.
        minCursor - This was the setting for the Cursor Boundary Window inside an instance of HTML Node List Iterator, when an exception threw.
        maxCursor - This was the setting for the Cursor Boundary Window inside an instance of HTML Node List Iterator, when an exception threw.
        pos - The position that generated this exception throw.
        See Also:
        minCursor, maxCursor, pos

      • CursorException

        public CursorException​(java.lang.String message,
                       java.lang.Throwable cause,
                       int minCursor,
                       int maxCursor,
                       int pos)
        Constructs a new exception with the specified detail message, and the two public, final parameters: maxCursor, minCursor and pos.
        Parameters:
        message - The detail message (which is saved for later retrieval by the Throwable.getMessage() method).
        cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown).
        minCursor - This was the setting for the Cursor Boundary Window inside an instance of HTML Node List Iterator, when an exception threw.
        maxCursor - This was the setting for the Cursor Boundary Window inside an instance of HTML Node List Iterator, when an exception threw.
        pos - The position that generated this exception throw.
        See Also:
        minCursor, maxCursor, pos

    • Method Detail

      • check

        public static void check​(int minCursor,
                         int maxCursor,
                         int pos)
        Checks that a supplied position parameter, 'pos', is within the bounds of a given window, and throws an appropriately formatted exception if it is not.
        Parameters:
        minCursor - This is the setting for a Cursor Boundary Window which was applied to an instance of HTML Node List Iterator, when an exception threw.
        maxCursor - This is the setting for a Cursor Boundary Window which was applied to an instance of HTML Node List Iterator, when an exception threw.
        pos - This is the position to be checked against the window bounds.
        Throws:
        CursorException - Throws this exception if the provided position parameter 'pos' is not within the supplied Cursor Bounds.
        See Also:
        minCursor, maxCursor, pos
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
         if ((maxCursor == -1) && (minCursor == -1)) return;

 if (pos < minCursor) throw new CursorException(
     "This iterator has had a Minimum-Cursor index [" + minCursor + "] set using the " +
     "restrictCursor(...) method.  Unfortunately, the position passed as a " +
     "parameter [" + pos + "], is less than this minimum-cursor index.",
     minCursor, maxCursor, pos
 );

 if (pos > maxCursor) throw new CursorException(
     "This iterator has had a Maximum-Cursor index [" + maxCursor + "] set using the " +
     "restrictCursor(...) method.  Unfortunately, the DotPair 'range' passed as a " +
     "parameter [" + pos + "], is greater than this maximum-cursor index.",
     minCursor, maxCursor, pos
 );

      • check

        public static void check​(int minCursor,
                         int maxCursor,
                         DotPair dp)
        Checks that a supplied DotPair parameter, 'dp', is FULLY within the bounds (READ: both DotPair.start and DotPair.end) of a given window, and throws an appropriately formatted exception if it is not.
        Parameters:
        minCursor - This is the setting for a Cursor Boundary Window which was applied to an instance of HTML Node List Iterator, when an exception threw.
        maxCursor - This is the setting for a Cursor Boundary Window which was applied to an instance of HTML Node List Iterator, when an exception threw.
        dp - This is the sub-list or sub-section to be checked against the window bounds. It must fully lay within the provided window in order for this method to avoid throwing the CursorException.
        Throws:
        CursorException - Throws this exception if the provided position parameter 'pos' is not within the supplied Cursor Bounds.
        See Also:
        minCursor, maxCursor, pos
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
         if ((maxCursor == -1) && (minCursor == -1)) return;

 if (dp.start < minCursor) throw new CursorException(
     "This iterator has had a Minimum-Cursor index [" + minCursor + "] set using the " +
     "restrictCursor(...) method.  Unfortunately, the DotPair 'range' " + dp + " passed " +
     "as a paremter starts before this minimum-cursor index.",
     minCursor, maxCursor, dp.start
 );

 if (dp.end > maxCursor) throw new CursorException(
     "This iterator has had a Maximum-Cursor index [" + maxCursor + "] set using the " +
     "restrictCursor(...) method.  Unfortunately, the DotPair 'range' " + dp + " passed " +
     "as a paremter extends past this maximum-cursor index.",
     minCursor, maxCursor, dp.end
 );

      • check

        public static void check​(int minCursor,
                         int maxCursor,
                         int[] posArr)
        Checks that each an every index-position from a supplied position-array parameter, 'posArr', is within the bounds of a given window, and throws an appropriately formatted exception if any of the indices in 'posArr' are not within the windows bounds.
        Parameters:
        minCursor - This is the setting for a Cursor Boundary Window which was applied to an instance of HTML Node List Iterator, when an exception threw.
        maxCursor - This is the setting for a Cursor Boundary Window which was applied to an instance of HTML Node List Iterator, when an exception threw.
        posArr - This is the int[] position-array to be checked against the window bounds. It value in this array must be within the provided window in order for this method to avoid throwing the CursorException.
        Throws:
        CursorException - Throws this exception if the provided position parameter 'pos' is not within the supplied Cursor Bounds.
        See Also:
        minCursor, maxCursor, pos
        Code:
        Exact Method Body:
         1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
         if ((maxCursor == -1) && (minCursor == -1)) return;

 int pos; // Temp Var

 for (int i=0; i < posArr.length; i++)
     if ((pos=posArr[i]) < minCursor) throw new CursorException(
         "This iterator has had a Minimum-Cursor, index [" + minCursor + "] set using " +
         "the restrictCursor(...) method.  Unfortunately, One of the elements of the " +
         "indices-list var-args array (parameter 'posArr') contains a Vector-position " +
         "index [" + pos + "], at varargs-array index [" + i + "] that is less than " +
         "this Minimum Cursor Vale.", minCursor, maxCursor, pos
     );
     else if (pos > maxCursor) throw new CursorException(
         "This iterator has had a Maximum-Cursor, index [" + maxCursor + "] set using " +
         "the setCursorBounds(...) method.  Unfortunately, One of the elements of the " +
         "indices-list var-args array (parameter 'posArr') contains a Vector-position " +
         "index [" + pos + "], at varargs-array index [" + i + "] that is greater than " +
         "this Maximum Cursor Vale.", minCursor, maxCursor, pos
     );