Top Description Constructors Methods
org.springframework.util

public abstract Class Assert

extends Object
Class Inheritance
Imports
java.util.Collection, .Map, java.util.function.Supplier, org.springframework.lang.Nullable
Assertion utility class that assists in validating arguments.

Useful for identifying programmer errors early and clearly at runtime.

For example, if the contract of a public method states it does not allow null arguments, Assert can be used to validate that contract. Doing this clearly indicates a contract violation when it occurs and protects the class's invariants.

Typically used to validate method arguments rather than configuration properties, to check for cases that are usually programmer errors rather than configuration errors. In contrast to configuration initialization code, there is usually no point in falling back to defaults in such methods.

This class is similar to JUnit's assertion library. If an argument value is deemed invalid, an IllegalArgumentException is thrown (typically). For example: 

Assert.notNull(clazz, "The class must not be null");
Assert.isTrue(i > 0, "The value must be greater than zero");

Mainly for internal use within the framework; for a more comprehensive suite of assertion utilities consider org.apache.commons.lang3.Validate from Apache Commons Lang, Google Guava's Preconditions, or similar third-party libraries.

Authors
Keith Donald, Juergen Hoeller, Sam Brannen, Colin Sampaleanu, Rob Harrop
Since
1.1.2

Constructor Summary

AccessConstructor and Description
public
Assert()

Method Summary

Modifier and TypeMethod and Description
private static void
assignableCheckFailed(Class<?> superType, Class<?> subType, String msg)

public static void
doesNotContain(String
the text to search
textToSearch, String
the substring to find within the text
substring, String
the exception message to use if the assertion fails
message)

Assert that the given text does not contain the given substring.

