Module org.klojang.check

Package org.klojang.check

Class Check

java.lang.Object

org.klojang.check.Check

public final class Check
extends Object

The central class of this Java module. All checks start out here. The Check class provides static factory methods for IntCheck and ObjectCheck instances, which do the actual orchestration of the checks to be executed. The Check class does contain a few validation methods itself, like Check.fromTo() and Check.offsetLength(). These stand somewhat apart from the rest of the Klojang Check. They are included for convenience.

See the User Guide for a detailed description of Defensive Programming using Klojang Check.

Author:

Ayco Holleman

Method Summary

Modifier and Type	Method	Description
static <T> T	fail(String message, Object... msgArgs)	Always throws an IllegalArgumentException with the specified message and message arguments.
static <T, X extends Throwable> T	fail(Function<String,X> excFactory, String message, Object... msgArgs)	Always throws the exception produced by the specified exception factory with the specified message and message arguments.
static <T, X extends Throwable> T	fail(Supplier<X> excFactory)	Always throws the exception supplied by the specified Supplier.
static int	fromTo(int size, int fromIndex, int toIndex)	All-in-one check for the provided size, from-index and to-index.
static int	fromTo(String string, int fromIndex, int toIndex)	All-in-one check for the provided string, from-index and to-index.
static int	fromTo(List<?> list, int fromIndex, int toIndex)	All-in-one check for the provided list, from-index and to-index.
static <T> int	fromTo(T[] array, int fromIndex, int toIndex)	All-in-one check for the provided array, from-index and to-index.
static <T> ObjectCheck<T,IllegalArgumentException>	notNull(T value)	Static factory method.
static <T> ObjectCheck<T,IllegalArgumentException>	notNull(T value, String tag)	Static factory method.
static void	offsetLength(byte[] array, int offset, int length)	All-in-one check for the specified array, offset and length.
static void	offsetLength(int size, int offset, int length)	All-in-one check for the provided size, offset and length.
static <X extends Exception> IntCheck<X>	on(Function<String,X> excFactory, int value)	Static factory method.
static <X extends Exception> IntCheck<X>	on(Function<String,X> excFactory, int value, String tag)	Static factory method.
static <T, X extends Exception> ObjectCheck<T,X>	on(Function<String,X> excFactory, T value)	Static factory method.
static <T, X extends Exception> ObjectCheck<T,X>	on(Function<String,X> excFactory, T value, String tag)	Static factory method.
static IntCheck<IllegalArgumentException>	that(int value)	Static factory method.
static IntCheck<IllegalArgumentException>	that(int value, String tag)	Static factory method.
static <T> ObjectCheck<T,IllegalArgumentException>	that(T value)	Static factory method.
static <T> ObjectCheck<T,IllegalArgumentException>	that(T value, String tag)	Static factory method.

Methods inherited from class java.lang.Object

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

Method Details

that

public static IntCheck<IllegalArgumentException> that(int value)

Static factory method. Returns an IntCheck instance suitable for testing int values.

Parameters:

value - the value to be validated

Returns:

an IntCheck instance suitable for testing int values

that

public static <T>
ObjectCheck<T,IllegalArgumentException> that(T value)

Static factory method. Returns an ObjectCheck instance suitable for validating values of type <T>.

Type Parameters:

T - the type of the value to be validated

Parameters:

value - the value to be validated

Returns:

an ObjectCheck instance suitable for validating values of type <T>.

that

public static IntCheck<IllegalArgumentException> that(int value,
 String tag)

Static factory method. Returns an IntCheck instance suitable for validating int values.

Parameters:

value - the value to be validated

tag - a descriptive name for the value (in case the value is a method argument probably something close to the parameter name)

Returns:

an IntCheck instance suitable for testing int values

that

public static <T>
ObjectCheck<T,IllegalArgumentException> that(T value,
 String tag)

Static factory method. Returns an ObjectCheck instance suitable for validating values of type <T>.

Type Parameters:

T - the type of the value to be validated

Parameters:

value - the value to be validated

tag - a descriptive name for the value (in case the value is a method argument probably something close to the parameter name)

Returns:

an ObjectCheck instance suitable for validating values of type <T>.

notNull

public static <T>
ObjectCheck<T,IllegalArgumentException> notNull(T value)
                                         throws NullPointerException

Static factory method. Returns an ObjectCheck instance suitable for validating values of type <T> if the specified value is not null, else throws a NullPointerException. null test. An IllegalArgumentException will be thrown if the specified value fails any of the subsequently specified checks.

Type Parameters:

T - the type of the value to be validated

Parameters:

value - the value to be validated

Returns:

an ObjectCheck instance suitable for validating values of type <T>.

Throws:

