Validating Lists in a Spring Controller

1. Introduction

Validating user inputs is a common requirement in any application. In this tutorial, we’ll go over ways to validate a List of objects as a parameter to a Spring controller.

We’ll add validation in the controller layer to ensure that the user-specified data satisfies the specified conditions.

2. Adding Constraints to Fields

For our example, we’ll use a simple Spring controller that manages a database of movies. We’ll focus on a method that accepts a list of movies and adds them to the database after performing validations on the list.

So, let’s start by adding constraints on the Movie class using javax validation:

public class Movie {

    private String id;

    @NotEmpty(message = "Movie name cannot be empty.")
    private String name;

    // standard setters and getters
}

3. Adding Validation Annotations in the Controller

Let’s look at our controller. First, we’ll add the @Validated annotation to the controller class:

@Validated
@RestController
@RequestMapping("/movies")
public class MovieController {

    @Autowired
    private MovieService movieService;

    //...
}

Next, let’s write the controller method where we’ll validate the list of Movie objects passed in.

We’ll add the @NotEmpty annotation to our list of movies to validate that there should be at least one element in the list. At the same time, we’ll add the @Valid annotation to ensure that the Movie objects themselves are valid:

@PostMapping
public void addAll(
  @RequestBody 
  @NotEmpty(message = "Input movie list cannot be empty.")
  List<@Valid Movie> movies) {
    movieService.addAll(movies);
}

If we call the controller method with an empty Movie list input, then the validation will fail because of the @NotEmpty annotation, and we’ll see the message:

Input movie list cannot be empty.

The @Valid annotation will make sure that the constraints specified in the Movie class are evaluated for each object in the list. Hence, if we pass a Movie with an empty name in the list, validation will fail with the message:

Movie name cannot be empty.

4. Custom Validators

We can also add custom constraint validators to the input list.

For our example, the custom constraint will validate the condition that the input list size is restricted to a maximum of four elements. Let’s create this custom constraint annotation:

@Constraint(validatedBy = MaxSizeConstraintValidator.class)
@Retention(RetentionPolicy.RUNTIME)
public @interface MaxSizeConstraint {
    String message() default "The input list cannot contain more than 4 movies.";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

Now, we’ll create a validator that will apply the above constraint:

public class MaxSizeConstraintValidator implements ConstraintValidator<MaxSizeConstraint, List<Movie>> {
    @Override
    public boolean isValid(List<Movie> values, ConstraintValidatorContext context) {
        return values.size() <= 4;
    }
}

Finally, we’ll add the @MaxSizeConstraint annotation to our controller method:

@PostMapping
public void addAll(
  @RequestBody
  @NotEmpty(message = "Input movie list cannot be empty.")
  @MaxSizeConstraint
  List<@Valid Movie> movies) {
    movieService.addAll(movies);
}

Here, @MaxSizeConstraint will validate the size of the input. So, if we pass more than four Movie objects in the input list, the validation will fail.

5. Handling the Exception

If any of the validations fail, ConstraintViolationException is thrown. Now, let’s see how we can add an exception handling component to catch this exception.

@ExceptionHandler(ConstraintViolationException.class)
public ResponseEntity handle(ConstraintViolationException constraintViolationException) {
    Set<ConstraintViolation<?>> violations = constraintViolationException.getConstraintViolations();
    String errorMessage = "";
    if (!violations.isEmpty()) {
        StringBuilder builder = new StringBuilder();
        violations.forEach(violation -> builder.append(" " + violation.getMessage()));
        errorMessage = builder.toString();
    } else {
        errorMessage = "ConstraintViolationException occured.";
    }
    return new ResponseEntity<>(errorMessage, HttpStatus.BAD_REQUEST);
 }

6. Testing the API

Now, we’ll test our controller with valid and invalid inputs.

Firstly, let’s provide valid input to the API:

curl -v -d '[{"name":"Movie1"}]' -H "Content-Type: application/json" -X POST http://localhost:8080/movies 

In this scenario, we’ll get an HTTP status 200 response:

...
HTTP/1.1 200
...

Next, we’ll check our API response when we pass invalid inputs.

Let’s try an empty list:

curl -d [] -H "Content-Type: application/json" -X POST http://localhost:8080/movies

In this scenario, we’ll get an HTTP status 400 response. This is because the input doesn’t satisfy the @NotEmpty constraint.

Input movie list cannot be empty.

Next, let’s try passing five Movie objects in the list:

curl -d '[{"name":"Movie1"},{"name":"Movie2"},{"name":"Movie3"},{"name":"Movie4"},{"name":"Movie5"}]'\
  -H "Content-Type: application/json" -X POST http://localhost:8080/movie

This will also result in HTTP status 400 response because we fail the @MaxSizeConstraint constraint:

The input list cannot contain more than 4 movies.

7. Conclusion

In this quick article, we learned how to validate a list of objects in Spring.