3.16 Bean Validation

Since Micronaut 1.2, Micronaut has built-in support for validating beans annotated with javax.validation annotations. At a minimum include the micronaut-validation module as a compile dependency:

implementation("io.micronaut:micronaut-validation")

<dependency>
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-validation</artifactId>
</dependency>

Note that Micronaut’s implementation is not currently fully compliant with the Bean Validator specification as the specification heavily relies on reflection-based APIs.

The following features are unsupported at this time:

• Annotations on generic argument types, since only the Java language supports this feature.

• Any interaction with the constraint metadata API, since Micronaut uses compile-time generated metadata.

• XML-based configuration

• Instead of using javax.validation.ConstraintValidator, use ConstraintValidator (io.micronaut.validation.validator.constraints.ConstraintValidator) to define custom constraints, which supports validating annotations at compile time.

Micronaut’s implementation includes the following benefits:

• Reflection and Runtime Proxy free validation, resulting in reduced memory consumption

• Smaller JAR size since Hibernate Validator adds another 1.4MB

• Faster startup since Hibernate Validator adds 200ms+ startup overhead

• Configurability via Annotation Metadata

• Support for Reactive Bean Validation

• Support for validating the source AST at compile time

• Automatic compatibility with GraalVM native without additional configuration

If you require full Bean Validator 2.0 compliance, add the micronaut-hibernate-validator module to your build, which replaces Micronaut’s implementation.

implementation("io.micronaut.beanvalidation:micronaut-hibernate-validator")

<dependency>
    <groupId>io.micronaut.beanvalidation</groupId>
    <artifactId>micronaut-hibernate-validator</artifactId>
</dependency>

Validating Bean Methods

You can validate methods of any class declared as a Micronaut bean by applying javax.validation annotations to arguments:

import jakarta.inject.Singleton;
import javax.validation.constraints.NotBlank;
@Singleton
public class PersonService {
    public void sayHello(@NotBlank String name) {
        System.out.println("Hello " + name);
    }
}

import jakarta.inject.Singleton
import javax.validation.constraints.NotBlank
@Singleton
class PersonService {
    void sayHello(@NotBlank String name) {
        println "Hello $name"
    }
}

import jakarta.inject.Singleton
import javax.validation.constraints.NotBlank
@Singleton
open class PersonService {
    open fun sayHello(@NotBlank name: String) {
        println("Hello $name")
    }
}

The above example declares that the @NotBlank annotation will be validated when invoking the sayHello method.

A javax.validation.ConstraintViolationException is thrown if a validation error occurs. For example:

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;
import jakarta.inject.Inject;
import javax.validation.ConstraintViolationException;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
@MicronautTest
class PersonServiceSpec {
    @Inject PersonService personService;
    @Test
    void testThatNameIsValidated() {
        final ConstraintViolationException exception =
                assertThrows(ConstraintViolationException.class, () ->
                personService.sayHello("") (1)
        );
        assertEquals("sayHello.name: must not be blank", exception.getMessage()); (2)
    }
}

import io.micronaut.test.extensions.spock.annotation.MicronautTest
import spock.lang.Specification
import jakarta.inject.Inject
import javax.validation.ConstraintViolationException
@MicronautTest
class PersonServiceSpec extends Specification {
    @Inject PersonService personService
    void "test person name is validated"() {
        when:"The sayHello method is called with a blank string"
        personService.sayHello("") (1)
        then:"A validation error occurs"
        def e = thrown(ConstraintViolationException)
        e.message == "sayHello.name: must not be blank" //  (2)
    }
}

import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertThrows
import org.junit.jupiter.api.Test
import jakarta.inject.Inject
import javax.validation.ConstraintViolationException
@MicronautTest
class PersonServiceSpec {
    @Inject
    lateinit var personService: PersonService
    @Test
    fun testThatNameIsValidated() {
        val exception = assertThrows(ConstraintViolationException::class.java) {
            personService.sayHello("") (1)
        }
        assertEquals("sayHello.name: must not be blank", exception.message) (2)
    }
}

Validating Data Classes