NullPointerException - if the argument is null

notNull

public static <T>
ObjectCheck<T,IllegalArgumentException> notNull(T value,
 String tag)
                                         throws NullPointerException

Static factory method. Returns an ObjectCheck instance suitable for validating values of type <T> if the specified value is not null, else throws a NullPointerException. null test. An IllegalArgumentException will be thrown if the specified value fails any of the subsequently specified checks.

Type Parameters:

T - the type of the value to be validated

Parameters:

value - the value to be validated

tag - a descriptive name for the value (in case the value is a method argument probably something close to the parameter name)

Returns:

an ObjectCheck instance suitable for validating values of type <T>.

Throws:

NullPointerException - if the argument is null

on

public static <X extends Exception> IntCheck<X> on(Function<String,X> excFactory,
 int value)

Static factory method. Returns an IntCheck instance suitable for validating int values. If the value fails any of the tests passed to the IntCheck instance, the exception produced by the provided exception factory is thrown.

Type Parameters:

X - the type of Exception thrown if the value fails to pass a test

Parameters:

excFactory - a function that will produce the exception if the value fails to pass a test. The function will be pass the exception message and must return the exception to be thrown

value - the value to be validated

Returns:

an IntCheck instance suitable for testing int values

on

public static <T,
X extends Exception>
ObjectCheck<T,X> on(Function<String,X> excFactory,
 T value)

Static factory method. Returns an ObjectCheck instance suitable for validating values of type <T>. If the value fails any of the tests passed to the ObjectCheck instance, the exception produced by the provided exception factory is thrown.

Type Parameters:

T - the type of the value to be validated

X - the type of Exception thrown if the value fails to pass a test

Parameters:

excFactory - a function that will produce the exception if the value fails to pass a test. The function will be pass the exception message and must return the exception to be thrown

value - the value to be validated

Returns:

an ObjectCheck instance suitable for validating values of type <T>.

on

public static <X extends Exception> IntCheck<X> on(Function<String,X> excFactory,
 int value,
 String tag)

Static factory method. Returns an IntCheck instance suitable for validating int values. If the value fails any of the tests passed to the IntCheck instance, the exception produced by the provided exception factory is thrown.

Type Parameters:

X - the type of Exception thrown if the value fails to pass a test

Parameters:

excFactory - a function that will produce the exception if the value fails to pass a test. The function will be pass the exception message and must return the exception to be thrown

value - the value to be validated

tag - a descriptive name for the value (in case the value is a method argument probably something close to the parameter name)

Returns:

an IntCheck instance suitable for testing int values

on

public static <T,
X extends Exception>
ObjectCheck<T,X> on(Function<String,X> excFactory,
 T value,
 String tag)

Static factory method. Returns a new Check instance suitable for testing the provided argument.

Type Parameters:

T - the type of the value to be validated

X - the type of Exception thrown if the value fails to pass a test

Parameters:

excFactory - a function that will produce the exception if the value fails to pass a test. The function will be pass the exception message and must return the exception to be thrown

value - the value to be validated

tag - a descriptive name for the value (in case the value is a method argument probably something close to the parameter name)

Returns:

an ObjectCheck instance suitable for validating values of type <T>.

offsetLength

public static void offsetLength(byte[] array,
 int offset,
 int length)

All-in-one check for the specified array, offset and length.

1. throws an NullPointerException if array is null.
2. throws an IndexOutOfBoundsException if offset or length is negative
3. throws an IndexOutOfBoundsException if offset+length > array.length

NB The fromTo() and offsetLength() checks stand somewhat apart from the rest of the check framework. They happen through "ordinary" static utility methods and they test multiple things at once. They are included for convenience.

Parameters:

array - the array

offset - the offset within the array

length - the length of the segment

See Also:

• offsetLength(int, int, int)
• OutputStream.write(byte[], int, int)
• InputStream.read(byte[], int, int)

offsetLength

public static void offsetLength(int size,
 int offset,
 int length)

All-in-one check for the provided size, offset and length. The size argument supposedly is the size or length of an array or array-like object.

1. throws an IndexOutOfBoundsException if size, offset or length is negative
2. throws an IndexOutOfBoundsException if offset+length > size

NB The fromTo() and offsetLength() checks stand somewhat apart from the rest of the check framework. They happen through "ordinary" static utility methods and they test multiple things at once. They are included for convenience.

Parameters:

size - the length/size of the array or array-like object

offset - the offset

length - the length of the segment

fromTo

public static int fromTo(List<?> list,
 int fromIndex,
 int toIndex)

All-in-one check for the provided list, from-index and to-index.

