Form Validation

<!-- pom.xml -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

// build.gradle
// implementation 'org.springframework.boot:spring-boot-starter-validation'

// Imports on Spring Boot 3 / Jakarta EE 9+:
//   import jakarta.validation.Valid;
//   import jakarta.validation.constraints.*;
// Imports on Spring Boot 2.x:
//   import javax.validation.Valid;
//   import javax.validation.constraints.*;

// Request lifecycle for POST /register
//
//   request parameters
//     -> data binding        (String "abc" into int age   => typeMismatch error)
//     -> Bean Validation     (@NotBlank, @Email, ...      => constraint errors)
//     -> BindingResult       (holds every error from both steps)
//     -> your controller     (hasErrors() ? re-render : process)

public class RegisterForm {

    @NotBlank(message = "Username is required")
    @Size(min = 3, max = 30, message = "Username must be 3 to 30 characters")
    @Pattern(regexp = "^[a-zA-Z0-9_]*$",
             message = "Use letters, numbers and underscores only")
    private String username;

    @NotBlank(message = "Email is required")
    @Email(message = "Enter a valid email address")
    @Size(max = 254)
    private String email;

    @NotBlank(message = "Password is required")
    @Size(min = 8, max = 72, message = "Password must be 8 to 72 characters")
    private String password;

    private String confirmPassword;

    // Integer, not int: an empty field then yields a clean @NotNull error
    // instead of a type-mismatch error.
    @NotNull(message = "Age is required")
    @Min(value = 18, message = "You must be at least 18")
    @Max(value = 120, message = "Enter a realistic age")
    private Integer age;

    // Primitive boolean: an unticked box binds to false, which @AssertTrue rejects.
    @AssertTrue(message = "You must accept the terms")
    private boolean acceptedTerms;

    // getters and setters
}

// Constraint cheat sheet
//   @NotNull            value is not null (empty string is allowed)
//   @NotEmpty           not null and length > 0 (strings, collections, arrays)
//   @NotBlank           not null and contains a non-whitespace character (strings only)
//   @Size(min, max)     length of string / size of collection (null passes)
//   @Min / @Max         numeric bounds (null passes)
//   @Email              basic format check, lenient by design
//   @Pattern(regexp)    full-string regex match (null passes)
//   @Past / @Future     dates
//   @Positive / @PositiveOrZero / @Digits
//
// Most constraints treat null as valid; pair them with @NotNull / @NotBlank
// when the field is required.

@Controller
@RequestMapping("/register")
public class RegistrationController {

    private final UserService userService;

    public RegistrationController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public String showForm(Model model) {
        model.addAttribute("form", new RegisterForm());
        return "register";
    }

    @PostMapping
    public String submit(
            @ModelAttribute("form") @Valid RegisterForm form,
            BindingResult bindingResult,          // must come right after the form
            RedirectAttributes redirectAttributes) {

        if (bindingResult.hasErrors()) {
            return "register";                    // re-render, no redirect
        }

        userService.register(form);
        redirectAttributes.addFlashAttribute("message", "Account created, please sign in");
        return "redirect:/login";                 // Post/Redirect/Get
    }
}

// WRONG: parameter between the form and its BindingResult
//   public String submit(@Valid RegisterForm form, Model model, BindingResult result)
//   -> the errors are not delivered to the method; Spring throws and responds 400.
//
// WRONG: no BindingResult at all
//   public String submit(@Valid RegisterForm form)
//   -> validation failure throws MethodArgumentNotValidException (400).
//      That is the right behaviour for REST bodies, not for HTML forms.

// Example submissions
//   age=""   with  Integer age + @NotNull  -> constraint error  NotNull.form.age
//   age="x"  with  Integer age             -> binding error     typeMismatch.form.age
//   age=""   with  int age                 -> binding error     typeMismatch.form.age  (avoid)

