ch.trick17.betterchecks

Class Check

java.lang.Object

ch.trick17.betterchecks.Check

@GwtCompatible
public final class Check
extends Object

The primary entry point to the Better Checks library. Argument checks are written like this:

Check.that(argument).check1().check2()...;

Examples:

Check.that(greeting).matches("hello .*!").hasLenghtBetween(0, 20);
Check.that(list).isNullOr().hasSize(0);
Check.that(names).named("list of names").isNotEmpty();

The check methods, such as matches(...) or hasSize(...), throw an exception if the check fails. The exact type of exception depends on the kind of check that is called but in most cases it is IllegalArgumentException.

Check Objects

You check the properties of your argument by calling Check.that(argument) and then appending the required checks. The that(...) method returns a check object that matches the (static) type of argument. This is done with method overloading. The returned check object has the argument "imprinted" to perform the checks that are called subsequently.

For instance, if you pass a String, you will get a StringCheck object, with methods like StringCheck.isNotEmpty(), StringCheck.hasLength(int) or StringCheck.matches(String).

If there is no specific check class that matches the passed argument, a generic ObjectCheck is returned, providing basic checks like ObjectBaseCheck.isNotNull() or ObjectBaseCheck.hasClass(Class) and the state-modifying methods (see below).

Check Modification

In addition to the checking methods, the check objects provide a few modifier methods that affect subsequent checks. For example, all checks by default also check that the argument is not null, throwing an exception if it is. To allow null as an accepted value, you can prepend your other checks with isNullOr(), like in the second example above.

It is also possible to name the arguments that you are checking. Doing so will make the exception messages more meaningful and debugging easier. To name an argument, prepend all checks with named("argument name"), just like in the third example at the top.

Finally, each check can be inverted by prepending .not(). Here is an example:

Check.that(message).not().containsAny(badWords);

Note that the not() only inverts the actual check and not the null check. In the above example this would mean that message must still be non-null. So null check inversion with isNullOr() is completely independent of check inversion with not().

Stack Trace Cleaning

To make the Better Checks library as unintrusive as possible, the stack traces of the exceptions thrown by the checks are modified to not contain any stack frames from this library. Thus, the exceptions look exactly like they are being thrown by the method using the checks itself.

The idea behind this is to make it clear that the arguments (or the state respectively) are illegal with respect to the client method and not with respect to the methods of the Better Checks library.

If stack trace cleaning is undesired, it can be turned off in the config file. See below for more information.

Compact and Simple Checks

Instead of the Check.that(...) syntax, you can use an even more compact syntax, provided by the CompactChecks class. Also, in addition to the fluent checks, there are also a few simple check methods, like arguments(boolean, String) and state(boolean, String).

Configuration and Use in Libraries

It is intentionally not possible to configure the type of exception the checking methods throw. Because of this, the Better Checks library may also safely be used in libraries (as opposed to applications), without the risk that the application reconfigures the behavior of the library methods, possibly breaking their specification.

The configuration possibilities of this library are rather limited. You can customize the exception messages and disable stack trace cleaning. The only way to configure those settings is via a properties file on the classpath. This is also a design decision that makes it possible to safely use Better Checks in libraries and, more generally, in all code that potentially runs before the application's initialization, such as static initializers.

See the documentation of the Config class for more information.

Author:

Michael Faes

See Also:

CompactChecks

Method Summary

