org.starchartlabs.alloy.core

Class Preconditions

java.lang.Object

org.starchartlabs.alloy.core.Preconditions

public final class Preconditions
extends java.lang.Object

Utilities intended to streamline verification of expected input conditions by callers.

In general, these utilities allow code of the form

 if (!expression) {
     throw new SomeException();
 }
 

to be replaced with

 Preconditions.check*(expression);
 

for compactness, behavioral clarity, and readability

It is highly recommended to constrain use of these utilities to verifying possible failure conditions which are the caller's fault, as otherwise behavior may be confusing in stack traces, and to future readers of caller implementations

For failure messages which may have non-trivial performance costs to create, it is highly recommended to use method forms which accept a Supplier

Since:

0.1.0

Method Summary

Modifier and Type	Method and Description
static void	checkArgument(boolean expression) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(boolean expression, java.lang.Object errorMessage) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(boolean expression, java.lang.String template, java.lang.Object... args) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(boolean expression, java.util.function.Supplier<java.lang.String> errorMessageSupplier) Ensures the truth of an expression involving one or more parameters to the calling method.
static <T> T	checkArgument(T value, java.util.function.Predicate<T> predicate) Evaluates a value against a provided Predicate expression
static <T> T	checkArgument(T value, java.util.function.Predicate<T> predicate, java.lang.Object errorMessage) Evaluates a value against a provided Predicate expression
static <T> T	checkArgument(T value, java.util.function.Predicate<T> predicate, java.lang.String template, java.lang.Object... args) Evaluates a value against a provided Predicate expression
static <T> T	checkArgument(T value, java.util.function.Predicate<T> predicate, java.util.function.Supplier<java.lang.String> errorMessageSupplier) Evaluates a value against a provided Predicate expression
static void	checkState(boolean expression) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkState(boolean expression, java.lang.Object errorMessage) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkState(boolean expression, java.lang.String template, java.lang.Object... args) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkState(boolean expression, java.util.function.Supplier<java.lang.String> errorMessageSupplier) Ensures the truth of an expression involving one or more parameters to the calling method.
static <T> T	checkState(T value, java.util.function.Predicate<T> predicate) Evaluates a value against a provided Predicate expression
static <T> T	checkState(T value, java.util.function.Predicate<T> predicate, java.lang.Object errorMessage) Evaluates a value against a provided Predicate expression
static <T> T	checkState(T value, java.util.function.Predicate<T> predicate, java.lang.String template, java.lang.Object... args) Evaluates a value against a provided Predicate expression
static <T> T	checkState(T value, java.util.function.Predicate<T> predicate, java.util.function.Supplier<java.lang.String> errorMessageSupplier) Evaluates a value against a provided Predicate expression

Methods inherited from class java.lang.Object

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

Method Detail

checkArgument

public static void checkArgument(boolean expression)

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

Parameters:

expression - A boolean expression

Throws:

java.lang.IllegalArgumentException - If expression is false

Since:

0.1.0

checkArgument

public static <T> T checkArgument(@Nullable
                                  T value,
                                  java.util.function.Predicate<T> predicate)

Evaluates a value against a provided Predicate expression

Type Parameters:

T - The type of the value being evaluated

Parameters:

value - An assignable value to evaluate

predicate - An operation to evaluate against value

Returns:

value if the provided predicate evaluates to true

Throws:

java.lang.IllegalArgumentException - If predicate evaluates to false

Since:

0.5.0

checkArgument

public static void checkArgument(boolean expression,
                                 @Nullable
                                 java.lang.Object errorMessage)

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

Parameters:

expression - A boolean expression

errorMessage - The message to provide in the exception, if the check fails; will be converted via String.valueOf(java.lang.Object)

Throws:

java.lang.IllegalArgumentException - If expression is false

Since:

0.1.0

checkArgument

