Package org.atlanmod.commons

Class Guards

java.lang.Object

org.atlanmod.commons.Guards

@ParametersAreNonnullByDefault
public class Guards
extends Object

Static convenience methods that help a method or constructor check whether it was invoked correctly (whether its preconditions have been met). These methods generally accept a boolean expression which is expected to be true (or in the case of checkNotNull, an object reference which is expected to be non-null). When false (or null) is passed instead, the Preconditions method throws an unchecked exception, which helps the calling method communicate to its caller that that caller has made a mistake. Warning: The goal of this class is to improve readability of code, but in some circumstances this may come at a significant performance cost. Remember that parameter values for message construction must all be computed eagerly, and autoboxing and varargs array creation may happen as well, even when the precondition check then succeeds (as it should almost always do in production). In some circumstances these wasted CPU cycles and allocations can add up to a real problem.

Method Summary

Modifier and Type	Method	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, String message)	Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(boolean expression, String pattern, Object... args)	Ensures the truth of an expression involving one or more parameters to the calling method.
static int	checkElementIndex(int index, int size)	Ensures that index specifies a valid element in an array, list or string of size.
static <T> T	checkEqualTo(T value, T other)	Ensures that a value passed as a parameter to the calling method is equal to other.
static <T> T	checkEqualTo(T value, T other, String message)	Ensures that a value passed as a parameter to the calling method is equal to other.
static <T> T	checkEqualTo(T value, T other, String pattern, Object... args)	Ensures that a value passed as a parameter to the calling method is equal to other.
static <C extends Comparable<C>> C	checkGreaterThan(C value, C lowerBoundExclusive)	Ensures that a value passed as a parameter to the calling method is strictly greater than lowerBoundExclusive.
static <C extends Comparable<C>> C	checkGreaterThan(C value, C lowerBoundExclusive, String message)	Ensures that a value passed as a parameter to the calling method is strictly greater than lowerBoundExclusive.
static <C extends Comparable<C>> C	checkGreaterThan(C value, C lowerBoundExclusive, String pattern, Object... args)	Ensures that a value passed as a parameter to the calling method is strictly greater than lowerBoundExclusive.
static <C extends Comparable<C>> C	checkGreaterThanOrEqualTo(C value, C lowerBoundInclusive)	Ensures that a value passed as a parameter to the calling method is greater than or equal to lowerBoundInclusive.
static <C extends Comparable<C>> C	checkGreaterThanOrEqualTo(C value, C lowerBoundInclusive, String message)	Ensures that a value passed as a parameter to the calling method is greater than or equal to lowerBoundInclusive.
static <C extends Comparable<C>> C	checkGreaterThanOrEqualTo(C value, C lowerBoundInclusive, String pattern, Object... args)	Ensures that a value passed as a parameter to the calling method is greater than or equal to lowerBoundInclusive.
static <T> T	checkInstanceOf(T reference, Class<?> type)	Ensures that an object reference passed as a parameter to the calling method is instance of type.
static <T> T	checkInstanceOf(T reference, Class<?> type, String message)	Ensures that an object reference passed as a parameter to the calling method is instance of type.
static <T> T	checkInstanceOf(T reference, Class<?> type, String pattern, Object... args)	Ensures that an object reference passed as a parameter to the calling method is instance of type.
static <C extends Comparable<C>> C	checkLessThan(C value, C upperBoundExclusive)	Ensures that a value passed as a parameter to the calling method is strictly less than upperBoundExclusive.
static <C extends Comparable<C>> C	checkLessThan(C value, C upperBoundExclusive, String message)	Ensures that a value passed as a parameter to the calling method is strictly less than upperBoundExclusive.
static <C extends Comparable<C>> C	checkLessThan(C value, C upperBoundExclusive, String pattern, Object... args)	Ensures that a value passed as a parameter to the calling method is strictly less than upperBoundExclusive.
static <C extends Comparable<C>> C	checkLessThanOrEqualTo(C value, C upperBoundInclusive)	Ensures that a value passed as a parameter to the calling method is less than or equal to upperBoundInclusive.
static <C extends Comparable<C>> C	checkLessThanOrEqualTo(C value, C upperBoundInclusive, String message)	Ensures that a value passed as a parameter to the calling method is less than or equal to upperBoundInclusive.
static <C extends Comparable<C>> C	checkLessThanOrEqualTo(C value, C upperBoundInclusive, String pattern, Object... args)	Ensures that a value passed as a parameter to the calling method is less than or equal to upperBoundInclusive.
static <C extends Collection<? extends T>,T> C	checkNotContainsNull(C collection)	Ensures that a collection passed as a parameter to the calling method is not null and does not contains any null element.
static <C extends Collection<? extends T>,T> C	checkNotContainsNull(C collection, String message)	Ensures that a collection passed as a parameter to the calling method is not null and does not contains any null element.
static <C extends Collection<? extends T>,T> C	checkNotContainsNull(C collection, String pattern, Object... args)	Ensures that a collection passed as a parameter to the calling method is not null and does not contains any null element.
static <T> T	checkNotNull(T reference)	Ensures that an object reference passed as a parameter to the calling method is not null.
static <T> T	checkNotNull(T reference, String message)	Ensures that an object reference passed as a parameter to the calling method is not null.
static <T> T	checkNotNull(T reference, String pattern, Object... args)	Ensures that an object reference passed as a parameter to the calling method is not null.
static int	checkPositionIndex(int index, int size)	Ensures that index specifies a valid position in an array, list or string of size.
static void	checkState(boolean expression)	Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkState(boolean expression, String message)	Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkState(boolean expression, String pattern, Object... args)	Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Methods inherited from class java.lang.Object

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

