1. Overview
In this tutorial, we’ll focus on and describe the purpose of the Spring Assert class and demonstrate how to use it.
2. Purpose of the Assert Class
The Spring Assert class helps us validate arguments. By using methods of the Assert class, we can write assumptions which we expect to be true. And if they aren’t met, a runtime exception is thrown.
Each Assert’s method can be compared with the Java assert statement. Java assert statement throws an Error at runtime if its condition fails. The interesting fact is that those assertions can be disabled.
Here are some characteristics of the Spring Assert’s methods:
- Assert’s methods are static
- They throw either IllegalArgumentException or IllegalStateException
- The first parameter is usually an argument for validation or a logical condition to check
- The last parameter is usually an exception message which is displayed if the validation fails
- The message can be passed either as a String parameter or as a Supplier<String> parameter
Also note that despite the similar name, Spring assertions have nothing in common with the assertions of JUnit and other testing frameworks. Spring assertions aren’t for testing, but for debugging.
3. Example of Use
Let’s define a Car class with a public method drive():
public class Car {
private String state = "stop";
public void drive(int speed) {
Assert.isTrue(speed > 0, "speed must be positive");
this.state = "drive";
// ...
}
}
We can see how speed must be a positive number. The above row is a short way to check the condition and throw an exception if the condition fails:
if (!(speed > 0)) {
throw new IllegalArgumentException("speed must be positive");
}
Each Assert’s public method contains roughly this code – a conditional block with a runtime exception from which the application is not expected to recover.
If we try to call the drive() method with a negative argument, an IllegalArgumentException exception will be thrown:
Exception in thread "main" java.lang.IllegalArgumentException: speed must be positive
4. Logical Assertions
4.1. isTrue()
This assertion was discussed above. It accepts a boolean condition and throws an IllegalArgumentException when the condition is false.
4.2. state()
The state() method has the same signature as isTrue() but throws the IllegalStateException.
As the name suggests, it should be used when the method mustn’t be continued because of an illegal state of the object.
Imagine that we can’t call the fuel() method if the car is running. Let’s use the state() assertion in this case:
public void fuel() {
Assert.state(this.state.equals("stop"), "car must be stopped");
// ...
}
Of course, we can validate everything using logical assertions. But for better readability, we can use additional assertions which make our code more expressive.
5. Object and Type Assertions
5.1. notNull()
We can assume that an object is not null by using the notNull() method:
public void сhangeOil(String oil) {
Assert.notNull(oil, "oil mustn't be null");
// ...
}
5.2. isNull()
On the other hand, we can check if an object is null using the isNull() method:
public void replaceBattery(CarBattery carBattery) {
Assert.isNull(
carBattery.getCharge(),
"to replace battery the charge must be null");
// ...
}
5.3. isInstanceOf()
To check if an object is an instance of another object of the specific type we can use the isInstanceOf() method:
public void сhangeEngine(Engine engine) {
Assert.isInstanceOf(ToyotaEngine.class, engine);
// ...
}
In our example, the check passes successfully as ToyotaEngine is a subclass of Engine.
5.4. isAssignable()
To check types, we can use Assert.isAssignable():
public void repairEngine(Engine engine) {
Assert.isAssignable(Engine.class, ToyotaEngine.class);
// ...
}
Two recent assertions represent an is-a relationship.
6. Text assertions
Text assertions are used to perform checks on String arguments.
6.1. hasLength()
We can check if a String isn’t blank, meaning it contains at least one whitespace, by using the hasLength() method:
public void startWithHasLength(String key) {
Assert.hasLength(key, "key must not be null and must not the empty");
// ...
}
6.2. hasText()
We can strengthen the condition and check if a String contains at least one non-whitespace character, by using the hasText() method:
public void startWithHasText(String key) {
Assert.hasText(
key,
"key must not be null and must contain at least one non-whitespace character");
// ...
}
6.3. doesNotContain()
We can determine if a String argument doesn’t contain a specific substring by using the doesNotContain() method:
public void startWithNotContain(String key) {
Assert.doesNotContain(key, "123", "key mustn't contain 123");
// ...
}
7. Collection and Map Assertions
7.1. notEmpty() for collections
As the name says, the notEmpty() method asserts that a collection is not empty meaning that it’s not null and contains at least one element:
public void repair(Collection<String> repairParts) {
Assert.notEmpty(
repairParts,
"collection of repairParts mustn't be empty");
// ...
}
7.2. notEmpty() for maps
The same method is overloaded for maps, and we can check if a map is not empty and contains at least one entry:
public void repair(Map<String, String> repairParts) {
Assert.notEmpty(
repairParts,
"map of repairParts mustn't be empty");
// ...
}
8. Array Assertions
8.1. notEmpty() for arrays
Finally, we can check if an array is not empty and contains at least one element by using the notEmpty() method:
public void repair(String[] repairParts) {
Assert.notEmpty(
repairParts,
"array of repairParts mustn't be empty");
// ...
}
8.2. noNullElements()
We can verify that an array doesn’t contain null elements by using the noNullElements() method:
public void repairWithNoNull(String[] repairParts) {
Assert.noNullElements(
repairParts,
"array of repairParts mustn't contain null elements");
// ...
}
Note that this check still passes if the array is empty, as long as there are no null elements in it.
9. Conclusion
In this article, we explored the Assert class. This class is widely used within the Spring framework, but we could easily write more robust and expressive code taking advantage of it.
As always, the complete code for this article can be found in the GitHub project.