Class CSSStrException

  • All Implemented Interfaces:
    java.io.Serializable

    public class CSSStrException
    extends TCCompareStrException
    CSSStrException - Documentation.

    This class does some passed-parameter checking for the HTML-Search routines. 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 the String's passed to the var-args parameter with the TextComparitor them has an invalid CSS Token according to the definition of valid CSS Naming-Convention Tokens.

    NOTE: This exception test is only performed when a TextComparitor is used with one of the TagNode CSS 'class' getter and setter methods, for example: TagNode.setCSSClasses​(SD, boolean, String[])

    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



    • Constructor Summary

      Constructors 
      Constructor
      CSSStrException​(String message, String[] compareStr, int i)
      CSSStrException​(String message, Throwable cause, String[] compareStr, int i)
    • Method Summary

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

        public static final java.util.regex.Pattern VALID_CSS_CLASS_OR_NAME_TOKEN
        This regular-expression can be used to identify valid versus invalid CSS Class-Names, and also CSS ID-Names. In English, this regular-expression says: A valid name should start with an underscore (_), a hyphen (-) or a letter (a-z) which is followed by any numbers, hyphens, underscores, letters. A name should be at least two characters long. Cannot start with a digit, two hyphens or a hyphen followed by a number.
        Code:
        Exact Field Declaration Expression:
        1
        2
        public static final Pattern VALID_CSS_CLASS_OR_NAME_TOKEN = 
                Pattern.compile("^[_\\-a-zA-Z]+[_\\-a-zA-Z0-9]*$");
        
    • Constructor Detail

      • CSSStrException

        public CSSStrException​(java.lang.String message,
                               java.lang.String[] compareStr,
                               int i)
        This constructor just calls the line: super(message, compareStr, i);
        Parameters:
        message - the detail message.
        compareStr - This SHOULD BE the list of compare-strings 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 cause the exception to throw.
      • CSSStrException

        public CSSStrException​(java.lang.String message,
                               java.lang.Throwable cause,
                               java.lang.String[] compareStr,
                               int i)
        This constructor just calls the line: super(message, cause, compareStr, i);
        Parameters:
        message - The detail message (which is saved for later retrieval by the Throwable.getMessage() method).
        cause - This is sometimes used to "chain" exceptions in multi-threaded or heavily I/O related code.
        compareStr - This SHOULD BE the list of compare-strings 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 cause the exception to throw.
    • 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 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 difference 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-parameter is 'null' actually makes the most sense.
        Parameters:
        compareStr - This should be the var-args parameter that was passed to a search method
        Throws:
        CSSStrException - If any of the elements of Var-Args parameter 'compareStr' is null, or if the array is zero-length.
        See Also:
        VALID_CSS_CLASS_OR_NAME_TOKEN, TCCompareStrException.check(String[])
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
         // Repackages the Exception into one with the name CSSStrException
         try
             { TCCompareStrException.check(compareStr); }
         catch (TCCompareStrException e)
         {
             String[] tempV = new String[compareStr.length];
             throw new CSSStrException(
                 e.getMessage() + "\nSee getCause() for details.",
                 e, e.compareStrVec.toArray(tempV), e.i
             );
         }
        
         for (int i=0; i < compareStr.length; i++) 
             if (! VALID_CSS_CLASS_OR_NAME_TOKEN.matcher(compareStr[i]).find())
                 throw new CSSStrException(
                     "One of the compare-strings passed to a search-method's var-args String " +
                     "parameter 'compareStr': [" + compareStr[i] + "]\n" +
                     "Did not pass the CSS Token-Naming Testing Regular-Expression: " +
                     "[" + VALID_CSS_CLASS_OR_NAME_TOKEN.pattern() + "]\n" +
                     "And this means it has been identified as an invalid CSS Token.  " +
                     "This is not allowed here.\n" +
                     "If you are using TagNode.cssClasses(), switch to TagNode.AV('class').\n" +
                     "If you are using TextComparitor.CONTAINS_CSS_CLASS*, switch to " +
                     "TextComparitor.EQ_CI_TRM",
                     compareStr, i);
        
      • check

        public static java.util.stream.Stream<java.lang.String> check​
                    (java.util.stream.Stream<java.lang.String> compareStrs)
        
        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 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 difference 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-parameter is 'null' actually makes the most sense.
        Parameters:
        compareStrs - This should be the any instance of Stream<String>
        Throws:
        CSSStrException - If any of the elements of the compareStrs stream are null, or if the stream is empty.
        See Also:
        VALID_CSS_CLASS_OR_NAME_TOKEN, TCCompareStrException.check(String[])
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
         // Repackages the Exception into one with the name CSSStrException
         String[] compareStr = compareStrs.toArray(String[]::new);
        
         try
             { TCCompareStrException.check(compareStr); }
         catch (TCCompareStrException e)
         {
             String[] tempV = new String[compareStr.length];
             throw new CSSStrException(
                 e.getMessage() + "\nSee getCause() for details.",
                 e, e.compareStrVec.toArray(tempV), e.i);
         }
        
         for (int i=0; i < compareStr.length; i++) 
             if (! VALID_CSS_CLASS_OR_NAME_TOKEN.matcher(compareStr[i]).find())
                 throw new CSSStrException(
                     "One of the compare-strings passed to a search-method's var-args String " +
                     "parameter 'compareStr': [" + compareStr[i] + "]\n" +
                     "Did not pass the CSS Token-Naming Testing Regular-Expression: " +
                     "[" + VALID_CSS_CLASS_OR_NAME_TOKEN.pattern() + "]\n" +
                     "And this means it has been identified as an invalid CSS Token.  " +
                     "This is not allowed here.\n" +
                     "If you are using TagNode.cssClasses(), switch to TagNode.AV('class').\n" +
                     "If you are using TextComparitor.CONTAINS_CSS_CLASS*, switch to " +
                     "TextComparitor.EQ_CI_TRM",
                     compareStr, i);
        
         return Stream.of(compareStr);
         // The original stream is now empty!  We must re-build it!