Modifier and Type	Method and Description
static void	arguments(boolean condition, String message) A simple argument check that throws an IllegalArgumentException with the given message if the given condition is false.
static void	state(boolean condition, String message) A simple check that throws an IllegalStateException with the given message if the given condition is false.
static PrimitiveArrayCheck	that(boolean[] argument) Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g.
static PrimitiveArrayCheck	that(byte[] argument) Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g.
static PrimitiveArrayCheck	that(char[] argument) Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g.
static CollectionCheck	that(Collection<?> argument) Returns a CollectionCheck which can be use to check various properties of a Collection, e.g.
static DoubleCheck	that(double argument) Returns a DoubleCheck which can be use to check various properties of an double, e.g.
static PrimitiveArrayCheck	that(double[] argument) Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g.
static PrimitiveArrayCheck	that(float[] argument) Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g.
static IntCheck	that(int argument) Returns an IntCheck which can be use to check various properties of an int, e.g.
static PrimitiveArrayCheck	that(int[] argument) Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g.
static LongCheck	that(long argument) Returns a LongCheck which can be use to check various properties of a long, e.g.
static PrimitiveArrayCheck	that(long[] argument) Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g.
static NumberCheck	that(Number argument) Returns a NumberCheck which can be use to check various properties of a Number, e.g.
static ObjectCheck	that(Object argument) Returns a generic ObjectCheck which can be use to check basic properties of all objects, e.g.
static ObjectArrayCheck	that(Object[] argument) Returns a ObjectArrayCheck which can be use to check various properties of an object array (Object[]), e.g.
static PrimitiveArrayCheck	that(short[] argument) Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g.
static StringCheck	that(String argument) Returns a StringCheck which can be use to check various properties of a String, e.g.
static UrlCheck	that(URL argument) Returns an UrlCheck which can be use to check various properties of an URL, e.g.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

arguments

public static void arguments(boolean condition,
                             String message)

A simple argument check that throws an IllegalArgumentException with the given message if the given condition is false.

Use this as a fallback option if you have to check something that the fluent checks don't provide or if you have to check two arguments together. Otherwise the fluent checks will probably be more readable and concise as you don't have to provide the exception message.

Parameters:

condition - The condition that must hold for the method arguments

message - The exception message

Throws:

IllegalArgumentException - if the condition is false

See Also:

state(boolean, String)

state

public static void state(boolean condition,
                         String message)

A simple check that throws an IllegalStateException with the given message if the given condition is false.

In contrast to most other checks, this check is for checking the state of your object (instead of the method arguments) at the beginning of a method invocation.

Parameters:

condition - The state condition that must hold at the beginning of the method invocation

message - The exception message

Throws:

IllegalStateException - if the condition is false

See Also:

arguments(boolean, String)

that

public static ObjectCheck that(Object argument)

Returns a generic ObjectCheck which can be use to check basic properties of all objects, e.g. ObjectBaseCheck.isNotNull() or ObjectBaseCheck.hasClass(Class).

Parameters:

argument - The argument to check

Returns:

A check object with the argument "imprinted"

See Also:

ObjectCheck

that

public static StringCheck that(String argument)

Returns a StringCheck which can be use to check various properties of a String, e.g. StringCheck.hasLength(int) or StringCheck.contains(CharSequence).

Parameters:

argument - The String argument to check

Returns:

A check object with the argument "imprinted"

See Also:

StringCheck

that

public static ObjectArrayCheck that(Object[] argument)

Returns a ObjectArrayCheck which can be use to check various properties of an object array (Object[]), e.g. ObjectArrayCheck.hasLength(int) or ObjectArrayCheck.containsNoNull().

Note that since arrays are covariant in Java, any type of array (e.g. String[] or Date[]) is accepted by this method. The only exception are arrays of primitive types (e.g. int[] ), which have their own that(...) methods.

Parameters:

argument - The object array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

ObjectArrayCheck

that

public static PrimitiveArrayCheck that(boolean[] argument)

Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g. int[]), e.g. PrimitiveArrayCheck.hasLength(int) or PrimitiveArrayCheck.isNotEmpty().

Parameters:

argument - The boolean[] array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

PrimitiveArrayCheck

that

public static PrimitiveArrayCheck that(byte[] argument)

Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g. int[]), e.g. PrimitiveArrayCheck.hasLength(int) or PrimitiveArrayCheck.isNotEmpty().

Parameters:

argument - The byte[] array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

PrimitiveArrayCheck

that

public static PrimitiveArrayCheck that(char[] argument)

Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g. int[]), e.g. PrimitiveArrayCheck.hasLength(int) or PrimitiveArrayCheck.isNotEmpty().

Parameters:

argument - The char[] array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

PrimitiveArrayCheck