Method Detail

checkArgument

@Contract(value="false -> fail",
          pure=true)
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:

IllegalArgumentException - if expression is false

checkArgument

@Contract(value="false, _ -> fail",
          pure=true)
public static void checkArgument(boolean expression,
                                 String message)

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

Parameters:

expression - a boolean expression

message - the exception message to use if the check fails

Throws:

IllegalArgumentException - if expression is false

checkArgument

@Contract(value="false, _, _ -> fail",
          pure=true)
public static void checkArgument(boolean expression,
                                 String pattern,
                                 Object... args)

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

Parameters:

expression - a boolean expression

pattern - a template for the exception message should the check fail

args - the arguments to be substituted into the message template

Throws:

IllegalArgumentException - if expression is false

NullPointerException - if the check fails and either pattern or args is null

checkState

@Contract(value="false -> fail",
          pure=true)
public static void checkState(boolean expression)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Parameters:

expression - a boolean expression

Throws:

IllegalStateException - if expression is false

checkState

@Contract(value="false, _ -> fail",
          pure=true)
public static void checkState(boolean expression,
                              String message)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Parameters:

expression - a boolean expression

message - the exception message to use if the check fails

Throws:

IllegalStateException - if expression is false

checkState

@Contract(value="false, _, _ -> fail",
          pure=true)
public static void checkState(boolean expression,
                              String pattern,
                              Object... args)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Parameters:

expression - a boolean expression

pattern - a template for the exception message should the check fail

args - the arguments to be substituted into the message template

Throws:

IllegalStateException - if expression is false

NullPointerException - if the check fails and either pattern or args is null

checkNotNull

@Nonnull
@Contract(value="null -> fail",
          pure=true)
public static <T> T checkNotNull(@Nullable
                                 T reference)

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

Parameters:

reference - an object reference

Returns:

the non-null reference that was validated

Throws:

NullPointerException - if reference is null

checkNotNull

@Nonnull
@Contract(value="null, _ -> fail",
          pure=true)
public static <T> T checkNotNull(@Nullable
                                 T reference,
                                 String message)

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

Parameters:

reference - an object reference

message - the exception message to use if the check fails

Returns:

the non-null reference that was validated

Throws:

NullPointerException - if reference is null

checkNotNull

@Nonnull
@Contract(value="null, _, _ -> fail",
          pure=true)
public static <T> T checkNotNull(@Nullable
                                 T reference,
                                 String pattern,
                                 Object... args)

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

Parameters:

reference - an object reference

pattern - a template for the exception message should the check fail

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

Returns:

the non-null reference that was validated

Throws:

NullPointerException - if reference is null

checkNotContainsNull

@Nonnull
public static <C extends Collection<? extends T>,T> C checkNotContainsNull(C collection)

Ensures that a collection passed as a parameter to the calling method is not null and does not contains any null element.

Parameters:

collection - a collection

Returns:

the non-null collection that was validated

Throws:

NullPointerException - if collection is null or contains at least one null element

checkNotContainsNull

@Nonnull
public static <C extends Collection<? extends T>,T> C checkNotContainsNull(C collection,
                                                                                 String message)

Ensures that a collection passed as a parameter to the calling method is not null and does not contains any null element.

Parameters:

collection - a collection

message - the exception message to use if the check fails

Returns:

the non-null collection that was validated

Throws:

NullPointerException - if collection is null or contains at least one null element

checkNotContainsNull

@Nonnull
public static <C extends Collection<? extends T>,T> C checkNotContainsNull(C collection,
                                                                                 String pattern,
                                                                                 Object... args)

Ensures that a collection passed as a parameter to the calling method is not null and does not contains any null element.

Parameters:

collection - a collection

pattern - a template for the exception message should the check fail

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

Returns:

the non-null collection that was validated

Throws:

NullPointerException - if collection is null or contains at least one null element

checkInstanceOf

@Nonnull
public static <T> T checkInstanceOf(T reference,
                                    Class<?> type)

Ensures that an object reference passed as a parameter to the calling method is instance of type.

Parameters:

reference - an object reference

type - the expected type of reference

Returns:

the reference that was validated

Throws:

IllegalArgumentException - if reference is not instance of type

checkInstanceOf

@Nonnull
public static <T> T checkInstanceOf(T reference,
                                    Class<?> type,
                                    String message)

Ensures that an object reference passed as a parameter to the calling method is instance of type.

Parameters:

reference - an object reference

type - the expected type of reference

message - the exception message to use if the check fails

Returns:

the reference that was validated

Throws:

IllegalArgumentException - if reference is not instance of type

checkInstanceOf

@Nonnull
public static <T> T checkInstanceOf(T reference,
                                    Class<?> type,
                                    String pattern,
                                    Object... args)

Ensures that an object reference passed as a parameter to the calling method is instance of type.

Parameters:

reference - an object reference

type - the expected type of reference

pattern - a template for the exception message should the check fail

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

Returns:

the reference that was validated

Throws:

IllegalArgumentException - if reference is not instance of type

checkEqualTo

public static <T> T checkEqualTo(@Nullable
                                 T value,
                                 @Nullable
                                 T other)

Ensures that a value passed as a parameter to the calling method is equal to other.

Parameters:

value - an object reference

other - another object reference

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is not equal to other

checkEqualTo

public static <T> T checkEqualTo(@Nullable
                                 T value,
                                 @Nullable
                                 T other,
                                 String message)

Ensures that a value passed as a parameter to the calling method is equal to other.

Parameters:

value - an object reference

other - another object reference

message - the exception message to use if the check fails

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is not equal to other

checkEqualTo

public static <T> T checkEqualTo(@Nullable
                                 T value,
                                 @Nullable
                                 T other,
                                 String pattern,
                                 Object... args)

Ensures that a value passed as a parameter to the calling method is equal to other.

Parameters:

value - an object reference

other - another object reference

pattern - a template for the exception message should the check fail

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

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is not equal to other

checkGreaterThan

@Nonnull
public static <C extends Comparable<C>> C checkGreaterThan(C value,
                                                           C lowerBoundExclusive)

Ensures that a value passed as a parameter to the calling method is strictly greater than lowerBoundExclusive.

Parameters:

value - a comparable

lowerBoundExclusive - the lower bound (exclusive)

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is less than or equal to lowerBoundExclusive

checkGreaterThan

@Nonnull
public static <C extends Comparable<C>> C checkGreaterThan(C value,
                                                           C lowerBoundExclusive,
                                                           String message)

Ensures that a value passed as a parameter to the calling method is strictly greater than lowerBoundExclusive.

Parameters:

value - a comparable

lowerBoundExclusive - the lower bound (exclusive)

message - the exception message to use if the check fails

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is less than or equal to lowerBoundExclusive

checkGreaterThan

@Nonnull
public static <C extends Comparable<C>> C checkGreaterThan(C value,
                                                           C lowerBoundExclusive,
                                                           String pattern,
                                                           Object... args)

Ensures that a value passed as a parameter to the calling method is strictly greater than lowerBoundExclusive.

Parameters:

value - a comparable

lowerBoundExclusive - the lower bound (exclusive)

pattern - a template for the exception message should the check fail

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

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is less than or equal to lowerBoundExclusive

checkGreaterThanOrEqualTo

@Nonnull
public static <C extends Comparable<C>> C checkGreaterThanOrEqualTo(C value,
                                                                    C lowerBoundInclusive)

Ensures that a value passed as a parameter to the calling method is greater than or equal to lowerBoundInclusive.

Parameters:

value - a comparable

lowerBoundInclusive - the lower bound (inclusive)

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is less than lowerBoundInclusive

checkGreaterThanOrEqualTo

@Nonnull
public static <C extends Comparable<C>> C checkGreaterThanOrEqualTo(C value,
                                                                    C lowerBoundInclusive,
                                                                    String message)

