Class TCCompareStrException

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    CSSStrException

    public class TCCompareStrException
    extends java.lang.IllegalArgumentException
    TCCompareStrException - Documentation.

    This class does some passed-parameter checking for the HTML-Search routines, such as: FIND, GET, REMOVE, POLL, etc... If one is using the class TextComparitor, it is important to remember that it usually works in coordination with Java's var-args syntax which allows anywhere from '0' to 'n' String's. This class of Exception will be thrown if any one of them is null, or if zero arguments were passed to the var-args syntax.

    This class provides some public final "inspection & convenience" fields which are guaranteed not to be null when this Exception is thrown by an internal method to the HTML Node-Search package. 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



    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method
      static void check​(String... compareStr)
      • 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;
        
      • compareStrVec

        public final java.util.Vector<java.lang.String> compareStrVec
        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 should contain the list of compare-String's passed for a parameter list to a TextComparitor.
        Code:
        Exact Field Declaration Expression:
        1
        public final Vector<String> compareStrVec;
        
      • i

        public final int i
        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 field is intended to store the index into the 'compareStrVec' of the compare-String that caused the exception throw in the first place.
        Code:
        Exact Field Declaration Expression:
        1
        public final int i;
        
    • Constructor Detail

      • TCCompareStrException

        public TCCompareStrException​(java.lang.String message,
                                     java.lang.String[] compareStr,
                                     int i)
        Constructs a new exception with the specified detail message, and the two public, final parameters: compareStr and i.
        Parameters:
        message - the detail message.
        compareStr - This SHOULD BE the list of compare-String's that were passed to a TextComparitor that may have contained a null value, or was empty. It is important not to pass null for this parameter, because checking the input to an exception's constructor is not very wise... "Exceptions about Exceptions" is usually unintelligible to a programmer.
        i - This is the index into the 'compareStr' var-args parameter list that caused the exception to throw.
        See Also:
        compareStrVec, i
      • TCCompareStrException

        public TCCompareStrException​(java.lang.String message,
                                     java.lang.Throwable cause,
                                     java.lang.String[] compareStr,
                                     int i)
        Constructs a new exception with the specified detail message, cause-chain throwable, and the two public, final parameters: compareStr and i.
        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.)
        compareStr - This SHOULD BE the list of compare-String's that were passed to a TextComparitor that may have contained a null value, or was empty. It is important not to pass null for this parameter, because checking the input to an exception's constructor is not very wise... "Exceptions about Exceptions" is usually unintelligible to a programmer.
        i - This is the index into the 'compareStr' var-args parameter list that caused the exception to throw.
        See Also:
        compareStrVec, i
    • Method Detail

      • check

        public static void check​(java.lang.String... compareStr)
        This will do a simple test of the compare-String's to make sure none of them are null, and that there are at least one String in the String[] array.

        REASON It is a subtle issue, but likely better to throw exceptions when one of the var-args to a String comparison is 'null' Java asserts, generally that two null's do not equal each-other, although testing if a reference is 'null' (obviously) is fine. Generally, the concept that a String-comparing-loop would just "skip" null compare-String's may seem all right, unfortunately there is a diffence between the way a String-compare 'AND,' a String-compare 'OR,' vs. a String-compare 'XOR' should behave. Since there is likely no general-convention or agreement on what null in the presence of logical AND, OR, NOT, XOR, NAND really means, throwing a StrCmprException when even one var-args String-parameters is 'null' actually makes the most sense.
        Parameters:
        compareStr - This should be the var-args parameter that was passed to a search method
        Throws:
        TCCompareStrException - If any of the elements of 'compareStr' is null, or if the String[] array is zero-length.
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
         if (compareStr == null) throw new NullPointerException
             ("The compareStr varags parameter, itself, was null.");
        
         if (compareStr.length == 0) throw new TCCompareStrException(
             "You have passed zero-arguments to a search-method's var-args String... " +
             "parameter.  You must pass at least one non-null compare-string",
             compareStr, 0
         );
        
         for (int i=0; i < compareStr.length; i++)
             if (compareStr[i] == null) throw new TCCompareStrException(
                 "One of the compare-strings passed to a search-method's var-args " +
                 "String... parameter was null.  This is not allowed.",
                 compareStr, i
             );