public static <T> T checkArgument(@Nullable
                                  T value,
                                  java.util.function.Predicate<T> predicate,
                                  @Nullable
                                  java.lang.Object errorMessage)

Evaluates a value against a provided Predicate expression

Type Parameters:

T - The type of the value being evaluated

Parameters:

value - An assignable value to evaluate

predicate - An operation to evaluate against value

errorMessage - The message to provide in the exception, if the check fails; will be converted via String.valueOf(java.lang.Object)

Returns:

value if the provided predicate evaluates to true

Throws:

java.lang.IllegalArgumentException - If predicate evaluates to false

Since:

0.5.0

checkArgument

public static void checkArgument(boolean expression,
                                 java.util.function.Supplier<java.lang.String> errorMessageSupplier)

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

Preferred to checkArgument(boolean, Object) when elements needs to be substituted or otherwise processed for performance reasons

Parameters:

expression - A boolean expression

errorMessageSupplier - A supplier for the message to provide in the exception, if the check fails; Will not be invoked if expression is true

Throws:

java.lang.IllegalArgumentException - If expression is false

Since:

0.1.0

checkArgument

public static <T> T checkArgument(@Nullable
                                  T value,
                                  java.util.function.Predicate<T> predicate,
                                  java.util.function.Supplier<java.lang.String> errorMessageSupplier)

Evaluates a value against a provided Predicate expression

Preferred to checkArgument(Object, Predicate, Object) when elements needs to be substituted or otherwise processed for performance reasons

Type Parameters:

T - The type of the value being evaluated

Parameters:

value - An assignable value to evaluate

predicate - An operation to evaluate against value

errorMessageSupplier - A supplier for the message to provide in the exception, if the check fails; Will not be invoked if predicate is true

Returns:

value if the provided predicate evaluates to true

Throws:

java.lang.IllegalArgumentException - If predicate evaluates to false

Since:

0.5.0

checkArgument

public static void checkArgument(boolean expression,
                                 @Nullable
                                 java.lang.String template,
                                 @Nullable
                                 java.lang.Object... args)

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

Preferred to checkArgument(boolean, Object) when elements needs to be substituted or otherwise processed for performance reasons

Parameters:

expression - A boolean expression

template - A template for a formatted message. The message is formed by replacing each %s placeholder in the template with an argument. These are matched by position - the first %s gets args[0], etc. Unmatched arguments will be appended to the formatted message in square braces. Unmatched placeholders will be left as-is.

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

Throws:

java.lang.IllegalArgumentException - If expression is false

Since:

0.1.0

checkArgument

public static <T> T checkArgument(@Nullable
                                  T value,
                                  java.util.function.Predicate<T> predicate,
                                  @Nullable
                                  java.lang.String template,
                                  @Nullable
                                  java.lang.Object... args)

Evaluates a value against a provided Predicate expression

Preferred to checkArgument(Object, Predicate, Object) when elements needs to be substituted or otherwise processed for performance reasons

Type Parameters:

T - The type of the value being evaluated

Parameters:

value - An assignable value to evaluate

predicate - An operation to evaluate against value

template - A template for a formatted message. The message is formed by replacing each %s placeholder in the template with an argument. These are matched by position - the first %s gets args[0], etc. Unmatched arguments will be appended to the formatted message in square braces. Unmatched placeholders will be left as-is.

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

Returns:

value if the provided predicate evaluates to true

Throws:

java.lang.IllegalArgumentException - If predicate evaluates to false

Since:

0.5.0

checkState

public static void checkState(boolean expression)

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

Parameters:

expression - A boolean expression

Throws:

java.lang.IllegalStateException - If expression is false

Since:

0.1.0

checkState

public static <T> T checkState(@Nullable
                               T value,
                               java.util.function.Predicate<T> predicate)

Evaluates a value against a provided Predicate expression

Type Parameters:

T - The type of the value being evaluated

Parameters:

value - An assignable value to evaluate

predicate - An operation to evaluate against value

