Package org.kiwiproject.base

Class KiwiPreconditions

java.lang.Object

org.kiwiproject.base.KiwiPreconditions

public class KiwiPreconditions
extends Object

Static utility methods similar to those found in Preconditions, but with a lovely Kiwi flavor to them. That class has good documentation, so go read it if you need more information on the intent and general usage.

Implementation Note:

Many of the methods in this class use Lombok's SneakyThrows so that methods do not need to declare that they throw exceptions of type T, for the case that T is a checked exception. Read more details about how this works in SneakyThrows. Most notably, this should give you more insight into how the JVM (versus Java the language) actually work: "The JVM does not check for the consistency of the checked exception system; javac does, and this annotation lets you opt out of its mechanism."

Constructor Summary

Constructors

Constructor	Description
KiwiPreconditions()

Method Summary

Modifier and Type	Method	Description
static <T extends Throwable> void	checkArgument(boolean expression, Class<T> exceptionType)	Ensures the truth of an expression involving one or more parameters to the calling method.
static <T extends Throwable> void	checkArgument(boolean expression, Class<T> exceptionType, String errorMessage)	Ensures the truth of an expression involving one or more parameters to the calling method.
static <T extends Throwable> void	checkArgument(boolean expression, Class<T> exceptionType, String errorMessageTemplate, Object... errorMessageArgs)	Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgumentNotBlank(String string)	Ensures that the string passed as a parameter to the calling method is not null, empty or blank, throwing an IllegalArgumentException if it is null, empty, or blank.
static void	checkArgumentNotBlank(String string, String errorMessage)	Ensures that the string passed as a parameter to the calling method is not null, empty or blank, throwing an IllegalArgumentException if it is null, empty, or blank.
static void	checkArgumentNotBlank(String string, String errorMessageTemplate, Object... errorMessageArgs)	Ensures that the string passed as a parameter to the calling method is not null, empty or blank, throwing an IllegalArgumentException if it is null, empty, or blank.
static <T> void	checkArgumentNotNull(T reference)	Ensures that an object reference passed as a parameter to the calling method is not null, throwing an IllegalArgumentException if null.
static <T> void	checkArgumentNotNull(T reference, String errorMessage)	Ensures that an object reference passed as a parameter to the calling method is not null, throwing an IllegalArgumentException if null.
static <T> void	checkArgumentNotNull(T reference, String errorMessageTemplate, Object... errorMessageArgs)	Ensures that an object reference passed as a parameter to the calling method is not null, throwing an IllegalArgumentException if null.
static <T> void	checkEvenItemCount(Collection<T> items)	Ensures that a collection of items has an even count.
static void	checkEvenItemCount(IntSupplier countSupplier)	Ensures that a collection of items has an even count.
static <T> void	checkEvenItemCount(T... items)	Ensures that a collection of items has an even count.
static String	requireNotBlank(String value)	Ensures that a String passed as a parameter to the calling method is not blank, throwing and IllegalArgumentException if blank or returning the String otherwise.
static String	requireNotBlank(String value, String errorMessage)	Ensures that a String passed as a parameter to the calling method is not blank, throwing and IllegalArgumentException if blank or returning the String otherwise.
static String	requireNotBlank(String value, String errorMessageTemplate, Object... errorMessageArgs)	Ensures that a String passed as a parameter to the calling method is not blank, throwing and IllegalArgumentException if blank or returning the String otherwise.
static <T> T	requireNotNull(T reference)	Ensures that an object reference passed as a parameter to the calling method is not null, throwing and IllegalArgumentException if null or returning the (non null) reference otherwise.
static <T> T	requireNotNull(T reference, String errorMessageTemplate, Object... errorMessageArgs)	Ensures that an object reference passed as a parameter to the calling method is not null, throwing and IllegalArgumentException if null or returning the (non null) reference otherwise.
static <T> T	requireNotNullElse(T obj, T defaultObj)	Returns the first argument if it is not null, otherwise the second argument (which must not be null).
static <T> T	requireNotNullElseGet(T obj, Supplier<? extends T> supplier)	Returns the first argument if it is not null, otherwise the value supplied by the Supplier, which must not be null.

