Package Torello.Java

Class StrCmprException

  • All Implemented Interfaces:
    java.io.Serializable
    public class StrCmprException
extends java.lang.IllegalArgumentException
    An exception that performs a little bit of passed-parameter checking for the class StrCmpr.

    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


    • Field Summary

       
      Serializable ID
      Modifier and Type Field
      static long serialVersionUID
       
      'final' Exception Convenience Fields
      Modifier and Type Field
      Vector<String> compareStrVec
      int i

    • Constructor Summary

      Constructors 
      Constructor Description
      StrCmprException​(String message, String[] compareStr, int i)
      Constructs a new exception with the specified detail 'message', and the two public, final parameters: compareStr and i.
      StrCmprException​(String message, Throwable cause, 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.

    • Method Summary

       
      'static' Exception Check 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:
         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 instances of this Exception ought to guarantee that when an instance is thrown - any & all "Convenience Fields" have been properly set.

        If this package is extended, or if this exception is used elsewhere, try to remember to not to accidentally leave this field null when using this class' constructors.

        In Summary:
        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 (NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - you would likely get pretty angry.

        This should contain the list of compare-String's passed for a parameter list to class StrCmpr.

      • i

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public final int i
        This field is provided to the user as a matter of convenience. All instances of this Exception ought to guarantee that when an instance is thrown - any & all "Convenience Fields" have been properly set.

        If this package is extended, or if this exception is used elsewhere, try to remember to not to accidentally leave this field null when using this class' constructors.

        In Summary:
        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 (NullPointerException) - BECAUSE THIS CONVENIENCE FIELD WAS LEFT NULL - you would likely get pretty angry.

        This field is intended to store the index into the compareStrVec of the compare-String that caused the exception throw in the first place.

    • Constructor Detail

      • StrCmprException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public StrCmprException​(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 - This should be a well-formatted message informing the user what has occurred.
        compareStr - This SHOULD BE the list of compare-String's that were passed to the class StrCmpr methods that may have contained a null value, or was empty.

        This parameter should not be left null. If it were accidentally left null, this could force exception-handling code to to throw an exception itself - while checking exceptions! Note that checking the input to this constructor does occur, and if this parameter is passed a null value, an instance of Torello.Java.ExceptionCheckError will throw.
        i - This is the index into the 'compareStr' var-args parameter list that cause the exception to throw. This value must be between 0 and comparestr.length - 1, or ExceptionCheckError will throw.
        Throws:
        ExceptionCheckError - If parameter 'compareStr' is passed null, or if parameter 'i' is not a valid array-index into 'compareStr'.
        See Also:
        compareStrVec, i

      • StrCmprException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public StrCmprException​(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 - This should be a well-formatted message informing the user what has occurred.
        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-String's that were passed to a class StrCmpr method that may have contained a null value, or was empty.

        This parameter should not be left null. If it were accidentally left null, this could force exception-handling code to to throw an exception itself - while checking exceptions! Note that checking the input to this constructor does occur, and if this parameter is passed a null value, an instance of Torello.Java.ExceptionCheckError will throw.
        i - This is the index into the 'compareStr' var-args parameter list that cause the exception to throw. This value must be between 0 and comparestr.length - 1, or ExceptionCheckError will throw.
        Throws:
        ExceptionCheckError - If parameter 'compareStr' is passed null, or if parameter 'i' is not a valid array-index into 'compareStr'.
        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 array.

        Explanation:
        It is a subtle issue, but likely better to throw exceptions when one of the Varargs to a String comparison is 'null'. 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 String[] array-parameter that was passed to a search method
        Throws:
        TCCompareStrException - If any of the elements of compareStr are null, or if the array is zero-length.
        Code:
        Exact Method Body:
         if (compareStr == null) throw new NullPointerException
     ("The compareStr varags parameter, itself, was null.");

 if (compareStr.length == 0) throw new StrCmprException(
     "You have passed zero-arguments to a StrCmpr 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 StrCmprException(
         "One of the compare-strings passed to a search-method's var-args String... parameter " +
         "was null.  This is not allowed.",
         compareStr, i
     );