@PostMapping
public String submit(@ModelAttribute("form") @Valid RegisterForm form,
                     BindingResult result) {

    if (result.hasFieldErrors("age")) {
        FieldError error = result.getFieldError("age");
        // error.getCode()            "typeMismatch" or "NotNull" or "Min" ...
        // error.getCodes()           the full message-code hierarchy, most specific first
        // error.getRejectedValue()   the raw value the user typed
        // error.isBindingFailure()   true for conversion errors, false for constraints
    }
    // ...
}

// Useful BindingResult methods
//   hasErrors(), hasFieldErrors(), hasFieldErrors("name"), hasGlobalErrors()
//   getFieldError("name")      first error for a field
//   getFieldErrors("name")     all errors for a field
//   getGlobalErrors()          errors not tied to a field
//   getErrorCount()

@PostMapping
public String submit(@ModelAttribute("form") @Valid RegisterForm form,
                     BindingResult result) {

    // 1. Stop if the basic constraints already failed.
    if (result.hasErrors()) {
        return "register";
    }

    // 2. Business rule that needs data from elsewhere.
    if (userService.usernameExists(form.getUsername())) {
        result.rejectValue("username", "username.taken",
                           "That username is already taken");
        return "register";
    }

    // 3. The database unique index is the real guarantee; two simultaneous
    //    requests can both pass step 2.
    try {
        userService.register(form);
    } catch (DataIntegrityViolationException ex) {
        result.rejectValue("email", "email.taken",
                           "That email address is already registered");
        return "register";
    }

    return "redirect:/login?registered";
}

// An error about the whole form, not one field:
result.reject("registration.blocked", "Registration is not available right now");

// Schema-level backstop (Flyway / Liquibase / DDL):
//   ALTER TABLE users ADD CONSTRAINT uk_users_email UNIQUE (email);

// 1. The annotation
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = UniqueEmailValidator.class)
@Documented
public @interface UniqueEmail {
    String message() default "This email address is already registered";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// 2. The validator. No @Component needed: Spring autowires constraint validators.
public class UniqueEmailValidator implements ConstraintValidator<UniqueEmail, String> {

    private final UserRepository userRepository;

    public UniqueEmailValidator(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    public boolean isValid(String email, ConstraintValidatorContext context) {
        if (email == null || email.isBlank()) {
            return true;   // let @NotBlank report missing values
        }
        return !userRepository.existsByEmailIgnoreCase(email.trim());
    }
}

// 3. Use it
public class RegisterForm {
    @NotBlank
    @Email
    @UniqueEmail
    private String email;
}

// Constraints with parameters:
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = AllowedDomainValidator.class)
public @interface AllowedDomain {
    String message() default "Email domain is not allowed";
    String[] value();                         // @AllowedDomain({"example.com", "acme.io"})
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// Option 1: @AssertTrue method. Simple, but the error is not on a field.
public class PasswordForm {

    @NotBlank @Size(min = 8) private String password;
    @NotBlank private String confirmPassword;

    @AssertTrue(message = "Passwords do not match")
    public boolean isPasswordMatching() {
        return password == null || password.equals(confirmPassword);
    }
}

// Option 2: class-level constraint that reports on a specific field.
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PasswordsMatchValidator.class)
public @interface PasswordsMatch {
    String message() default "Passwords do not match";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class PasswordsMatchValidator
        implements ConstraintValidator<PasswordsMatch, PasswordForm> {

    @Override
    public boolean isValid(PasswordForm form, ConstraintValidatorContext ctx) {
        if (form.getPassword() == null || form.getConfirmPassword() == null) {
            return true;   // the field-level constraints report missing values
        }
        if (form.getPassword().equals(form.getConfirmPassword())) {
            return true;
        }
        ctx.disableDefaultConstraintViolation();
        ctx.buildConstraintViolationWithTemplate(ctx.getDefaultConstraintMessageTemplate())
           .addPropertyNode("confirmPassword")     // error shows on this input
           .addConstraintViolation();
        return false;
    }
}

@PasswordsMatch
public class PasswordForm {
    @NotBlank @Size(min = 8) private String password;
    @NotBlank private String confirmPassword;
}

// Nested objects: @Valid cascades into them.
public class OrderForm {

    @NotBlank private String customerName;

