Package Torello.Java

Class ParallelArrayException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

java.lang.IllegalArgumentException

Torello.Java.ParallelArrayException

All Implemented Interfaces:

java.io.Serializable

public class ParallelArrayException
extends java.lang.IllegalArgumentException

This may be used to check that array have equal lengths - if two or more arrays are expected to be parallel, but their lengths are not equal, then this exception should be thrown. This class also provides multiple 'check' methods that will automatically scan for the specific error cases, and it will provide consistently worded and formatted error messages to the invoking code.

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

Hi-Lited Source-Code:

• View Here: Torello/Java/ParallelArrayException.java
• Open New Browser-Tab: Torello/Java/ParallelArrayException.java

File Size: 14,848 Bytes Line Count: 320 '\n' Characters Found

Field Summary

Serializable ID
Modifier and Type	Field
static long	serialVersionUID

Constructor Summary

Constructors

Constructor	Description
ParallelArrayException()	Constructs a ParallelArrayException with no detail message.
ParallelArrayException(String message)	Constructs an ParallelArrayException with the specified detail message.
ParallelArrayException(String message, Throwable cause)	Constructs a new exception with the specified detail 'message' and 'cause'.
ParallelArrayException(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).

Method Summary

'static' Exception Check 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:

 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 into 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:

 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:

 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:

 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");
      ...
 }

Type Parameters:

T - This type-parameter is merely being utilized to allow any array type to be received by this method. It is nothing more than a place-holder (similar to the '?' for generic classes).

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:

 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:

 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);
      ...
 }

Type Parameters:

T - This type-parameter is merely being utilized to allow any array type to be received by this method. It is nothing more than a place-holder (similar to the '?' for generic classes).

U - This type-parameter is merely being utilized to allow any array type to be received by this method. It is nothing more than a place-holder (similar to the '?' for generic classes).

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:

 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."
             );