To validate data classes, e.g. POJOs (typically used in JSON interchange), the class must be annotated with @Introspected (see the previous section on Bean Introspection) or, if the class is external, be imported by the @Introspected annotation.

import io.micronaut.core.annotation.Introspected;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
@Introspected
public class Person {
    private String name;
    @Min(18)
    private int age;
    @NotBlank
    public String getName() {
        return name;
    }
    public int getAge() {
        return age;
    }
    public void setName(String name) {
        this.name = name;
    }
    public void setAge(int age) {
        this.age = age;
    }
}

import io.micronaut.core.annotation.Introspected
import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank
@Introspected
class Person {
    @NotBlank
    String name
    @Min(18L)
    int age
}

import io.micronaut.core.annotation.Introspected
import javax.validation.constraints.Min
import javax.validation.constraints.NotBlank
@Introspected
data class Person(
    @field:NotBlank var name: String,
    @field:Min(18) var age: Int
)

The above example defines a Person class that has two properties (name and age) that have constraints applied. Note that in Java the annotations can be on the field or the getter, and with Kotlin data classes, the annotation should target the field.

To validate the class manually, inject an instance of Validator:

@Inject
Validator validator;
@Test
void testThatPersonIsValidWithValidator() {
    Person person = new Person();
    person.setName("");
    person.setAge(10);
    final Set<ConstraintViolation<Person>> constraintViolations = validator.validate(person);  (1)
    assertEquals(2, constraintViolations.size()); (2)
}

@Inject Validator validator
void "test person is validated with validator"() {
    when:"The person is validated"
    def constraintViolations = validator.validate(new Person(name: "", age: 10)) (1)
    then:"A validation error occurs"
    constraintViolations.size() == 2 //  (2)
}

@Inject
lateinit var validator: Validator
@Test
fun testThatPersonIsValidWithValidator() {
    val person = Person("", 10)
    val constraintViolations = validator.validate(person) (1)
    assertEquals(2, constraintViolations.size) (2)
}

Alternatively on Bean methods you can use javax.validation.Valid to trigger cascading validation:

@Singleton
public class PersonService {
    public void sayHello(@Valid Person person) {
        System.out.println("Hello " + person.getName());
    }
}

@Singleton
class PersonService {
    void sayHello(@Valid Person person) {
        println "Hello $person.name"
    }
}

@Singleton
open class PersonService {
    open fun sayHello(@Valid person: Person) {
        println("Hello ${person.name}")
    }
}

The PersonService now validates the Person class when invoked:

@Inject
PersonService personService;
@Test
void testThatPersonIsValid() {
    Person person = new Person();
    person.setName("");
    person.setAge(10);
    final ConstraintViolationException exception =
        assertThrows(ConstraintViolationException.class, () ->
            personService.sayHello(person) (1)
        );
    assertEquals(2, exception.getConstraintViolations().size()); (2)
}

@Inject PersonService personService
void "test person name is validated"() {
    when:"The sayHello method is called with an invalid person"
    personService.sayHello(new Person(name: "", age: 10)) (1)
    then:"A validation error occurs"
    def e = thrown(ConstraintViolationException)
    e.constraintViolations.size() == 2 //  (2)
}

@Inject
lateinit var personService: PersonService
@Test
fun testThatPersonIsValid() {
    val person = Person("", 10)
    val exception = assertThrows(ConstraintViolationException::class.java) {
        personService.sayHello(person) (1)
    }
    assertEquals(2, exception.constraintViolations.size) (2)
}

Validating Configuration Properties

You can also validate the properties of classes that are annotated with @ConfigurationProperties to ensure configuration is correct.

Defining Additional Constraints

To define additional constraints, create a new annotation, for example:

import javax.validation.Constraint;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.ElementType.TYPE_USE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Retention(RUNTIME)
@Constraint(validatedBy = { }) (1)
public @interface DurationPattern {
    String message() default "invalid duration ({validatedValue})"; (2)
    /**
     * Defines several constraints on the same element.
     */
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Documented
    @interface List {
        DurationPattern[] value(); (3)
    }
}

