Package Torello.HTML.NodeSearch

Class CursorException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

java.lang.IllegalArgumentException

Torello.HTML.NodeSearch.CursorException

All Implemented Interfaces:

java.io.Serializable

public class CursorException
extends java.lang.IllegalArgumentException

This exception is thrown when attempts to violate a Cursor Boundary Window Contract (possibly rendering the window invalid) are made inside any of the methods exported by the AbstractHNLI, HNLI or HNLIInclusive iterators.

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 shall be ignored (cannot be returned) by the Iterator.

Internally, the Iterator 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

Hi-Lited Source-Code:

• View Here: Torello/HTML/NodeSearch/CursorException.java
• Open New Browser-Tab: Torello/HTML/NodeSearch/CursorException.java

File Size: 10,553 Bytes Line Count: 231 '\n' Characters Found

Field Summary

Serializable ID
Modifier and Type	Field
static long	serialVersionUID
'final' Exception Convenience Fields
Modifier and Type	Field
int	maxCursor
int	minCursor
int	pos

Constructor Summary

Constructors

Constructor	Description
CursorException(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.
CursorException(String message, 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.

Method Summary

'static' Exception Check 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:

 public static final long serialVersionUID = 1;

minCursor

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final int minCursor

This will contain the value for minCursor defined in an HTML Node Iterator's settings for the Cursor Bounds.

maxCursor

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final int maxCursor

This will contain the value for maxCursor defined in an HTML Node Iterator's settings for the Cursor Bounds.

pos

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public final int pos

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.

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:

 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:

 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:

 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
     );