Ensures that a value passed as a parameter to the calling method is greater than or equal to lowerBoundInclusive.

Parameters:

value - a comparable

lowerBoundInclusive - the lower bound (inclusive)

message - the exception message to use if the check fails

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is less than lowerBoundInclusive

checkGreaterThanOrEqualTo

@Nonnull
public static <C extends Comparable<C>> C checkGreaterThanOrEqualTo(C value,
                                                                    C lowerBoundInclusive,
                                                                    String pattern,
                                                                    Object... args)

Ensures that a value passed as a parameter to the calling method is greater than or equal to lowerBoundInclusive.

Parameters:

value - a comparable

lowerBoundInclusive - the lower bound (inclusive)

pattern - a template for the exception message should the check fail

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

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is less than lowerBoundInclusive

checkLessThan

@Nonnull
public static <C extends Comparable<C>> C checkLessThan(C value,
                                                        C upperBoundExclusive)

Ensures that a value passed as a parameter to the calling method is strictly less than upperBoundExclusive.

Parameters:

value - a comparable

upperBoundExclusive - the upper bound (exclusive)

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is greater than or equal to upperBoundExclusive

checkLessThan

@Nonnull
public static <C extends Comparable<C>> C checkLessThan(C value,
                                                        C upperBoundExclusive,
                                                        String message)

Ensures that a value passed as a parameter to the calling method is strictly less than upperBoundExclusive.

Parameters:

value - a comparable

upperBoundExclusive - the upper bound (exclusive)

message - the exception message to use if the check fails

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is greater than or equal to upperBoundExclusive

checkLessThan

@Nonnull
public static <C extends Comparable<C>> C checkLessThan(C value,
                                                        C upperBoundExclusive,
                                                        String pattern,
                                                        Object... args)

Ensures that a value passed as a parameter to the calling method is strictly less than upperBoundExclusive.

Parameters:

value - a comparable

upperBoundExclusive - the upper bound (exclusive)

pattern - a template for the exception message should the check fail

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

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is greater than or equal to upperBoundExclusive

checkLessThanOrEqualTo

@Nonnull
public static <C extends Comparable<C>> C checkLessThanOrEqualTo(C value,
                                                                 C upperBoundInclusive)

Ensures that a value passed as a parameter to the calling method is less than or equal to upperBoundInclusive.

Parameters:

value - a comparable

upperBoundInclusive - the upper bound (inclusive)

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is greater than upperBoundInclusive

checkLessThanOrEqualTo

@Nonnull
public static <C extends Comparable<C>> C checkLessThanOrEqualTo(C value,
                                                                 C upperBoundInclusive,
                                                                 String message)

Ensures that a value passed as a parameter to the calling method is less than or equal to upperBoundInclusive.

Parameters:

value - a comparable

upperBoundInclusive - the upper bound (inclusive)

message - the exception message to use if the check fails

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is greater than upperBoundInclusive

checkLessThanOrEqualTo

@Nonnull
public static <C extends Comparable<C>> C checkLessThanOrEqualTo(C value,
                                                                 C upperBoundInclusive,
                                                                 String pattern,
                                                                 Object... args)

Ensures that a value passed as a parameter to the calling method is less than or equal to upperBoundInclusive.

Parameters:

value - a comparable

upperBoundInclusive - the upper bound (inclusive)

pattern - a template for the exception message should the check fail

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

Returns:

the value that was validated

Throws:

IllegalArgumentException - if value is greater than upperBoundInclusive

checkElementIndex

@Nonnegative
public static int checkElementIndex(@Nonnegative
                                    int index,
                                    @Nonnegative
                                    int size)

Ensures that index specifies a valid element in an array, list or string of size. An element index may range from zero, inclusive, to size, exclusive.

Parameters:

index - a user-supplied index identifying an element of an array, list or string

size - the size of that array, list or string

Returns:

the index that was validated

Throws:

IndexOutOfBoundsException - if index is negative or is not less than size

IllegalArgumentException - if size is negative

checkPositionIndex

@Nonnegative
public static int checkPositionIndex(@Nonnegative
                                     int index,
                                     @Nonnegative
                                     int size)

Ensures that index specifies a valid position in an array, list or string of size. A position index may range from zero to size, inclusive.

Parameters:

index - a user-supplied index identifying a position in an array, list or string

size - the size of that array, list or string

Returns:

the index that was validated

Throws:

IndexOutOfBoundsException - if index is negative or is greater than size

IllegalArgumentException - if size is negative