import javax.validation.Constraint
import java.lang.annotation.Retention
import static java.lang.annotation.RetentionPolicy.RUNTIME
@Retention(RUNTIME)
@Constraint(validatedBy = []) (1)
@interface DurationPattern {
    String message() default "invalid duration ({validatedValue})" (2)
}

import javax.validation.Constraint
import kotlin.annotation.AnnotationRetention.RUNTIME
@Retention(RUNTIME)
@Constraint(validatedBy = []) (1)
annotation class DurationPattern(
    val message: String = "invalid duration ({validatedValue})" (2)
)

Once you have defined the annotation, implement a ConstraintValidator that validates the annotation. You can either create a bean class that implements the interface directly or define a factory that returns one or more validators.

The latter approach is recommended if you plan to define multiple validators:

import io.micronaut.context.annotation.Factory;
import io.micronaut.validation.validator.constraints.ConstraintValidator;
import jakarta.inject.Singleton;
@Factory
public class MyValidatorFactory {
    @Singleton
    ConstraintValidator<DurationPattern, CharSequence> durationPatternValidator() {
        return (value, annotationMetadata, context) -> {
            context.messageTemplate("invalid duration ({validatedValue}), additional custom message"); (1)
            return value == null || value.toString().matches("^PT?[\\d]+[SMHD]{1}$");
        };
    }
}

import io.micronaut.context.annotation.Factory
import io.micronaut.core.annotation.AnnotationValue
import io.micronaut.validation.validator.constraints.ConstraintValidator
import io.micronaut.validation.validator.constraints.ConstraintValidatorContext
import jakarta.inject.Singleton
@Factory
class MyValidatorFactory {
    @Singleton
    ConstraintValidator<DurationPattern, CharSequence> durationPatternValidator() {
        return { CharSequence value,
                 AnnotationValue<DurationPattern> annotation,
                 ConstraintValidatorContext context ->
            context.messageTemplate("invalid duration ({validatedValue}), additional custom message") (1)
            return value == null || value.toString() ==~ /^PT?[\d]+[SMHD]{1}$/
        } as ConstraintValidator<DurationPattern, CharSequence>
    }
}

import io.micronaut.context.annotation.Factory
import io.micronaut.validation.validator.constraints.ConstraintValidator
import jakarta.inject.Singleton
@Factory
class MyValidatorFactory {
    @Singleton
    fun durationPatternValidator() : ConstraintValidator<DurationPattern, CharSequence> {
        return ConstraintValidator { value, annotation, context ->
            context.messageTemplate("invalid duration ({validatedValue}), additional custom message") (1)
            value == null || value.toString().matches("^PT?[\\d]+[SMHD]{1}$".toRegex())
        }
    }
}

The above example implements a validator that validates any field, parameter etc. that is annotated with DurationPattern, ensuring that the string can be parsed with java.time.Duration.parse.

For example:

@Singleton
public class HolidayService {
    public String startHoliday(@NotBlank String person,
                               @DurationPattern String duration) {
        final Duration d = Duration.parse(duration);
        return "Person " + person + " is off on holiday for " + d.toMinutes() + " minutes";
    }
}

@Singleton
class HolidayService {
    String startHoliday(@NotBlank String person,
                        @DurationPattern String duration) {
        final Duration d = Duration.parse(duration)
        return "Person $person is off on holiday for ${d.toMinutes()} minutes"
    }
}

@Singleton
open class HolidayService {
    open fun startHoliday(@NotBlank person: String,
                          @DurationPattern duration: String): String {
        val d = Duration.parse(duration)
        return "Person $person is off on holiday for ${d.toMinutes()} minutes"
    }
}

To verify the above examples validates the duration parameter, define a test:

@Inject HolidayService holidayService;
@Test
void testCustomValidator() {
    final ConstraintViolationException exception =
        assertThrows(ConstraintViolationException.class, () ->
            holidayService.startHoliday("Fred", "junk") (1)
        );
    assertEquals("startHoliday.duration: invalid duration (junk), additional custom message", exception.getMessage()); (2)
}

