Class ARGCHECK

  • public class ARGCHECK
extends java.lang.Object
    This class is used internally to do argument validity-checks, and guarantees consistent exception-message reporting.

    This class is a 'public' class in this package not because of its exceptional usability or usefullness, but rather so that it remains visible in case a programmer wishes to see how the validity-checking mechanisms work in this 'NodeSearch' package.



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 13 Method(s), 13 declared static
    • 2 Field(s), 2 declared static, 2 declared final


    • Field Detail

      • TRUE

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<java.lang.String> TRUE
        Code:
        Exact Field Declaration Expression:
         public static final Predicate<String> TRUE = (String innerTagValue) -> true;

      • CSSTCs

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final TextComparitor[] CSSTCs
        This just keeps a short list of all the instance-objects of class TextComparitor that perform the "CSS Class" Checks. These TextComparitor's, when used with a var-args String[] array input, should have a finer-grain of exception checking and error checking performed on their inputs. Checking to ensure CSS Class String's inside of HTML Elements are only checked against valid CSS-Names is possible in this argument-checking class.
        Code:
        Exact Field Declaration Expression:
         protected static final TextComparitor[] CSSTCs =
     { 
         TextComparitor.C, TextComparitor.C_OR, TextComparitor.C_AND, 
         TextComparitor.C_NAND, TextComparitor.C_XOR
     };

    • Method Detail

      • n

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static int n​(int nth,
                    java.util.Vector<?> v)
        Internally Used. Checks for valid values of 'nth' to the search methods nth and nthFromEnd.
        Parameters:
        nth - This is a number identify which search-match to return. If n = 3, the third match shall be returned. Remember to ensure that a negative number is not passed, nor a number too large.
        v - This should be the html-Vector on which a search is being performed.

        The symbols <?> appended to the (almost) 'raw-type' here, are only there to prevent the java-compiler from issuing warnings regarding the use of "Raw Types." This warning is, actually, only issued if the command-line option -Xlint:all option is used.
        Throws:
        NException - When a negative value for 'nth' is passed, or 'nth' is greater than the size of the Vector.
        Code:
        Exact Method Body:
         NException.check(nth, v);
 return nth;

      • htmlTag

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String htmlTag​(java.lang.String htmlTag)
        Internally Used. Checks for valid and invalid HTML Token arguments to all search methods. Calls Java String method toLowerCase() on HTML Token and returns it. All HTML tokens are stored in lower-case form internally, for quicker comparisons.
        Parameters:
        htmlTag - Make sure the user is searching for a valid HTMT Element. If new tags have been added to the java Collection (internally represented by class java.util.TreeSet), make sure the check those too.
        Throws:
        HTMLTokException - When an invalid HTML Token Element is passed.
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        HTMLTags
        Code:
        Exact Method Body:
         HTMLTokException.check(htmlTag);
 return htmlTag.toLowerCase();

      • htmlTags

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String[] htmlTags​(java.lang.String... htmlTags)
        Internally Used. Checks multiple HTML Token arguments to all search methods for validity. Calls Java String method String.toLowerCase() on each HTML Token and returns the array of tokens - all in lower-case. All HTML tokens are stored in lower-case form internally, for quicker comparisons.

        Save Var-Args:
        Here, the Var-Args String[]-Array parameter 'htmlTags' is not modified at all. Upon invocation, this method creates a new instance of the imported String[]-Array (using lower-cased String's stored in place of the originals).

        All Java-String's are immutable, and here new lower-case String's are being saved to a newly instantiated array. The original input parameter will not be modified.
        Parameters:
        htmlTags - These are a list of html-tags to be checked.
        Throws:
        HTMLTokException - When any invalid HTML Token Element is passed.
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        HTMLTags, HTMLTokException.check(String[])
        Code:
        Exact Method Body:
         HTMLTokException.check(htmlTags);

 String[] ret = new String[htmlTags.length];

 for (int i=0; i < htmlTags.length; i++) ret[i] = htmlTags[i].toLowerCase();

 return ret;

      • innerTag

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static java.lang.String innerTag​(java.lang.String innerTag)
        Internally Used. Checks validity of inner-tag arguments to search routines. Returns lower-case version of the inner-tag.
        Throws:
        InnerTagKeyException - If an inner-tag value is invalid.
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        InnerTagKeyException.check(String[])
        Code:
        Exact Method Body:
         InnerTagKeyException.check(innerTag);
 return innerTag.toLowerCase();

      • TC

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<java.lang.String> TC​
            (TextComparitor tc,
             java.lang.String... compareStr)
        Internally Used. Checks validity of the TextComparitor String's, and the TextComparitor. Wraps the TextComparitor and its String... compareStr arguments into a Java Lambda Predicate<String>.
        Parameters:
        tc - Any valid instance of TextComparitor
        compareStr - A varargs String[] array of test-String's.
        Returns:
        This returns a String-Predicate that uses the provided TextComparitor and its associated 'compareStr' String[] array list to test input String's.
        Throws:
        TCCompareStrException - This is thrown for invalid search parameters. Review the Exception class itself for what constitutes invalid parameter data.
        CSSStrException - If one of the provided comparison String's is not a valid CSS name, and the TextComparitor passed is a CSS Class Test TextComparitor.
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        TCCompareStrException.check(String[]), TextComparitor, TextComparitor.test(String, String[])
        Code:
        Exact Method Body:
         if (tc == null) throw new NullPointerException(
     "You have passed a null value to the parameter TextComparitor here, " +
     "but this is not allowed."
 );

 TCCompareStrException.check(compareStr);

 for (TextComparitor cssTC : CSSTCs)
     if (cssTC == tc)
     { CSSStrException.check(compareStr); break; }

 // String[] cmpStr = compareStr.clone(); // MADNESS, ISN'T IT?
 return (String innerTagValue) -> tc.test(innerTagValue, compareStr);

      • TC_TXNP

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<TextNode> TC_TXNP​
            (TextComparitor tc,
             java.lang.String... compareStr)
        Internally Used. Checks validity of the TextComparitor String's, and the TextComparitor. Wraps the TextComparitor and its String... compareStr arguments into a Java Lambda Predicate<String>.
        Parameters:
        tc - Any valid instance of TextComparitor
        compareStr - A varargs String[] array of test-String's.
        Returns:
        This returns a Predicate<TextNode> that uses the provided TextComparitor and compareStr's to test input TextNode's using the 'TextNode.str' field.
        Throws:
        TCCompareStrException - This is thrown for invalid search parameters. Review the Exception class itself for what constitutes invalid parameter data.
        CSSStrException - If one of the provided compareStr's is not a valid CSS name, and the TextComparitor passed is a CSS Class Test TextComparitor.
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        TCCompareStrException.check(String[]), TextComparitor, TextComparitor.test(String, String[]), HTMLNode.str, HTMLNode.str
        Code:
        Exact Method Body:
         if (tc == null) throw new NullPointerException(
     "You have passed a null value to the parameter TextComparitor here, " +
     "but this is not allowed."
 );

 TCCompareStrException.check(compareStr);

 for (TextComparitor cssTC : CSSTCs)
     if (cssTC == tc)
         { CSSStrException.check(compareStr); break; }

 // String[] cmpStr = compareStr.clone(); // MADNESS, ISN'T IT?
 return (TextNode txn) -> tc.test(txn.str, compareStr);

      • TC_CNP

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<CommentNode> TC_CNP​
            (TextComparitor tc,
             java.lang.String... compareStr)
        Internally Used. Checks validity of the TextComparitor String's, and the TextComparitor. Wraps the TextComparitor and its String... compareStr arguments into a Java Lambda Predicate.
        Parameters:
        tc - Any valid instance of TextComparitor
        compareStr - A varargs String[] array of test-String's.
        Returns:
        This returns a Predicate<CommentNode> that uses the provided TextComparitor and compareStr's to test input CommentNode's using the CommentNode.body field.
        Throws:
        TCCompareStrException - This is thrown for invalid search parameters. Review the Exception class itself for what constitutes invalid parameter data.
        CSSStrException - If one of the provided compareStr's is not a valid CSS name, and the TextComparitor passed is a CSS Class Test TextComparitor.
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        TCCompareStrException.check(String[]), TextComparitor, TextComparitor.test(String, String[]), CommentNode.body
        Code:
        Exact Method Body:
         if (tc == null) throw new NullPointerException(
     "You have passed a null value to the parameter TextComparitor here, " +
     "but this is not allowed."
 );

 TCCompareStrException.check(compareStr);

 for (TextComparitor cssTC : CSSTCs)
     if (cssTC == tc)
         { CSSStrException.check(compareStr); break; }

 // String[] cmpStr = compareStr.clone(); // MADNESS, ISN'T IT?
 return (CommentNode cn) -> tc.test(cn.body, compareStr);

      • REGEX

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<java.lang.String> REGEX​
            (java.util.regex.Pattern p)
        Internally Used. Checks that a Java Regex Pattern is not null. Wraps the reg-ex Pattern into a Java Lambda Predicate<String> Tester Expression.
        Parameters:
        p - This may be any valid input regular-expression Pattern.
        Returns:
        This shall return a Predicate<String> that tests input String's against the regular-expression.
        Throws:
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        Code:
        Exact Method Body:
         if (p == null) throw new NullPointerException(
     "You have passed a null value to a search-method's regular-expression 'Pattern' " +
     "parameter, but this is not allowed."
 );

 return p.asPredicate();

 // return (String innerTagValue) -> p.matcher(innerTagValue).find();

      • REGEX_TXNP

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<TextNode> REGEX_TXNP​
            (java.util.regex.Pattern p)
        Internally Used. Checks that a Java Regex Pattern is not null. Wraps the reg-ex Pattern into a Java Lambda Predicate<TextNode> Tester Expression.
        Parameters:
        p - This may be any valid input regular-expression Pattern.
        Returns:
        This shall return a Predicate<TextNode> that tests input TextNode's (using the TextNode.str - inherited from HTMLNode.str field) against the regular-expression.
        Throws:
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        HTMLNode.str, HTMLNode.str
        Code:
        Exact Method Body:
         if (p == null) throw new NullPointerException(
     "You have passed a null value to a search-method's regular-expression 'Pattern' " +
     "parameter, but this is not allowed."
 );

 Predicate<String> pred = p.asPredicate();

 return (TextNode txn) -> pred.test(txn.str);

 // return (TextNode txn) -> p.matcher(txn.str).find();

      • REGEX_CNP

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<CommentNode> REGEX_CNP​
            (java.util.regex.Pattern p)
        Internally Used. Checks that a Java Regex Pattern is not null. Wraps the reg-ex Pattern into a Java Lambda Predicate<CommentNode> Tester Expression.
        Parameters:
        p - This may be any valid input regular-expression pattern.
        Returns:
        This shall return a CommentNode-Predicate that tests input CommentNode's (using the CommentNode.body field) against the regular-expression.
        Throws:
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        CommentNode.body
        Code:
        Exact Method Body:
         if (p == null) throw new NullPointerException(
     "You have passed a null value to a search-method's regular-expression 'Pattern' " +
     "parameter, but this is not allowed."
 );

 Predicate<String> pred = p.asPredicate();

 return (CommentNode cn) -> pred.test(cn.body);

 // return (CommentNode cn) -> p.matcher(cn.body).find();

      • SP_TO_TXNP

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<TextNode> SP_TO_TXNP​
            (java.util.function.Predicate<java.lang.String> p)
        Internally Used. Checks that a Java Regex Pattern is not null. Wraps the reg-ex Pattern into a Java Lambda Predicate<TextNode> Tester Expression.
        Parameters:
        p - This may be any valid String-Predicate
        Returns:
        This shall return a TextNode-Predicate that "wraps" the input String-Predicate and uses the field TextNode.str (inherited from HTMLNode.str) as a value for the wrapped, "original," String-Predicate test.
        Throws:
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        HTMLNode.str, HTMLNode.str
        Code:
        Exact Method Body:
         if (p == null) throw new NullPointerException(
     "You have passed a null value to a search-method's String-Predicate 'p' parameter, " +
     "but this is not allowed."
 );

 return (TextNode txn) -> p.test(txn.str);

      • SP_TO_CNP

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final java.util.function.Predicate<CommentNode> SP_TO_CNP​
            (java.util.function.Predicate<java.lang.String> p)
        Internally Used. Checks that a Java Regex Pattern is not null. Wraps the reg-ex Pattern into a Java Lambda Predicate<CommentNode> Tester Expression.
        Parameters:
        p - This may be any valid String-Predicate
        Returns:
        This shall return a CommentNode-Predicate that "wraps" the input String-Predicate and uses the field CommentNode.body as a value for the wrapped, "original," String-Predicate test.
        Throws:
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        See Also:
        CommentNode.body
        Code:
        Exact Method Body:
         if (p == null) throw new NullPointerException(
     "You have passed a null value to a search-method's String-Predicate 'p' parameter, " +
     "but this is not allowed."
 );

 return (CommentNode cn) -> p.test(cn.body);

      • index

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static int index​(java.util.Vector<? extends HTMLNode> page,
                        int index)
        Internally Used. Checks to ensure that an index-parameter, when use in conjunction with the class Surrounding (which is sometimes referred to by the term 'Container') find methods is properly within the bounds of the HTML page.
        Parameters:
        page - This may be any valid vectorized-html page or sub-page.
        index - This is expected to be an index into the 'page' parameter-vector. If this is not a valid index, then this method shall throw an exception.
        Returns:
        This method returns the exact-value of input parameter 'index'
        Throws:
        java.lang.NullPointerException - If any of the provided input reference parameters are null.
        java.lang.IndexOutOfBoundsException - If the 'index' parameter is not a valid index into the 'page' parameter, then this exception will be thrown.
        Code:
        Exact Method Body:
         if (index < 0) throw new IndexOutOfBoundsException(
     "The index you passed [" + index + "] into vectorized-HTML page was negative, " +
     "this is not allowed here."
 );

 if (index >= page.size()) throw new IndexOutOfBoundsException(
     "The index you passed [" + index + "] into vectorized-HTML page was is greater than " +
     "the vector's size [" + page.size() + "]"
 );

 return index;