Returns:

value if the provided predicate evaluates to true

Throws:

java.lang.IllegalStateException - If predicate evaluates to false

Since:

0.5.0

checkState

public static void checkState(boolean expression,
                              @Nullable
                              java.lang.Object errorMessage)

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

Parameters:

expression - A boolean expression

errorMessage - The message to provide in the exception, if the check fails; will be converted via String.valueOf(java.lang.Object)

Throws:

java.lang.IllegalStateException - If expression is false

Since:

0.1.0

checkState

public static <T> T checkState(@Nullable
                               T value,
                               java.util.function.Predicate<T> predicate,
                               @Nullable
                               java.lang.Object errorMessage)

Evaluates a value against a provided Predicate expression

Type Parameters:

T - The type of the value being evaluated

Parameters:

value - An assignable value to evaluate

predicate - An operation to evaluate against value

errorMessage - The message to provide in the exception, if the check fails; will be converted via String.valueOf(java.lang.Object)

Returns:

value if the provided predicate evaluates to true

Throws:

java.lang.IllegalStateException - If predicate evaluates to false

Since:

0.5.0

checkState

public static void checkState(boolean expression,
                              java.util.function.Supplier<java.lang.String> errorMessageSupplier)

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

Preferred to checkState(boolean, Object) when elements needs to be substituted or otherwise processed for performance reasons

Parameters:

expression - A boolean expression

errorMessageSupplier - A supplier for the message to provide in the exception, if the check fails; Will not be invoked if expression is true

Throws:

java.lang.IllegalStateException - If expression is false

Since:

0.1.0

checkState

public static <T> T checkState(@Nullable
                               T value,
                               java.util.function.Predicate<T> predicate,
                               java.util.function.Supplier<java.lang.String> errorMessageSupplier)

Evaluates a value against a provided Predicate expression

Preferred to checkArgument(Object, Predicate, Object) when elements needs to be substituted or otherwise processed for performance reasons

Type Parameters:

T - The type of the value being evaluated

Parameters:

value - An assignable value to evaluate

predicate - An operation to evaluate against value

errorMessageSupplier - A supplier for the message to provide in the exception, if the check fails; Will not be invoked if predicate is true

Returns:

value if the provided predicate evaluates to true

Throws:

java.lang.IllegalStateException - If predicate evaluates to false

Since:

0.5.0

checkState

public static void checkState(boolean expression,
                              @Nullable
                              java.lang.String template,
                              @Nullable
                              java.lang.Object... args)

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

Preferred to checkState(boolean, Object) when elements needs to be substituted or otherwise processed for performance reasons

Parameters:

expression - A boolean expression

template - A template for a formatted message. The message is formed by replacing each %s placeholder in the template with an argument. These are matched by position - the first %s gets args[0], etc. Unmatched arguments will be appended to the formatted message in square braces. Unmatched placeholders will be left as-is.

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

Throws:

java.lang.IllegalStateException - If expression is false

Since:

0.5.0

checkState

public static <T> T checkState(@Nullable
                               T value,
                               java.util.function.Predicate<T> predicate,
                               @Nullable
                               java.lang.String template,
                               @Nullable
                               java.lang.Object... args)

Evaluates a value against a provided Predicate expression

Preferred to checkArgument(Object, Predicate, Object) when elements needs to be substituted or otherwise processed for performance reasons

Type Parameters:

T - The type of the value being evaluated

Parameters:

value - An assignable value to evaluate

predicate - An operation to evaluate against value

template - A template for a formatted message. The message is formed by replacing each %s placeholder in the template with an argument. These are matched by position - the first %s gets args[0], etc. Unmatched arguments will be appended to the formatted message in square braces. Unmatched placeholders will be left as-is.

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

Returns:

value if the provided predicate evaluates to true

Throws:

java.lang.IllegalStateException - If predicate evaluates to false

Since:

0.5.0