public static void
doesNotContain(String
the text to search
textToSearch, String
the substring to find within the text
substring, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that the given text does not contain the given substring.

private static boolean
endsWithSeparator(String msg)

public static void
hasLength(String
the String to check
text, String
the exception message to use if the assertion fails
message)

Assert that the given String is not empty; that is, it must not be null and not the empty String.

public static void
hasLength(String
the String to check
text, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that the given String is not empty; that is, it must not be null and not the empty String.

public static void
hasText(String
the String to check
text, String
the exception message to use if the assertion fails
message)

Assert that the given String contains valid text content; that is, it must not be null and must contain at least one non-whitespace character.

public static void
hasText(String
the String to check
text, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that the given String contains valid text content; that is, it must not be null and must contain at least one non-whitespace character.

private static void
instanceCheckFailed(Class<?> type, Object obj, String msg)

public static void
isAssignable(Class<?>
the supertype to check against
superType, Class<?>
the subtype to check
subType, String
a message which will be prepended to provide further context. If it is empty or ends in ":" or ";" or "," or ".", a full exception message will be appended. If it ends in a space, the name of the offending subtype will be appended. In any other case, a ":" with a space and the name of the offending subtype will be appended.
message)

Assert that superType.isAssignableFrom(subType) is true.

public static void
isAssignable(Class<?>
the supertype to check against
superType, Class<?>
the subtype to check
subType, Supplier<String>
a supplier for the exception message to use if the assertion fails. See isAssignable(Class, Class, String) for details.
messageSupplier)

Assert that superType.isAssignableFrom(subType) is true.

public static void
isAssignable(Class<?>
the supertype to check
superType, Class<?>
the subtype to check
subType)

Assert that superType.isAssignableFrom(subType) is true.

public static void
isInstanceOf(Class<?>
the type to check against
type, Object
the object to check
obj, String
a message which will be prepended to provide further context. If it is empty or ends in ":" or ";" or "," or ".", a full exception message will be appended. If it ends in a space, the name of the offending object's type will be appended. In any other case, a ":" with a space and the name of the offending object's type will be appended.
message)

Assert that the provided object is an instance of the provided class.

public static void
isInstanceOf(Class<?>
the type to check against
type, Object
the object to check
obj, Supplier<String>
a supplier for the exception message to use if the assertion fails. See isInstanceOf(Class, Object, String) for details.
messageSupplier)

Assert that the provided object is an instance of the provided class.

public static void
isInstanceOf(Class<?>
the type to check against
type, Object
the object to check
obj)

Assert that the provided object is an instance of the provided class.

public static void
isNull(Object
the object to check
object, String
the exception message to use if the assertion fails
message)

Assert that an object is null.

public static void
isNull(Object
the object to check
object, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that an object is null.

public static void
isTrue(boolean
a boolean expression
expression, String
the exception message to use if the assertion fails
message)

Assert a boolean expression, throwing an IllegalArgumentException if the expression evaluates to false.

public static void
isTrue(boolean
a boolean expression
expression, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert a boolean expression, throwing an IllegalArgumentException if the expression evaluates to false.

private static String
messageWithTypeName(String msg, Object typeName)

public static void
noNullElements(Object[]
the array to check
array, String
the exception message to use if the assertion fails
message)

Assert that an array contains no null elements.

public static void
noNullElements(Object[]
the array to check
array, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that an array contains no null elements.

public static void
noNullElements(Collection<?>
the collection to check
collection, String
the exception message to use if the assertion fails
message)

Assert that a collection contains no null elements.

public static void
noNullElements(Collection<?>
the collection to check
collection, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that a collection contains no null elements.

public static void
notEmpty(Object[]
the array to check
array, String
the exception message to use if the assertion fails
message)

Assert that an array contains elements; that is, it must not be null and must contain at least one element.

public static void
notEmpty(Object[]
the array to check
array, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that an array contains elements; that is, it must not be null and must contain at least one element.

public static void
notEmpty(Collection<?>
the collection to check
collection, String
the exception message to use if the assertion fails
message)

Assert that a collection contains elements; that is, it must not be null and must contain at least one element.

public static void
notEmpty(Collection<?>
the collection to check
collection, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that a collection contains elements; that is, it must not be null and must contain at least one element.

public static void
notEmpty(Map<?, ?>
the map to check
map, String
the exception message to use if the assertion fails
message)

Assert that a Map contains entries; that is, it must not be null and must contain at least one entry.

public static void
notEmpty(Map<?, ?>
the map to check
map, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that a Map contains entries; that is, it must not be null and must contain at least one entry.

public static void
notNull(Object
the object to check
object, String
the exception message to use if the assertion fails
message)

Assert that an object is not null.

public static void
notNull(Object
the object to check
object, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert that an object is not null.

private static String
nullSafeGet(Supplier<String> messageSupplier)

public static void
state(boolean
a boolean expression
expression, String
the exception message to use if the assertion fails
message)

Assert a boolean expression, throwing an IllegalStateException if the expression evaluates to false.

public static void
state(boolean
a boolean expression
expression, Supplier<String>
a supplier for the exception message to use if the assertion fails
messageSupplier)

Assert a boolean expression, throwing an IllegalStateException if the expression evaluates to false.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Assertback to summary
public Assert()

Method Detail

assignableCheckFailedback to summary
private static void assignableCheckFailed(Class<?> superType, Class<?> subType, String msg)
doesNotContainback to summary
public static void doesNotContain(String textToSearch, String substring, String message)

Assert that the given text does not contain the given substring. 

Assert.doesNotContain(name, "rod", "Name must not contain 'rod'");
Parameters
textToSearch:String

the text to search

substring:String

the substring to find within the text

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the text contains the substring
doesNotContainback to summary
public static void doesNotContain(String textToSearch, String substring, Supplier<String> messageSupplier)

Assert that the given text does not contain the given substring. 

Assert.doesNotContain(name, forbidden, () -> "Name must not contain '" + forbidden + "'");
Parameters
textToSearch:String

the text to search

substring:String

the substring to find within the text

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the text contains the substring
Since
5.0
endsWithSeparatorback to summary
private static boolean endsWithSeparator(String msg)
hasLengthback to summary
public static void hasLength(String text, String message)

Assert that the given String is not empty; that is, it must not be null and not the empty String. 

Assert.hasLength(name, "Name must not be empty");
Parameters
text:String

the String to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the text is empty
See Also
StringUtils#hasLength
hasLengthback to summary
public static void hasLength(String text, Supplier<String> messageSupplier)

Assert that the given String is not empty; that is, it must not be null and not the empty String. 

Assert.hasLength(account.getName(),
    () -> "Name for account '" + account.getId() + "' must not be empty");
Parameters
text:String

the String to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the text is empty
Since
5.0
See Also
StringUtils#hasLength
hasTextback to summary
public static void hasText(String text, String message)

Assert that the given String contains valid text content; that is, it must not be null and must contain at least one non-whitespace character. 

Assert.hasText(name, "'name' must not be empty");
Parameters
text:String

the String to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the text does not contain valid text content
See Also
StringUtils#hasText
hasTextback to summary
public static void hasText(String text, Supplier<String> messageSupplier)

Assert that the given String contains valid text content; that is, it must not be null and must contain at least one non-whitespace character. 

Assert.hasText(account.getName(),
    () -> "Name for account '" + account.getId() + "' must not be empty");
Parameters
text:String

the String to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the text does not contain valid text content
Since
5.0
See Also
StringUtils#hasText
instanceCheckFailedback to summary
private static void instanceCheckFailed(Class<?> type, Object obj, String msg)
isAssignableback to summary
public static void isAssignable(Class<?> superType, Class<?> subType, String message)

Assert that superType.isAssignableFrom(subType) is true. 

Assert.isAssignable(Number.class, myClass, "Number expected");
Parameters
superType:Class<?>

the supertype to check against

subType:Class<?>

the subtype to check

message:String

a message which will be prepended to provide further context. If it is empty or ends in ":" or ";" or "," or ".", a full exception message will be appended. If it ends in a space, the name of the offending subtype will be appended. In any other case, a ":" with a space and the name of the offending subtype will be appended.

Exceptions
IllegalArgumentException:
if the classes are not assignable
isAssignableback to summary
public static void isAssignable(Class<?> superType, Class<?> subType, Supplier<String> messageSupplier)

Assert that superType.isAssignableFrom(subType) is true. 

Assert.isAssignable(Number.class, myClass, () -> "Processing " + myAttributeName + ":");
Parameters
superType:Class<?>

the supertype to check against

subType:Class<?>

the subtype to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails. See isAssignable(Class, Class, String) for details.

Exceptions
IllegalArgumentException:
if the classes are not assignable
Since
5.0
isAssignableback to summary
public static void isAssignable(Class<?> superType, Class<?> subType)

Assert that superType.isAssignableFrom(subType) is true. 

Assert.isAssignable(Number.class, myClass);
Parameters
superType:Class<?>

the supertype to check

subType:Class<?>

the subtype to check

Exceptions
IllegalArgumentException:
if the classes are not assignable
isInstanceOfback to summary
public static void isInstanceOf(Class<?> type, Object obj, String message)

Assert that the provided object is an instance of the provided class. 

Assert.instanceOf(Foo.class, foo, "Foo expected");
Parameters
type:Class<?>

the type to check against

obj:Object

the object to check

message:String

a message which will be prepended to provide further context. If it is empty or ends in ":" or ";" or "," or ".", a full exception message will be appended. If it ends in a space, the name of the offending object's type will be appended. In any other case, a ":" with a space and the name of the offending object's type will be appended.

Exceptions
IllegalArgumentException:
if the object is not an instance of type
isInstanceOfback to summary
public static void isInstanceOf(Class<?> type, Object obj, Supplier<String> messageSupplier)

Assert that the provided object is an instance of the provided class. 

Assert.instanceOf(Foo.class, foo, () -> "Processing " + Foo.class.getSimpleName() + ":");
Parameters
type:Class<?>

the type to check against

obj:Object

the object to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails. See isInstanceOf(Class, Object, String) for details.

Exceptions
IllegalArgumentException:
if the object is not an instance of type
Since
5.0
isInstanceOfback to summary
public static void isInstanceOf(Class<?> type, Object obj)

Assert that the provided object is an instance of the provided class. 

Assert.instanceOf(Foo.class, foo);
Parameters
type:Class<?>

the type to check against

obj:Object

the object to check

Exceptions
IllegalArgumentException:
if the object is not an instance of type
isNullback to summary
public static void isNull(Object object, String message)

Assert that an object is null. 

Assert.isNull(value, "The value must be null");
Parameters
object:Object

the object to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the object is not null
isNullback to summary
public static void isNull(Object object, Supplier<String> messageSupplier)

Assert that an object is null. 

Assert.isNull(value, () -> "The value '" + value + "' must be null");
Parameters
object:Object

the object to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the object is not null
Since
5.0
isTrueback to summary
public static void isTrue(boolean expression, String message)

Assert a boolean expression, throwing an IllegalArgumentException if the expression evaluates to false. 

Assert.isTrue(i > 0, "The value must be greater than zero");
Parameters
expression:boolean

a boolean expression

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if expression is false
isTrueback to summary
public static void isTrue(boolean expression, Supplier<String> messageSupplier)

Assert a boolean expression, throwing an IllegalArgumentException if the expression evaluates to false. 

Assert.isTrue(i > 0, () -> "The value '" + i + "' must be greater than zero");
Parameters
expression:boolean

a boolean expression

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if expression is false
Since
5.0
messageWithTypeNameback to summary
private static String messageWithTypeName(String msg, Object typeName)
noNullElementsback to summary
public static void noNullElements(Object[] array, String message)

Assert that an array contains no null elements.

Note

Does not complain if the array is empty! 

Assert.noNullElements(array, "The array must contain non-null elements");
Parameters
array:Object[]

the array to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the object array contains a null element
noNullElementsback to summary
public static void noNullElements(Object[] array, Supplier<String> messageSupplier)

Assert that an array contains no null elements.

Note

Does not complain if the array is empty! 

Assert.noNullElements(array, () -> "The " + arrayType + " array must contain non-null elements");
Parameters
array:Object[]

the array to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the object array contains a null element
Since
5.0
noNullElementsback to summary
public static void noNullElements(Collection<?> collection, String message)

Assert that a collection contains no null elements.

Note

Does not complain if the collection is empty! 

Assert.noNullElements(collection, "Collection must contain non-null elements");
Parameters
collection:Collection<?>

the collection to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the collection contains a null element
Since
5.2
noNullElementsback to summary
public static void noNullElements(Collection<?> collection, Supplier<String> messageSupplier)

Assert that a collection contains no null elements.

Note

Does not complain if the collection is empty! 

Assert.noNullElements(collection, () -> "Collection " + collectionName + " must contain non-null elements");
Parameters
collection:Collection<?>

the collection to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the collection contains a null element
Since
5.2
notEmptyback to summary
public static void notEmpty(Object[] array, String message)

Assert that an array contains elements; that is, it must not be null and must contain at least one element. 

Assert.notEmpty(array, "The array must contain elements");
Parameters
array:Object[]

the array to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the object array is null or contains no elements
notEmptyback to summary
public static void notEmpty(Object[] array, Supplier<String> messageSupplier)

Assert that an array contains elements; that is, it must not be null and must contain at least one element. 

Assert.notEmpty(array, () -> "The " + arrayType + " array must contain elements");
Parameters
array:Object[]

the array to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the object array is null or contains no elements
Since
5.0
notEmptyback to summary
public static void notEmpty(Collection<?> collection, String message)

Assert that a collection contains elements; that is, it must not be null and must contain at least one element. 

Assert.notEmpty(collection, "Collection must contain elements");
Parameters
collection:Collection<?>

the collection to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the collection is null or contains no elements
notEmptyback to summary
public static void notEmpty(Collection<?> collection, Supplier<String> messageSupplier)

Assert that a collection contains elements; that is, it must not be null and must contain at least one element. 

Assert.notEmpty(collection, () -> "The " + collectionType + " collection must contain elements");
Parameters
collection:Collection<?>

the collection to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the collection is null or contains no elements
Since
5.0
notEmptyback to summary
public static void notEmpty(Map<?, ?> map, String message)

Assert that a Map contains entries; that is, it must not be null and must contain at least one entry. 

Assert.notEmpty(map, "Map must contain entries");
Parameters
map:Map<?, ?>

the map to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the map is null or contains no entries
notEmptyback to summary
public static void notEmpty(Map<?, ?> map, Supplier<String> messageSupplier)

Assert that a Map contains entries; that is, it must not be null and must contain at least one entry. 

Assert.notEmpty(map, () -> "The " + mapType + " map must contain entries");
Parameters
map:Map<?, ?>

the map to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the map is null or contains no entries
Since
5.0
notNullback to summary
public static void notNull(Object object, String message)

Assert that an object is not null. 

Assert.notNull(clazz, "The class must not be null");
Parameters
object:Object

the object to check

message:String

the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the object is null
notNullback to summary
public static void notNull(Object object, Supplier<String> messageSupplier)

Assert that an object is not null. 

Assert.notNull(entity.getId(),
    () -> "ID for entity " + entity.getName() + " must not be null");
Parameters
object:Object

the object to check

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalArgumentException:
if the object is null
Since
5.0
nullSafeGetback to summary
private static String nullSafeGet(Supplier<String> messageSupplier)
Annotations
@Nullable
stateback to summary
public static void state(boolean expression, String message)

Assert a boolean expression, throwing an IllegalStateException if the expression evaluates to false.

Call isTrue if you wish to throw an IllegalArgumentException on an assertion failure. 

Assert.state(id == null, "The id property must not already be initialized");
Parameters
expression:boolean

a boolean expression

message:String

the exception message to use if the assertion fails

Exceptions
IllegalStateException:
if expression is false
stateback to summary
public static void state(boolean expression, Supplier<String> messageSupplier)

Assert a boolean expression, throwing an IllegalStateException if the expression evaluates to false.

Call isTrue if you wish to throw an IllegalArgumentException on an assertion failure. 

Assert.state(entity.getId() == null,
    () -> "ID for entity " + entity.getName() + " must not already be initialized");
Parameters
expression:boolean

a boolean expression

messageSupplier:Supplier<String>

a supplier for the exception message to use if the assertion fails

Exceptions
IllegalStateException:
if expression is false
Since
5.0