Methods inherited from class java.lang.Object

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

Constructor Detail

KiwiPreconditions

public KiwiPreconditions()

Method Detail

checkArgument

public static <T extends Throwable> void checkArgument(boolean expression,
                                                       Class<T> exceptionType)

Ensures the truth of an expression involving one or more parameters to the calling method.

Throws an exception of type T if expression is false.

Type Parameters:

T - the type of exception

Parameters:

expression - a boolean expression

exceptionType - the type of exception to be thrown if expression is false

Implementation Note:

This uses Lombok's SneakyThrows to throw any checked exceptions without declaring them.

checkArgument

public static <T extends Throwable> void checkArgument(boolean expression,
                                                       Class<T> exceptionType,
                                                       String errorMessage)

Ensures the truth of an expression involving one or more parameters to the calling method.

Throws an exception of type T if expression is false.

Type Parameters:

T - the type of exception

Parameters:

expression - a boolean expression

exceptionType - the type of exception to be thrown if expression is false

errorMessage - the exception message to use if the check fails

Implementation Note:

This uses Lombok's SneakyThrows to throw any checked exceptions without declaring them.

checkArgument

public static <T extends Throwable> void checkArgument(boolean expression,
                                                       Class<T> exceptionType,
                                                       String errorMessageTemplate,
                                                       Object... errorMessageArgs)

Ensures the truth of an expression involving one or more parameters to the calling method.

Throws an exception of type T if expression is false.

Type Parameters:

T - the type of exception

Parameters:

expression - a boolean expression

exceptionType - the type of exception to be thrown if expression is false

errorMessageTemplate - a template for the exception message should the check fail, according to how KiwiStrings.format(String, Object...) handles placeholders

errorMessageArgs - the arguments to be substituted into the message template. Arguments are converted to strings using String.valueOf(Object).

Throws:

NullPointerException - if the check fails and either errorMessageTemplate or errorMessageArgs is null (don't let this happen)

Implementation Note:

This uses Lombok's SneakyThrows to throw any checked exceptions without declaring them.

requireNotBlank

public static String requireNotBlank(String value)

Ensures that a String passed as a parameter to the calling method is not blank, throwing and IllegalArgumentException if blank or returning the String otherwise.

Parameters:

value - the String value to check

Returns:

the given String

See Also:

checkArgumentNotBlank(String)

requireNotBlank

public static String requireNotBlank(String value,
                                     String errorMessage)

Ensures that a String passed as a parameter to the calling method is not blank, throwing and IllegalArgumentException if blank or returning the String otherwise.

Parameters:

value - the String value to check

errorMessage - the error message for the exception

Returns:

the given String

See Also:

checkArgumentNotBlank(String, String)

requireNotBlank

public static String requireNotBlank(String value,
                                     String errorMessageTemplate,
                                     Object... errorMessageArgs)

Ensures that a String passed as a parameter to the calling method is not blank, throwing and IllegalArgumentException if blank or returning the String otherwise.

Parameters:

value - the String value to check

errorMessageTemplate - a template for the exception message should the check fail, according to how KiwiStrings.format(String, Object...) handles placeholders

errorMessageArgs - the arguments to be substituted into the message template. Arguments are converted to strings using String.valueOf(Object).

Returns:

the given String

See Also:

checkArgumentNotBlank(String, String, Object...)

requireNotNull

public static <T> T requireNotNull(T reference)

Ensures that an object reference passed as a parameter to the calling method is not null, throwing and IllegalArgumentException if null or returning the (non null) reference otherwise.

Type Parameters:

T - the type of object

Parameters:

reference - an object reference

Returns:

the object type

requireNotNull

public static <T> T requireNotNull(T reference,
                                   String errorMessageTemplate,
                                   Object... errorMessageArgs)

Ensures that an object reference passed as a parameter to the calling method is not null, throwing and IllegalArgumentException if null or returning the (non null) reference otherwise.

Type Parameters:

T - the type of object

Parameters:

reference - an object reference

errorMessageTemplate - a template for the exception message should the check fail, according to how KiwiStrings.format(String, Object...) handles placeholders

errorMessageArgs - the arguments to be substituted into the message template. Arguments are converted to strings using String.valueOf(Object).

Returns:

the object type

checkArgumentNotNull

public static <T> void checkArgumentNotNull(T reference)

Ensures that an object reference passed as a parameter to the calling method is not null, throwing an IllegalArgumentException if null.

Type Parameters:

T - the object type

Parameters:

reference - an object reference

checkArgumentNotNull

public static <T> void checkArgumentNotNull(T reference,
                                            String errorMessage)

Ensures that an object reference passed as a parameter to the calling method is not null, throwing an IllegalArgumentException if null.

Type Parameters:

T - the object type

Parameters:

reference - an object reference

errorMessage - the error message for the exception

checkArgumentNotNull

public static <T> void checkArgumentNotNull(T reference,
                                            String errorMessageTemplate,
                                            Object... errorMessageArgs)

Ensures that an object reference passed as a parameter to the calling method is not null, throwing an IllegalArgumentException if null.

Type Parameters:

T - the object type

Parameters:

reference - an object reference

errorMessageTemplate - a template for the exception message should the check fail, according to how KiwiStrings.format(String, Object...) handles placeholders

errorMessageArgs - the arguments to be substituted into the message template. Arguments are converted to strings using String.valueOf(Object).

checkArgumentNotBlank

public static void checkArgumentNotBlank(String string)

Ensures that the string passed as a parameter to the calling method is not null, empty or blank, throwing an IllegalArgumentException if it is null, empty, or blank.

Parameters:

string - a string

checkArgumentNotBlank

public static void checkArgumentNotBlank(String string,
                                         String errorMessage)

Ensures that the string passed as a parameter to the calling method is not null, empty or blank, throwing an IllegalArgumentException if it is null, empty, or blank.

Parameters:

string - a string

errorMessage - the error message for the exception

checkArgumentNotBlank

public static void checkArgumentNotBlank(String string,
                                         String errorMessageTemplate,
                                         Object... errorMessageArgs)

Ensures that the string passed as a parameter to the calling method is not null, empty or blank, throwing an IllegalArgumentException if it is null, empty, or blank.

Parameters:

string - a string

errorMessageTemplate - a template for the exception message should the check fail, according to how KiwiStrings.format(String, Object...) handles placeholders

errorMessageArgs - the arguments to be substituted into the message template. Arguments are converted to strings using String.valueOf(Object).

checkEvenItemCount

@SafeVarargs
public static <T> void checkEvenItemCount(T... items)

Ensures that a collection of items has an even count.

Type Parameters:

T - the object type

Parameters:

items - items to count

checkEvenItemCount

public static <T> void checkEvenItemCount(Collection<T> items)

Ensures that a collection of items has an even count.

Type Parameters:

T - the object type

Parameters:

items - items to count

checkEvenItemCount

public static void checkEvenItemCount(IntSupplier countSupplier)

Ensures that a collection of items has an even count.

Parameters:

countSupplier - an IntSupplier that returns the count to evaluate

requireNotNullElse

public static <T> T requireNotNullElse(T obj,
                                       T defaultObj)

Returns the first argument if it is not null, otherwise the second argument (which must not be null).

The main reason for this method instead of the Objects.requireNonNullElse(Object, Object) is that this method throws an IllegalArgumentException instead of a NullPointerException, which was an unfortunate choice by the JDK.

Type Parameters:

T - the type of the reference

Parameters:

obj - an object, possibly null

defaultObj - a non-null object

Returns:

the first non-null argument

requireNotNullElseGet

public static <T> T requireNotNullElseGet(T obj,
                                          Supplier<? extends T> supplier)

Returns the first argument if it is not null, otherwise the value supplied by the Supplier, which must not be null.

The main reason for this method instead of the Objects.requireNonNullElse(Object, Object) is that this method throws an IllegalArgumentException instead of a NullPointerException, which was an unfortunate choice by the JDK.

Type Parameters:

T - the type of the reference

Parameters:

obj - an object, possibly null

supplier - creates a non-null object

Returns:

the first argument, or the value from supplier