    @Valid                          // without this, Address constraints are skipped
    @NotNull
    private AddressForm address;

    @Valid                          // validates each element
    @NotEmpty(message = "Add at least one item")
    private List<@Valid ItemForm> items = new ArrayList<>();
}

public class AddressForm {
    @NotBlank private String street;
    @Pattern(regexp = "\\d{5}") private String postalCode;   // error path: address.postalCode
}

// Groups: marker interfaces
public interface OnCreate { }
public interface OnUpdate { }

public class UserForm {
    @Null(groups = OnCreate.class)
    @NotNull(groups = OnUpdate.class)
    private Long id;

    @NotBlank(groups = {OnCreate.class, OnUpdate.class})
    private String name;

    @NotBlank(groups = OnCreate.class)   // password only required when creating
    private String password;
}

// @Validated selects the groups. @Valid cannot.
@PostMapping("/users")
public String create(@ModelAttribute("form") @Validated(OnCreate.class) UserForm form,
                     BindingResult result) { ... }

@PostMapping("/users/{id}")
public String update(@ModelAttribute("form") @Validated(OnUpdate.class) UserForm form,
                     BindingResult result) { ... }

// Ordered checks: report "required" first, then the format rules.
public interface Required { }
public interface Format { }

@GroupSequence({Required.class, Format.class})
public interface Ordered { }

public class LoginForm {
    @NotBlank(groups = Required.class)
    @Size(min = 3, groups = Format.class)
    private String username;
}
// controller: @Validated(Ordered.class)

# src/main/resources/messages.properties

# Most specific: constraint + form name + field
NotBlank.form.username=Choose a username
Size.form.password=Password must be between {2} and {1} characters

# Per field name (any form)
Email.email=Enter a valid email address, for example name@example.com

# Per field type
Min=Must be at least {1}

# Per constraint (general fallback)
NotBlank=This field is required
Size=Must be between {2} and {1} characters
Pattern=Invalid format

# Binding failures: the friendly replacement for "Failed to convert property value..."
typeMismatch=Invalid value
typeMismatch.int=Enter a whole number
typeMismatch.java.lang.Integer=Enter a whole number
typeMismatch.java.time.LocalDate=Enter a date as yyyy-mm-dd

# Programmatic error codes (rejectValue / reject)
username.taken=That username is already taken
email.taken=That email address is already registered
registration.blocked=Registration is not available right now

# Custom constraints (code = annotation name)
UniqueEmail=This email address is already registered
PasswordsMatch=Passwords do not match

# Placeholders in these lookups are POSITIONAL:
#   {0} = field name,  then attributes alphabetically:
#   @Size  -> {1}=max, {2}=min
#   @Min   -> {1}=value
#   @Max   -> {1}=value
# Named {min}/{max} placeholders belong in the annotation message or in
# ValidationMessages.properties, which uses Hibernate's own interpolation.

# application.yml
spring:
  messages:
    basename: messages,validation      # messages.properties, validation.properties
    encoding: UTF-8
    fallback-to-system-locale: false   # unknown locale -> messages.properties
    use-code-as-default-message: false # missing code -> error, not the raw code

// Let users switch language with ?lang=fr
@Configuration
public class LocaleConfig implements WebMvcConfigurer {

    @Bean
    public LocaleResolver localeResolver() {
        CookieLocaleResolver resolver = new CookieLocaleResolver("lang");
        resolver.setDefaultLocale(Locale.ENGLISH);
        return resolver;
    }

    @Bean
    public LocaleChangeInterceptor localeChangeInterceptor() {
        LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
        interceptor.setParamName("lang");
        return interceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localeChangeInterceptor());
    }
}

// Files:
//   messages.properties        default (English)
//   messages_fr.properties     French
//   messages_de.properties     German

// Global: every controller trims strings and turns "" into null
@ControllerAdvice
public class GlobalBindingConfig {

