@GwtCompatible public final class Check extends Object
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
.
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).
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()
.
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.
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)
.
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.
CompactChecks
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)
|
public static void arguments(boolean condition, String message)
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.
condition
- The condition that must hold for the method argumentsmessage
- The exception messageIllegalArgumentException
- if the condition is false
state(boolean, String)
public static void state(boolean condition, String message)
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.
condition
- The state condition that must hold at the beginning of the
method invocationmessage
- The exception messageIllegalStateException
- if the condition is false
arguments(boolean, String)
public static ObjectCheck that(Object argument)
ObjectCheck
which can be use to check basic
properties of all objects, e.g. ObjectBaseCheck.isNotNull()
or
ObjectBaseCheck.hasClass(Class)
.argument
- The argument to checkObjectCheck
public static StringCheck that(String argument)
StringCheck
which can be use to check various
properties of a String
, e.g. StringCheck.hasLength(int)
or StringCheck.contains(CharSequence)
.argument
- The String argument to checkStringCheck
public static ObjectArrayCheck that(Object[] argument)
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.
argument
- The object array argument to checkObjectArrayCheck
public static PrimitiveArrayCheck that(boolean[] argument)
PrimitiveArrayCheck
which can be use to check various
properties of a primitive array (e.g. int[]
), e.g.
PrimitiveArrayCheck.hasLength(int)
or
PrimitiveArrayCheck.isNotEmpty()
.argument
- The boolean[]
array argument to checkPrimitiveArrayCheck
public static PrimitiveArrayCheck that(byte[] argument)
PrimitiveArrayCheck
which can be use to check various
properties of a primitive array (e.g. int[]
), e.g.
PrimitiveArrayCheck.hasLength(int)
or
PrimitiveArrayCheck.isNotEmpty()
.argument
- The byte[]
array argument to checkPrimitiveArrayCheck
public static PrimitiveArrayCheck that(char[] argument)
PrimitiveArrayCheck
which can be use to check various
properties of a primitive array (e.g. int[]
), e.g.
PrimitiveArrayCheck.hasLength(int)
or
PrimitiveArrayCheck.isNotEmpty()
.argument
- The char[]
array argument to checkPrimitiveArrayCheck
public static PrimitiveArrayCheck that(double[] argument)
PrimitiveArrayCheck
which can be use to check various
properties of a primitive array (e.g. int[]
), e.g.
PrimitiveArrayCheck.hasLength(int)
or
PrimitiveArrayCheck.isNotEmpty()
.argument
- The double[]
array argument to checkPrimitiveArrayCheck
public static PrimitiveArrayCheck that(float[] argument)
PrimitiveArrayCheck
which can be use to check various
properties of a primitive array (e.g. int[]
), e.g.
PrimitiveArrayCheck.hasLength(int)
or
PrimitiveArrayCheck.isNotEmpty()
.argument
- The float[]
array argument to checkPrimitiveArrayCheck
public static PrimitiveArrayCheck that(int[] argument)
PrimitiveArrayCheck
which can be use to check various
properties of a primitive array (e.g. int[]
), e.g.
PrimitiveArrayCheck.hasLength(int)
or
PrimitiveArrayCheck.isNotEmpty()
.argument
- The int[]
array argument to checkPrimitiveArrayCheck
public static PrimitiveArrayCheck that(long[] argument)
PrimitiveArrayCheck
which can be use to check various
properties of a primitive array (e.g. int[]
), e.g.
PrimitiveArrayCheck.hasLength(int)
or
PrimitiveArrayCheck.isNotEmpty()
.argument
- The long[]
array argument to checkPrimitiveArrayCheck
public static PrimitiveArrayCheck that(short[] argument)
PrimitiveArrayCheck
which can be use to check various
properties of a primitive array (e.g. int[]
), e.g.
PrimitiveArrayCheck.hasLength(int)
or
PrimitiveArrayCheck.isNotEmpty()
.argument
- The short[]
array argument to checkPrimitiveArrayCheck
public static CollectionCheck that(Collection<?> argument)
CollectionCheck
which can be use to check various
properties of a Collection
, e.g.
CollectionCheck.hasSize(int)
or
CollectionCheck.containsNoNull()
.argument
- The Collection argument to checkCollectionCheck
public static NumberCheck that(Number argument)
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.
argument
- The Number argument to checkNumberCheck
@GwtIncompatible(value="java.net.URL") public static UrlCheck that(URL argument)
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.
argument
- The URL argument to checkUrlCheck
public static IntCheck that(int argument)
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.
argument
- The int
argument to checkIntCheck
public static LongCheck that(long argument)
LongCheck
which can be use to check various properties
of a long
, e.g. LongCheck.isPositive()
or
LongCheck.isBetween(long, long)
.argument
- The long
argument to checkLongCheck
public static DoubleCheck that(double argument)
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.
argument
- The double
or float
argument to
checkDoubleCheck
Copyright © 2012–2017 Michael Faes. All rights reserved.