This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Framework 6.0.26! |
Java Bean Validation
The Spring Framework provides support for the Java Bean Validation API.
Overview of Bean Validation
Bean Validation provides a common way of validation through constraint declaration and metadata for Java applications. To use it, you annotate domain model properties with declarative validation constraints which are then enforced by the runtime. There are built-in constraints, and you can also define your own custom constraints.
Consider the following example, which shows a simple PersonForm
model with two properties:
-
Java
-
Kotlin
public class PersonForm {
private String name;
private int age;
}
class PersonForm(
private val name: String,
private val age: Int
)
Bean Validation lets you declare constraints as the following example shows:
-
Java
-
Kotlin
public class PersonForm {
@NotNull
@Size(max=64)
private String name;
@Min(0)
private int age;
}
class PersonForm(
@get:NotNull @get:Size(max=64)
private val name: String,
@get:Min(0)
private val age: Int
)
A Bean Validation validator then validates instances of this class based on the declared constraints. See Bean Validation for general information about the API. See the Hibernate Validator documentation for specific constraints. To learn how to set up a bean validation provider as a Spring bean, keep reading.
Configuring a Bean Validation Provider
Spring provides full support for the Bean Validation API including the bootstrapping of a
Bean Validation provider as a Spring bean. This lets you inject a
jakarta.validation.ValidatorFactory
or jakarta.validation.Validator
wherever validation
is needed in your application.
You can use the LocalValidatorFactoryBean
to configure a default Validator as a Spring
bean, as the following example shows:
-
Java
-
XML
import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean;
@Configuration
public class AppConfig {
@Bean
public LocalValidatorFactoryBean validator() {
return new LocalValidatorFactoryBean();
}
}
<bean id="validator"
class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean"/>
The basic configuration in the preceding example triggers bean validation to initialize by using its default bootstrap mechanism. A Bean Validation provider, such as the Hibernate Validator, is expected to be present in the classpath and is automatically detected.
Injecting a Validator
LocalValidatorFactoryBean
implements both jakarta.validation.ValidatorFactory
and
jakarta.validation.Validator
, as well as Spring’s org.springframework.validation.Validator
.
You can inject a reference to either of these interfaces into beans that need to invoke
validation logic.
You can inject a reference to jakarta.validation.Validator
if you prefer to work with the Bean
Validation API directly, as the following example shows:
-
Java
-
Kotlin
import jakarta.validation.Validator;
@Service
public class MyService {
@Autowired
private Validator validator;
}
import jakarta.validation.Validator;
@Service
class MyService(@Autowired private val validator: Validator)
You can inject a reference to org.springframework.validation.Validator
if your bean
requires the Spring Validation API, as the following example shows:
-
Java
-
Kotlin
import org.springframework.validation.Validator;
@Service
public class MyService {
@Autowired
private Validator validator;
}
import org.springframework.validation.Validator
@Service
class MyService(@Autowired private val validator: Validator)
Configuring Custom Constraints
Each bean validation constraint consists of two parts:
-
A
@Constraint
annotation that declares the constraint and its configurable properties. -
An implementation of the
jakarta.validation.ConstraintValidator
interface that implements the constraint’s behavior.
To associate a declaration with an implementation, each @Constraint
annotation
references a corresponding ConstraintValidator
implementation class. At runtime, a
ConstraintValidatorFactory
instantiates the referenced implementation when the
constraint annotation is encountered in your domain model.
By default, the LocalValidatorFactoryBean
configures a SpringConstraintValidatorFactory
that uses Spring to create ConstraintValidator
instances. This lets your custom
ConstraintValidators
benefit from dependency injection like any other Spring bean.
The following example shows a custom @Constraint
declaration followed by an associated
ConstraintValidator
implementation that uses Spring for dependency injection:
-
Java
-
Kotlin
@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy=MyConstraintValidator.class)
public @interface MyConstraint {
}
@Target(AnnotationTarget.FUNCTION, AnnotationTarget.FIELD)
@Retention(AnnotationRetention.RUNTIME)
@Constraint(validatedBy = MyConstraintValidator::class)
annotation class MyConstraint
-
Java
-
Kotlin
import jakarta.validation.ConstraintValidator;
public class MyConstraintValidator implements ConstraintValidator {
@Autowired;
private Foo aDependency;
// ...
}
import jakarta.validation.ConstraintValidator
class MyConstraintValidator(private val aDependency: Foo) : ConstraintValidator {
// ...
}
As the preceding example shows, a ConstraintValidator
implementation can have its dependencies
@Autowired
as any other Spring bean.
Spring-driven Method Validation
You can integrate the method validation feature supported by Bean Validation 1.1 (and, as
a custom extension, also by Hibernate Validator 4.3) into a Spring context through a
MethodValidationPostProcessor
bean definition:
-
Java
-
XML
import org.springframework.validation.beanvalidation.MethodValidationPostProcessor;
@Configuration
public class AppConfig {
@Bean
public MethodValidationPostProcessor validationPostProcessor() {
return new MethodValidationPostProcessor();
}
}
<bean class="org.springframework.validation.beanvalidation.MethodValidationPostProcessor"/>
To be eligible for Spring-driven method validation, all target classes need to be annotated
with Spring’s @Validated
annotation, which can optionally also declare the validation
groups to use. See
MethodValidationPostProcessor
for setup details with the Hibernate Validator and Bean Validation 1.1 providers.
Method validation relies on AOP Proxies around the target classes, either JDK dynamic proxies for methods on interfaces or CGLIB proxies. There are certain limitations with the use of proxies, some of which are described in Understanding AOP Proxies. In addition remember to always use methods and accessors on proxied classes; direct field access will not work. |
Additional Configuration Options
The default LocalValidatorFactoryBean
configuration suffices for most
cases. There are a number of configuration options for various Bean Validation
constructs, from message interpolation to traversal resolution. See the
LocalValidatorFactoryBean
javadoc for more information on these options.
Configuring a DataBinder
You can configure a DataBinder
instance with a Validator
. Once configured, you can
invoke the Validator
by calling binder.validate()
. Any validation Errors
are
automatically added to the binder’s BindingResult
.
The following example shows how to use a DataBinder
programmatically to invoke validation
logic after binding to a target object:
-
Java
-
Kotlin
Foo target = new Foo();
DataBinder binder = new DataBinder(target);
binder.setValidator(new FooValidator());
// bind to the target object
binder.bind(propertyValues);
// validate the target object
binder.validate();
// get BindingResult that includes any validation errors
BindingResult results = binder.getBindingResult();
val target = Foo()
val binder = DataBinder(target)
binder.validator = FooValidator()
// bind to the target object
binder.bind(propertyValues)
// validate the target object
binder.validate()
// get BindingResult that includes any validation errors
val results = binder.bindingResult
You can also configure a DataBinder
with multiple Validator
instances through
dataBinder.addValidators
and dataBinder.replaceValidators
. This is useful when
combining globally configured bean validation with a Spring Validator
configured
locally on a DataBinder instance. See
Spring MVC Validation Configuration.
Spring MVC 3 Validation
See Validation in the Spring MVC chapter.