void "test test custom validator"() {
    when:"A custom validator is used"
    holidayService.startHoliday("Fred", "junk") (1)
    then:"A validation error occurs"
    def e = thrown(ConstraintViolationException)
    e.message == "startHoliday.duration: invalid duration (junk), additional custom message" //  (2)
}

@Inject
lateinit var holidayService: HolidayService
@Test
fun testCustomValidator() {
    val exception = assertThrows(ConstraintViolationException::class.java) {
        holidayService.startHoliday("Fred", "junk") (1)
    }
    assertEquals("startHoliday.duration: invalid duration (junk), additional custom message", exception.message) (2)
}

Validating Annotations at Compile Time

You can use Micronaut’s validator to validate annotation elements at compile time by including micronaut-validation in the annotation processor classpath:

annotationProcessor("io.micronaut:micronaut-validation")

<annotationProcessorPaths>
    <path>
        <groupId>io.micronaut</groupId>
        <artifactId>micronaut-validation</artifactId>
    </path>
</annotationProcessorPaths>

Then Micronaut will at compile time validate annotation values that are themselves annotated with javax.validation. For example consider the following annotation:

import java.lang.annotation.Retention;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
@Retention(RUNTIME)
public @interface TimeOff {
    @DurationPattern
    String duration();
}

import java.lang.annotation.Retention
import static java.lang.annotation.RetentionPolicy.RUNTIME
@Retention(RUNTIME)
@interface TimeOff {
    @DurationPattern
    String duration()
}

import kotlin.annotation.AnnotationRetention.RUNTIME
@Retention(RUNTIME)
annotation class TimeOff(
    @DurationPattern val duration: String
)

If you attempt to use @TimeOff(duration="junk") in your source, Micronaut will fail compilation due to the duration value violating the DurationPattern constraint.

Note that to use a custom ConstraintValidator at compile time you must instead define the validator as a class:

import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.annotation.Nullable;
import io.micronaut.core.annotation.AnnotationValue;
import io.micronaut.validation.validator.constraints.ConstraintValidator;
import io.micronaut.validation.validator.constraints.ConstraintValidatorContext;
public class DurationPatternValidator implements ConstraintValidator<DurationPattern, CharSequence> {
    @Override
    public boolean isValid(
            @Nullable CharSequence value,
            @NonNull AnnotationValue<DurationPattern> annotationMetadata,
            @NonNull ConstraintValidatorContext context) {
        return value == null || value.toString().matches("^PT?[\\d]+[SMHD]{1}$");
    }
}

import io.micronaut.core.annotation.NonNull
import io.micronaut.core.annotation.Nullable
import io.micronaut.core.annotation.AnnotationValue
import io.micronaut.validation.validator.constraints.ConstraintValidator
import io.micronaut.validation.validator.constraints.ConstraintValidatorContext
class DurationPatternValidator implements ConstraintValidator<DurationPattern, CharSequence> {
    @Override
    boolean isValid(
            @Nullable CharSequence value,
            @NonNull AnnotationValue<DurationPattern> annotationMetadata,
            @NonNull ConstraintValidatorContext context) {
        return value == null || value.toString() ==~ /^PT?[\d]+[SMHD]{1}$/
    }
}

import io.micronaut.core.annotation.AnnotationValue
import io.micronaut.validation.validator.constraints.ConstraintValidator
import io.micronaut.validation.validator.constraints.ConstraintValidatorContext
class DurationPatternValidator : ConstraintValidator<DurationPattern, CharSequence> {
    override fun isValid(
            value: CharSequence?,
            annotationMetadata: AnnotationValue<DurationPattern>,
            context: ConstraintValidatorContext): Boolean {
        return value == null || value.toString().matches("^PT?[\\d]+[SMHD]{1}$".toRegex())
    }
}

Additionally:

• Define a META-INF/services/io.micronaut.validation.validator.constraints.ConstraintValidator file that references the class.

• The class must be public and have a public no-argument constructor

• The class must be on the annotation processor classpath of the project to be validated.