that

public static PrimitiveArrayCheck that(double[] argument)

Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g. int[]), e.g. PrimitiveArrayCheck.hasLength(int) or PrimitiveArrayCheck.isNotEmpty().

Parameters:

argument - The double[] array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

PrimitiveArrayCheck

that

public static PrimitiveArrayCheck that(float[] argument)

Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g. int[]), e.g. PrimitiveArrayCheck.hasLength(int) or PrimitiveArrayCheck.isNotEmpty().

Parameters:

argument - The float[] array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

PrimitiveArrayCheck

that

public static PrimitiveArrayCheck that(int[] argument)

Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g. int[]), e.g. PrimitiveArrayCheck.hasLength(int) or PrimitiveArrayCheck.isNotEmpty().

Parameters:

argument - The int[] array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

PrimitiveArrayCheck

that

public static PrimitiveArrayCheck that(long[] argument)

Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g. int[]), e.g. PrimitiveArrayCheck.hasLength(int) or PrimitiveArrayCheck.isNotEmpty().

Parameters:

argument - The long[] array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

PrimitiveArrayCheck

that

public static PrimitiveArrayCheck that(short[] argument)

Returns a PrimitiveArrayCheck which can be use to check various properties of a primitive array (e.g. int[]), e.g. PrimitiveArrayCheck.hasLength(int) or PrimitiveArrayCheck.isNotEmpty().

Parameters:

argument - The short[] array argument to check

Returns:

A check object with the argument "imprinted"

See Also:

PrimitiveArrayCheck

that

public static CollectionCheck that(Collection<?> argument)

Returns a CollectionCheck which can be use to check various properties of a Collection, e.g. CollectionCheck.hasSize(int) or CollectionCheck.containsNoNull().

Parameters:

argument - The Collection argument to check

Returns:

A check object with the argument "imprinted"

See Also:

CollectionCheck

that

public static NumberCheck that(Number argument)

Returns a NumberCheck which can be use to check various properties of a Number, e.g. NumberCheck.isPositive() or NumberCheck.isBetween(Number, Number).

Note that this method is (should be) only used for numbers other than the ones corresponding to the primitive type numbers ( byte, short, int, long, float, double). Those types have their own that(...) method and check classes with specific features. Also, they do not require any boxing or unboxing.

Parameters:

argument - The Number argument to check

Returns:

A check object with the argument "imprinted"

See Also:

NumberCheck

that

@GwtIncompatible(value="java.net.URL")
public static UrlCheck that(URL argument)

Returns an UrlCheck which can be use to check various properties of an URL, e.g. UrlCheck.hasProtocol(String).

Note that the typical use case is to obtain a UrlCheck via the StringCheck.isUrlWhich() method which "converts" a StringCheck to an UrlCheck.

Parameters:

argument - The URL argument to check

Returns:

A check object with the argument "imprinted"

See Also:

UrlCheck

that

public static IntCheck that(int argument)

Returns an IntCheck which can be use to check various properties of an int, e.g. IntCheck.isPositive(), IntCheck.isBetween(int, int) or IntCheck.isValidIndex(Object[]).

This method is (should be) also used for short and byte arguments as there is no (need for a) separate check class for them.

Parameters:

argument - The int argument to check

Returns:

A check object with the argument "imprinted"

See Also:

IntCheck

that

public static LongCheck that(long argument)

Returns a LongCheck which can be use to check various properties of a long, e.g. LongCheck.isPositive() or LongCheck.isBetween(long, long).

Parameters:

argument - The long argument to check

Returns:

A check object with the argument "imprinted"

See Also:

LongCheck

that

public static DoubleCheck that(double argument)

Returns a DoubleCheck which can be use to check various properties of an double, e.g. DoubleCheck.isPositive(), DoubleCheck.isBetween(double, double) or DoubleCheck.isNotNaN().

This method is (should be) also used for float arguments as there is no (need for a) separate check class for them.

Parameters:

argument - The double or float argument to check

Returns:

A check object with the argument "imprinted"

See Also:

DoubleCheck