Class Conditions
- Author:
- Garret Wilson
- API Note:
- The name of this class was inspired by the
Preconditions
class in Google Guava Library.
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
checkArgument
(boolean test) Checks the results of an expression to see if an argument is correct, and throws anIllegalArgumentException
if the value isfalse
.static void
checkArgument
(boolean test, String description, Object... arguments) Checks the results of an expression to see if an argument is correct, and throws anIllegalArgumentException
if the value isfalse
.static <T> T
checkArgumentIsInstance
(Object object, Class<T> instanceClass) Checks to make sure an argument is an instance of a given type, returning the object cast to the appropriate type.static <T> T
checkArgumentIsInstance
(Object object, Class<T> instanceClass, String description, Object... arguments) Checks to make sure an argument is an instance of a given type, returning the object cast to the appropriate type.static int
checkArgumentMinimum
(int value, int rangeMin) Checks to make sure that a given value is not smaller than the given minimum.static long
checkArgumentMinimum
(long value, long rangeMin) Checks to make sure that a given value is not smaller than the given minimum.static int
checkArgumentNotNegative
(int value) Checks to make sure that a given value is not negative.static long
checkArgumentNotNegative
(long value) Checks to make sure that a given value is not negative.static <T> T
checkArgumentNotNull
(T object) Checks to make sure an argument isn'tnull
, throwingIllegalArgumentException
if the object isnull
.static <T> T
checkArgumentNotNull
(T object, String description, Object... arguments) Checks to make sure an argument isn'tnull
, throwingIllegalArgumentException
if the object isnull
.static int
checkArgumentPositive
(int value) Checks to make sure that a given value is not zero or negativestatic long
checkArgumentPositive
(long value) Checks to make sure that a given value is not zero or negativestatic <T> T
checkArgumentPresent
(Optional<T> optional) Checks to make sure an argument is present, throwingIllegalArgumentException
if the optional is not present.static <T> T
checkArgumentPresent
(Optional<T> optional, String description, Object... arguments) Checks to make sure an argument is present, throwingIllegalArgumentException
if the optional is not present.static int
checkArgumentRange
(int value, int rangeMin, int rangeMax) Checks to make sure that a given argument value is within the given range.static void
checkArgumentRange
(int from, int to, int rangeMin, int rangeMax) Checks to make sure that the given range is within the given range.static long
checkArgumentRange
(long value, long rangeMin, long rangeMax) Checks to make sure that a given argument value is within the given range.static void
checkConfiguration
(boolean test) Deprecated.static void
checkConfiguration
(boolean test, String description, Object... arguments) Deprecated.to be removed in favor ofcheckConfiguredState(boolean, String, Object...)
.static <T> T
checkConfigurationNotNull
(T variable) Deprecated.to be removed in favor ofcheckConfiguredStateNotNull(Object)
.static <T> T
checkConfigurationNotNull
(T variable, String description) Deprecated.to be removed in favor ofcheckConfiguredStateNotNull(Object, String)
.static void
checkConfiguredState
(boolean test) Checks the results of an expression to see if an argument is correct, and throws aConfiguredStateException
if the value isfalse
.static void
checkConfiguredState
(boolean test, String description, Object... arguments) Checks the results of an expression to see if an argument is correct, and throws aConfiguredStateException
if the value isfalse
.static <T> T
checkConfiguredStateNotNull
(T variable) Checks to see if a given variable is an instance of any object, and throws aConfiguredStateException
if the variable isnull
.static <T> T
checkConfiguredStateNotNull
(T variable, String description) Checks to see if a given variable is an instance of any object, and throws aConfiguredStateException
if the variable isnull
.static int
checkIndexBounds
(int index, int length) Checks to make sure that a given index is within the range of zero inclusive to the given length exclusive.static int
checkIndexBounds
(int index, int rangeMin, int rangeMax) Checks to make sure that a given index is within the given range.static long
checkIndexBounds
(long index, long length) Checks to make sure that a given index is within the range of zero inclusive to the given length exclusive.static long
checkIndexBounds
(long index, long rangeMin, long rangeMax) Checks to make sure that a given index is within the given range.static void
checkState
(boolean state) Checks to make sure a given state istrue
.static void
checkState
(boolean state, String description, Object... errorMessageArgs) Checks to make sure a given state istrue
.static void
checkSupportedOperation
(boolean test) Checks the results of an expression to see if an operation is supported, and throws anUnsupportedOperationException
if the value isfalse
.static void
checkSupportedOperation
(boolean test, String description, Object... arguments) Checks the results of an expression to see if an operation is supported, and throws anUnsupportedOperationException
if the value isfalse
.static AssertionError
Creates a throwable indicating a logically impossible condition, which can be thrown by the caller.static AssertionError
impossible
(String message) Creates a throwable indicating a logically impossible condition, which can be thrown by the caller.static AssertionError
impossible
(String message, Throwable cause) Creates a throwable indicating a logically impossible condition, which can be thrown by the caller.static AssertionError
impossible
(Throwable cause) Creates a throwable indicating a logically impossible condition, which can be thrown by the caller.static IllegalStateException
unexpected
(String message) Creates a throwable indicating an unexpected condition, which can be thrown by the caller.static IllegalStateException
unexpected
(String message, Throwable cause) Creates a throwable indicating an unexpected condition, which can be thrown by the caller.static IllegalStateException
unexpected
(Throwable cause) Creates a throwable indicating an unexpected condition, which can be thrown by the caller.
-
Constructor Details
-
Conditions
public Conditions()
-
-
Method Details
-
checkArgument
public static void checkArgument(boolean test) Checks the results of an expression to see if an argument is correct, and throws anIllegalArgumentException
if the value isfalse
.- API Note:
- This is a precondition check.
- Parameters:
test
- The result of the test.- Throws:
IllegalArgumentException
- if the given value isfalse
.
-
checkArgument
Checks the results of an expression to see if an argument is correct, and throws anIllegalArgumentException
if the value isfalse
.- API Note:
- This is a precondition check.
- Parameters:
test
- The result of the test.description
- A description of the test to be used when generating an exception, optionally formatted with arguments, ornull
for no description.arguments
- The arguments to be applied when formatting, or an empty array if the message should not be formatted.- Throws:
NullPointerException
- if the given arguments isnull
.IllegalArgumentException
- if the given value isfalse
.IllegalArgumentException
- if the description is an invalid pattern, or if an argument in the arguments array is not of the type expected by the format element(s) that use it.- See Also:
-
checkArgumentIsInstance
Checks to make sure an argument is an instance of a given type, returning the object cast to the appropriate type.- API Note:
- This is a precondition check.
- Type Parameters:
T
- The expected type of the object.- Parameters:
object
- The object to test.instanceClass
- The class of which to test that the object is an instance.- Returns:
- The given object, cast to the given type.
- Throws:
IllegalArgumentException
- if the given object not of the indicated type.
-
checkArgumentIsInstance
public static <T> T checkArgumentIsInstance(Object object, @Nonnull Class<T> instanceClass, @Nullable String description, @Nonnull Object... arguments) Checks to make sure an argument is an instance of a given type, returning the object cast to the appropriate type.- API Note:
- This is a precondition check.
- Type Parameters:
T
- The expected type of the object.- Parameters:
object
- The object to test.instanceClass
- The class of which to test that the object is an instance.description
- A description of the test to be used when generating an exception, optionally formatted with arguments, ornull
for no description.arguments
- The arguments to be applied when formatting, or an empty array if the message should not be formatted.- Returns:
- The given object, cast to the given type.
- Throws:
IllegalArgumentException
- if the given object not of the indicated type.NullPointerException
- if the given arguments isnull
.IllegalArgumentException
- if the description is an invalid pattern, or if an argument in the arguments array is not of the type expected by the format element(s) that use it.- See Also:
-
checkArgumentNotNull
public static <T> T checkArgumentNotNull(T object) Checks to make sure an argument isn'tnull
, throwingIllegalArgumentException
if the object isnull
.- API Note:
- This is a precondition check.
- Type Parameters:
T
- The type of the object to be tested.- Parameters:
object
- The object to test.- Returns:
- The object, if it is not
null
. - Throws:
IllegalArgumentException
- if the given object isnull
.
-
checkArgumentNotNull
Checks to make sure an argument isn'tnull
, throwingIllegalArgumentException
if the object isnull
.- API Note:
- This is a precondition check.
- Type Parameters:
T
- The type of the object to be tested.- Parameters:
object
- The object to test.description
- A description of the test to be used when generating an exception, optionally formatted with arguments, ornull
for no description.arguments
- The arguments to be applied when formatting, or an empty array if the message should not be formatted.- Returns:
- The given object.
- Throws:
IllegalArgumentException
- if the given object isnull
.NullPointerException
- if the given arguments isnull
.IllegalArgumentException
- if the description is an invalid pattern, or if an argument in the arguments array is not of the type expected by the format element(s) that use it.- See Also:
-
checkArgumentPresent
Checks to make sure an argument is present, throwingIllegalArgumentException
if the optional is not present.- API Note:
- This is a precondition check.
- Type Parameters:
T
- The type of optional object to be tested.- Parameters:
optional
- The optional object to test.- Returns:
- The optional object.
- Throws:
NullPointerException
- if the given optional isnull
.IllegalArgumentException
- if the given optional is not present.- See Also:
-
checkArgumentPresent
public static <T> T checkArgumentPresent(@Nonnull Optional<T> optional, @Nullable String description, @Nonnull Object... arguments) Checks to make sure an argument is present, throwingIllegalArgumentException
if the optional is not present.- API Note:
- This is a precondition check.
- Type Parameters:
T
- The type of optional object to be tested.- Parameters:
optional
- The optional object to test.description
- A description of the test to be used when generating an exception, optionally formatted with arguments, ornull
for no description.arguments
- The arguments to be applied when formatting, or an empty array if the message should not be formatted.- Returns:
- The optional object.
- Throws:
NullPointerException
- if the given optional and/or arguments isnull
.IllegalArgumentException
- if the given optional is not present, or if an argument in the arguments array is not of the type expected by the format element(s) that use it.- See Also:
-
checkArgumentMinimum
public static int checkArgumentMinimum(int value, int rangeMin) Checks to make sure that a given value is not smaller than the given minimum.- API Note:
- This is a precondition check.
- Parameters:
value
- The value to check.rangeMin
- The minimum range value, inclusive.- Returns:
- The given value.
- Throws:
IllegalArgumentException
- if the value is less than the range minimum.
-
checkArgumentMinimum
public static long checkArgumentMinimum(long value, long rangeMin) Checks to make sure that a given value is not smaller than the given minimum.- API Note:
- This is a precondition check.
- Parameters:
value
- The value to check.rangeMin
- The minimum range value, inclusive.- Returns:
- The given value.
- Throws:
IllegalArgumentException
- if the value is less than the range minimum.
-
checkArgumentNotNegative
public static int checkArgumentNotNegative(int value) Checks to make sure that a given value is not negative.- API Note:
- This is a precondition check.
- Parameters:
value
- The value to check.- Returns:
- The given value.
- Throws:
IllegalArgumentException
- if the value is negative.- See Also:
-
checkArgumentPositive
public static int checkArgumentPositive(int value) Checks to make sure that a given value is not zero or negative- API Note:
- This is a precondition check.
- Parameters:
value
- The value to check.- Returns:
- The given value.
- Throws:
IllegalArgumentException
- if the value is not positive.- See Also:
-
checkArgumentNotNegative
public static long checkArgumentNotNegative(long value) Checks to make sure that a given value is not negative.- API Note:
- This is a precondition check.
- Parameters:
value
- The value to check.- Returns:
- The given value.
- Throws:
IllegalArgumentException
- if the value is negative.- See Also:
-
checkArgumentPositive
public static long checkArgumentPositive(long value) Checks to make sure that a given value is not zero or negative- API Note:
- This is a precondition check.
- Parameters:
value
- The value to check.- Returns:
- The given value.
- Throws:
IllegalArgumentException
- if the value is not positive.- See Also:
-
checkArgumentRange
public static int checkArgumentRange(int value, int rangeMin, int rangeMax) Checks to make sure that a given argument value is within the given range.- API Note:
- This is a precondition check.
- Parameters:
value
- The value to check.rangeMin
- The minimum range value, inclusive.rangeMax
- The maximum range value, inclusive.- Returns:
- The given value.
- Throws:
IllegalArgumentException
- if the value is less than the range minimum or greater than the range maximum.
-
checkArgumentRange
public static void checkArgumentRange(int from, int to, int rangeMin, int rangeMax) Checks to make sure that the given range is within the given range.- API Note:
- This is a precondition check.
- Parameters:
from
- The beginning value to check, inclusive.to
- The ending value to check, inclusive.rangeMin
- The minimum range value, inclusive.rangeMax
- The maximum range value, inclusive.- Throws:
IllegalArgumentException
- if the from value is less than the range minimum or greater than the range maximum; or if the to value is less than the from value or greater than the range maximum.
-
checkArgumentRange
public static long checkArgumentRange(long value, long rangeMin, long rangeMax) Checks to make sure that a given argument value is within the given range.- API Note:
- This is a precondition check.
- Parameters:
value
- The value to check.rangeMin
- The minimum range value, inclusive.rangeMax
- The maximum range value, inclusive.- Returns:
- The given value.
- Throws:
IllegalArgumentException
- if the value is less than the range minimum or greater than the range maximum.
-
checkConfiguration
Deprecated.to be removed in favor ofcheckConfiguredState(boolean)
.Checks the results of an expression to see if an argument is correct, and throws aConfiguredStateException
if the value isfalse
.- Parameters:
test
- The result of the test.- Throws:
ConfiguredStateException
- if the given value isfalse
.
-
checkConfiguration
@Deprecated public static void checkConfiguration(boolean test, String description, Object... arguments) Deprecated.to be removed in favor ofcheckConfiguredState(boolean, String, Object...)
.Checks the results of an expression to see if an argument is correct, and throws aConfiguredStateException
if the value isfalse
.- Parameters:
test
- The result of the test.description
- A description of the test to be used when generating an exception, optionally formatted with arguments, ornull
for no description.arguments
- The arguments to be applied when formatting, or an empty array if the message should not be formatted.- Throws:
NullPointerException
- if the given arguments isnull
.ConfiguredStateException
- if the given value isfalse
.IllegalArgumentException
- if the description is an invalid pattern, or if an argument in the arguments array is not of the type expected by the format element(s) that use it.- See Also:
-
checkConfigurationNotNull
Deprecated.to be removed in favor ofcheckConfiguredStateNotNull(Object)
.Checks to see if a given variable is an instance of any object, and throws aConfiguredStateException
if the variable isnull
.- Type Parameters:
T
- The type of variable to check.- Parameters:
variable
- The variable to check.- Returns:
- The given variable.
- Throws:
ConfiguredStateException
- if the given variable isnull
.
-
checkConfigurationNotNull
Deprecated.to be removed in favor ofcheckConfiguredStateNotNull(Object, String)
.Checks to see if a given variable is an instance of any object, and throws aConfiguredStateException
if the variable isnull
.- Type Parameters:
T
- The type of variable to check.- Parameters:
variable
- The variable to check.description
- A description of the variable to be used when generating an exception, ornull
for no description.- Returns:
- The given variable.
- Throws:
NullPointerException
- if the given variable isnull
.
-
checkConfiguredState
public static void checkConfiguredState(boolean test) Checks the results of an expression to see if an argument is correct, and throws aConfiguredStateException
if the value isfalse
.- Parameters:
test
- The result of the test.- Throws:
ConfiguredStateException
- if the given value isfalse
.
-
checkConfiguredState
Checks the results of an expression to see if an argument is correct, and throws aConfiguredStateException
if the value isfalse
.- Parameters:
test
- The result of the test.description
- A description of the test to be used when generating an exception, optionally formatted with arguments, ornull
for no description.arguments
- The arguments to be applied when formatting, or an empty array if the message should not be formatted.- Throws:
NullPointerException
- if the given arguments isnull
.ConfiguredStateException
- if the given value isfalse
.IllegalArgumentException
- if the description is an invalid pattern, or if an argument in the arguments array is not of the type expected by the format element(s) that use it.- See Also:
-
checkConfiguredStateNotNull
public static <T> T checkConfiguredStateNotNull(T variable) Checks to see if a given variable is an instance of any object, and throws aConfiguredStateException
if the variable isnull
.- Type Parameters:
T
- The type of variable to check.- Parameters:
variable
- The variable to check.- Returns:
- The given variable.
- Throws:
ConfiguredStateException
- if the given variable isnull
.
-
checkConfiguredStateNotNull
Checks to see if a given variable is an instance of any object, and throws aConfiguredStateException
if the variable isnull
.- Type Parameters:
T
- The type of variable to check.- Parameters:
variable
- The variable to check.description
- A description of the variable to be used when generating an exception, ornull
for no description.- Returns:
- The given variable.
- Throws:
NullPointerException
- if the given variable isnull
.
-
checkIndexBounds
public static int checkIndexBounds(int index, int length) Checks to make sure that a given index is within the range of zero inclusive to the given length exclusive.This is normally a precondition check.
- API Note:
- Java 9 introduced an equivalent method in
Objects
. - Parameters:
index
- The index to check.length
- The exclusive length.- Returns:
- The given index.
- Throws:
IndexOutOfBoundsException
- if the index is less than zero, or equal to or greater than given length.
-
checkIndexBounds
public static long checkIndexBounds(long index, long length) Checks to make sure that a given index is within the range of zero inclusive to the given length exclusive.This is normally a precondition check.
- API Note:
- Java 16 introduced an equivalent method in
Objects
. - Parameters:
index
- The index to check.length
- The exclusive length.- Returns:
- The given index.
- Throws:
IndexOutOfBoundsException
- if the index is less than zero, or equal to or greater than given length.
-
checkIndexBounds
public static int checkIndexBounds(int index, int rangeMin, int rangeMax) Checks to make sure that a given index is within the given range.This is normally a precondition check.
- Parameters:
index
- The index to check.rangeMin
- The minimum range index, inclusive.rangeMax
- The maximum range index, exclusive.- Returns:
- The given index.
- Throws:
IndexOutOfBoundsException
- if the index is less than the range minimum, or equal to or greater than the range maximum.
-
checkIndexBounds
public static long checkIndexBounds(long index, long rangeMin, long rangeMax) Checks to make sure that a given index is within the given range.This is normally a precondition check.
- Parameters:
index
- The index to check.rangeMin
- The minimum range index, inclusive.rangeMax
- The maximum range index, exclusive.- Returns:
- The given index.
- Throws:
IndexOutOfBoundsException
- if the index is less than the range minimum, or equal to or greater than the range maximum.
-
checkState
public static void checkState(boolean state) Checks to make sure a given state istrue
.- Parameters:
state
- The state to check.- Throws:
IllegalStateException
- if the given state isfalse
.
-
checkState
Checks to make sure a given state istrue
.- Parameters:
state
- The state to check.description
- A description of the state to be used when generating an exception, ornull
for no description. The message is formed by replacing each %s placeholder in the template with an argument. These are matched by position - the first %s gets errorMessageArgs[0], etc.errorMessageArgs
- The arguments to be substituted into the message template.- Throws:
IllegalStateException
- if the given state isfalse
.
-
checkSupportedOperation
public static void checkSupportedOperation(boolean test) Checks the results of an expression to see if an operation is supported, and throws anUnsupportedOperationException
if the value isfalse
.- Parameters:
test
- The result of the test.- Throws:
UnsupportedOperationException
- if the given value isfalse
.
-
checkSupportedOperation
Checks the results of an expression to see if an operation is supported, and throws anUnsupportedOperationException
if the value isfalse
.- Parameters:
test
- The result of the test.description
- A description of the test to be used when generating an exception, optionally formatted with arguments, ornull
for no description.arguments
- The arguments to be applied when formatting, or an empty array if the message should not be formatted.- Throws:
NullPointerException
- if the given arguments isnull
.IllegalArgumentException
- if the given value isfalse
.IllegalArgumentException
- if the description is an invalid pattern, or if an argument in the arguments array is not of the type expected by the format element(s) that use it.- See Also:
-
unexpected
Creates a throwable indicating an unexpected condition, which can be thrown by the caller.An unexpected condition is one that is logically possible to occur, but yet should not occur because of an API contract, for instance. For example, all JVMs should support UTF-8, so one would not expect an
UnsupportedEncodingException
if UTF-8 is explicitly specified.This is a convenience method that makes the semantics of the condition more readily apparent.
- Parameters:
message
- The detail message, ornull
if there is no detail message.- Returns:
- A throwable indicating an unexpected condition.
-
unexpected
Creates a throwable indicating an unexpected condition, which can be thrown by the caller.An unexpected condition is one that is logically possible to occur, but yet should not occur because of an API contract, for instance. For example, all JVMs should support UTF-8, so one would not expect an
UnsupportedEncodingException
if UTF-8 is explicitly specified.This is a convenience method that makes the semantics of the condition more readily apparent.
- Parameters:
cause
- The throwable cause of the unexpected condition, ornull
if a throwable cause is nonexistent or unknown.- Returns:
- A throwable indicating an unexpected condition.
-
unexpected
Creates a throwable indicating an unexpected condition, which can be thrown by the caller.An unexpected condition is one that is logically possible to occur, but yet should not occur because of an API contract, for instance. For example, all JVMs should support UTF-8, so one would not expect an
UnsupportedEncodingException
if UTF-8 is explicitly specified.This is a convenience method that makes the semantics of the condition more readily apparent.
- Parameters:
message
- The detail message, ornull
if there is no detail message.cause
- The throwable cause of the unexpected condition, ornull
if a throwable cause is nonexistent or unknown.- Returns:
- A throwable indicating an unexpected condition.
-
impossible
Creates a throwable indicating a logically impossible condition, which can be thrown by the caller.An impossible condition is one that is supposedly logically impossible to occur. For example, a default section of a switch statement covering all possible values of an enum should never be executed; the throwable produced by this method provides a convenient outcome to indicate this condition (for example, if a new enum value is later introduced and the switch statement isn't updated). The code following a method guaranteed to throw an exception is another example.
This is a convenience method that makes the semantics of the condition more readily apparent.
- Returns:
- A throwable indicating an impossible condition.
-
impossible
Creates a throwable indicating a logically impossible condition, which can be thrown by the caller.An impossible condition is one that is supposedly logically impossible to occur. For example, a default section of a switch statement covering all possible values of an enum should never be executed; the throwable produced by this method provides a convenient outcome to indicate this condition (for example, if a new enum value is later introduced and the switch statement isn't updated). The code following a method guaranteed to throw an exception is another example.
This is a convenience method that makes the semantics of the condition more readily apparent.
- Parameters:
message
- The detail message, ornull
if there is no detail message.- Returns:
- A throwable indicating an impossible condition.
-
impossible
Creates a throwable indicating a logically impossible condition, which can be thrown by the caller.An impossible condition is one that is supposedly logically impossible to occur. For example, a default section of a switch statement covering all possible values of an enum should never be executed; the throwable produced by this method provides a convenient outcome to indicate this condition (for example, if a new enum value is later introduced and the switch statement isn't updated). The code following a method guaranteed to throw an exception is another example.
This is a convenience method that makes the semantics of the condition more readily apparent.
- Parameters:
cause
- The throwable cause of the impossible condition, ornull
if a throwable cause is nonexistent or unknown.- Returns:
- A throwable indicating an impossible condition.
-
impossible
Creates a throwable indicating a logically impossible condition, which can be thrown by the caller.An impossible condition is one that is supposedly logically impossible to occur. For example, a default section of a switch statement covering all possible values of an enum should never be executed; the throwable produced by this method provides a convenient outcome to indicate this condition (for example, if a new enum value is later introduced and the switch statement isn't updated). The code following a method guaranteed to throw an exception is another example.
This is a convenience method that makes the semantics of the condition more readily apparent.
- Parameters:
message
- The detail message, ornull
if there is no detail message.cause
- The throwable cause of the impossible condition, ornull
if a throwable cause is nonexistent or unknown.- Returns:
- A throwable indicating an impossible condition.
-
checkConfiguredState(boolean)
.