Package org.apache.sis.util
Class ArgumentChecks
Static methods for performing argument checks.
Every methods in this class can throw one of the following exceptions:
More specialized
| Exception | Thrown by |
|---|---|
NullArgumentException |
ensureNonNull,
ensureNonEmpty.
|
IllegalArgumentException |
ensureNonEmpty,
ensurePositive,
ensureStrictlyPositive,
ensureBetween,
ensureBetween,
ensureCanCast.
|
IndexOutOfBoundsException |
ensureValidIndex.
|
MismatchedDimensionException |
ensureDimensionMatches.
|
ensureXXX(…) methods are provided in the following classes:
Method Arguments
By convention, the value to check is always the last parameter given to every methods in this class. The other parameters may include the programmatic name of the argument being checked. This programmatic name is used for building an error message localized in the default locale if the check failed.- Since:
- 0.3
Defined in the sis-utility module
-
Method Summary
Modifier and TypeMethodDescriptionstatic voidensureBetween(String name, double min, double max, double value) Ensures that the given floating point value is between the given bounds, inclusive.static voidensureBetween(String name, float min, float max, float value) Ensures that the given floating point value is between the given bounds, inclusive.static voidensureBetween(String name, int min, int max, int value) Ensures that the given integer value is between the given bounds, inclusive.static voidensureBetween(String name, long min, long max, long value) Ensures that the given long value is between the given bounds, inclusive.static voidensureCanCast(String name, Class<?> expectedType, Object value) Ensures that the specified value is null or an instance assignable to the given type.static voidensureDimensionMatches(String name, int expected, double[] vector) Ensures that the given vector, if non-null, has the expected number of dimensions (taken as its length).static voidensureDimensionMatches(String name, int expected, int[] indices) Ensures that the given array of indices, if non-null, has the expected number of dimensions (taken as its length).static voidensureDimensionMatches(String name, int expected, DirectPosition position) Ensures that the given direct position, if non-null, has the expected number of dimensions.static voidensureDimensionMatches(String name, int expected, Envelope envelope) Ensures that the given envelope, if non-null, has the expected number of dimensions.static voidensureDimensionMatches(String name, int expected, CoordinateReferenceSystem crs) Ensures that the given CRS, if non-null, has the expected number of dimensions.static voidensureDimensionMatches(String name, int expected, CoordinateSystem cs) Ensures that the given coordinate system, if non-null, has the expected number of dimensions.static voidensureDimensionsMatch(String name, int expectedSource, int expectedTarget, MathTransform transform) Ensures that the given transform, if non-null, has the expected number of source and target dimensions.static voidensureDivisor(String name, int number, int divisor) Ensures that a given value is a divisor of specified number.static voidensureExpectedCount(String name, int expected, int actual) Ensures that a method receiving a variable number of arguments got the expected count.static voidensureFinite(String name, double value) Ensures that the given floating point value is not NaN neither Double.isInfinite(double).static voidensureFinite(String name, float value) Ensures that the given floating point value is not NaN neither Float.isInfinite(float).static voidensureMultiple(String name, int number, int multiple) Ensures that a given value is a multiple of specified number.static voidensureNonEmpty(String name, int[] values, int min, int max, boolean distinct) Ensures that the givenvaluesarray is non-null and non-empty.static voidensureNonEmpty(String name, CharSequence text) Makes sure that a character sequence is non-null and non-empty.static voidensureNonEmpty(String name, Object[] array) Makes sure that an array is non-null and non-empty.static voidensureNonEmpty(String name, Collection<?> toCheck) Makes sure that given collection is non-null and non-empty.static voidensureNonNull(String name, Object object) Makes sure that an argument is non-null.static voidensureNonNullElement(String name, int index, Object element) Makes sure that an array element is non-null.static voidensurePositive(String name, double value) Ensures that the given floating point value is not NaN and is greater than or equals to zero.static voidensurePositive(String name, float value) Ensures that the given floating point value is not NaN and is greater than or equals to zero.static voidensurePositive(String name, int value) Ensures that the given integer value is greater than or equals to zero.static voidensurePositive(String name, long value) Ensures that the given long value is greater than or equals to zero.static voidensureSizeBetween(String name, int min, int max, int size) Ensures that the given collection size or array length is between the given bounds, inclusive.static voidensureStrictlyPositive(String name, double value) Ensures that the given floating point value is not NaN and is greater than zero.static voidensureStrictlyPositive(String name, float value) Ensures that the given floating point value is not NaN and is greater than zero.static voidensureStrictlyPositive(String name, int value) Ensures that the given integer value is greater than zero.static voidensureStrictlyPositive(String name, long value) Ensures that the given long value is greater than zero.static voidensureValidIndex(int upper, int index) Ensures that the given index is equal or greater than zero and lower than the given upper value.static voidensureValidIndexRange(int length, int lower, int upper) Ensures that the given index range is valid for a sequence of the given length.static voidensureValidUnicodeCodePoint(String name, int code) Ensures that the given integer is a valid Unicode code point.
-
Method Details
-
ensureNonNull
Makes sure that an argument is non-null. If the givenobjectis null, then aNullArgumentExceptionis thrown with a localized message containing the given name.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.object- the user argument to check against null value.- Throws:
NullArgumentException- ifobjectis null.
-
ensureNonNullElement
public static void ensureNonNullElement(String name, int index, Object element) throws NullArgumentException Makes sure that an array element is non-null. Ifelementis null, then aNullArgumentExceptionis thrown with a localized message containing the given name and index. The name and index are formatted as below:- If the
namecontains the"[#]"sequence of characters, then the'#'character is replaced by theindexvalue. For example ifnameis"axes[#].unit"and the index is 2, then the formatted message will contain"axes[2].unit". - If the
namedoes not contain the"[#]"sequence of characters, thenindexvalue is appended between square brackets. For example ifnameis"axes"and the index is 2, then the formatted message will contain"axes[2]".
- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.index- the Index of the element to check in an array or a list. Used only if an exception is thrown.element- the array or list element to check against null value.- Throws:
NullArgumentException- ifelementis null.
- If the
-
ensureNonEmpty
public static void ensureNonEmpty(String name, CharSequence text) throws NullArgumentException, IllegalArgumentException Makes sure that a character sequence is non-null and non-empty. If the giventextis null, then aNullArgumentExceptionis thrown. Otherwise if the giventexthas a length equals to 0, then anIllegalArgumentExceptionis thrown.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.text- the user argument to check against null value and empty sequences.- Throws:
NullArgumentException- iftextis null.IllegalArgumentException- iftextis empty.
-
ensureNonEmpty
public static void ensureNonEmpty(String name, Object[] array) throws NullArgumentException, IllegalArgumentException Makes sure that an array is non-null and non-empty. If the givenarrayis null, then aNullArgumentExceptionis thrown. Otherwise if the array length is equal to 0, then anIllegalArgumentExceptionis thrown.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.array- the user argument to check against null value and empty array.- Throws:
NullArgumentException- ifarrayis null.IllegalArgumentException- ifarrayis empty.- Since:
- 1.0
-
ensureNonEmpty
Makes sure that given collection is non-null and non-empty. If it is null, then aNullArgumentExceptionis thrown. Otherwise if it is empty, then anIllegalArgumentExceptionis thrown.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.toCheck- the user argument to check against null value and empty collection.- Throws:
NullArgumentException- iftoCheckis null.IllegalArgumentException- iftoCheckis empty.- Since:
- 1.1
-
ensureNonEmpty
public static void ensureNonEmpty(String name, int[] values, int min, int max, boolean distinct) throws IllegalArgumentException Ensures that the givenvaluesarray is non-null and non-empty. This method can also ensures that all values are between the given bounds (inclusive) and are distinct. The distinct values requirement is useful for validating arrays of spatiotemporal dimension indices, where dimensions cannot be repeated.Note that a successful call to
ensureNonEmpty(name, values, 0, max, true)implies 1 ≤values.length≤max.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.values- integer values to validate.min- the minimal allowed value (inclusive), orInteger.MIN_VALUEif none.max- the maximal allowed value (inclusive), orInteger.MAX_VALUEif none.distinct-trueif each value must be unique.- Throws:
NullArgumentException- ifvaluesis null.IllegalArgumentException- ifvaluesis empty, contains a value lower thanmin, contains a value greater thanmax, or contains duplicated values whiledistinctistrue.- Since:
- 1.0
-
ensureExpectedCount
Ensures that a method receiving a variable number of arguments got the expected count. Ifactual=expected, then this method does nothing. Otherwise a message saying "Too few" or "Too many arguments" is thrown.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.expected- expected number of arguments.actual- actual number of arguments.- Since:
- 1.0
-
ensureCanCast
public static void ensureCanCast(String name, Class<?> expectedType, Object value) throws IllegalArgumentException Ensures that the specified value is null or an instance assignable to the given type. If this method does not thrown an exception, then the value can be casted to the class represented byexpectedTypewithout throwing aClassCastException.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown. Can benullif the name is unknown.expectedType- the expected type (class or interface).value- the value to check, ornull.- Throws:
IllegalArgumentException- ifvalueis non-null and is not assignable to the given type.- See Also:
-
ensureValidIndex
Ensures that the given index is equal or greater than zero and lower than the given upper value. This method is designed for methods that expect an index value as the only argument. For this reason, this method does not take the argument name.- Parameters:
upper- the maximal index value, exclusive.index- the index to check.- Throws:
IndexOutOfBoundsException- if the given index is negative or not lower than the given upper value.- See Also:
-
ensureValidIndexRange
public static void ensureValidIndexRange(int length, int lower, int upper) throws IndexOutOfBoundsException Ensures that the given index range is valid for a sequence of the given length. This method is designed for methods that expect an index range as their only arguments. For this reason, this method does not take argument names.This method verifies only the
lowerandupperargument values. It does not not verify the validity of thelengthargument, because this information is assumed to be provided by the implementation rather than the user.- Parameters:
length- the length of the sequence (array,CharSequence, etc.).lower- the user-specified lower index, inclusive.upper- the user-specified upper index, exclusive.- Throws:
IndexOutOfBoundsException- if the given [lower…upper] range is out of the sequence index range.- See Also:
-
ensurePositive
Ensures that the given integer value is greater than or equals to zero. This method is used for checking values that are not index. For checking index values, useensureValidIndex(int, int)instead.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is negative.- See Also:
-
ensurePositive
Ensures that the given long value is greater than or equals to zero.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is negative.- See Also:
-
ensurePositive
Ensures that the given floating point value is not NaN and is greater than or equals to zero. Note that positive infinity is considered a valid value.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is NaN or negative.- See Also:
-
ensurePositive
Ensures that the given floating point value is not NaN and is greater than or equals to zero. Note that positive infinity is considered a valid value.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is NaN or negative.- See Also:
-
ensureStrictlyPositive
Ensures that the given integer value is greater than zero.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is negative or equals to zero.- See Also:
-
ensureStrictlyPositive
Ensures that the given long value is greater than zero.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is negative or equals to zero.- See Also:
-
ensureStrictlyPositive
Ensures that the given floating point value is not NaN and is greater than zero. Note that positive infinity is considered a valid value.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is NaN, zero or negative.- See Also:
-
ensureStrictlyPositive
public static void ensureStrictlyPositive(String name, double value) throws IllegalArgumentException Ensures that the given floating point value is not NaN and is greater than zero. Note that positive infinity is considered a valid value.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is NaN, zero or negative.- See Also:
-
ensureFinite
Ensures that the given floating point value is not NaN neither Float.isInfinite(float). The value can be negative, zero or positive.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is NaN or infinite.
-
ensureFinite
Ensures that the given floating point value is not NaN neither Double.isInfinite(double). The value can be negative, zero or positive.- Parameters:
name- the name of the argument to be checked, used only if an exception is thrown.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is NaN or infinite.
-
ensureBetween
public static void ensureBetween(String name, int min, int max, int value) throws IllegalArgumentException Ensures that the given integer value is between the given bounds, inclusive. This is a general-purpose method for checking integer arguments. Note that the following specialized methods are provided for common kinds of integer range checks:ensureSizeBetween(…)if thevalueargument is a collection size or an array length.ensureValidIndex(…)if thevalueargument is an index in a list or an array.
- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.min- the minimal value, inclusive.max- the maximal value, inclusive.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is not in the given range.- See Also:
-
ensureBetween
public static void ensureBetween(String name, long min, long max, long value) throws IllegalArgumentException Ensures that the given long value is between the given bounds, inclusive.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.min- the minimal value, inclusive.max- the maximal value, inclusive.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is not in the given range.
-
ensureBetween
public static void ensureBetween(String name, float min, float max, float value) throws IllegalArgumentException Ensures that the given floating point value is between the given bounds, inclusive.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.min- the minimal value, inclusive.max- the maximal value, inclusive.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is NaN or not in the given range.
-
ensureBetween
public static void ensureBetween(String name, double min, double max, double value) throws IllegalArgumentException Ensures that the given floating point value is between the given bounds, inclusive.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.min- the minimal value, inclusive.max- the maximal value, inclusive.value- the user argument to check.- Throws:
IllegalArgumentException- if the given value is NaN or not in the given range.
-
ensureSizeBetween
public static void ensureSizeBetween(String name, int min, int max, int size) throws IllegalArgumentException Ensures that the given collection size or array length is between the given bounds, inclusive. This method performs the same check thanensureBetween(…), but the error message is different in case of failure.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.min- the minimal size (inclusive), or 0 if none.max- the maximal size (inclusive), orInteger.MAX_VALUEif none.size- the user collection size or array length to be checked.- Throws:
IllegalArgumentException- if the given value is not in the given range.- See Also:
-
ensureValidUnicodeCodePoint
public static void ensureValidUnicodeCodePoint(String name, int code) throws IllegalArgumentException Ensures that the given integer is a valid Unicode code point. The range of valid code points goes fromU+0000toU+10FFFFinclusive.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.code- the Unicode code point to verify.- Throws:
IllegalArgumentException- if the given value is not a valid Unicode code point.- Since:
- 0.4
-
ensureDivisor
Ensures that a given value is a divisor of specified number. This method verifies that(number % divisor) == 0. If above condition is not met, the value considered to be wrong is the divisor.- Parameters:
name- name of the argument for the divisor value. Used only if an exception is thrown.number- the number to be divided.divisor- the value to verify.- Throws:
IllegalArgumentException- if(number % divisor) != 0.ArithmeticException- ifdivisor == 0.- Since:
- 1.1
-
ensureMultiple
Ensures that a given value is a multiple of specified number. This method verifies that(multiple % number) == 0. If above condition is not met, the value considered to be wrong is the multiple.- Parameters:
name- name of the argument for the multiple value. Used only if an exception is thrown.number- the number to be multiplied.multiple- the value to verify.- Throws:
IllegalArgumentException- if(multiple % number) != 0.ArithmeticException- ifnumber == 0.- Since:
- 1.1
-
ensureDimensionMatches
public static void ensureDimensionMatches(String name, int expected, CoordinateReferenceSystem crs) throws MismatchedDimensionException Ensures that the given CRS, if non-null, has the expected number of dimensions. This method does nothing if the given coordinate reference system is null.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.expected- the expected number of dimensions.crs- the coordinate reference system to check for its dimension, ornull.- Throws:
MismatchedDimensionException- if the given coordinate reference system is non-null and does not have the expected number of dimensions.
-
ensureDimensionMatches
public static void ensureDimensionMatches(String name, int expected, CoordinateSystem cs) throws MismatchedDimensionException Ensures that the given coordinate system, if non-null, has the expected number of dimensions. This method does nothing if the given coordinate system is null.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.expected- the expected number of dimensions.cs- the coordinate system to check for its dimension, ornull.- Throws:
MismatchedDimensionException- if the given coordinate system is non-null and does not have the expected number of dimensions.- Since:
- 0.6
-
ensureDimensionMatches
public static void ensureDimensionMatches(String name, int expected, int[] indices) throws MismatchedDimensionException Ensures that the given array of indices, if non-null, has the expected number of dimensions (taken as its length). This method does nothing if the given array is null.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.expected- the expected number of dimensions.indices- the array of indices to check for its number of dimensions, ornull.- Throws:
MismatchedDimensionException- if the given array of indices is non-null and does not have the expected number of dimensions (taken as its length).- Since:
- 1.0
-
ensureDimensionMatches
public static void ensureDimensionMatches(String name, int expected, double[] vector) throws MismatchedDimensionException Ensures that the given vector, if non-null, has the expected number of dimensions (taken as its length). This method does nothing if the given vector is null.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.expected- the expected number of dimensions.vector- the vector to check for its number of dimensions, ornull.- Throws:
MismatchedDimensionException- if the given vector is non-null and does not have the expected number of dimensions (taken as its length).
-
ensureDimensionMatches
public static void ensureDimensionMatches(String name, int expected, DirectPosition position) throws MismatchedDimensionException Ensures that the given direct position, if non-null, has the expected number of dimensions. This method does nothing if the given direct position is null.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.expected- the expected number of dimensions.position- the direct position to check for its dimension, ornull.- Throws:
MismatchedDimensionException- if the given direct position is non-null and does not have the expected number of dimensions.
-
ensureDimensionMatches
public static void ensureDimensionMatches(String name, int expected, Envelope envelope) throws MismatchedDimensionException Ensures that the given envelope, if non-null, has the expected number of dimensions. This method does nothing if the given envelope is null.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.expected- the expected number of dimensions.envelope- the envelope to check for its dimension, ornull.- Throws:
MismatchedDimensionException- if the given envelope is non-null and does not have the expected number of dimensions.
-
ensureDimensionsMatch
public static void ensureDimensionsMatch(String name, int expectedSource, int expectedTarget, MathTransform transform) throws MismatchedDimensionException Ensures that the given transform, if non-null, has the expected number of source and target dimensions. This method does nothing if the given transform is null.- Parameters:
name- the name of the argument to be checked. Used only if an exception is thrown.expectedSource- the expected number of source dimensions.expectedTarget- the expected number of target dimensions.transform- the transform to check for its dimension, ornull.- Throws:
MismatchedDimensionException- if the given transform is non-null and does not have the expected number of dimensions.- Since:
- 1.1
-