1. Throws a NullPointerException if list is null
2. Throws an IndexOutOfBoundsException if fromIndex < 0
3. Throws an IndexOutOfBoundsException if toIndex < fromIndex
4. Throws an IndexOutOfBoundsException if toIndex > list.size()

NB The fromTo() and offsetLength() checks stand somewhat apart from the rest of the check framework. They happen through "ordinary" static utility methods and they test multiple things at once. They are included for convenience.

Parameters:

list - the list

fromIndex - the start index of the sublist

toIndex - the end index of the sublist

Returns:

the size of the sublist

See Also:

• fromTo(int, int, int)
• List.subList(int, int)

fromTo

public static <T> int fromTo(T[] array,
 int fromIndex,
 int toIndex)

All-in-one check for the provided array, from-index and to-index.

1. Throws a NullPointerException if the array is null
2. Throws an IndexOutOfBoundsException if fromIndex or toIndex is negative
3. Throws an IndexOutOfBoundsException if toIndex < fromIndex
4. Throws an IndexOutOfBoundsException if toIndex > array.length

NB The fromTo() and offsetLength() checks stand somewhat apart from the rest of the check framework. They happen through "ordinary" static utility methods and they test multiple things at once. They are included for convenience.

Type Parameters:

T - the type of the array elements

Parameters:

array - the array

fromIndex - the start index of the array segment

toIndex - the end index of the array segment

Returns:

the length of the array segment

See Also:

• fromTo(int, int, int)
• Arrays.copyOfRange(Object[], int, int)

fromTo

public static int fromTo(String string,
 int fromIndex,
 int toIndex)

All-in-one check for the provided string, from-index and to-index.

1. Throws a NullPointerException if string is null
2. Throws an IndexOutOfBoundsException if fromIndex or toIndex is negative
3. Throws an IndexOutOfBoundsException if toIndex < fromIndex
4. Throws an IndexOutOfBoundsException if toIndex > string.length()

NB The fromTo() and offsetLength() checks stand somewhat apart from the rest of the check framework. They happen through "ordinary" static utility methods and they test multiple things at once. They are included for convenience.

Parameters:

string - the string

fromIndex - the start index of the substring

toIndex - the end index of the substring

Returns:

the length of the substring

See Also:

• fromTo(int, int, int)
• String.substring(int, int)

fromTo

public static int fromTo(int size,
 int fromIndex,
 int toIndex)

All-in-one check for the provided size, from-index and to-index. The size argument supposedly is the size or length of an array or array-like object.

1. Throws an IndexOutOfBoundsException if size or fromIndex or toIndex is negative
2. Throws an IndexOutOfBoundsException if toIndex < fromIndex
3. Throws an IndexOutOfBoundsException if toIndex > size

NB The fromTo() and offsetLength() checks stand somewhat apart from the rest of the check framework. They happen through "ordinary" static utility methods and they test multiple things at once. They are included for convenience.

Parameters:

size - the size (or length) of the array, string, list, etc.

fromIndex - the start index of the segment

toIndex - the end index of the segment

Returns:

the length of the segment

fail

public static <T> T fail(String message,
 Object... msgArgs)
                  throws IllegalArgumentException

Always throws an IllegalArgumentException with the specified message and message arguments. The method is still declared to return a value of type <T> so it can be used as the expression for a return statement.

Type Parameters:

T - the desired type of the return value

Parameters:

message - the message (pattern)

msgArgs - the message arguments. The first message argument within the message pattern would be ${0}; the second would be ${1}, etc. For more information, see Custom Error Messages.

Returns:

nothing, but allows fail() to be used as the expression in a return statement

Throws:

IllegalArgumentException - always

fail

public static <T,
X extends Throwable> T fail(Supplier<X> excFactory)
                                       throws X

Always throws the exception supplied by the specified Supplier. The method is still declared to return a value of type <T> so it can be used as the expression for a return statement.

Type Parameters:

T - the desired type of the return value

X - the type of the exception

Parameters:

excFactory - the supplier of the exception

Returns:

nothing, but allows fail() to be used as the expression in a return statement

Throws:

X - always

fail

public static <T,
X extends Throwable> T fail(Function<String,X> excFactory,
 String message,
 Object... msgArgs)
                                       throws X

Always throws the exception produced by the specified exception factory with the specified message and message arguments. The method is still declared to return a value of type <T> so it can be used as the expression for a return statement.

Type Parameters:

T - the type of the object that would have been returned if it had passed the checks

X - the type of the exception

Parameters:

excFactory - a function that takes a String (the exception message) and produces an Exception.

message - the message

msgArgs - the message arguments. The first message argument within the message pattern would be ${0}; the second would be ${1}, etc. For more information, see Custom Error Messages.

Returns:

nothing, but allows fail to be used as the expression in a return statement

Throws:

X - always