Package com.globalmentor.java

Class Conditions

java.lang.Object
com.globalmentor.java.Conditions
public class Conditions extends Object
Various checks on objects. Some of these methods indicate preconditions on objects given as arguments in a method.

The name of this class was inspired by the Preconditions class in Google Guava Library.

Author:
Garret Wilson

  • 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 an IllegalArgumentException if the value is false.
      API Note:
      This is a precondition check.
      Parameters:
      test - The result of the test.
      Throws:
      IllegalArgumentException - if the given value is false.

    • checkArgument

      public static void checkArgument(boolean test, String description, Object... arguments)
      Checks the results of an expression to see if an argument is correct, and throws an IllegalArgumentException if the value is false.
      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, or null 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 is null.
      IllegalArgumentException - if the given value is false.
      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

      public static <T> T checkArgumentIsInstance(Object object, @Nonnull Class<T> instanceClass)
      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, or null 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 is null.
      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't null, throwing IllegalArgumentException if the object is null.
      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 is null.

    • checkArgumentNotNull

      public static <T> T checkArgumentNotNull(T object, String description, Object... arguments)
      Checks to make sure an argument isn't null, throwing IllegalArgumentException if the object is null.
      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, or null 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 is null.
      NullPointerException - if the given arguments is null.
      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

      public static <T> T checkArgumentPresent(@Nonnull Optional<T> optional)
      Checks to make sure an argument is present, throwing IllegalArgumentException 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 is null.
      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, throwing IllegalArgumentException 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, or null 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 is null.
      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

      public static void checkConfiguration(boolean test)
      Checks the results of an expression to see if an argument is correct, and throws a ConfigurationException if the value is false.
      Parameters:
      test - The result of the test.
      Throws:
      ConfigurationException - if the given value is false.

    • checkConfiguration

      public static void checkConfiguration(boolean test, String description, Object... arguments)
      Checks the results of an expression to see if an argument is correct, and throws a ConfigurationException if the value is false.
      Parameters:
      test - The result of the test.
      description - A description of the test to be used when generating an exception, optionally formatted with arguments, or null 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 is null.
      ConfigurationException - if the given value is false.
      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

      public static <T> T checkConfigurationNotNull(T variable)
      Checks to see if a given variable is an instance of any object, and throws a ConfigurationException if the variable is null.
      Type Parameters:
      T - The type of variable to check.
      Parameters:
      variable - The variable to check.
      Returns:
      The given variable.
      Throws:
      ConfigurationException - if the given variable is null.

    • checkConfigurationNotNull

      public static <T> T checkConfigurationNotNull(T variable, String description)
      Checks to see if a given variable is an instance of any object, and throws a ConfigurationException if the variable is null.
      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, or null for no description.
      Returns:
      The given variable.
      Throws:
      NullPointerException - if the given variable is null.

    • 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 is true.
      Parameters:
      state - The state to check.
      Throws:
      IllegalStateException - if the given state is false.

    • checkState

      public static void checkState(boolean state, String description, Object... errorMessageArgs)
      Checks to make sure a given state is true.
      Parameters:
      state - The state to check.
      description - A description of the state to be used when generating an exception, or null 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 is false.

    • checkSupportedOperation

      public static void checkSupportedOperation(boolean test)
      Checks the results of an expression to see if an operation is supported, and throws an UnsupportedOperationException if the value is false.
      Parameters:
      test - The result of the test.
      Throws:
      UnsupportedOperationException - if the given value is false.

    • checkSupportedOperation

      public static void checkSupportedOperation(boolean test, String description, Object... arguments)
      Checks the results of an expression to see if an operation is supported, and throws an UnsupportedOperationException if the value is false.
      Parameters:
      test - The result of the test.
      description - A description of the test to be used when generating an exception, optionally formatted with arguments, or null 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 is null.
      IllegalArgumentException - if the given value is false.
      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

      public static IllegalStateException unexpected(String message)
      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, or null if there is no detail message.
      Returns:
      A throwable indicating an unexpected condition.

    • unexpected

      public static IllegalStateException unexpected(Throwable cause)
      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, or null if a throwable cause is nonexistent or unknown.
      Returns:
      A throwable indicating an unexpected condition.

    • unexpected

      public static IllegalStateException unexpected(String message, Throwable cause)
      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, or null if there is no detail message.
      cause - The throwable cause of the unexpected condition, or null if a throwable cause is nonexistent or unknown.
      Returns:
      A throwable indicating an unexpected condition.

    • impossible

      public static AssertionError 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

      public static AssertionError impossible(String message)
      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, or null if there is no detail message.
      Returns:
      A throwable indicating an impossible condition.

    • impossible

      public static AssertionError impossible(Throwable cause)
      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, or null if a throwable cause is nonexistent or unknown.
      Returns:
      A throwable indicating an impossible condition.

    • impossible

      public static AssertionError impossible(String message, Throwable cause)
      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, or null if there is no detail message.
      cause - The throwable cause of the impossible condition, or null if a throwable cause is nonexistent or unknown.
      Returns:
      A throwable indicating an impossible condition.