Module org.klojang.check
Package org.klojang.check

Class CommonChecks

java.lang.Object
org.klojang.check.CommonChecks
public final class CommonChecks extends Object
Defines various common checks on arguments, variables, object state, program input, etc. The checks have short, informative error messages associated with them, so you don't have to invent them yourself. Unless specified otherwise they only test what they are documented to be testing. Many of them do nothing but return a method reference (e.g. Collection::contains). More specifically: the checks will not execute a preliminary null check on the argument before proceeding with the actual check. If the argument might be null, always perform a notNull() check first. Otherwise, a raw, unprocessed NullPointerException can and will be thrown from the code underlying Klojang Check. 

 Check.notNull(file).is(readable());

For ease of reading, the documentation for the checks will mostly use the term "argument" for the value being tested. Constantly repeating "argument, field, variable, program argument, system property, environment variable, etc." would not improve the quality and clarity of the documentation.

Author:
Ayco Holleman

  • Method Details

    • NULL

      public static <T> ComposablePredicate<T> NULL()
      Verifies that the argument is null. Equivalent to Objects::isNull.
      Type Parameters:
      T - the type of the argument
      Returns:
      a function implementing the test described above

    • notNull

      public static <T> ComposablePredicate<T> notNull()
      Verifies that the argument is not null. Equivalent to Objects::nonNull. Note that NULL(), yes() and empty() are the only checks that come with their negation: notNull(), no() and notEmpty(). The other checks need to be inverted using the isNot(...) and notHas(...) methods of ObjectCheck and IntCheck.
      Type Parameters:
      T - the type of the argument
      Returns:
      a function implementing the test described above

    • yes

      public static ComposablePredicate<Boolean> yes()
      Verifies that a condition evaluates to true. 
      
 Check.that(connection.isOpen()).is(yes());
      Returns:
      a function implementing the test described above

    • no

      public static ComposablePredicate<Boolean> no()
      Verifies that a condition evaluates to false.
      Returns:
      a function implementing the test described above

    • empty

      public static <T> ComposablePredicate<T> empty()
      Verifies that the argument is empty. 
      
 Check.that(list).isNot(empty());

      A value is defined to be empty if any of the following applies:

      This check (implicitly) performs a null check and can be safely executed without or instead of executing the notNull() check first.

      Type Parameters:
      T - the type of the argument
      Returns:
      a function implementing the test described above

    • emptyString

      public static ComposablePredicate<String> emptyString()
      Verifies that the argument is either null or an empty string.

      This check (implicitly) performs a null check and can be safely executed without or instead of executing the notNull() check first.

      Returns:
      a function implementing the test described above

    • notEmpty

      public static <T> ComposablePredicate<T> notEmpty()
      Verifies that the argument is not empty. More precisely: it verifies the negation of the empty() test.

      This check (implicitly) performs a null check and can be safely executed without or instead of executing the notNull() check first.

      Type Parameters:
      T - the type of the argument
      Returns:
      a function implementing the test described above

    • deepNotNull

      public static <T> ComposablePredicate<T> deepNotNull()
      Verifies that the argument is not null and, if it is an array, collection or map, that it does not contain any null values. It could still be a zero-length array or zero-size collection or map, however. For maps, both keys and values are tested for null.

      This check (implicitly) performs a null check and can be safely executed without or instead of executing the notNull() check first.

      Type Parameters:
      T - the type of the argument
      Returns:
      a function implementing the test described above

    • deepNotEmpty

      public static <T> ComposablePredicate<T> deepNotEmpty()
      Verifies that the argument is recursively non-empty. A value is defined to be deep-not-empty if any of the following applies:
      • it is a non-empty CharSequence
      • it is a non-empty Collection containing only deep-not-empty elements
      • it is a non-empty Map containing only deep-not-empty keys and values
      • it is a deep-not-empty Emptyable
      • it is a non-zero-length Object[] containing only deep-not-empty elements
      • it is a non-zero-length array of primitive values
      • it is a non-empty Optional containing a deep-not-empty value
      • it is a File containing at least one non-whitespace character. Consequently, this check could be expensive if the argument is a large File. Also note that this check will not verify that the file exists in the first place. If in doubt, execute the regularFile() check first.
      • it is a non-null object of any other type

      This check (implicitly) performs a null check and can be safely executed without or instead of executing the notNull() check first.

      Type Parameters:
      T - the type of the argument
      Returns:
      a function implementing the test described above

    • blank

      public static ComposablePredicate<String> blank()
      Verifies that the argument is null or contains whitespace only. Probably more useful when called from an isNot method.

      This check (implicitly) performs a null check and can be safely executed without or instead of executing the notNull() check first.

      Returns:
      a function implementing the test described above

    • plainInt

      public static ComposablePredicate<String> plainInt()
      Verifies that a string consists of digits only (without '+' or '-' sign), no leading zeros, and can be parsed into an integer (by implication non-negative).
      Returns:
      a function implementing the test described above

    • plainShort

      public static ComposablePredicate<String> plainShort()
      Verifies that a string consists of digits only (without '+' or '-' sign), no leading zeros, and can be parsed into a half-precision integer (by implication non-negative). Useful, for example, for validating TCP port numbers.
      Returns:
      a function implementing the test described above

    • array

      public static <T> ComposablePredicate<T> array()
      Verifies that the argument is an array or an array type. 
      
 Object obj = new int[] {1, 2, 3, 4, 5};
 Check.that(obj).is(array());             // OK
 Check.that(obj.getClass()).is(array());  // OK
 Check.that("foo").is(array());           // IllegalArgumentException
      Type Parameters:
      T - the type of the argument
      Returns:
      a function implementing the test described above

    • regularFile

      public static ComposablePredicate<File> regularFile()
      Verifies that the argument is an existing, regular file. NB To verify that a path string is valid, execute: 
      
 Check.that(path).has(File::new, regularFile());
      Returns:
      a function implementing the test described above

    • directory

      public static ComposablePredicate<File> directory()
      Verifies that the argument is an existing directory.
      Returns:
      a function implementing the test described above

    • symlink

      public static ComposablePredicate<File> symlink()
      Verifies that the argument is a symbolic link.
      Returns:
      a function implementing the test described above

    • fileExists

      public static ComposablePredicate<File> fileExists()
      Verifies that the specified file is present on the file system. Equivalent to File::exists. 
      
 // import static org.klojang.CommonChecks.fileExists;
 // import static org.klojang.CommonExceptions.fileNotFound;
 Check.that(file).is(fileExists(), fileNotFound(file));
      Returns:
      a function implementing the test described above
      See Also:

    • readable

      public static ComposablePredicate<File> readable()
      Verifies that a file is readable. Implies that the file exists. Equivalent to File::canRead.
      Returns:
      a function implementing the test described above

    • writable

      public static ComposablePredicate<File> writable()
      Verifies that a file is writable. Implies that the file exists. Equivalent to File::canWrite.
      Returns:
      a function implementing the test described above

    • present

      public static <T> ComposablePredicate<Optional<T>> present()
      Verifies that the argument is a non-empty Optional. Note that this check differs from the empty() check in that it only verifies that the Optional contains a value. The empty() check (in its negation) additionally requires that the value is itself non-empty.
      Type Parameters:
      T - the type of the value contained in the Optional
      Returns:
      a function implementing the test described above

    • available

      public static <T> ComposablePredicate<Result<T>> available()
      Verifies that a result is available. Note that this check differs from the empty() check in that it only verifies that Result contains a value. The empty() check (in its negation) additionally requires that the value it contains is itself non-empty.
      Type Parameters:
      T - the type of the value contained in the Result
      Returns:
      a function implementing the test described above

    • even

      public static ComposableIntPredicate even()
      Verifies that the argument is an even integer.
      Returns:
      a function implementing the test described above

    • odd

      public static ComposableIntPredicate odd()
      Verifies that the argument is an odd integer.
      Returns:
      a function implementing the test described above

    • positive

      public static ComposableIntPredicate positive()
      Verifies that the argument is a positive integer.
      Returns:
      a function implementing the test described above

    • negative

      public static ComposableIntPredicate negative()
      Verifies that the argument is a negative integer.
      Returns:
      a function implementing the test described above

    • zero

      public static ComposableIntPredicate zero()
      Verifies that the argument is zero (0).
      Returns:
      a function implementing the test described above

    • eq

      public static IntRelation eq()
      Verifies that the argument equals the specified int value.
      Returns:
      a function implementing the test described above

    • ne

      public static IntRelation ne()
      Verifies that the argument does not equal the specified int value.
      Returns:
      a function implementing the test described above

    • gt

      public static IntRelation gt()
      Verifies that the argument is greater than the specified int value.
      Returns:
      a function implementing the test described above

    • gte

      public static IntRelation gte()
      Verifies that the argument is greater than or equal to the specified int value.
      Returns:
      a function implementing the test described above

    • lt

      public static IntRelation lt()
      Verifies that the argument is less than the specified int value.
      Returns:
      a function implementing the test described above

    • lte

      public static IntRelation lte()
      Verifies that the argument is less than or equal to the specified int value.
      Returns:
      a function implementing the test described above

    • multipleOf

      public static IntRelation multipleOf()
      Verifies that the argument is a multiple of the specified int value.
      Returns:
      a function implementing the test described above

    • EQ

      public static <S, O> Relation<S,O> EQ()
      Verifies that the argument equals the provided value. Equivalent to Object::equals. Note that this method is not equivalent to Objects::equals and is therefore not null-safe. Execute a null check first, if necessary.
      Type Parameters:
      S - the type of the subject of the relationship (which is the value being tested)
      O - the type of the object of the relationship
      Returns:
      a function implementing the test described above

    • equalTo

      public static <T> Relation<T,T> equalTo()
      Verifies that the argument equals some value. Equivalent to Object::equals. Use this check instead of EQ() if you want the compiler to enforce type equality between subject and object.
      Type Parameters:
      T - the type of the objects being compared
      Returns:
      a function implementing the test described above

    • GT

      public static <T extends Comparable<T>> Relation<T,T> GT()
      Verifies that the argument is greater than another value.
      Type Parameters:
      T - the type of the values being compared
      Returns:
      a function implementing the test described above
      See Also:

    • LT

      public static <T extends Comparable<T>> Relation<T,T> LT()
      Verifies that the argument is less than another value.
      Type Parameters:
      T - the type of the values being compared
      Returns:
      a function implementing the test described above
      See Also:

    • GTE

      public static <T extends Comparable<T>> Relation<T,T> GTE()
      Verifies that the argument is greater than or equal to another value.
      Type Parameters:
      T - the type of the values being compared
      Returns:
      a function implementing the test described above
      See Also:

    • LTE

      public static <T extends Comparable<T>> Relation<T,T> LTE()
      Verifies that the argument is less than or equal to another value.
      Type Parameters:
      T - the type of the values being compared
      Returns:
      a function implementing the test described above
      See Also:

    • sameAs

      public static <S, O> Relation<S,O> sameAs()
      Verifies that a value references the same object as another value.
      Type Parameters:
      S - the type of the subject of the relationship (which is the value being tested) (the subject of the Relation)
      O - the type of the value to compare it with (the object of the Relation)
      Returns:
      a function implementing the test described above

    • nullOr

      public static <T> Relation<T,T> nullOr()
      Verifies that the argument is either null or equals a particular value.

      This check (implicitly) performs a null check and can be safely executed without or instead of executing the notNull() check first.

      Type Parameters:
      T - the type of the subject of the relationship (which is the value being tested)
      Returns:
      a function implementing the test described above

    • instanceOf

      public static <S> Relation<S,Class<?>> instanceOf()
      Verifies that the argument is an instance of a particular class or interface.
      Type Parameters:
      S - the type of the subject of the relation (which is the value being tested)
      Returns:
      a function implementing the test described above

    • supertypeOf

      public static <S, O> Relation<Class<S>,Class<O>> supertypeOf()
      Verifies that the argument is a supertype of the provided type. In other words, the provided type should extend, implement or equal the argument. Equivalent to Class::isAssignableFrom.
      Type Parameters:
      S - the type of the subject's class
      O - the type of the object's class
      Returns:
      a function that implements the test described above

    • subtypeOf

      public static <S, O> Relation<Class<S>,Class<O>> subtypeOf()
      Verifies that the argument is a subtype of the provided type. In other words, the argument should extend, implement or equal the provided type.
      Type Parameters:
      S - the type of the subject's class
      O - the type of the object's class
      Returns:
      a function that implements the test described above

    • contains

      public static <O, S extends Collection<? super O>> Relation<S,O> contains()
      Verifies that a collection contains a particular value. Equivalent to Collection::contains.
      Type Parameters:
      O - the type of the elements in the Collection
      S - the type of the collection
      Returns:
      a function implementing the test described above

    • containsKey

      public static <O, S extends Map<? super O, ?>> Relation<S,O> containsKey()
      Verifies that a map contains a particular key. Equivalent to Map::containsKey.
      Type Parameters:
      O - the type of the keys within the map
      S - the Type of the Map
      Returns:
      a function implementing the test described above

    • containsValue

      public static <O, S extends Map<?, ? super O>> Relation<S,O> containsValue()
      Verifies that a map contains a particular value. Equivalent to Map::containsValue.
      Type Parameters:
      O - the type of the values within the map
      S - the Type of the Map
      Returns:
      a function implementing the test described above

    • in

      public static <S, O extends Collection<? super S>> Relation<S,O> in()
      Verifies that the argument is an element of a collection.
      Type Parameters:
      S - the type of the argument
      O - the type of the Collection
      Returns:
      a function implementing the test described above

    • elementOf

      public static <S, O extends Collection<? super S>> Relation<S,O> elementOf()
      Alias for in(). Note that this method will even report itself to be the "in" check.
      Type Parameters:
      S - the type of the argument
      O - the type of the Collection
      Returns:
      a function implementing the test described above

    • keyIn

      public static <S, O extends Map<? super S, ?>> Relation<S,O> keyIn()
      Verifies the presence of a key within a map.
      Type Parameters:
      S - the type of the keys within the map
      O - the Type of the Map
      Returns:
      a function implementing the test described above

    • valueIn

      public static <S, O extends Map<?, ? super S>> Relation<S,O> valueIn()
      Verifies the presence of a value within a map.
      Type Parameters:
      S - the type of the keys within the map
      O - the Type of the Map
      Returns:
      a function implementing the test described above

    • inArray

      public static <O, S extends O> Relation<S,O[]> inArray()
      Verifies that the argument is an element of an array.
      Type Parameters:
      O - the component type of the array
      S - the type of the subject of the relationship (which is the value being tested)
      Returns:
      a function implementing the test described above

    • containsAll

      public static <E, C0 extends Collection<? super E>, C1 extends Collection<E>> Relation<C0,C1> containsAll()
      Verifies that a Collection argument contains all the elements of the specified collection. Equivalent to Collection::containsAll. 
      
 Check.that(List.of(1, 2, 3)).is(enclosing(), Set.of(1, 2)); // true
 Check.that(List.of(1, 2)).is(enclosing(), Set.of(1, 2, 3)); // false
      Type Parameters:
      E - The type of the elements in the Collection
      C0 - The type of the argument (the subject of the Relation)
      C1 - The type of the object of the Relation
      Returns:
      a function implementing the test described above

    • containedIn

      public static <E, C0 extends Collection<E>, C1 extends Collection<? super E>> Relation<C0,C1> containedIn()
      Verifies that a Collection argument is a subset or sublist of another Collection. 
      
 Check.that(List.of(1, 2, 3)).is(enclosedBy(), Set.of(1, 2)); // false
 Check.that(List.of(1, 2)).is(enclosedBy(), Set.of(1, 2, 3)); // true
      Type Parameters:
      E - The type of the elements in the Collection
      C0 - The type of the argument (the subject of the Relation)
      C1 - The type of the object of the Relation
      Returns:
      a function implementing the test described above

    • hasSubstring

      public static Relation<String,CharSequence> hasSubstring()
      Verifies that the argument contains the specified substring. Equivalent to String::contains.
      Returns:
      a function implementing the test described above

    • substringOf

      public static Relation<String,String> substringOf()
      Verifies that the argument is a substring of the specified string.
      Returns:
      a function implementing the test described above

    • startsWith

      public static Relation<String,String> startsWith()
      Verifies that the argument starts with the specified substring. Equivalent to String::startsWith.
      Returns:
      a function implementing the test described above

    • endsWith

      public static Relation<String,String> endsWith()
      Verifies that the argument ends with the specified substring. Equivalent to String::endsWith.
      Returns:
      a function implementing the test described above

    • hasPattern

      public static Relation<String,Pattern> hasPattern()
      Verifies that the argument matches the specified pattern (that is, the pattern fully describes the string).
      Returns:
      a function implementing the test described above
      See Also:

    • containsPattern

      public static Relation<String,Pattern> containsPattern()
      Verifies that the argument contains the specified pattern (that is, the pattern can be found somewhere in the string).
      Returns:
      a function implementing the test described above
      See Also:

    • matches

      public static Relation<String,String> matches()
      Verifies that the argument matches the specified pattern (that is, the pattern fully describes the string). The subject of the returned Relation is the string to match; the object of the Relation is a regular expression to be compiled into a Pattern. 
      
 Check.that("abcd123").is(matches(), "^\\w{4}\\d{3}$"); // yes
 Check.that("abcd123").is(matches(), "\\d{3}"); // no
      Returns:
      a function implementing the test described above

    • containsMatch

      public static Relation<String,String> containsMatch()
      Verifies that the argument contains the specified pattern (that is, the pattern can be found somewhere in the string). The subject of the returned Relation is the string to match; the object of the Relation is a regular expression to be compiled into a Pattern. 
      
 Check.that("abcd123").is(containsMatch(), "\\d{3}"); // yes
 Check.that("abcd123").is(containsMatch(), "\\d{4}"); // no
      Returns:
      a function implementing the test described above

    • numerical

      public static <T extends Number> Relation<String,Class<T>> numerical()
      Verifies that a string can be parsed into a number of the specified type without loss of information. The provided type must be one of the primitive number types: long, int, short, byte, double or float. Specifying a wrapper type (e.g. Integer) will result in a CorruptCheckException. 
      
 Check.that("123").is(numerical(), int.class); // yes
 Check.that("123.0").is(numerical(), int.class); // no
      Type Parameters:
      T - the type of the number into which to parse the string
      Returns:
      a function implementing the test described above
      See Also:

    • parsableAs

      public static <T extends Number> Relation<String,Class<T>> parsableAs()
      Verifies that a string can be parsed into a Number of the specified type without loss of information. The provided type must be one of the primitive number types: long, int, short, byte, double or float. Specifying a wrapper type (e.g. Integer) will result in a CorruptCheckException. Contrary to the numerical() check, this check allows the string to contain a fractional part even if the target type is an integral type (like byte), as long as it consists of zeros only. Scientific notation is allowed, too, as long as the effective fractional part consists of zeros only. For Double and Float there is no difference between the two checks. 
      
 Check.that("123").is(parsableAs(), int.class); // yes
 Check.that("123.0").is(parsableAs(), int.class); // yes
      Type Parameters:
      T - the type of the number into which to parse the string
      Returns:
      a function implementing the test described above
      See Also:

    • equalsIC

      public static Relation<String,String> equalsIC()
      Verifies that a string value equals, ignoring case, the specified string. Equivalent to String::equalsIgnoreCase.
      Returns:
      a function implementing the test described above

    • startsWithIC

      public static Relation<String,String> startsWithIC()
      Verifies that a string value starts with, ignoring case, the specified string.
      Returns:
      a function implementing the test described above

    • endsWithIC

      public static Relation<String,String> endsWithIC()
      Verifies that a string value starts with, ignoring case, the specified string.
      Returns:
      a function implementing the test described above

    • hasSubstringIC

      public static Relation<String,String> hasSubstringIC()
      Verifies that a string value contains, ignoring case, the specified string.
      Returns:
      a function implementing the test described above

    • indexOf

      public static <T> IntObjRelation<T> indexOf()
      Verifies that the argument is a valid index into the specified array, List or String. No preliminary check is done to ensure the provided object actually is an array, List or String. A CorruptCheckException is thrown if it is not. Execute the instanceOf() or array() check first, if necessary.
      Type Parameters:
      T - the type of the object of the IntObjRelation - must be a String, List or array
      Returns:
      a function implementing the test described above

    • indexExclusiveOf

      public static <T> IntObjRelation<T> indexExclusiveOf()
      Alias for indexOf(). Can be used if the class you are working in already contains an indexOf() method. Note that this will report itself to be the indexOf() check: 
      
 Check.that(42, "foo").is(indexExclusiveOf(), new int[10], "${tag} did not pass the ${test}() test");
 // "foo did not pass the indexOf() test"
      Type Parameters:
      T - the type of the object of the IntObjRelation - must be a String, List or array
      Returns:
      a function implementing the test described above

    • indexInclusiveOf

      public static <T> IntObjRelation<T> indexInclusiveOf()
      Verifies that a value can be used as a "from" or "to" index in operations like Arrays.copyOfRange(), String.substring() and List.subList(). These operations allow both the "from" index and the "to" index to be equal to the length of the array, string or list. No preliminary check is done to ensure the provided object actually is an array, List or String. A CorruptCheckException is thrown if it is not. Execute the instanceOf() or array() check first, if necessary.
      Type Parameters:
      T - the type of the object of the IntObjRelation - must be a String, List or array
      Returns:
      a function implementing the test described above
      See Also:

    • inIntArray

      public static IntObjRelation<int[]> inIntArray()
      Verifies that the argument is present in the specified int array.
      Returns:
      a function implementing the test described above