    @InitBinder
    public void initBinder(WebDataBinder binder) {
        binder.registerCustomEditor(String.class, new StringTrimmerEditor(true));
    }
}

// Per controller, excluding password fields from trimming
@InitBinder("form")
public void initBinder(WebDataBinder binder) {
    StringTrimmerEditor trimmer = new StringTrimmerEditor(true);
    binder.registerCustomEditor(String.class, "username", trimmer);
    binder.registerCustomEditor(String.class, "email", trimmer);
    // password / confirmPassword intentionally left untouched
}

// Also useful in the same method:
//   binder.setDisallowedFields("id", "role");   // never bind these from the request
//   binder.setAllowedFields("username", "email");  // or whitelist instead
// Binding to an entity directly? Disallowing fields prevents mass-assignment attacks.
// Better still, bind to a dedicated form class that has no such fields.

<form th:action="@{/register}" th:object="${form}" method="post" novalidate>

    <!-- Summary of every error -->
    <div th:if="${#fields.hasAnyErrors()}" class="alert alert-danger" role="alert">
        <p>Please fix the following:</p>
        <ul>
            <li th:each="err : ${#fields.allErrors()}" th:text="${err}"></li>
        </ul>
    </div>

    <!-- Errors not tied to a field (from bindingResult.reject) -->
    <div th:if="${#fields.hasGlobalErrors()}" class="alert alert-warning">
        <p th:each="err : ${#fields.globalErrors()}" th:text="${err}"></p>
    </div>

    <div class="mb-3">
        <label for="username" class="form-label">Username</label>
        <input type="text" id="username" th:field="*{username}"
               th:errorclass="is-invalid" class="form-control" />
        <div class="invalid-feedback" th:if="${#fields.hasErrors('username')}"
             th:errors="*{username}"></div>
    </div>

    <div class="mb-3">
        <label for="email" class="form-label">Email</label>
        <input type="email" id="email" th:field="*{email}"
               th:errorclass="is-invalid" class="form-control" />
        <div class="invalid-feedback" th:if="${#fields.hasErrors('email')}"
             th:errors="*{email}"></div>
    </div>

    <div class="mb-3">
        <label for="age" class="form-label">Age</label>
        <input type="number" id="age" th:field="*{age}"
               th:errorclass="is-invalid" class="form-control" />
        <div class="invalid-feedback" th:if="${#fields.hasErrors('age')}"
             th:errors="*{age}"></div>
    </div>

    <div class="form-check mb-3">
        <input type="checkbox" id="terms" th:field="*{acceptedTerms}"
               th:errorclass="is-invalid" class="form-check-input" />
        <label for="terms" class="form-check-label">I accept the terms</label>
        <div class="invalid-feedback" th:if="${#fields.hasErrors('acceptedTerms')}"
             th:errors="*{acceptedTerms}"></div>
    </div>

    <button type="submit" class="btn btn-primary">Register</button>
</form>

<!-- Notes
     - novalidate turns off the browser's own popups so users see your messages.
       Keep client-side checks as a convenience only; the server is the authority.
     - Errors rendered with th:errors are HTML-escaped by default. Keep it that way.
     - Password inputs do not echo their value back, which is the desired behaviour. -->

// 1. Validator injected directly
@Service
public class ImportService {

    private final Validator validator;

    public ImportService(Validator validator) {
        this.validator = validator;
    }

    public List<String> check(RegisterForm form) {
        Set<ConstraintViolation<RegisterForm>> violations = validator.validate(form);
        return violations.stream()
            .map(v -> v.getPropertyPath() + ": " + v.getMessage())
            .sorted()
            .toList();
    }
}

// 2. Method validation: Spring checks arguments before the method runs.
@Service
@Validated
public class AccountService {

    public void changeEmail(@NotNull Long userId, @Email @NotBlank String newEmail) { ... }

    public void import(@Valid List<@Valid RegisterForm> forms) { ... }
}
// Failure -> jakarta.validation.ConstraintViolationException
// Only works through the Spring proxy: this.changeEmail(...) from inside the class is NOT checked.

// 3. Validating into a Spring Errors object
@Autowired private SmartValidator smartValidator;

public BindingResult validate(RegisterForm form) {
    BindingResult result = new BeanPropertyBindingResult(form, "form");
    smartValidator.validate(form, result);
    return result;
}

@WebMvcTest(RegistrationController.class)
class RegistrationControllerTest {

