Package Torello.Java

Class ParallelArrayException

  • All Implemented Interfaces:
    java.io.Serializable

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

    This may be used to check that array lengths are equal, and if not, this exception should throw The primary value of this class is that it will provide consistently worded and formatted error messages, using the three check(...) methods provided.

    Note that you may also request that the checker look for nulls, and throw a NullPointerException if nulls are found. Furthermore, primitive-arrays may also be checked.
    See Also:
    Serialized Form




    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method
      static void check​(Object arr1, String arr1Name, Object arr2, String arr2Name)
      static <T> void check​(T[] tArr, String tName, boolean throwIfHasNulls, Object arr, String arrName)
      static <T,​U>
      void
      check​(T[] tArr, String tName, boolean throwIfTHasNulls, U[] uArr, String uName, boolean throwIfUHasNulls)
      • 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;
        
    • Constructor Detail

      • ParallelArrayException

        public ParallelArrayException()
        Constructs a ParallelArrayException with no detail message.
      • ParallelArrayException

        public ParallelArrayException​(java.lang.String message)
        Constructs an ParallelArrayException with the specified detail message.
        Parameters:
        message - the detail message.
      • ParallelArrayException

        public ParallelArrayException​(java.lang.String message,
                                      java.lang.Throwable cause)
        Constructs a new exception with the specified detail 'message' and 'cause'.

        NOTE: The detail message associated with 'cause' is not automatically incorporated in this exception's detail message.
        Parameters:
        message - The detail message (which is saved for later retrieval by th 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.)
      • ParallelArrayException

        public ParallelArrayException​(java.lang.Throwable cause)
        Constructs a new exception with the specified 'cause' and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause). This constructor is useful for exceptions that are little more than wrappers for other throwables.
        Parameters:
        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.)
    • Method Detail

      • check

        public static void check​(java.lang.Object arr1,
                                 java.lang.String arr1Name,
                                 java.lang.Object arr2,
                                 java.lang.String arr2Name)
        This will check that the parameter 'arr1' (which is presumed to be an array) has an identical length to that of parameter 'arr2'. If these two arrays do not have the same length, a ParallelArrayException with throw with an error message.

        Since the purpose of this code is to generate reasonable error messages, without having to retype this sort of thing of and again, the 'Variable Name' of the arrays are required as parameters. The only effects that they have on this code is that they ensure the output exception messages include those names (The array names are not part of the error checking process).

        NOTE: If for whatever reason, the caller of this method accidentally sends an Object to this method which isn't an Array at all, an exception will throw. There isn't really a way to guarantee "Compile Time Checking" for this sort of thing. Make sure this method is for checking that Array's are Parallel.

        FINALLY: Just about any type of array may be passed - including primitive-arrays (int[], float[]) etc...

        The method StrReplace.r(String, char[], char[]) makes use of this check as follows:

        Example:
        1
        2
        3
        4
        5
        6
        7
        8
         public static String r(String s, char[] matchChars, char[] replaceChars)
         {
              // Check that these arrays have equal lengths, and if not throw the 
              // ParallelArrayException.
              ParallelArrayException.check(matchChars, "matchChars", replaceChars, "replaceChars");
              ...
         }
         
        
        Parameters:
        arr1 - This may be any primitive or Object[] array.
        arr1Name - This should be the 'Variable Name' of that array, in your code. This is merely used for 'Pretty Printing' purposes.
        arr2 - This may be any other primitive or Object[] array.
        arr2Name - This should be the 'Variable Name' of the second array.
        Throws:
        ParallelArrayException - This exception throws if the arrays don't have equal lengths.
        ArrayExpectedError - If a non-Array Object is passed to either of the Array Parameters. An 'Error' is thrown, rather than an 'Exception' since the purpose of this check is to identify parallel arrays. Providing a non-array reference to this method signals a flaw in the code itself.
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
         if (arr1 == null) NPE(arr1Name);
         if (arr2 == null) NPE(arr2Name);
        
         if (! arr1.getClass().isArray()) throw new ArrayExpectedError
             ("Array Parameter '" + arr1Name + "' is not an array.");
        
         if (! arr2.getClass().isArray()) throw new ArrayExpectedError
             ("Array Parameter '" + arr2Name + "' is not an array.");
                
         CHECK(
             arr1, java.lang.reflect.Array.getLength(arr1), arr1Name,
             arr2, java.lang.reflect.Array.getLength(arr2), arr2Name
         );
        
      • check

        public static <T> void check​(T[] tArr,
                                     java.lang.String tName,
                                     boolean throwIfHasNulls,
                                     java.lang.Object arr,
                                     java.lang.String arrName)
        This will check that the parameter 'tArr' has an identical length to that of parameter 'arr' (which is presumed to be an array). If these two arrays do not have the same length, a ParallelArrayException with throw with an error message.

        This method differs from the previous check(Object, String, Object, String), in that the Variable-Type Parameter '<T>' guarantees that at least one of the parameters must be an array. This facilitates another check - that for nulls in the array. It may or may not be desired to check for the prescense of 'null', but if it is that can be requested by passing 'TRUE' to the parameter 'throwIfHasNulls'.

        The StrReplace.r(boolean, String, String[], char[]) utilizes this method as below:

        Example:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
         public static String r
              (boolean ignoreCase, String s, String[] matchStrs, char[] replaceChars)
         {
              // Make sure the 'matchStrs' array is parallel to 'replaceChars', and also make sure
              // 'matchStr' does not have null elements.  If not, throw ParallelArrayException
              ParallelArrayException.check
                  (matchStrs, "matchStrs", true, replaceChars, "replaceChars");
              ...
         }
         
        
        Parameters:
        tArr - This may be any Object[] instance array.
        tName - This should be the 'Variable Name' of that array, in your code. This is merely used for 'Pretty Printing' purposes.
        throwIfHasNulls - This parameter requests to check for the presence of a 'null' inside the 'tArr' array, and will throw a NullPointerException is one is found.
        arr - This may be any primitive or Object[] array.
        arrName - This should be the 'Variable Name' of the second array.
        Throws:
        ParallelArrayException - This exception throws if the arrays don't have equal lengths.
        java.lang.NullPointerException - This exception throws if the 'tArr' contains any 'null' values.
        ArrayExpectedError - If a non-Array Object is passed to either of the Array Parameters. An 'Error' is thrown, rather than an 'Exception' since the purpose of this check is to identify parallel arrays. Providing a non-array reference to this method signals a flaw in the code itself.
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
         if (tArr == null)   NPE(tName);
         if (arr == null)    NPE(arrName);
        
         if (! arr.getClass().isArray()) throw new ArrayExpectedError
             ("Array Parameter '" + arrName + "' is not an array.");
        
         CHECK(tArr, tArr.length, tName, arr, Array.getLength(arr), arrName);
        
         if (throwIfHasNulls)
             for (int i=0; i < tArr.length; i++)
                 if (tArr[i] == null)
                     throw new NullPointerException(
                         tName + '[' + i + "] (" + tArr.getClass().getSimpleName() + ") " +
                         "contains a null reference."
                     );
        
      • check

        public static <T,​U> void check​(T[] tArr,
                                             java.lang.String tName,
                                             boolean throwIfTHasNulls,
                                             U[] uArr,
                                             java.lang.String uName,
                                             boolean throwIfUHasNulls)
        This will check that the parameter 'tArr' has an identical length to that of parameter 'arr' (which is presumed to be an array). If these two arrays do not have the same length, a ParallelArrayException with throw with an error message.

        This method differs from the previous check(Object, String, Object, String), in that using Variable-Type Parameters ('<T>' and '<U>') guarantee that both parameters are arrays. The purpose here is that it facilitates another check - that for the presence of 'nulls'. It may or may not be desired to check for the prescense of 'null' within the arrays, but if it is, simply pass 'TRUE' to either of the 'throwIfHasNulls' parameters, and the corresponding array will be checked.

        This check is used by StrReplace.r(boolean, String, String[], String[]) as below:

        Example:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
         public static String r
              (boolean ignoreCase, String s, String[] matchStrs, String[] replaceStrs)
         {
              // Make sure these arrays are parallel, and if not throw ParallelArrayException
              // If there are any 'null' values in these arrays, throw NullPointerException
              ParallelArrayException.check
                  (matchStrs, "matchStrs", true, replaceStrs, "replaceStrs", true);
              ...
         }
         
        
        Parameters:
        tArr - This may be any Object[] instance array.
        tName - This should be the 'Variable Name' of that array, in your code. This is merely used for 'Pretty Printing' purposes.
        throwIfTHasNulls - This parameter requests to check for the presence of a 'null' inside the 'tArr' array, and will throw a NullPointerException is one is found.
        uArr - This may be any Object[] instance array.
        uName - This should be the 'Variable Name' of that array, in your code. This is merely used for 'Pretty Printing' purposes.
        throwIfUHasNulls - This parameter requests to check for the presence of a 'null' inside the 'uArr' array, and will throw a NullPointerException is one is found.
        Throws:
        ParallelArrayException - This exception throws if the arrays don't have equal lengths.
        java.lang.NullPointerException - This exception throws if the 'tArr' contains any 'null' values.
        Code:
        Exact Method Body:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
         if (tArr == null) NPE(tName);
         if (uArr == null) NPE(uName);
        
         CHECK(tArr, tArr.length, tName, uArr, uArr.length, uName);
        
         if (throwIfTHasNulls)
             for (int i=0; i < tArr.length; i++)
                 if (tArr[i] == null)
                     throw new NullPointerException(
                         tName + '[' + i + "] (" + tArr.getClass().getSimpleName() + ") " +
                         "contains a null reference."
                     );
        
         if (throwIfUHasNulls)
             for (int i=0; i < uArr.length; i++)
                 if (uArr[i] == null)
                     throw new NullPointerException(
                         uName + "[" + i + "] (" + uArr.getClass().getSimpleName() + ") " +
                         "contains a null reference."
                     );