    @Autowired private MockMvc mockMvc;
    @MockitoBean private UserService userService;   // @MockBean on Spring Boot < 3.4

    @Test
    void invalidForm_redisplaysFormWithFieldErrors() throws Exception {
        mockMvc.perform(post("/register")
                .with(csrf())
                .param("username", "ab")                 // too short
                .param("email", "not-an-email")
                .param("password", "short")
                .param("age", "17"))
            .andExpect(status().isOk())
            .andExpect(view().name("register"))
            .andExpect(model().attributeHasFieldErrors(
                "form", "username", "email", "password", "age"));

        verifyNoInteractions(userService);
    }

    @Test
    void nonNumericAge_isABindingError() throws Exception {
        mockMvc.perform(post("/register")
                .with(csrf())
                .param("username", "alice")
                .param("email", "alice@example.com")
                .param("password", "Passw0rd!x")
                .param("age", "abc"))
            .andExpect(model().attributeHasFieldErrorCode("form", "age", "typeMismatch"));
    }

    @Test
    void validForm_redirectsToLogin() throws Exception {
        mockMvc.perform(post("/register")
                .with(csrf())
                .param("username", "alice")
                .param("email", "alice@example.com")
                .param("password", "Passw0rd!x")
                .param("confirmPassword", "Passw0rd!x")
                .param("age", "30")
                .param("acceptedTerms", "true"))
            .andExpect(status().is3xxRedirection())
            .andExpect(redirectedUrl("/login"));

        verify(userService).register(any(RegisterForm.class));
    }
}

// A custom validator is a plain class; test it without Spring.
class PasswordsMatchValidatorTest {
    private final PasswordsMatchValidator validator = new PasswordsMatchValidator();

    @Test
    void matchingPasswords_arePassing() {
        PasswordForm form = new PasswordForm();
        form.setPassword("secret123");
        form.setConfirmPassword("secret123");
        assertThat(validator.isValid(form, null)).isTrue();
    }
}

# Symptom -> likely cause -> fix

# Constraints are ignored entirely
#   spring-boot-starter-validation missing, or @Valid missing on the parameter.
#   -> add the starter; annotate the @ModelAttribute parameter with @Valid.

# Page returns 400 instead of re-rendering the form
#   No BindingResult, or another parameter sits between the form and its BindingResult.
#   -> put BindingResult immediately after the @Valid parameter.

# Nested object / list element constraints never fire
#   Cascading is opt-in.
#   -> add @Valid on the nested field and on collection type arguments.

# Annotation message ignored, a different text appears
#   A matching code in messages.properties takes precedence.
#   -> check NotBlank.form.username, NotBlank.username, NotBlank.java.lang.String, NotBlank.

# {min} / {max} appear literally, or messages.properties throws on them
#   Named placeholders are not used in code lookups.
#   -> use {1}, {2} in messages.properties, or put {min} in ValidationMessages.properties.

# Message reads "Failed to convert property value of type String to required type..."
#   A typeMismatch binding error.
#   -> define typeMismatch.* messages; use Integer instead of int for optional numbers.

# Two messages for one empty field (e.g. "required" and "too short")
#   @NotBlank and @Size both fail on "".
#   -> @GroupSequence, or accept both, or let @Size skip empties with a custom constraint.

# Checkbox always fails or always passes
#   -> use primitive boolean + @AssertTrue; th:field adds the hidden _field marker.

# th:field fails on a record
#   th:field reads through getters; records expose name(), not getName().
#   -> use a regular class for forms that back Thymeleaf templates.

# Duplicate records despite a @UniqueEmail constraint
#   Check-then-insert races.
#   -> add the database unique index and handle DataIntegrityViolationException.

# Mass assignment
#   Binding request data to an entity lets users set fields you did not render.
#   -> bind to a form class, or use setAllowedFields / setDisallowedFields.