In order to use Hibernate Validator within a Maven project, simply add the following dependency toyourpom.xml:

This transitively pulls in the dependency to the Jakarta Bean Validation API(jakarta.validation:jakarta.validation-api:2.0.2).

1.1.1. Unified EL

<dependency>    <groupId>org.glassfish</groupId>    <artifactId>jakarta.el</artifactId>    <version>3.0.3</version></dependency>

1.1.2. CDI

<dependency>    <groupId>org.hibernate.validator</groupId>    <artifactId>hibernate-validator-cdi</artifactId>    <version>6.2.5.Final</version></dependency>

1.1.3. Running with a security manager

grant codeBase "file:path/to/hibernate-validator-6.2.5.Final.jar" {    permission java.lang.reflect.ReflectPermission "suppressAccessChecks";    permission java.lang.RuntimePermission "accessDeclaredMembers";    permission java.lang.RuntimePermission "setContextClassLoader";    permission org.hibernate.validator.HibernateValidatorPermission "accessPrivateMembers";    // Only needed when working with XML descriptors (validation.xml or XML constraint mappings)    permission java.util.PropertyPermission "mapAnyUriToUri", "read";};grant codeBase "file:path/to/jakarta.validation-api-2.0.2.jar" {    permission java.io.FilePermission "path/to/hibernate-validator-6.2.5.Final.jar", "read";};grant codeBase "file:path/to/jboss-logging-3.4.1.Final.jar" {    permission java.util.PropertyPermission "org.jboss.logging.provider", "read";    permission java.util.PropertyPermission "org.jboss.logging.locale", "read";};grant codeBase "file:path/to/classmate-1.5.1.jar" {    permission java.lang.RuntimePermission "accessDeclaredMembers";};grant codeBase "file:path/to/validation-caller-x.y.z.jar" {    permission org.hibernate.validator.HibernateValidatorPermission "accessPrivateMembers";};

1.1.4. Updating Hibernate Validator in WildFly

<dependency>    <groupId>org.hibernate.validator</groupId>    <artifactId>hibernate-validator-modules</artifactId>    <version>6.2.5.Final</version>    <classifier>wildfly-22.0.0.Final-patch</classifier>    <type>zip</type></dependency>

<dependency>    <groupId>org.hibernate.validator</groupId>    <artifactId>hibernate-validator-modules</artifactId>    <version>6.2.5.Final</version>    <classifier>wildfly--patch</classifier>    <type>zip</type></dependency>

$JBOSS_HOME/bin/jboss-cli.sh patch apply hibernate-validator-modules-6.2.5.Final-wildfly-22.0.0.Final-patch.zip

$JBOSS_HOME/bin/jboss-cli.sh patch rollback --reset-configuration=true

1.1.5. Running on Java 9

Let’s dive directly into an example to see how to apply constraints.

The@NotNull,@Size and@Min annotations are used to declare the constraints which should be appliedto the fields of a Car instance:

• manufacturer must never benull

• licensePlate must never benull and must be between 2 and 14 characters long

• seatCount must be at least 2

To perform a validation of these constraints, you use aValidator instance. Let’s have a look at aunit test forCar:

In thesetUp() method aValidator object is retrieved from theValidatorFactory. AValidatorinstance is thread-safe and may be reused multiple times. It thus can safely be stored in a staticfield and be used in the test methods to validate the differentCar instances.

Thevalidate() method returns a set ofConstraintViolation instances, which you can iterate over inorder to see which validation errors occurred. The first three test methods show some expectedconstraint violations:

• The@NotNull constraint onmanufacturer is violated inmanufacturerIsNull()

• The@Size constraint onlicensePlate is violated inlicensePlateTooShort()

• The@Min constraint onseatCount is violated inseatCountTooLow()

If the object validates successfully,validate() returns an empty set as you can see incarIsValid().

Note that only classes from the packagejavax.validation are used. These are provided from the BeanValidation API. No classes from Hibernate Validator are directly referenced, resulting in portablecode.

That concludes the 5 minutes tour through the world of Hibernate Validator and Jakarta Bean Validation.Continue exploring the code examples or look at further examples referenced inChapter 14,Further reading.

To learn more about the validation of beans and properties, just continue readingChapter 2,Declaring and validating bean constraints. If you are interested in using Jakarta Bean Validation for the validation ofmethod pre- and postcondition refer toChapter 3,Declaring and validating method constraints. In case your application hasspecific validation requirements have a look atChapter 6,Creating custom constraints.

Constraints in Jakarta Bean Validation are expressed via Java annotations. In this section you will learnhow to enhance an object model with these annotations. There are four types of bean constraints:

• field constraints

• property constraints

• container element constraints

• class constraints

2.1.1. Field-level constraints

package org.hibernate.validator.referenceguide.chapter02.fieldlevel;public class Car {    @NotNull    private String manufacturer;    @AssertTrue    private boolean isRegistered;    public Car(String manufacturer, boolean isRegistered) {        this.manufacturer = manufacturer;        this.isRegistered = isRegistered;    }    //getters and setters...}

2.1.2. Property-level constraints

package org.hibernate.validator.referenceguide.chapter02.propertylevel;public class Car {    private String manufacturer;    private boolean isRegistered;    public Car(String manufacturer, boolean isRegistered) {        this.manufacturer = manufacturer;        this.isRegistered = isRegistered;    }    @NotNull    public String getManufacturer() {        return manufacturer;    }    public void setManufacturer(String manufacturer) {        this.manufacturer = manufacturer;    }    @AssertTrue    public boolean isRegistered() {        return isRegistered;    }    public void setRegistered(boolean isRegistered) {        this.isRegistered = isRegistered;    }}

2.1.3. Container element constraints

package org.hibernate.validator.referenceguide.chapter02.containerelement.set;public class Car {    private Set<@ValidPart String> parts = new HashSet<>();    public void addPart(String part) {        parts.add( part );    }    //...}

Car car = new Car();car.addPart( "Wheel" );car.addPart( null );Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );assertEquals( 1, constraintViolations.size() );ConstraintViolation<Car> constraintViolation =        constraintViolations.iterator().next();assertEquals(        "'null' is not a valid car part.",        constraintViolation.getMessage());assertEquals( "parts[].<iterable element>",        constraintViolation.getPropertyPath().toString() );

package org.hibernate.validator.referenceguide.chapter02.containerelement.list;public class Car {    private List<@ValidPart String> parts = new ArrayList<>();    public void addPart(String part) {        parts.add( part );    }    //...}

Car car = new Car();car.addPart( "Wheel" );car.addPart( null );Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );assertEquals( 1, constraintViolations.size() );ConstraintViolation<Car> constraintViolation =        constraintViolations.iterator().next();assertEquals(        "'null' is not a valid car part.",        constraintViolation.getMessage());assertEquals( "parts[1].<list element>",        constraintViolation.getPropertyPath().toString() );

package org.hibernate.validator.referenceguide.chapter02.containerelement.map;public class Car {    public enum FuelConsumption {        CITY,        HIGHWAY    }    private Map<@NotNull FuelConsumption, @MaxAllowedFuelConsumption Integer> fuelConsumption = new HashMap<>();    public void setFuelConsumption(FuelConsumption consumption, int value) {        fuelConsumption.put( consumption, value );    }    //...}

Car car = new Car();car.setFuelConsumption( Car.FuelConsumption.HIGHWAY, 20 );Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );assertEquals( 1, constraintViolations.size() );ConstraintViolation<Car> constraintViolation =        constraintViolations.iterator().next();assertEquals(        "20 is outside the max fuel consumption.",        constraintViolation.getMessage());assertEquals(        "fuelConsumption[HIGHWAY].<map value>",        constraintViolation.getPropertyPath().toString());

Car car = new Car();car.setFuelConsumption( null, 5 );Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );assertEquals( 1, constraintViolations.size() );ConstraintViolation<Car> constraintViolation =        constraintViolations.iterator().next();assertEquals(        "must not be null",        constraintViolation.getMessage());assertEquals(        "fuelConsumption<K>[].<map key>",        constraintViolation.getPropertyPath().toString());

package org.hibernate.validator.referenceguide.chapter02.containerelement.optional;public class Car {    private Optional<@MinTowingCapacity(1000) Integer> towingCapacity = Optional.empty();    public void setTowingCapacity(Integer alias) {        towingCapacity = Optional.of( alias );    }    //...}

Car car = new Car();car.setTowingCapacity( 100 );Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );assertEquals( 1, constraintViolations.size() );ConstraintViolation<Car> constraintViolation = constraintViolations.iterator().next();assertEquals(        "Not enough towing capacity.",        constraintViolation.getMessage());assertEquals(        "towingCapacity",        constraintViolation.getPropertyPath().toString());

package org.hibernate.validator.referenceguide.chapter02.containerelement.custom;public class Car {    private GearBox<@MinTorque(100) Gear> gearBox;    public void setGearBox(GearBox<Gear> gearBox) {        this.gearBox = gearBox;    }    //...}

package org.hibernate.validator.referenceguide.chapter02.containerelement.custom;public class GearBox<T extends Gear> {    private final T gear;    public GearBox(T gear) {        this.gear = gear;    }    public Gear getGear() {        return this.gear;    }}

package org.hibernate.validator.referenceguide.chapter02.containerelement.custom;public class Gear {    private final Integer torque;    public Gear(Integer torque) {        this.torque = torque;    }    public Integer getTorque() {        return torque;    }    public static class AcmeGear extends Gear {        public AcmeGear() {            super( 60 );        }    }}

package org.hibernate.validator.referenceguide.chapter02.containerelement.custom;public class GearBoxValueExtractor implements ValueExtractor<GearBox<@ExtractedValue ?>> {    @Override    public void extractValues(GearBox<@ExtractedValue ?> originalValue, ValueExtractor.ValueReceiver receiver) {        receiver.value( null, originalValue.getGear() );    }}

Car car = new Car();car.setGearBox( new GearBox<>( new Gear.AcmeGear() ) );Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );assertEquals( 1, constraintViolations.size() );ConstraintViolation<Car> constraintViolation =        constraintViolations.iterator().next();assertEquals(        "Gear is not providing enough torque.",        constraintViolation.getMessage());assertEquals(        "gearBox",        constraintViolation.getPropertyPath().toString());

package org.hibernate.validator.referenceguide.chapter02.containerelement.nested;public class Car {    private Map<@NotNull Part, List<@NotNull Manufacturer>> partManufacturers =            new HashMap<>();    //...}

2.1.4. Class-level constraints

package org.hibernate.validator.referenceguide.chapter02.classlevel;@ValidPassengerCountpublic class Car {    private int seatCount;    private List<Person> passengers;    //...}

2.1.5. Constraint inheritance

package org.hibernate.validator.referenceguide.chapter02.inheritance;public class Car {    private String manufacturer;    @NotNull    public String getManufacturer() {        return manufacturer;    }    //...}

package org.hibernate.validator.referenceguide.chapter02.inheritance;public class RentalCar extends Car {    private String rentalStation;    @NotNull    public String getRentalStation() {        return rentalStation;    }    //...}

2.1.6. Object graphs

package org.hibernate.validator.referenceguide.chapter02.objectgraph;public class Car {    @NotNull    @Valid    private Person driver;    //...}

package org.hibernate.validator.referenceguide.chapter02.objectgraph;public class Person {    @NotNull    private String name;    //...}

package org.hibernate.validator.referenceguide.chapter02.objectgraph.containerelement;public class Car {    private List<@NotNull @Valid Person> passengers = new ArrayList<Person>();    private Map<@Valid Part, List<@Valid Manufacturer>> partManufacturers = new HashMap<>();    //...}

package org.hibernate.validator.referenceguide.chapter02.objectgraph.containerelement;public class Part {    @NotNull    private String name;    //...}

package org.hibernate.validator.referenceguide.chapter02.objectgraph.containerelement;public class Manufacturer {    @NotNull    private String name;    //...}

TheValidator interface is the most important object in Jakarta Bean Validation. The next section shows howto obtain aValidator instance. Afterwards you’ll learn how to use the different methods of theValidator interface.

2.2.1. Obtaining aValidator instance

ValidatorFactory factory = Validation.buildDefaultValidatorFactory();validator = factory.getValidator();

2.2.2. Validator methods

Car car = new Car( null, true );Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );assertEquals( 1, constraintViolations.size() );assertEquals( "must not be null", constraintViolations.iterator().next().getMessage() );

Car car = new Car( null, true );Set<ConstraintViolation<Car>> constraintViolations = validator.validateProperty(        car,        "manufacturer");assertEquals( 1, constraintViolations.size() );assertEquals( "must not be null", constraintViolations.iterator().next().getMessage() );

Set<ConstraintViolation<Car>> constraintViolations = validator.validateValue(        Car.class,        "manufacturer",        null);assertEquals( 1, constraintViolations.size() );assertEquals( "must not be null", constraintViolations.iterator().next().getMessage() );

2.2.3.ConstraintViolation

Hibernate Validator comprises a basic set of commonly used constraints. These are foremost theconstraints defined by the Jakarta Bean Validation specification (seeSection 2.3.1, “Jakarta Bean Validation constraints”).Additionally, Hibernate Validator provides useful custom constraints (seeSection 2.3.2, “Additional constraints”).

2.3.1. Jakarta Bean Validation constraints

2.3.2. Additional constraints

3.1.1. Parameter constraints

package org.hibernate.validator.referenceguide.chapter03.parameter;public class RentalStation {    public RentalStation(@NotNull String name) {        //...    }    public void rentCar(            @NotNull Customer customer,            @NotNull @Future Date startDate,            @Min(1) int durationInDays) {        //...    }}

package org.hibernate.validator.referenceguide.chapter03.crossparameter;public class Car {    @LuggageCountMatchesPassengerCount(piecesOfLuggagePerPassenger = 2)    public void load(List<Person> passengers, List<PieceOfLuggage> luggage) {        //...    }}

package org.hibernate.validator.referenceguide.chapter03.crossparameter.constrainttarget;public class Garage {    @ELAssert(expression = "...", validationAppliesTo = ConstraintTarget.PARAMETERS)    public Car buildCar(List<Part> parts) {        //...        return null;    }    @ELAssert(expression = "...", validationAppliesTo = ConstraintTarget.RETURN_VALUE)    public Car paintCar(int color) {        //...        return null;    }}

3.1.2. Return value constraints

package org.hibernate.validator.referenceguide.chapter03.returnvalue;public class RentalStation {    @ValidRentalStation    public RentalStation() {        //...    }    @NotNull    @Size(min = 1)    public List<@NotNull Customer> getCustomers() {        //...        return null;    }}

3.1.3. Cascaded validation

package org.hibernate.validator.referenceguide.chapter03.cascaded;public class Garage {    @NotNull    private String name;    @Valid    public Garage(String name) {        this.name = name;    }    public boolean checkCar(@Valid @NotNull Car car) {        //...        return false;    }}

package org.hibernate.validator.referenceguide.chapter03.cascaded;public class Car {    @NotNull    private String manufacturer;    @NotNull    @Size(min = 2, max = 14)    private String licensePlate;    public Car(String manufacturer, String licencePlate) {        this.manufacturer = manufacturer;        this.licensePlate = licencePlate;    }    //getters and setters ...}

package org.hibernate.validator.referenceguide.chapter03.cascaded.containerelement;public class Garage {    public boolean checkCars(@NotNull List<@Valid Car> cars) {        //...        return false;    }}

3.1.4. Method constraints in inheritance hierarchies

package org.hibernate.validator.referenceguide.chapter03.inheritance.parameter;public interface Vehicle {    void drive(@Max(75) int speedInMph);}

package org.hibernate.validator.referenceguide.chapter03.inheritance.parameter;public class Car implements Vehicle {    @Override    public void drive(@Max(55) int speedInMph) {        //...    }}

package org.hibernate.validator.referenceguide.chapter03.inheritance.parallel;public interface Vehicle {    void drive(@Max(75) int speedInMph);}

package org.hibernate.validator.referenceguide.chapter03.inheritance.parallel;public interface Car {    void drive(int speedInMph);}

package org.hibernate.validator.referenceguide.chapter03.inheritance.parallel;public class RacingCar implements Car, Vehicle {    @Override    public void drive(int speedInMph) {        //...    }}

package org.hibernate.validator.referenceguide.chapter03.inheritance.returnvalue;public interface Vehicle {    @NotNull    List<Person> getPassengers();}

package org.hibernate.validator.referenceguide.chapter03.inheritance.returnvalue;public class Car implements Vehicle {    @Override    @Size(min = 1)    public List<Person> getPassengers() {        //...        return null;    }}

The validation of method constraints is done using theExecutableValidator interface.

InSection 3.2.1, “Obtaining anExecutableValidator instance” you will learn how to obtain anExecutableValidatorinstance whileSection 3.2.2, “ExecutableValidator methods” shows how to use the different methodsoffered by this interface.

Instead of calling theExecutableValidator methods directly from within application code, they areusually invoked via a method interception technology such as AOP, proxy objects, etc. This causesexecutable constraints to be validated automatically and transparently upon method or constructorinvocation. Typically aConstraintViolationException is raised by the integration layer in case anyof the constraints is violated.

3.2.1. Obtaining anExecutableValidator instance

ValidatorFactory factory = Validation.buildDefaultValidatorFactory();executableValidator = factory.getValidator().forExecutables();

3.2.2.ExecutableValidator methods

package org.hibernate.validator.referenceguide.chapter03.validation;public class Car {    public Car(@NotNull String manufacturer) {        //...    }    @ValidRacingCar    public Car(String manufacturer, String team) {        //...    }    public void drive(@Max(75) int speedInMph) {        //...    }    @Size(min = 1)    public List<Passenger> getPassengers() {        //...        return Collections.emptyList();    }}

Car object = new Car( "Morris" );Method method = Car.class.getMethod( "drive", int.class );Object[] parameterValues = { 80 };Set<ConstraintViolation<Car>> violations = executableValidator.validateParameters(        object,        method,        parameterValues);assertEquals( 1, violations.size() );Class<? extends Annotation> constraintType = violations.iterator()        .next()        .getConstraintDescriptor()        .getAnnotation()        .annotationType();assertEquals( Max.class, constraintType );

Car object = new Car( "Morris" );Method method = Car.class.getMethod( "getPassengers" );Object returnValue = Collections.<Passenger>emptyList();Set<ConstraintViolation<Car>> violations = executableValidator.validateReturnValue(        object,        method,        returnValue);assertEquals( 1, violations.size() );Class<? extends Annotation> constraintType = violations.iterator()        .next()        .getConstraintDescriptor()        .getAnnotation()        .annotationType();assertEquals( Size.class, constraintType );

Constructor<Car> constructor = Car.class.getConstructor( String.class );Object[] parameterValues = { null };Set<ConstraintViolation<Car>> violations = executableValidator.validateConstructorParameters(        constructor,        parameterValues);assertEquals( 1, violations.size() );Class<? extends Annotation> constraintType = violations.iterator()        .next()        .getConstraintDescriptor()        .getAnnotation()        .annotationType();assertEquals( NotNull.class, constraintType );

//constructor for creating racing carsConstructor<Car> constructor = Car.class.getConstructor( String.class, String.class );Car createdObject = new Car( "Morris", null );Set<ConstraintViolation<Car>> violations = executableValidator.validateConstructorReturnValue(        constructor,        createdObject);assertEquals( 1, violations.size() );Class<? extends Annotation> constraintType = violations.iterator()        .next()        .getConstraintDescriptor()        .getAnnotation()        .annotationType();assertEquals( ValidRacingCar.class, constraintType );

3.2.3.ConstraintViolation methods for method validation

Car object = new Car( "Morris" );Method method = Car.class.getMethod( "drive", int.class );Object[] parameterValues = { 80 };Set<ConstraintViolation<Car>> violations = executableValidator.validateParameters(        object,        method,        parameterValues);assertEquals( 1, violations.size() );Iterator<Node> propertyPath = violations.iterator()        .next()        .getPropertyPath()        .iterator();MethodNode methodNode = propertyPath.next().as( MethodNode.class );assertEquals( "drive", methodNode.getName() );assertEquals( Arrays.<Class<?>>asList( int.class ), methodNode.getParameterTypes() );ParameterNode parameterNode = propertyPath.next().as( ParameterNode.class );assertEquals( "speedInMph", parameterNode.getName() );assertEquals( 0, parameterNode.getParameterIndex() );

In addition to the built-in bean and property-level constraints discussed inSection 2.3, “Built-in constraints”, Hibernate Validator currently provides one method-level constraint,@ParameterScriptAssert. This is a generic cross-parameter constraint which allows to implementvalidation routines using any JSR 223 compatible ("Scripting for the Java^TM Platform") scriptinglanguage, provided an engine for this language is available on the classpath.

To refer to the executable’s parameters from within the expression, use their name as obtained fromthe active parameter name provider (seeSection 9.2.4, “ParameterNameProvider”).Example 3.17, “Using@ParameterScriptAssert” shows how the validation logic of the@LuggageCountMatchesPassengerCountconstraint fromExample 3.2, “Declaring a cross-parameter constraint” could be expressed with the help of@ParameterScriptAssert.

Constraint violation messages are retrieved from so called message descriptors. Each constraintdefines its default message descriptor using the message attribute. At declaration time, the defaultdescriptor can be overridden with a specific value as shown inExample 4.1, “Specifying a message descriptor using the message attribute”.

If a constraint is violated, its descriptor will be interpolated by the validation engine using thecurrently configuredMessageInterpolator. The interpolated error message can then be retrieved fromthe resulting constraint violation by callingConstraintViolation#getMessage().

Message descriptors can containmessage parameters as well asmessage expressions which will beresolved during interpolation. Message parameters are string literals enclosed in{}, whilemessage expressions are string literals enclosed in${}. The following algorithm is applied duringmethod interpolation:

1. Resolve any message parameters by using them as key for the resource bundleValidationMessages. Ifthis bundle contains an entry for a given message parameter, that parameter will be replaced in themessage with the corresponding value from the bundle. This step will be executed recursively in casethe replaced value again contains message parameters. The resource bundle is expected to be providedby the application developer, e.g. by adding a file namedValidationMessages.properties to theclasspath. You can also create localized error messages by providing locale specific variations ofthis bundle, such asValidationMessages_en_US.properties. By default, the JVM’s default locale(Locale#getDefault()) will be used when looking up messages in the bundle.

2. Resolve any message parameters by using them as key for a resource bundle containing the standarderror messages for the built-in constraints as defined in Appendix B of the Jakarta Bean Validationspecification. In the case of Hibernate Validator, this bundle is namedorg.hibernate.validator.ValidationMessages. If this step triggers a replacement, step 1 is executedagain, otherwise step 3 is applied.

3. Resolve any message parameters by replacing them with the value of the constraint annotation memberof the same name. This allows to refer to attribute values of the constraint (e.g.Size#min()) inthe error message (e.g. "must be at least ${min}").

4. Resolve any message expressions by evaluating them as expressions of the Unified ExpressionLanguage. SeeSection 4.1.2, “Interpolation with message expressions” to learn more about the usage ofUnified EL in error messages.

4.1.1. Special characters

4.1.2. Interpolation with message expressions

4.1.3. Examples

package org.hibernate.validator.referenceguide.chapter04.complete;public class Car {    @NotNull    private String manufacturer;    @Size(            min = 2,            max = 14,            message = "The license plate '${validatedValue}' must be between {min} and {max} characters long"    )    private String licensePlate;    @Min(            value = 2,            message = "There must be at least {value} seat${value > 1 ? 's' : ''}"    )    private int seatCount;    @DecimalMax(            value = "350",            message = "The top speed ${formatter.format('%1$.2f', validatedValue)} is higher " +                    "than {value}"    )    private double topSpeed;    @DecimalMax(value = "100000", message = "Price must not be higher than ${value}")    private BigDecimal price;    public Car(            String manufacturer,            String licensePlate,            int seatCount,            double topSpeed,            BigDecimal price) {        this.manufacturer = manufacturer;        this.licensePlate = licensePlate;        this.seatCount = seatCount;        this.topSpeed = topSpeed;        this.price = price;    }    //getters and setters ...}

Car car = new Car( null, "A", 1, 400.123456, BigDecimal.valueOf( 200000 ) );String message = validator.validateProperty( car, "manufacturer" )        .iterator()        .next()        .getMessage();assertEquals( "must not be null", message );message = validator.validateProperty( car, "licensePlate" )        .iterator()        .next()        .getMessage();assertEquals(        "The license plate 'A' must be between 2 and 14 characters long",        message);message = validator.validateProperty( car, "seatCount" ).iterator().next().getMessage();assertEquals( "There must be at least 2 seats", message );message = validator.validateProperty( car, "topSpeed" ).iterator().next().getMessage();assertEquals( "The top speed 400.12 is higher than 350", message );message = validator.validateProperty( car, "price" ).iterator().next().getMessage();assertEquals( "Price must not be higher than $100000", message );

If the default message interpolation algorithm does not fit your requirements, it is also possible toplug in a customMessageInterpolator implementation.

Custom interpolators must implement the interfacejavax.validation.MessageInterpolator. Note thatimplementations must be thread-safe. It is recommended that custom message interpolators delegatefinal implementation to the default interpolator, which can be obtained viaConfiguration#getDefaultMessageInterpolator().

In order to use a custom message interpolator it must be registered either by configuring it in theJakarta Bean Validation XML descriptorMETA-INF/validation.xml (seeSection 8.1, “Configuring the validator factory invalidation.xml”) or by passing it when bootstrapping aValidatorFactory orValidator (seeSection 9.2.1, “MessageInterpolator” andSection 9.3, “Configuring a Validator”, respectively).

4.2.1.ResourceBundleLocator

Validator validator = Validation.byDefaultProvider()        .configure()        .messageInterpolator(                new ResourceBundleMessageInterpolator(                        new PlatformResourceBundleLocator( "MyMessages" )                )        )        .buildValidatorFactory()        .getValidator();

Validator validator = Validation.byDefaultProvider()        .configure()        .messageInterpolator(                new ResourceBundleMessageInterpolator(                        new AggregateResourceBundleLocator(                                Arrays.asList(                                        "MyMessages",                                        "MyOtherMessages"                                )                        )                )        )        .buildValidatorFactory()        .getValidator();

Groups allow you to restrict the set of constraints applied during validation. One use case forvalidation groups are UI wizards where in each step only a specified subset of constraints shouldget validated. The groups targeted are passed as var-arg parameters to the appropriate validatemethod.

Let’s have a look at an example. The classPerson inExample 5.1, “Example classPerson” has a@NotNullconstraint onname. Since no group is specified for this annotation the default groupjavax.validation.groups.Default is assumed.

The classDriver inExample 5.2, “Driver” extendsPerson and adds the propertiesage andhasDrivingLicense. Drivers must be at least 18 years old (@Min(18)) and have a driving license(@AssertTrue). Both constraints defined on these properties belong to the groupDriverChecks whichis just a simple tagging interface.

Finally the classCar (Example 5.3, “Car”) has some constraints which are part of the default group aswell as@AssertTrue in the groupCarChecks on the propertypassedVehicleInspection which indicateswhether a car passed the road worthy tests.

Overall three different groups are used in the example:

• The constraints onPerson.name,Car.manufacturer,Car.licensePlate andCar.seatCountall belong to theDefault group

• The constraints onDriver.age andDriver.hasDrivingLicense belong toDriverChecks

• The constraint onCar.passedVehicleInspection belongs to the groupCarChecks

Example 5.4, “Using validation groups” shows how passing different group combinations to theValidator#validate()method results in different validation results.

The firstvalidate() call inExample 5.4, “Using validation groups” is done using no explicit group. There are novalidation errors, even though the propertypassedVehicleInspection is per defaultfalse asthe constraint defined on this property does not belong to the default group.

The next validation using theCarChecks group fails until the car passes the vehicle inspection.Adding a driver to the car and validating againstDriverChecks again yields one constraint violationdue to the fact that the driver has not yet passed the driving test. Only after settingpassedDrivingTest totrue the validation againstDriverChecks passes.

The lastvalidate() call finally shows that all constraints are passing by validating against alldefined groups.

InExample 5.4, “Using validation groups”, we need to callvalidate() for each validation group, or specify all ofthem one by one.

In some situations, you may want to define a group of constraints which includes another group.You can do that using group inheritance.

InExample 5.5, “SuperCar”, we define aSuperCar and a groupRaceCarChecks that extends theDefault group.ASuperCar must have safety belts to be allowed to run in races.

In the example below, we will check if aSuperCar with one seat and no security belts is a valid carand if it is a valid race-car.

On the first call tovalidate(), we do not specify a group. There is one validation error because acar must have at least one seat. It is the constraint from theDefault group.

On the second call, we specify only the groupRaceCarChecks. There are two validation errors: oneabout the missing seat from theDefault group, another one about the fact that there is no safetybelts coming from theRaceCarChecks group.

By default, constraints are evaluated in no particular order, regardless of which groups they belongto. In some situations, however, it is useful to control the order in which constraints are evaluated.

In the example fromExample 5.4, “Using validation groups” it could for instance be required that first all defaultcar constraints are passing before checking the road worthiness of the car. Finally, before drivingaway, the actual driver constraints should be checked.

In order to implement such a validation order you just need to define an interface and annotate itwith@GroupSequence, defining the order in which the groups have to be validated (seeExample 5.7, “Defining a group sequence”). If at least one constraint fails in a sequenced group, none of theconstraints of the following groups in the sequence get validated.

You then can use the new sequence as shown in inExample 5.8, “Using a group sequence”.

5.4.1.@GroupSequence

package org.hibernate.validator.referenceguide.chapter05;@GroupSequence({ RentalChecks.class, CarChecks.class, RentalCar.class })public class RentalCar extends Car {    @AssertFalse(message = "The car is currently rented out", groups = RentalChecks.class)    private boolean rented;    public RentalCar(String manufacturer, String licencePlate, int seatCount) {        super( manufacturer, licencePlate, seatCount );    }    public boolean isRented() {        return rented;    }    public void setRented(boolean rented) {        this.rented = rented;    }}

package org.hibernate.validator.referenceguide.chapter05;public interface RentalChecks {}

RentalCar rentalCar = new RentalCar( "Morris", "DD-AB-123", 2 );rentalCar.setPassedVehicleInspection( true );rentalCar.setRented( true );Set<ConstraintViolation<RentalCar>> constraintViolations = validator.validate( rentalCar );assertEquals( 1, constraintViolations.size() );assertEquals(        "Wrong message",        "The car is currently rented out",        constraintViolations.iterator().next().getMessage());rentalCar.setRented( false );constraintViolations = validator.validate( rentalCar );assertEquals( 0, constraintViolations.size() );

5.4.2.@GroupSequenceProvider

package org.hibernate.validator.referenceguide.chapter05.groupsequenceprovider;public class RentalCarGroupSequenceProvider        implements DefaultGroupSequenceProvider<RentalCar> {    @Override    public List<Class<?>> getValidationGroups(RentalCar car) {        List<Class<?>> defaultGroupSequence = new ArrayList<Class<?>>();        defaultGroupSequence.add( RentalCar.class );        if ( car != null && !car.isRented() ) {            defaultGroupSequence.add( CarChecks.class );        }        return defaultGroupSequence;    }}

package org.hibernate.validator.referenceguide.chapter05.groupsequenceprovider;@GroupSequenceProvider(RentalCarGroupSequenceProvider.class)public class RentalCar extends Car {    @AssertFalse(message = "The car is currently rented out", groups = RentalChecks.class)    private boolean rented;    public RentalCar(String manufacturer, String licencePlate, int seatCount) {        super( manufacturer, licencePlate, seatCount );    }    public boolean isRented() {        return rented;    }    public void setRented(boolean rented) {        this.rented = rented;    }}

What if you wanted to validate the car related checks together with the driver checks? Of course youcould pass the required groups to the validate call explicitly, but what if you wanted to make thesevalidations occur as part of theDefault group validation? Here@ConvertGroup comes into play whichallows you to use a different group than the originally requested one during cascaded validation.

Let’s have a look atExample 5.12, “@ConvertGroup usage”. Here@GroupSequence({CarChecks.class, Car.class }) is used to combine the car related constraints under theDefault group(seeSection 5.4, “Redefining the default group sequence”). There is also a@ConvertGroup(from = Default.class, to =DriverChecks.class) which ensures theDefault group gets converted to theDriverChecks group duringcascaded validation of the driver association.

As a result the validation inExample 5.13, “Test case for@ConvertGroup” succeeds, even though the constraintonhasDrivingLicense belongs to theDriverChecks group and only theDefault group is requested inthevalidate() call.

You can define group conversions wherever@Valid can be used, namely associations as well as methodand constructor parameters and return values. Multiple conversions can be specified using@ConvertGroup.List.

However, the following restrictions apply:

• @ConvertGroup must only be used in combination with@Valid. If used without, aConstraintDeclarationException is thrown.

• It is not legal to have multiple conversion rules on the same element with the same from value.In this case, aConstraintDeclarationException is raised.

• Thefrom attribute must not refer to a group sequence. AConstraintDeclarationException israised in this situation.

To create a custom constraint, the following three steps are required:

• Create a constraint annotation

• Implement a validator

• Define a default error message

6.1.1. The constraint annotation

package org.hibernate.validator.referenceguide.chapter06;public enum CaseMode {    UPPER,    LOWER;}

package org.hibernate.validator.referenceguide.chapter06;import static java.lang.annotation.ElementType.ANNOTATION_TYPE;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;@Target({ FIELD, METHOD, PARAMETER, ANNOTATION_TYPE, TYPE_USE })@Retention(RUNTIME)@Constraint(validatedBy = CheckCaseValidator.class)@Documented@Repeatable(List.class)public @interface CheckCase {    String message() default "{org.hibernate.validator.referenceguide.chapter06.CheckCase." +            "message}";    Class<?>[] groups() default { };    Class<? extends Payload>[] payload() default { };    CaseMode value();    @Target({ FIELD, METHOD, PARAMETER, ANNOTATION_TYPE })    @Retention(RUNTIME)    @Documented    @interface List {        CheckCase[] value();    }}

6.1.2. The constraint validator

package org.hibernate.validator.referenceguide.chapter06;public class CheckCaseValidator implements ConstraintValidator<CheckCase, String> {    private CaseMode caseMode;    @Override    public void initialize(CheckCase constraintAnnotation) {        this.caseMode = constraintAnnotation.value();    }    @Override    public boolean isValid(String object, ConstraintValidatorContext constraintContext) {        if ( object == null ) {            return true;        }        if ( caseMode == CaseMode.UPPER ) {            return object.equals( object.toUpperCase() );        }        else {            return object.equals( object.toLowerCase() );        }    }}

package org.hibernate.validator.referenceguide.chapter06.constraintvalidatorcontext;public class CheckCaseValidator implements ConstraintValidator<CheckCase, String> {    private CaseMode caseMode;    @Override    public void initialize(CheckCase constraintAnnotation) {        this.caseMode = constraintAnnotation.value();    }    @Override    public boolean isValid(String object, ConstraintValidatorContext constraintContext) {        if ( object == null ) {            return true;        }        boolean isValid;        if ( caseMode == CaseMode.UPPER ) {            isValid = object.equals( object.toUpperCase() );        }        else {            isValid = object.equals( object.toLowerCase() );        }        if ( !isValid ) {            constraintContext.disableDefaultConstraintViolation();            constraintContext.buildConstraintViolationWithTemplate(                    "{org.hibernate.validator.referenceguide.chapter06." +                    "constraintvalidatorcontext.CheckCase.message}"            )            .addConstraintViolation();        }        return isValid;    }}

package org.hibernate.validator.referenceguide.chapter06;public class MyFutureValidator implements HibernateConstraintValidator<MyFuture, Instant> {    private Clock clock;    private boolean orPresent;    @Override    public void initialize(ConstraintDescriptor<MyFuture> constraintDescriptor,            HibernateConstraintValidatorInitializationContext initializationContext) {        this.orPresent = constraintDescriptor.getAnnotation().orPresent();        this.clock = initializationContext.getClockProvider().getClock();    }    @Override    public boolean isValid(Instant instant, ConstraintValidatorContext constraintContext) {        //...        return false;    }}

ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )        .configure()        .constraintValidatorPayload( "US" )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

HibernateValidatorFactory hibernateValidatorFactory = Validation.byDefaultProvider()        .configure()        .buildValidatorFactory()        .unwrap( HibernateValidatorFactory.class );Validator validator = hibernateValidatorFactory.usingContext()        .constraintValidatorPayload( "US" )        .getValidator();// [...] US specific validation checksvalidator = hibernateValidatorFactory.usingContext()        .constraintValidatorPayload( "FR" )        .getValidator();// [...] France specific validation checks

package org.hibernate.validator.referenceguide.chapter06.constraintvalidatorpayload;public class ZipCodeValidator implements ConstraintValidator<ZipCode, String> {    public String countryCode;    @Override    public boolean isValid(String object, ConstraintValidatorContext constraintContext) {        if ( object == null ) {            return true;        }        boolean isValid = false;        String countryCode = constraintContext                .unwrap( HibernateConstraintValidatorContext.class )                .getConstraintValidatorPayload( String.class );        if ( "US".equals( countryCode ) ) {            // checks specific to the United States        }        else if ( "FR".equals( countryCode ) ) {            // checks specific to France        }        else {            // ...        }        return isValid;    }}

6.1.3. The error message

org.hibernate.validator.referenceguide.chapter06.CheckCase.message=Case mode must be {value}.

6.1.4. Using the constraint

package org.hibernate.validator.referenceguide.chapter06;public class Car {    @NotNull    private String manufacturer;    @NotNull    @Size(min = 2, max = 14)    @CheckCase(CaseMode.UPPER)    private String licensePlate;    @Min(2)    private int seatCount;    public Car(String manufacturer, String licencePlate, int seatCount) {        this.manufacturer = manufacturer;        this.licensePlate = licencePlate;        this.seatCount = seatCount;    }    //getters and setters ...}

//invalid license plateCar car = new Car( "Morris", "dd-ab-123", 4 );Set<ConstraintViolation<Car>> constraintViolations =        validator.validate( car );assertEquals( 1, constraintViolations.size() );assertEquals(        "Case mode must be UPPER.",        constraintViolations.iterator().next().getMessage());//valid license platecar = new Car( "Morris", "DD-AB-123", 4 );constraintViolations = validator.validate( car );assertEquals( 0, constraintViolations.size() );

As discussed earlier, constraints can also be applied on the class level to validate the state of anentire object. Class-level constraints are defined in the same way as are property constraints.Example 6.12, “Implementing a class-level constraint” shows constraint annotation and validator of the@ValidPassengerCount constraint you already saw in use inExample 2.9, “Class-level constraint”.

As the example demonstrates, you need to use the element typeTYPE in the@Target annotation. Thisallows the constraint to be put on type definitions. The validator of the constraint in the examplereceives aCar in theisValid() method and can access the complete object state to decide whetherthe given instance is valid or not.

6.2.1. Custom property paths

package org.hibernate.validator.referenceguide.chapter06.custompath;public class ValidPassengerCountValidator        implements ConstraintValidator<ValidPassengerCount, Car> {    @Override    public void initialize(ValidPassengerCount constraintAnnotation) {    }    @Override    public boolean isValid(Car car, ConstraintValidatorContext constraintValidatorContext) {        if ( car == null ) {            return true;        }        boolean isValid = car.getPassengers().size() <= car.getSeatCount();        if ( !isValid ) {            constraintValidatorContext.disableDefaultConstraintViolation();            constraintValidatorContext                    .buildConstraintViolationWithTemplate( "{my.custom.template}" )                    .addPropertyNode( "passengers" ).addConstraintViolation();        }        return isValid;    }}

Jakarta Bean Validation distinguishes between two different kinds of constraints.

Generic constraints (which have been discussed so far) apply to the annotated element, e.g. a type,field, container element, method parameter or return value etc.Cross-parameter constraints, in contrast, apply to the array of parameters of a method or constructorand can be used to express validation logic which depends on several parameter values.

In order to define a cross-parameter constraint, its validator class must be annotated with@SupportedValidationTarget(ValidationTarget.PARAMETERS). The type parameterT from theConstraintValidator interface must resolve to eitherObject orObject[] in order to receive thearray of method/constructor arguments in theisValid() method.

The following example shows the definition of a cross-parameter constraint which can be used tocheck that twoDate parameters of a method are in the correct order:

The definition of a cross-parameter constraint isn’t any different from defining a genericconstraint, i.e. it must specify the membersmessage(),groups() andpayload() and be annotated with@Constraint. This meta annotation also specifies the corresponding validator, which is shown inExample 6.15, “Generic and cross-parameter constraint”. Note that besides the element typesMETHOD andCONSTRUCTORalsoANNOTATION_TYPE is specified as target of the annotation, in order to enable the creation ofcomposed constraints based on@ConsistentDateParameters (seeSection 6.4, “Constraint composition”).

As discussed above, the validation targetPARAMETERS must be configured for a cross-parametervalidator by using the@SupportedValidationTarget annotation. Since a cross-parameter constraintcould be applied to any method or constructor, it is considered a best practice to check for theexpected number and types of parameters in the validator implementation.

As with generic constraints,null parameters should be considered valid and@NotNull on theindividual parameters should be used to make sure that parameters are notnull.

In rare situations a constraint is both, generic and cross-parameter. This is the case if aconstraint has a validator class which is annotated with@SupportedValidationTarget({ValidationTarget.PARAMETERS, ValidationTarget.ANNOTATED_ELEMENT}) or ifit has a generic and a cross-parameter validator class.

When declaring such a constraint on a method which has parameters and also a return value, theintended constraint target can’t be determined. Constraints which are generic and cross-parameter atthe same time must therefore define a membervalidationAppliesTo() which allows the constraint userto specify the constraint’s target as shown inExample 6.16, “Generic and cross-parameter constraint”.

The@ScriptAssert constraint has two validators (not shown), a generic and a cross-parameter one andthus defines the membervalidationAppliesTo(). The default valueIMPLICIT allows to derive thetarget automatically in situations where this is possible (e.g. if the constraint is declared on afield or on a method which has parameters but no return value).

If the target can not be determined implicitly, it must be set by the user to eitherPARAMETERS orRETURN_VALUE as shown inExample 6.17, “Specifying the target for a generic and cross-parameter constraint”.

Looking at thelicensePlate field of theCar class inExample 6.10, “Applying the@CheckCase constraint”, you see threeconstraint annotations already. In more complex scenarios, where even more constraints could be appliedto one element, this might easily become a bit confusing. Furthermore, if there was alicensePlatefield in another class, you would have to copy all constraint declarations to the other class aswell, violating the DRY principle.

You can address this kind of problem by creating higher level constraints, composed from severalbasic constraints.Example 6.18, “Creating a composing constraint@ValidLicensePlate” shows a composed constraint annotation whichcomprises the constraints@NotNull,@Size and@CheckCase:

To create a composed constraint, simply annotate the constraint declaration with its comprisingconstraints. If the composed constraint itself requires a validator, this validator is to bespecified within the@Constraint annotation. For composed constraints which don’t need an additionalvalidator such as@ValidLicensePlate, just setvalidatedBy() to an empty array.

Using the new composed constraint at thelicensePlate field is fully equivalent to the previousversion, where the three constraints were declared directly at the field itself:

The set ofConstraintViolations retrieved when validating aCar instance will contain an entry foreach violated composing constraint of the@ValidLicensePlate constraint. If you rather prefer asingleConstraintViolation in case any of the composing constraints is violated, the@ReportAsSingleViolation meta constraint can be used as follows:

Hibernate Validator comes with built-in value extractors for the usual Java containertypes so, except if you are using your own custom container types (or the onesof external libraries such asGuava'sMultimap),you should not have to add your own value extractors.

Built-in value extractors are present for all the following container types:

• java.util.Iterable;

• java.util.List;

• java.util.Map: for keys and values;

• java.util.Optional,java.util.OptionalInt,java.util.OptionalLong andjava.util.OptionalDouble;

• JavaFX'sObservableValue (seeSection 7.4, “JavaFX value extractors”for more details).

The complete list of built-in value extractors with all the details on how theybehave can be found in theJakarta Bean Validation specification.

To extract values from a custom container, one needs to implement aValueExtractor.

ValueExtractor is a very simple API as the only purpose of a value extractor is to providethe extracted values to aValueReceiver.

For instance, let’s consider the case of Guava’sOptional. It is an easy exampleas we can shape its value extractor after thejava.util.Optional one:

Some explanations are in order:

• The@ExtractedValue annotation marks the type argument under consideration: itis going to be used to resolve the type of the validated value;

• We use thevalue() method of the receiver asOptional is a pure wrapper type;

• We don’t want to add a node to the property path of the constraint violationas we want the violation to be reported as if it were directly on the propertyso we pass anull node name tovalue().

A more interesting example is the case of Guava’sMultimap: we would like to beable to validate both the keys and the values of this container type.

Let’s first consider the case of the values. A value extractor extracting themis required:

It allows to validate constraints for the values of theMultimap:

Another value extractor is required to be able to put constraints on the keysof aMultimap:

Once these two value extractors are registered, you can declare constraints on thekeys and values of aMultimap:

The differences between the two value extractors may be a bit subtle at a firstglance so let’s shed some light on them:

• The@ExtractedValue annotation marks the targeted type argument (eitherK orV in this case).

• We use different node names (<multimap key> vs.<multimap value>).

• In one case, we pass the values to the receiver (third argument of thekeyedValue() call), in the other, we pass the keys.

Depending on your container type, you should choose theValueReceivermethod fitting the best:

value()

for a simple wrapping container - it is used forOptionals

iterableValue()

for an iterable container - it is used forSets

indexedValue()

for a container containing indexed values - it is used forLists

keyedValue()

for a container containing keyed values - it is used forMaps.It is used for both the keys and the values. In the case of keys,the key is also passed as the validated value.

For all these methods, you need to pass a node name: it is the name included inthe node added to the property path of the constraint violation. As mentionedearlier, if the node name isnull, no node is added to the property path:it is be useful for pure wrapper types similar toOptional.

The choice of the method used is important as it adds contextual information to theproperty path of the constraint violation e.g. the index or the key of thevalidated value.

You might have noticed that, until now, we only implemented value extractorsfor generic containers.

Hibernate Validator also supports value extraction for non generic containers.

Let’s take the case ofjava.util.OptionalInt which wraps a primitiveintinto anOptional-like container.

A first attempt at a value extractor forOptionalInt would look like:

There is an obvious thing missing for a non generic container: we don’t havea type parameter. It has two consequences:

• we cannot determine the type of the validated value using the type argument;

• we cannot add constraints on the type argument (e.g.Container<@NotNull String>).

First things first, we need a way to tell Hibernate Validator that the valueextracted from anOptionalInt is of typeInteger.As you can see in the above example, thetype attribute of the@ExtractedValueannotation allows to provide this information to the validation engine.

Then you have to tell the validation engine that theMin constraint you want toadd to theOptionalInt property relates to the wrapped value and not the wrapper.

Jakarta Bean Validation provides theUnwrapping.Unwrap payload for this situation:

If we take a step back, most - if not all - the constraints we would like to add to anOptionalInt property would be applied to the wrapped value so having a way to make itthe default would be nice.

This is exactly what the@UnwrapByDefault annotation is for:

When declaring this value extractor forOptionalInt, constraint annotations willby default be applied to the wrapped value:

Note that you can still declare an annotation for the wrapper itself by usingtheUnwrapping.Skip payload:

Bean properties in JavaFX are typically not of simple data types likeStringorint, but are wrapped inProperty types which allows to make them observable,use them for data binding etc.

Thus, value extraction is required to be able to apply constraints on thewrapped values.

The JavaFXObservableValue value extractor is marked with@UnwrapByDefault.As such, the constraints hosted on the container target the wrapped value bydefault.

Thus, you can constrain aStringProperty as below:

Or aLongProperty:

The iterable property types, namelyReadOnlyListProperty,ListProperty and theirSet andMap counterparts are generic and, as such,container element constraints can be used. Thus, they have specific valueextractors that are not marked with@UnwrapByDefault.

AReadOnlyListProperty would naturally be constrained as aList:

Hibernate Validator does not detect automatically the value extractors in theclasspath so they have to be registered.

There are several ways to register value extractors (in increasing order ofpriority):

Provided by the validation engine itself

SeeSection 7.1, “Built-in value extractors”.

Via the Java service loader mechanism

The fileMETA-INF/services/javax.validation.valueextraction.ValueExtractormust be provided, with the fully-qualified names of one or more valueextractor implementations as its contents, each on a separate line.

In theMETA-INF/validation.xml file

SeeSection 8.1, “Configuring the validator factory invalidation.xml” for more information abouthow to register value extractors in the XML configuration.

By callingConfiguration#addValueExtractor(ValueExtractor<?>)

SeeSection 9.2.6, “RegisteringValueExtractors”for more information.

By invokingValidatorContext#addValueExtractor(ValueExtractor<?>)

It only declares the value extractor for thisValidator instance.

A value extractor for a given type and type parameter specified at a higherpriority overrides any other extractors for the same type and type parametergiven at lower priorities.

In most cases, you should not have to worry about this but, if you are overridingexisting value extractors, you can find a detailed description of the valueextractors resolution algorithms in the Jakarta Bean Validation specification:

• forcontainer element constraints,

• forcascaded validation,

• and forimplicit unwrapping.

One important thing to have in mind is that:

• for container element constraints, the declared type is used to resolve the valueextractors;

• for cascaded validation, it is the runtime type.

The key to enable XML configuration for Hibernate Validator is the fileMETA-INF/validation.xml.If this file exists on the classpath its configuration will be applied when theValidatorFactorygets created.Figure 1, “Validation configuration schema” shows a model view of the XML schema to whichvalidation.xml has to adhere.

Example 8.1, “validation.xml”shows the several configuration options ofvalidation.xml. All settings are optional and the sameconfiguration options are also available programmatically throughjavax.validation.Configuration. Infact, the XML configuration will be overridden by values explicitly specified via the programmaticAPI. It is even possible to ignore the XML configuration completely viaConfiguration#ignoreXmlConfiguration(). See alsoSection 9.2, “Configuring aValidatorFactory”.

The nodedefault-provider allows to choose the Jakarta Bean Validation provider. This is useful if there ismore than one provider on the classpath.message-interpolator,traversable-resolver,constraint-validator-factory,parameter-name-provider andclock-provider allow to customizethe used implementations for the interfacesMessageInterpolator,TraversableResolver,ConstraintValidatorFactory,ParameterNameProvider andClockProvider defined in thejavax.validation package.See the sub-sections ofSection 9.2, “Configuring aValidatorFactory” for more information about theseinterfaces.

value-extractor allows to declare additional value extractors either to extract values from customcontainer types or to override the built-in value extractors. SeeChapter 7,Value extraction formore information about how to implementjavax.validation.valueextraction.ValueExtractor.

executable-validation and its subnodes define defaults for method validation. The Jakarta Bean Validationspecification defines constructor and non getter methods as defaults. The enabled attribute acts asglobal switch to turn method validation on and off (see alsoChapter 3,Declaring and validating method constraints).

Via theconstraint-mapping element you can list an arbitrary number of additional XML filescontaining the actual constraint configuration. Mapping file names must be specified using theirfully-qualified name on the classpath. Details on writing mapping files can be found in the nextsection.

Last but not least, you can specify provider specific properties via theproperty nodes. In theexample, we are using the Hibernate Validator specifichibernate.validator.fail_fast property (seeSection 12.2, “Fail fast mode”).

Expressing constraints in XML is possible via files adhering to the schema seen inFigure 2, “Validation mapping schema”. Note that these mapping files are only processed if listed viaconstraint-mapping invalidation.xml.

Example 8.2, “Bean constraints configured via XML” shows how the classes Car and RentalCar fromExample 5.3, “Car” resp.Example 5.9, “ClassRentalCar with redefined default group” could be mapped in XML.

Example 8.3, “Method constraints configured via XML” shows how the constraints fromExample 3.1, “Declaring method and constructor parameter constraints”,Example 3.4, “Declaring method and constructor return value constraints”andExample 3.3, “Specifying a constraint’s target” can be expressed in XML.

The XML configuration is closely mirroring the programmatic API. For this reason it should sufficeto just add some comments.default-package is used for all fields where a class name is expected. Ifthe specified class is not fully qualified the configured default package will be used. Everymapping file can then have several bean nodes, each describing the constraints on the entity withthe specified class name.

Settingignore-annotations totrue means that constraint annotations placed on the configured beanare ignored. The default for this value is true.ignore-annotations is also available for the nodesclass,fields,getter,constructor,method,parameter,cross-parameter andreturn-value.If not explicitly specified on these levels the configured bean value applies.

The nodesclass,field,getter,container-element-type,constructor andmethod(and its sub node parameter) determine on which level the constraint gets placed.Thevalid node is used to enable cascaded validation and theconstraint node to add a constrainton the corresponding level.Each constraint definition must define the class via theannotation attribute.The constraint attributes required by the Jakarta Bean Validation specification (message,groups andpayload) have dedicated nodes. All other constraint specific attributes are configured using theelement node.

Theclass node also allows to reconfigure the default group sequence (seeSection 5.4, “Redefining the default group sequence”) via thegroup-sequence node. Not shown in the example is the useofconvert-group tospecify group conversions (seeSection 5.5, “Group conversion”). This node is available onfield,getter,container-element-type,parameter andreturn-value and specifies afrom and atoattributes to specify the groups.

Last but not least, the list ofConstraintValidator instances associated to a given constraintcan be altered via theconstraint-definition node. The annotation attribute represents the constraintannotation being altered. Thevalidated-by element represent the (ordered) list ofConstraintValidatorimplementations associated to the constraint. Ifinclude-existing-validator is set tofalse,validators defined on the constraint annotation are ignored. If set totrue, the list of constraintvalidators described in XML is concatenated to the list of validators specified on the annotation.

You obtain aValidator by retrieving aValidatorFactory via one of the static methods onjavax.validation.Validation and callinggetValidator() on the factory instance.

Example 9.1, “Bootstrapping defaultValidatorFactory andValidator” shows how to obtain a validator from the defaultvalidator factory:

Jakarta Bean Validation supports working with several providers such as Hibernate Validator within oneapplication. If more than one provider is present on the classpath, it is not guaranteed which oneis chosen when creating a factory viabuildDefaultValidatorFactory().

In this case, you can explicitly specify the provider to use viaValidation#byProvider(), passing theprovider’sValidationProvider class as shown inExample 9.2, “BootstrappingValidatorFactory andValidator using a specific provider”.

Note that the configuration object returned byconfigure() allows to specifically customize thefactory before callingbuildValidatorFactory(). The available options are discussed later in thischapter.

Similarly you can retrieve the default validator factory for configuration which is demonstrated inExample 9.3, “Retrieving the defaultValidatorFactory for configuration”.

9.1.1.ValidationProviderResolver

package org.hibernate.validator.referenceguide.chapter09;public class OsgiServiceDiscoverer implements ValidationProviderResolver {    @Override    public List<ValidationProvider<?>> getValidationProviders() {        //...        return null;    }}

ValidatorFactory validatorFactory = Validation.byDefaultProvider()        .providerResolver( new OsgiServiceDiscoverer() )        .configure()        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

By default, validator factories retrieved fromValidation and any validators they create areconfigured as per the XML descriptorMETA-INF/validation.xml (seeChapter 8,Configuring via XML),if present.

If you want to disable the XML based configuration, you can do so by invokingConfiguration#ignoreXmlConfiguration().

The different values of the XML configuration can be accessed viaConfiguration#getBootstrapConfiguration(). This can for instance be helpful if you want to integrateJakarta Bean Validation into a managed environment and want to create managed instances of the objectsconfigured via XML.

Using the fluent configuration API, you can override one or more of the settings when bootstrappingthe factory. The following sections show how to make use of the different options. Note that theConfiguration class exposes the default implementations of the different extension points which canbe useful if you want to use these as delegates for your custom implementations.

9.2.1.MessageInterpolator

package org.hibernate.validator.referenceguide.chapter09;public class MyMessageInterpolator implements MessageInterpolator {    @Override    public String interpolate(String messageTemplate, Context context) {        //...        return null;    }    @Override    public String interpolate(String messageTemplate, Context context, Locale locale) {        //...        return null;    }}

ValidatorFactory validatorFactory = Validation.byDefaultProvider()        .configure()        .messageInterpolator( new MyMessageInterpolator() )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

9.2.2.TraversableResolver

package org.hibernate.validator.referenceguide.chapter09;public class MyTraversableResolver implements TraversableResolver {    @Override    public boolean isReachable(            Object traversableObject,            Node traversableProperty,            Class<?> rootBeanType,            Path pathToTraversableObject,            ElementType elementType) {        //...        return false;    }    @Override    public boolean isCascadable(            Object traversableObject,            Node traversableProperty,            Class<?> rootBeanType,            Path pathToTraversableObject,            ElementType elementType) {        //...        return false;    }}

ValidatorFactory validatorFactory = Validation.byDefaultProvider()        .configure()        .traversableResolver( new MyTraversableResolver() )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

<?xml version="1.0" encoding="UTF-8"?><validation-config        xmlns="http://xmlns.jcp.org/xml/ns/validation/configuration"        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"        xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/validation/configuration validation-configuration-2.0.xsd"        version="2.0">    <default-provider>org.hibernate.validator.HibernateValidator</default-provider>    <property name="hibernate.validator.enable_traversable_resolver_result_cache">false</property></validation-config>

ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )        .configure()        .traversableResolver( new MyFastTraversableResolver() )        .enableTraversableResolverResultCache( false )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

9.2.3.ConstraintValidatorFactory

package org.hibernate.validator.referenceguide.chapter09;public class MyConstraintValidatorFactory implements ConstraintValidatorFactory {    @Override    public <T extends ConstraintValidator<?, ?>> T getInstance(Class<T> key) {        //...        return null;    }    @Override    public void releaseInstance(ConstraintValidator<?, ?> instance) {        //...    }}

ValidatorFactory validatorFactory = Validation.byDefaultProvider()        .configure()        .constraintValidatorFactory( new MyConstraintValidatorFactory() )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

9.2.4.ParameterNameProvider

package org.hibernate.validator.referenceguide.chapter09;public class MyParameterNameProvider implements ParameterNameProvider {    @Override    public List<String> getParameterNames(Constructor<?> constructor) {        //...        return null;    }    @Override    public List<String> getParameterNames(Method method) {        //...        return null;    }}

ValidatorFactory validatorFactory = Validation.byDefaultProvider()        .configure()        .parameterNameProvider( new MyParameterNameProvider() )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

9.2.5.ClockProvider and temporal validation tolerance

package org.hibernate.validator.referenceguide.chapter09;public class FixedClockProvider implements ClockProvider {    private Clock clock;    public FixedClockProvider(ZonedDateTime dateTime) {        clock = Clock.fixed( dateTime.toInstant(), dateTime.getZone() );    }    @Override    public Clock getClock() {        return clock;    }}

ValidatorFactory validatorFactory = Validation.byDefaultProvider()        .configure()        .clockProvider( new FixedClockProvider( ZonedDateTime.of( 2016, 6, 15, 0, 0, 0, 0, ZoneId.of( "Europe/Paris" ) ) ) )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )        .configure()        .temporalValidationTolerance( Duration.ofMillis( 10 ) )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

9.2.6. RegisteringValueExtractors

ValidatorFactory validatorFactory = Validation.byDefaultProvider()        .configure()        .addValueExtractor( new MultimapKeyValueExtractor() )        .addValueExtractor( new MultimapValueValueExtractor() )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

9.2.7. Adding mapping streams

InputStream constraintMapping1 = null;InputStream constraintMapping2 = null;ValidatorFactory validatorFactory = Validation.byDefaultProvider()        .configure()        .addMapping( constraintMapping1 )        .addMapping( constraintMapping2 )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

9.2.8. Provider-specific settings

ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )        .configure()        .failFast( true )        .addMapping( (ConstraintMapping) null )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )        .configure()        .addProperty( "hibernate.validator.fail_fast", "true" )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

9.2.9. Configuring theScriptEvaluatorFactory

<validation-config        xmlns="http://xmlns.jcp.org/xml/ns/validation/configuration"        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"        xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/validation/configuration            http://xmlns.jcp.org/xml/ns/validation/configuration/validation-configuration-2.0.xsd"        version="2.0">    <property name="hibernate.validator.script_evaluator_factory">        org.hibernate.validator.referenceguide.chapter09.CustomScriptEvaluatorFactory    </property></validation-config>

ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )        .configure()        .scriptEvaluatorFactory( new CustomScriptEvaluatorFactory() )        .buildValidatorFactory();Validator validator = validatorFactory.getValidator();

/* * Hibernate Validator, declare and validate application constraints * * License: Apache License, Version 2.0 * See the license.txt file in the root directory or <http://www.apache.org/licenses/LICENSE-2.0>. */package org.hibernate.validator.osgi.scripting;import javax.script.ScriptEngine;import javax.script.ScriptEngineManager;import org.hibernate.validator.spi.scripting.AbstractCachingScriptEvaluatorFactory;import org.hibernate.validator.spi.scripting.ScriptEngineScriptEvaluator;import org.hibernate.validator.spi.scripting.ScriptEvaluationException;import org.hibernate.validator.spi.scripting.ScriptEvaluator;import org.hibernate.validator.spi.scripting.ScriptEvaluatorFactory;/** * {@link ScriptEvaluatorFactory} that allows you to pass multiple {@link ClassLoader}s that will be used * to search for {@link ScriptEngine}s. Useful in environments similar to OSGi, where script engines can be * found only in {@link ClassLoader}s different from default one. * * @author Marko Bekhta */public class MultiClassLoaderScriptEvaluatorFactory extends AbstractCachingScriptEvaluatorFactory {    private final ClassLoader[] classLoaders;    public MultiClassLoaderScriptEvaluatorFactory(ClassLoader... classLoaders) {        if ( classLoaders.length == 0 ) {            throw new IllegalArgumentException( "No class loaders were passed" );        }        this.classLoaders = classLoaders;    }    @Override    protected ScriptEvaluator createNewScriptEvaluator(String languageName) {        for ( ClassLoader classLoader : classLoaders ) {            ScriptEngine engine = new ScriptEngineManager( classLoader ).getEngineByName( languageName );            if ( engine != null ) {                return new ScriptEngineScriptEvaluator( engine );            }        }        throw new ScriptEvaluationException( "No JSR 223 script engine found for language " + languageName );    }}

Validator validator = Validation.byProvider( HibernateValidator.class )        .configure()        .scriptEvaluatorFactory(                new MultiClassLoaderScriptEvaluatorFactory( GroovyScriptEngineFactory.class.getClassLoader() )        )        .buildValidatorFactory()        .getValidator();

/* * Hibernate Validator, declare and validate application constraints * * License: Apache License, Version 2.0 * See the license.txt file in the root directory or <http://www.apache.org/licenses/LICENSE-2.0>. */package org.hibernate.validator.osgi.scripting;import java.io.BufferedReader;import java.io.IOException;import java.io.InputStreamReader;import java.net.URL;import java.util.Arrays;import java.util.Collections;import java.util.Enumeration;import java.util.List;import java.util.Objects;import java.util.stream.Collectors;import java.util.stream.Stream;import javax.script.ScriptEngineFactory;import javax.script.ScriptEngineManager;import javax.validation.ValidationException;import org.hibernate.validator.spi.scripting.AbstractCachingScriptEvaluatorFactory;import org.hibernate.validator.spi.scripting.ScriptEngineScriptEvaluator;import org.hibernate.validator.spi.scripting.ScriptEvaluator;import org.hibernate.validator.spi.scripting.ScriptEvaluatorFactory;import org.hibernate.validator.spi.scripting.ScriptEvaluatorNotFoundException;import org.osgi.framework.Bundle;import org.osgi.framework.BundleContext;/** * {@link ScriptEvaluatorFactory} suitable for OSGi environments. It is created * based on the {@code BundleContext} which is used to iterate through {@code Bundle}s and find all {@link ScriptEngineFactory} * candidates. * * @author Marko Bekhta */public class OsgiScriptEvaluatorFactory extends AbstractCachingScriptEvaluatorFactory {    private final List<ScriptEngineManager> scriptEngineManagers;    public OsgiScriptEvaluatorFactory(BundleContext context) {        this.scriptEngineManagers = Collections.unmodifiableList( findManagers( context ) );    }    @Override    protected ScriptEvaluator createNewScriptEvaluator(String languageName) throws ScriptEvaluatorNotFoundException {        return scriptEngineManagers.stream()                .map( manager -> manager.getEngineByName( languageName ) )                .filter( Objects::nonNull )                .map( engine -> new ScriptEngineScriptEvaluator( engine ) )                .findFirst()                .orElseThrow( () -> new ValidationException( String.format( "Unable to find script evaluator for '%s'.", languageName ) ) );    }    private List<ScriptEngineManager> findManagers(BundleContext context) {        return findFactoryCandidates( context ).stream()                .map( className -> {                    try {                        return new ScriptEngineManager( Class.forName( className ).getClassLoader() );                    }                    catch (ClassNotFoundException e) {                        throw new ValidationException( "Unable to instantiate '" + className + "' based engine factory manager.", e );                    }                } ).collect( Collectors.toList() );    }    /**     * Iterates through all bundles to get the available {@link ScriptEngineFactory} classes     *     * @return the names of the available ScriptEngineFactory classes     *     * @throws IOException     */    private List<String> findFactoryCandidates(BundleContext context) {        return Arrays.stream( context.getBundles() )                .filter( Objects::nonNull )                .filter( bundle -> !"system.bundle".equals( bundle.getSymbolicName() ) )                .flatMap( this::toStreamOfResourcesURL )                .filter( Objects::nonNull )                .flatMap( url -> toListOfFactoryCandidates( url ).stream() )                .collect( Collectors.toList() );    }    private Stream<URL> toStreamOfResourcesURL(Bundle bundle) {        Enumeration<URL> entries = bundle.findEntries(                "META-INF/services",                "javax.script.ScriptEngineFactory",                false        );        return entries != null ? Collections.list( entries ).stream() : Stream.empty();    }    private List<String> toListOfFactoryCandidates(URL url) {        try ( BufferedReader reader = new BufferedReader( new InputStreamReader( url.openStream(), "UTF-8" ) ) ) {            return reader.lines()                    .map( String::trim )                    .filter( line -> !line.isEmpty() )                    .filter( line -> !line.startsWith( "#" ) )                    .collect( Collectors.toList() );        }        catch (IOException e) {            throw new ValidationException( "Unable to read the ScriptEngineFactory resource file", e );        }    }}

Validator validator = Validation.byProvider( HibernateValidator.class )        .configure()        .scriptEvaluatorFactory(                new OsgiScriptEvaluatorFactory( FrameworkUtil.getBundle( this.getClass() ).getBundleContext() )        )        .buildValidatorFactory()        .getValidator();

package org.hibernate.validator.referenceguide.chapter09;public class SpringELScriptEvaluatorFactory extends AbstractCachingScriptEvaluatorFactory {    @Override    public ScriptEvaluator createNewScriptEvaluator(String languageName) {        if ( !"spring".equalsIgnoreCase( languageName ) ) {            throw new IllegalStateException( "Only Spring EL is supported" );        }        return new SpringELScriptEvaluator();    }    private static class SpringELScriptEvaluator implements ScriptEvaluator {        private final ExpressionParser expressionParser = new SpelExpressionParser();        @Override        public Object evaluate(String script, Map<String, Object> bindings) throws ScriptEvaluationException {            try {                Expression expression = expressionParser.parseExpression( script );                EvaluationContext context = new StandardEvaluationContext( bindings.values().iterator().next() );                for ( Entry<String, Object> binding : bindings.entrySet() ) {                    context.setVariable( binding.getKey(), binding.getValue() );                }                return expression.getValue( context );            }            catch (ParseException | EvaluationException e) {                throw new ScriptEvaluationException( "Unable to evaluate SpEL script", e );            }        }    }}

@ScriptAssert(script = "value > 0", lang = "spring")public class Foo {    private final int value;    private Foo(int value) {        this.value = value;    }    public int getValue() {        return value;    }}

When working with a configured validator factory it can occasionally be required to apply adifferent configuration to a singleValidator instance.Example 9.25, “Configuring aValidator instance viausingContext()” shows how this canbe achieved by callingValidatorFactory#usingContext().

The entry point into the metadata API is the methodValidator#getConstraintsForClass(), whichreturns an instance of theBeanDescriptor interface. Using thisdescriptor, you can obtain metadata for constraints declared directly on the bean itself (class- orproperty-level), but also retrieve metadata descriptors representing single properties, methods andconstructors.

Example 10.2, “UsingBeanDescriptor” demonstrates how to retrieve aBeanDescriptor for theCar class and how to use this descriptor in form of assertions.

You can determine whether the specified class hosts any class- or property-level constraints viaisBeanConstrained(). Method or constructor constraints are not considered byisBeanConstrained().

The methodgetConstraintDescriptors() is common to all descriptors derived fromElementDescriptor(seeSection 10.4, “ElementDescriptor”) and returns a set of descriptors representing theconstraints directly declared on the given element. In case ofBeanDescriptor, the bean’s class-level constraints are returned. More details onConstraintDescriptor can be found inSection 10.7, “ConstraintDescriptor”.

ViagetConstraintsForProperty(),getConstraintsForMethod() andgetConstraintsForConstructor() youcan obtain a descriptor representing one given property or executable element, identified by itsname and, in case of methods and constructors, parameter types. The different descriptor typesreturned by these methods are described in the following sections.

Note that these methods consider constraints declared at super-types according to the rules forconstraint inheritance as described inSection 2.1.5, “Constraint inheritance”. An example is thedescriptor for themanufacturer property, which provides access to all constraints defined onVehicle#getManufacturer() and the implementing methodCar#getManufacturer().null is returned incase the specified element does not exist or is not constrained.

The methodsgetConstrainedProperties(),getConstrainedMethods() andgetConstrainedConstructors()return (potentially empty) sets with all constrained properties, methods and constructors,respectively. An element is considered constrained if it has at least one constraint or is markedfor cascaded validation. When invokinggetConstrainedMethods(), you can specify the type of themethods to be returned (getters, non-getters or both).

The interfacePropertyDescriptor represents one given property of aclass. It is transparent whether constraints are declared on a field or a property getter, providedthe JavaBeans naming conventions are respected.Example 10.3, “UsingPropertyDescriptor” showshow to use thePropertyDescriptor interface.

UsinggetConstraintDescriptors(), you can retrieve a set ofConstraintDescriptors providing moreinformation on the individual constraints of a given property. The methodisCascaded() returnstrue if the property is marked for cascaded validation (either using the@Valid annotation or viaXML),false otherwise. Any configured group conversions are returned bygetGroupConversions(). SeeSection 10.6, “GroupConversionDescriptor” for more details onGroupConversionDescriptor.

Constrained methods and constructors are represented by the interfacesMethodDescriptorConstructorDescriptor, respectively.Example 10.4, “UsingMethodDescriptor andConstructorDescriptor” demonstrates how to work with thesedescriptors.

getName() returns the name of the given method or constructor. The methodshasConstrainedParameters() andhasConstrainedReturnValue() can be used to perform a quick checkwhether an executable element has any parameter constraints (either constraints on single parametersor cross-parameter constraints) or return value constraints.

Note that constraints are not directly exposed onMethodDescriptor andConstructorDescriptor,but rather on dedicated descriptors representing an executable’s parameters, its return value andits cross-parameter constraints. To get hold of one of these descriptors, invokegetParameterDescriptors(),getReturnValueDescriptor() orgetCrossParameterDescriptor(),respectively.

These descriptors provide access to the element’s constraints (getConstraintDescriptors()) and, inthe case of parameters and return value, to its configuration for cascaded validation (isValid() andgetGroupConversions()). For parameters, you also can retrieve the index and the name, as returned bythe currently used parameter name provider (seeSection 9.2.4, “ParameterNameProvider”) viagetName()andgetIndex().

TheElementDescriptorinterface is the common base class for theindividual descriptor types such asBeanDescriptor,PropertyDescriptor etc. BesidesgetConstraintDescriptors() it provides some more methods common to all descriptors.

hasConstraints() allows for a quick check whether an element has any direct constraints (e.g. class-level constraints in case ofBeanDescriptor).

getElementClass() returns the Java type of the elementrepresented by a given descriptor. More specifically, the method returns

• the object type when invoked onBeanDescriptor,

• the type of a property or parameter when invoked onPropertyDescriptor orParameterDescriptorrespectively,

• Object[].class when invoked onCrossParameterDescriptor,

• the return type when invoked onConstructorDescriptor,MethodDescriptor orReturnValueDescriptor.void.class will be returned for methods which don’t have a return value.

Example 10.5, “UsingElementDescriptor methods” shows how these methods are used.

Finally,ElementDescriptor offers access to theConstraintFinder API which allows you to query forconstraint metadata in a fine grained way.Example 10.6, “Usage ofConstraintFinder” shows how to retrieve aConstraintFinder instance viafindConstraints() and use the API to query for constraint metadata.

ViadeclaredOn() you can search forConstraintDescriptors declared on certain element types. This isuseful to find property constraints declared on either fields or getter methods.

unorderedAndMatchingGroups() restricts the resulting constraints to those matching the givenvalidation group(s).

lookingAt() allows to distinguish between constraints directly specified on the element(Scope.LOCAL_ELEMENT) or constraints belonging to the element but hosted anywhere in the classhierarchy (Scope.HIERARCHY).

You can also combine the different options as shown in the last example.

TheContainerDescriptorinterface is the common interface for all the elements that support container element constraints and cascadingvalidation (PropertyDescriptor,ParameterDescriptor,ReturnValueDescriptor).

It has a single methodgetConstrainedContainerElementTypes() that returns a set ofContainerElementTypeDescriptor.

ContainerElementTypeDescriptor extendsContainerDescriptor to support nested container element constraints.

ContainerElementTypeDescriptor contains the information about the container, the constraints and the cascadingvalidation.

Example 10.7, “UsingContainerElementTypeDescriptor” shows how to usegetConstrainedContainerElementTypes()to retrieve the set ofContainerElementTypeDescriptor.

All those descriptor types that represent elements which can be subject of cascaded validation(i.e.,PropertyDescriptor,ParameterDescriptor andReturnValueDescriptor) provide access to theelement’s group conversions viagetGroupConversions(). The returned set contains aGroupConversionDescriptorfor each configured conversion, allowing to retrievesource and target groups of the conversion.Example 10.8, “UsingGroupConversionDescriptor”shows an example.

Last but not least, theConstraintDescriptorinterface describes asingle constraint together with its composing constraints. Via an instance of this interface you getaccess to the constraint annotation and its parameters.

Example 10.9, “UsingConstraintDescriptor”shows how to retrieve default constraint attributes (such as message template, groups etc.) as wellas custom constraint attributes (piecesOfLuggagePerPassenger) and other metadata such as theconstraint’s annotation type and its validators from aConstraintDescriptor.

Hibernate Validator integrates with both Hibernate ORM and all pure Java Persistence providers.

11.1.1. Database schema-level validation

11.1.2. Hibernate ORM event-based validation

<hibernate-configuration>    <session-factory>        ...        <property name="javax.persistence.validation.group.pre-persist">            javax.validation.groups.Default        </property>        <property name="javax.persistence.validation.group.pre-update">            javax.validation.groups.Default        </property>        <property name="javax.persistence.validation.group.pre-remove"></property>        ...        <event type="pre-update">            <listener/>        </event>        <event type="pre-insert">            <listener/>        </event>        <event type="pre-delete">            <listener/>        </event>    </session-factory></hibernate-configuration>

11.1.3. JPA

When working with JSF2 or JBoss Seam and Hibernate Validator (Jakarta Bean Validation) is present in theruntime environment, validation is triggered for every field in the application.Example 11.2, “Usage of Jakarta Bean Validation within JSF2”shows an example of thef:validateBean tag in a JSF page. ThevalidationGroups attribute is optionaland can be used to specify a comma separated list of validation groups. The default isjavax.validation.groups.Default. For more information refer to the Seam documentation or the JSF 2specification.

As of version 1.1, Bean Validation (and therefore Jakarta Bean Validation) is integrated with CDI(Contexts and Dependency Injection for Jakarta EE).

This integration provides CDI managed beans forValidator andValidatorFactory and enablesdependency injection in constraint validators as well as custom message interpolators, traversableresolvers, constraint validator factories, parameter name providers, clock providers and valueextractors.

Furthermore, parameter and return value constraints on the methods and constructors of CDI managedbeans will automatically be validated upon invocation.

When your application runs on a Java EE container, this integration is enabled by default. Whenworking with CDI in a Servlet container or in a pure Java SE environment, you can use the CDIportable extension provided by Hibernate Validator. To do so, add the portable extension to yourclass path as described inSection 1.1.2, “CDI”.

11.3.1. Dependency injection

package org.hibernate.validator.referenceguide.chapter11.cdi.validator;@ApplicationScopedpublic class RentalStation {    @Inject    private ValidatorFactory validatorFactory;    @Inject    private Validator validator;    //...}

package org.hibernate.validator.referenceguide.chapter11.cdi.validator.qualifier;@ApplicationScopedpublic class RentalStation {    @Inject    @HibernateValidator    private ValidatorFactory validatorFactory;    @Inject    @HibernateValidator    private Validator validator;    //...}

package org.hibernate.validator.referenceguide.chapter11.cdi.injection;public class ValidLicensePlateValidator        implements ConstraintValidator<ValidLicensePlate, String> {    @Inject    private VehicleRegistry vehicleRegistry;    @PostConstruct    public void postConstruct() {        //do initialization logic...    }    @PreDestroy    public void preDestroy() {        //do destruction logic...    }    @Override    public void initialize(ValidLicensePlate constraintAnnotation) {    }    @Override    public boolean isValid(String licensePlate, ConstraintValidatorContext constraintContext) {        return vehicleRegistry.isValidLicensePlate( licensePlate );    }}

11.3.2. Method validation

package org.hibernate.validator.referenceguide.chapter11.cdi.methodvalidation;@ApplicationScopedpublic class RentalStation {    @Valid    public RentalStation() {        //...    }    @NotNull    @Valid    public Car rentCar(            @NotNull Customer customer,            @NotNull @Future Date startDate,            @Min(1) int durationInDays) {        //...        return null;    }    @NotNull    List<Car> getAvailableCars() {        //...        return null;    }}

package org.hibernate.validator.referenceguide.chapter11.cdi.methodvalidation;@RequestScopedpublic class RentCarRequest {    @Inject    private RentalStation rentalStation;    public void rentCar(String customerId, Date startDate, int duration) {        //causes ConstraintViolationException        rentalStation.rentCar( null, null, -1 );    }}

package org.hibernate.validator.referenceguide.chapter11.cdi.methodvalidation.configuration;@ApplicationScoped@ValidateOnExecution(type = ExecutableType.ALL)public class RentalStation {    @Valid    public RentalStation() {        //...    }    @NotNull    @Valid    @ValidateOnExecution(type = ExecutableType.NONE)    public Car rentCar(            @NotNull Customer customer,            @NotNull @Future Date startDate,            @Min(1) int durationInDays) {        //...        return null;    }    @NotNull    public List<Car> getAvailableCars() {        //...        return null;    }}

package org.hibernate.validator.referenceguide.chapter11.cdi.methodvalidation.implicit;@ValidateOnExecution(type = ExecutableType.ALL)public interface RentalStation {    @NotNull    @Valid    Car rentCar(            @NotNull Customer customer,            @NotNull @Future Date startDate,            @Min(1) int durationInDays);    @NotNull    List<Car> getAvailableCars();}

package org.hibernate.validator.referenceguide.chapter11.cdi.methodvalidation.implicit;@ApplicationScoped@ValidateOnExecution(type = ExecutableType.IMPLICIT)public class ExpressRentalStation implements RentalStation {    @Override    public Car rentCar(Customer customer, Date startDate, @Min(1) int durationInDays) {        //...        return null;    }    @Override    public List<Car> getAvailableCars() {        //...        return null;    }}

When your application runs on a Java EE application server such asWildFly,you also can obtainValidator andValidatorFactory instances via@Resource injection inmanaged objects such as EJBs etc., as shown inExample 11.9, “RetrievingValidator andValidatorFactory via@Resource injection”.

Alternatively you can obtain a validator and a validator factory from JNDI under the names"java:comp/Validator" and "java:comp/ValidatorFactory", respectively.

Similar to CDI-based injection via@Inject, these objects represent default validator and validatorfactory and thus can be configured using the XML descriptorMETA-INF/validation.xml (seeChapter 8,Configuring via XML).

When your application is CDI-enabled, the injected objects are CDI-aware as well and e.g. supportdependency injection in constraint validators.

Hibernate Validator also provides support for the unwrapping of JavaFX properties. If JavaFX is presenton the classpath,ValueExtractors for JavaFX properties are automatically registered.SeeSection 7.4, “JavaFX value extractors” for examples and further discussion.

Let’s start, however, with a look at the public API of Hibernate Validator. Below you can find a list of all packages belonging to this API and their purpose.Note that when a package is part of the public API this is not necessarily true for its sub-packages.

org.hibernate.validator

Classes used by the Jakarta Bean Validation bootstrap mechanism (eg. validation provider, configuration class); for more details seeChapter 9,Bootstrapping.

org.hibernate.validator.cfg,org.hibernate.validator.cfg.context,org.hibernate.validator.cfg.defs,org.hibernate.validator.spi.cfg

Hibernate Validator’s fluent API for constraint declaration; inorg.hibernate.validator.cfg you will find theConstraintMapping interface, inorg.hibernate.validator.cfg.defs all constraint definitions and inorg.hibernate.validator.spi.cfg a callback for using the API for configuring the default validator factory. Refer toSection 12.4, “Programmatic constraint definition and declaration” for the details.

org.hibernate.validator.constraints,org.hibernate.validator.constraints.br,org.hibernate.validator.constraints.pl

Some useful custom constraints provided by Hibernate Validator in addition to the built-in constraints defined by the Jakarta Bean Validation specification; the constraints are described in detail inSection 2.3.2, “Additional constraints”.

org.hibernate.validator.constraintvalidation

Extended constraint validator context which allows to set custom attributes for message interpolation.Section 12.13.1, “HibernateConstraintValidatorContext” describes how to make use of that feature.

org.hibernate.validator.group,org.hibernate.validator.spi.group

The group sequence provider feature which allows you to define dynamic default group sequences in function of the validated object state; the specifics can be found inSection 5.4, “Redefining the default group sequence”.

org.hibernate.validator.messageinterpolation,org.hibernate.validator.resourceloading,org.hibernate.validator.spi.resourceloading

Classes related to constraint message interpolation; the first package contains Hibernate Validator’s default message interpolator,ResourceBundleMessageInterpolator. The latter two packages provide theResourceBundleLocator SPI for the loading of resource bundles (seeSection 4.2.1, “ResourceBundleLocator”) and its default implementation.

org.hibernate.validator.parameternameprovider

AParameterNameProvider based on the Paranamer library, seeSection 12.14, “Paranamer basedParameterNameProvider”.

org.hibernate.validator.propertypath

Extensions to thejavax.validation.Path API, seeSection 12.7, “Extensions of the Path API”.

org.hibernate.validator.spi.constraintdefinition

An SPI for registering additional constraint validators programmatically, seeSection 12.15, “Providing constraint definitions”.

org.hibernate.validator.spi.messageinterpolation

An SPI that can be used to tweak the resolution of the locale when interpolating the constraint violation messages. SeeSection 12.12, “Customizing the locale resolution”.

org.hibernate.validator.spi.nodenameprovider

An SPI that can be used to alter how the names of properties will be resolved when the property path is constructed. SeeSection 12.18, “Customizing the property name resolution for constraint violations”.

Any packages not listed in that table are internal packages of Hibernate Validator and are notintended to be accessed by clients. The contents of these internal packages can change from releaseto release without notice, thus possibly breaking any client code relying on it.

Using the fail fast mode, Hibernate Validator allows to return from the current validation as soonas the first constraint violation occurs. This can be useful for the validation of large objectgraphs where you are only interested in a quick check whether there is any constraint violation atall.

Example 12.1, “Using the fail fast validation mode” shows how to bootstrap and use a fail fast enabled validator.

Here the validated object actually fails to satisfy both the constraints declared on theCar class,yet the validation call yields only oneConstraintViolation since the fail fast mode is enabled.

Refer toSection 9.2.8, “Provider-specific settings” to learn about the different ways of enabling thefail fast mode when bootstrapping a validator.

The Jakarta Bean Validation specification defines a set of preconditions which apply when definingconstraints on methods within class hierarchies. These preconditions are defined insection 5.6.5of the Jakarta Bean Validation 2.0 specification. See alsoSection 3.1.4, “Method constraints in inheritance hierarchies”in this guide.

As per specification, a Jakarta Bean Validation provider is allowed to relax these preconditions.With Hibernate Validator you can do this in one of two ways.

First you can use the configuration propertieshibernate.validator.allow_parameter_constraint_override,hibernate.validator.allow_multiple_cascaded_validation_on_result andhibernate.validator.allow_parallel_method_parameter_constraint invalidation.xml. See exampleExample 12.2, “Configuring method validation behaviour in class hierarchies via properties”.

Alternatively these settings can be applied during programmatic bootstrapping.

By default, all of these properties are false, implementing the default behavior as defined in theJakarta Bean Validation specification.

As per the Jakarta Bean Validation specification, you can define and declare constraints using Java annotations and XMLbased constraint mappings.

In addition, Hibernate Validator provides a fluent API which allows for the programmaticconfiguration of constraints. Use cases include the dynamic addition of constraints at runtimedepending on some application state or tests where you need entities with different constraints indifferent scenarios but don’t want to implement actual Java classes for each test case.

By default, constraints added via the fluent API are additive to constraints configured via thestandard configuration capabilities. But it is also possible to ignore annotation and XML configuredconstraints where required.

The API is centered around theConstraintMapping interface. You obtain a new mapping viaHibernateValidatorConfiguration#createConstraintMapping() which you then can configure in a fluentmanner as shown inExample 12.4, “Programmatic constraint declaration”.

Constraints can be configured on multiple classes and properties using method chaining. Theconstraint definition classesNotNullDef andSizeDef are helper classes which allow to configureconstraint parameters in a type-safe fashion. Definition classes exist for all built-in constraintsin theorg.hibernate.validator.cfg.defs package. By callingignoreAnnotations() any constraintsconfigured via annotations or XML are ignored for the given element.

Having configured the mapping, you must add it back to the configuration object from which you thencan obtain a validator factory.

For custom constraints, you can either create your own definition classes extendingConstraintDef oryou can useGenericConstraintDef as seen inExample 12.5, “Programmatic declaration of a custom constraint”.

Container element constraints are supported by the programmatic API, usingcontainerElementType().

Example 12.6, “Programmatic declaration of a nested container element constraint” show an example where constraints are declared onnested container elements.

As demonstrated, the parameters passed tocontainerElementType() are the path of type argumentindexes used to obtain the desired nested container element type.

By invokingvalid() you can mark a member for cascaded validation which is equivalent to annotatingit with@Valid. Configure any group conversions to be applied during cascaded validation using theconvertGroup() method (equivalent to@ConvertGroup). An example can be seen inExample 12.7, “Marking a property for cascaded validation”.

You can not only configure bean constraints using the fluent API but also method and constructorconstraints. As shown inExample 12.8, “Programmatic declaration of method and constructor constraints” constructors are identified by theirparameter types and methods by their name and parameter types. Having selected a method orconstructor, you can mark its parameters and/or return value for cascaded validation and addconstraints as well as cross-parameter constraints.

As shown in the example,valid() can be also invoked on a container element type.

Last but not least you can configure the default group sequence or the default group sequenceprovider of a type as shown in the following example.

If you are not bootstrapping a validator factory manuallybut work with the default factory as configured viaMETA-INF/validation.xml(seeChapter 8,Configuring via XML),you can add one or more constraint mappings by creating one or several constraint mapping contributors.To do so, implement theConstraintMappingContributor contract:

You then need to specify the fully-qualified class name of the contributor implementation inMETA-INF/validation.xml,using the property keyhibernate.validator.constraint_mapping_contributors. You can specify severalcontributors by separating them with a comma.

12.6.1. Validation target specification for purely composed constraints

package org.hibernate.validator.referenceguide.chapter12.purelycomposed;@Min(value = 0)@NotNull@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })@Retention(RUNTIME)@Documented@Constraint(validatedBy = {})@SupportedValidationTarget(ValidationTarget.ANNOTATED_ELEMENT)@ReportAsSingleViolationpublic @interface ValidInvoiceAmount {    String message() default "{org.hibernate.validator.referenceguide.chapter11.purelycomposed."            + "ValidInvoiceAmount.message}";    Class<?>[] groups() default {};    Class<? extends Payload>[] payload() default {};    @OverridesAttribute(constraint = Min.class, name = "value")    long value();}

12.6.2. Boolean composition of constraints

package org.hibernate.validator.referenceguide.chapter12.booleancomposition;@ConstraintComposition(OR)@Pattern(regexp = "[a-z]")@Size(min = 2, max = 3)@ReportAsSingleViolation@Target({ METHOD, FIELD })@Retention(RUNTIME)@Constraint(validatedBy = { })public @interface PatternOrSize {    String message() default "{org.hibernate.validator.referenceguide.chapter11." +            "booleancomposition.PatternOrSize.message}";    Class<?>[] groups() default { };    Class<? extends Payload>[] payload() default { };}

Hibernate Validator provides an extension to thejavax.validation.Path API.For nodes ofElementKind.PROPERTY andElementKind.CONTAINER_ELEMENT it allows to obtain the value of therepresented property.To do so, narrow down a given node to the typeorg.hibernate.validator.path.PropertyNode ororg.hibernate.validator.path.ContainerElementNode respectively usingNode#as(), asshown in the following example:

This is also very useful to obtain the element ofSet properties on the property path (e.g.apartmentsin the example) which otherwise could not be identified (unlike forMap andList, there is no key nor indexin this case).

In some cases automatic processing of violations can be aided, if the constraint violation provides additionaldata - a so called dynamic payload. This dynamic payload could for example contain hints to the user on how toresolve the violation.

Dynamic payloads can be set incustom constraints usingHibernateConstraintValidatorContext.This is shown in exampleExample 12.14, “ConstraintValidator implementation setting a dynamic payload” where thejavax.validation.ConstraintValidatorContext is unwrapped toHibernateConstraintValidatorContext in order to callwithDynamicPayload.

On the constraint violation processing side, ajavax.validation.ConstraintViolation can then in turn beunwrapped toHibernateConstraintViolation in order to retrieve the dynamic payload for further processing.

Hibernate Validator restricts the Expression Language features exposed by default.

For this purpose, we define several feature levels inExpressionLanguageFeatureLevel:

• NONE: Expression Language interpolation is fully disabled.

• VARIABLES: Allow interpolation of the variables injected viaaddExpressionVariable(), resources bundles and usage of theformatter object.

• BEAN_PROPERTIES: Allow everythingVARIABLES allows plus the interpolation of bean properties.

• BEAN_METHODS: Also allow execution of bean methods. This can lead to serious security issues, including arbitrary code execution if not carefully handled.

Depending on the context, the features we expose are different:

• For constraints, the default level isBEAN_PROPERTIES.For all the built-in constraint messages to be correctly interpolated, you need at least theVARIABLES level.

• For custom violations, created via theConstraintValidatorContext, Expression Language is disabled by default.You can enable it for specific custom violations and, when enabled, it will default toVARIABLES.

Hibernate Validator provides ways to override these defaults when boostrapping theValidatorFactory.

To change the Expression Language feature level for constraints, use the following:

To change the Expression Language feature level for custom violations, use the following:

These levels can also be defined using the following properties:

• hibernate.validator.constraint_expression_language_feature_level

• hibernate.validator.custom_violation_expression_language_feature_level

Accepted values for these properties are:none,variables,bean-properties andbean-methods.

Hibernate Validator requires per default an implementation of the Unified EL (seeSection 1.1.1, “Unified EL”) to be available. This is needed to allow the interpolationof constraint error messages using EL expressions as defined by the Jakarta Bean Validation specification.

For environments where you cannot or do not want to provide an EL implementation, Hibernate Validatoroffers a non EL based message interpolator -org.hibernate.validator.messageinterpolation.ParameterMessageInterpolator.

Refer toSection 4.2, “Custom message interpolation” to see how to plug in custom message interpolatorimplementations.

WithResourceBundleLocator, Hibernate Validator provides an additional SPI which allows to retrieveerror messages from other resource bundles thanValidationMessages while still using the actualinterpolation algorithm as defined by the specification. Refer toSection 4.2.1, “ResourceBundleLocator” to learn how to make use of that SPI.

Hibernate Validator provides several extension points to build a custom locale resolution strategy.The resolved locale is used when interpolating the constraint violation messages.

The default behavior of Hibernate Validator is to always use the system default locale (as obtained viaLocale.getDefault()).This might not be the desired behavior if, for example, you usually set your system locale toen-US but want your application to provide messages in French.

The following example shows how to set the Hibernate Validator default locale tofr-FR:

While this is already a nice improvement, in a fully internationalized application, this is not sufficient:you need Hibernate Validator to select the locale depending on the user context.

Hibernate Validator provides theorg.hibernate.validator.spi.messageinterpolation.LocaleResolver SPIwhich allows to fine-tune the resolution of the locale.Typically, in a JAX-RS environment, you can resolve the locale to use from theAccept-Language HTTP header.

In the following example, we use a hardcoded value but, for instance, in the case of a RESTEasy application,you could extract the header from theResteasyContext.

The Jakarta Bean Validation specification offers at several points in its API the possibility to unwrap agiven interface to an implementor specific subtype. In the case of constraint violation creation inConstraintValidator implementations as well as message interpolation inMessageInterpolatorinstances, there existunwrap() methods for the provided context instances -ConstraintValidatorContext respectivelyMessageInterpolatorContext. Hibernate Validator providescustom extensions for both of these interfaces.

12.13.1.HibernateConstraintValidatorContext

public class SafeValidator implements ConstraintValidator<ZipCode, String> {    @Override    public boolean isValid(String value, ConstraintValidatorContext context) {        if ( value == null ) {            return true;        }        HibernateConstraintValidatorContext hibernateContext = context.unwrap(                HibernateConstraintValidatorContext.class );        hibernateContext.disableDefaultConstraintViolation();        if ( isInvalid( value ) ) {            hibernateContext                    .addExpressionVariable( "validatedValue", value )                    .buildConstraintViolationWithTemplate( "${validatedValue} is not a valid ZIP code" )                    .enableExpressionLanguage()                    .addConstraintViolation();            return false;        }        return true;    }    private boolean isInvalid(String value) {        // ...        return false;    }}

public class UnsafeValidator implements ConstraintValidator<ZipCode, String> {    @Override    public boolean isValid(String value, ConstraintValidatorContext context) {        if ( value == null ) {            return true;        }        context.disableDefaultConstraintViolation();        HibernateConstraintValidatorContext hibernateContext = context.unwrap(                HibernateConstraintValidatorContext.class );        hibernateContext.disableDefaultConstraintViolation();        if ( isInvalid( value ) ) {            hibernateContext                    // THIS IS UNSAFE, DO NOT COPY THIS EXAMPLE                    .buildConstraintViolationWithTemplate( value + " is not a valid ZIP code" )                    .enableExpressionLanguage()                    .addConstraintViolation();            return false;        }        return true;    }    private boolean isInvalid(String value) {        // ...        return false;    }}

12.13.2.HibernateMessageInterpolatorContext

public interface HibernateMessageInterpolatorContext extends MessageInterpolator.Context {    /**     * Returns the currently validated root bean type.     *     * @return The currently validated root bean type.     */    Class<?> getRootBeanType();    /**     * @return the message parameters added to this context for interpolation     *     * @since 5.4.1     */    Map<String, Object> getMessageParameters();    /**     * @return the expression variables added to this context for EL interpolation     *     * @since 5.4.1     */    Map<String, Object> getExpressionVariables();    /**     * @return the path to the validated constraint starting from the root bean     *     * @since 6.1     */    Path getPropertyPath();    /**     * @return the level of features enabled for the Expression Language engine     *     * @since 6.2     */    ExpressionLanguageFeatureLevel getExpressionLanguageFeatureLevel();}

Hibernate Validator comes with aParameterNameProvider implementation which leverages theParanamer library.

This library provides several ways for obtaining parameter names at runtime, e.g. based on debugsymbols created by the Java compiler, constants with the parameter names woven into the bytecode ina post-compile step or annotations such as the@Named annotation from JSR 330.

In order to useParanamerParameterNameProvider, either pass an instance when bootstrapping avalidator as shown inExample 9.10, “Using a customParameterNameProvider” or specifyorg.hibernate.validator.parameternameprovider.ParanamerParameterNameProvider as value for the<parameter-name-provider> element in theMETA-INF/validation.xml file.

By defaultParanamerParameterNameProvider retrieves parameter names from constants added to the bytecode at build time (viaDefaultParanamer) and debug symbols (viaBytecodeReadingParanamer).Alternatively you can specify aParanamer implementation of your choice when creating aParanamerParameterNameProvider instance.

Jakarta Bean Validation allows to (re-)define constraint definitions via XML in its constraint mappingfiles. SeeSection 8.2, “Mapping constraints viaconstraint-mappings” for more information andExample 8.2, “Bean constraints configured via XML”for an example. While this approach is sufficient for many use cases, it has its shortcomingsin others. Imagine for example a constraint library wanting to contribute constraintdefinitions for custom types. This library could provide a mapping file with their library, but thisfile still would need to be referenced by the user of the library. Luckily there are better ways.

12.15.1. Constraint definitions viaServiceLoader

# Assuming a custom constraint annotation @org.mycompany.CheckCaseorg.mycompany.CheckCaseValidator

12.15.2. Adding constraint definitions programmatically

ConstraintMapping constraintMapping = configuration.createConstraintMapping();constraintMapping        .constraintDefinition( ValidPassengerCount.class )        .validatedBy( ValidPassengerCountValidator.class );

ConstraintMapping constraintMapping = configuration.createConstraintMapping();constraintMapping        .constraintDefinition( ValidPassengerCount.class )            .validateType( Bus.class )                .with( b -> b.getSeatCount() >= b.getPassengers().size() );

ConstraintMapping constraintMapping = configuration.createConstraintMapping();constraintMapping        .constraintDefinition( URL.class )        .includeExistingValidators( false )        .validatedBy( RegexpURLValidator.class );

There are several cases in which Hibernate Validator needs to load resources or classes given by name:

• XML descriptors (META-INF/validation.xml as well as XML constraint mappings)

• classes specified by name in XML descriptors (e.g. custom message interpolators etc.)

• theValidationMessages resource bundle

• theExpressionFactory implementation used for expression based message interpolation

By default, Hibernate Validator tries to load these resources via the current thread context class loader.If that’s not successful, Hibernate Validator’s own class loader will be tried as a fallback.

For cases where this strategy is not appropriate (e.g. modularized environments such as OSGi),you may provide a specific class loader for loading these resources when bootstrapping the validator factory:

In the case of OSGi, you could e.g. pass the loader of a class from the bundle bootstrapping Hibernate Validatoror a custom class loader implementation which delegates toBundle#loadClass() etc.

When a bean is validated by Hibernate Validator, its properties get validated. A property can eitherbe a field or a getter.By default, Hibernate Validator respects the JavaBeans specification and considers a method as a getter as soonas one of the conditions below is true:

• the method name starts withget, it has a non-void return type and has no parameters;

• the method name starts withis, has a return type ofboolean and has no parameters;

• the method name starts withhas, has a return type ofboolean and has no parameters (this ruleis specific to Hibernate Validator and is not mandated by the JavaBeans specification)

While these rules are usually appropriate when following the classic JavaBeans convention, it might happen,especially with code generators, that the JavaBeans naming convention is not followed and that the getters'names are following a different convention.

In this case, the strategy for detecting getters should be redefined in order to fully validate the object.

A classic example of this requirement is when the classes follow a fluent naming convention,as illustrated inExample 12.23, “A class that uses non-standard getters”.

If such object gets validated, no validation will be performed on the getters as they are not detectedby the standard strategy.

To make Hibernate Validator treat such methods as properties, a customGetterPropertySelectionStrategyshould be configured.In this particular case, a possible implementation of the strategy would be:

There are multiple ways to configure Hibernate Validator to use this strategy. It can either be doneprogrammatically (seeExample 12.26, “Configuring a customGetterPropertySelectionStrategy programmatically”) or by using thehibernate.validator.getter_property_selection_strategy property in the XML configuration(seeExample 12.27, “Configuring a customGetterPropertySelectionStrategy using an XML property”).

Imagine that we have a simple data class that has@NotNull constraints on some fields:

This class can be serialized to JSON by using theJackson library:

As we can see, the object is serialized to:

Notice how the names of the properties differ. In the Java object, we havefirstName andlastName, whereas in the JSON output, we havefirst_name andlast_name.We customized this behavior through@JsonProperty annotations.

Now imagine that we use this class in a REST environment, where a user can sendaPerson instance as JSON in the request body.It would be nice, when indicating on which field the validation failed, to indicate the name they use in their JSON request,first_name,and not the name we use internally in our Java code,firstName.

Theorg.hibernate.validator.spi.nodenameprovider.PropertyNodeNameProvider contract allows us to do this.By implementing it, we can define how the name of a property will be resolved during validation.In our case, we want to read the value from the Jackson configuration.

One example of how to do this is to leverage the Jackson API:

And when doing the validation:

We can see that the property path now returnsfirst_name.

Note that this also works when the annotations are on a getter:

This is just one use case of why we would like to change how the property names are resolved.

org.hibernate.validator.spi.nodenameprovider.PropertyNodeNameProvider can be implemented to provide a property name inwhatever way you see fit (reading from annotations, for instance).

There are two more interfaces that are worth mentioning:

• org.hibernate.validator.spi.nodenameprovider.Property is a base interface that holds metadata about a property. Ithas a singleString getName() method that can be used to get the "original" name of a property. This interfaceshould be used as a default way of resolving the name (see how it is used inExample 12.31, “JacksonPropertyNodeNameProvider implementation”).

• org.hibernate.validator.spi.nodenameprovider.JavaBeanProperty is an interface that holds metadata about a bean property. Itextendsorg.hibernate.validator.spi.nodenameprovider.Property and provide some additional methods likeClass<?> getDeclaringClass()which returns the class that is the owner of the property.

The Hibernate Validator Annotation Processor is based on the "Pluggable Annotation Processing API"as defined byJSR 269 which is part of the JavaPlatform.

As of Hibernate Validator 6.2.5.Final the Hibernate Validator Annotation Processor checks that:

• constraint annotations are allowed for the type of the annotated element

• only non-static fields or methods are annotated with constraint annotations

• only non-primitive fields or methods are annotated with@Valid

• only such methods are annotated with constraint annotations which are valid JavaBeansgetter methods (optionally, see below)

• only such annotation types are annotated with constraint annotations which are constraintannotations themselves

• definition of dynamic default group sequence with@GroupSequenceProvider is valid

• annotation parameter values are meaningful and valid

• method parameter constraints in inheritance hierarchies respect the inheritance rules

• method return value constraints in inheritance hierarchies respect the inheritance rules

The behavior of the Hibernate Validator Annotation Processor can be controlled using the followingprocessor options:

diagnosticKind

Controls how constraint problems are reported. Must be thestring representation of one of the values from the enumjavax.tools.Diagnostic.Kind,e.g.WARNING. A value ofERROR will cause compilation to halt whenever the AP detectsa constraint problem. Defaults toERROR.

methodConstraintsSupported

Controls whether constraints are allowed at methods of anykind. Must be set totrue when working with method level constraints as supported byHibernate Validator. Can be set tofalse to allow constraints only atJavaBeans getter methods as defined by the Jakarta Bean Validation API. Defaults totrue.

verbose

Controls whether detailed processing information shall bedisplayed or not, useful for debugging purposes. Must be eithertrue orfalse. Defaults tofalse.

This section shows in detail how to integrate the Hibernate Validator Annotation Processor intocommand line builds (Maven, Ant, javac) as well as IDE-based builds (Eclipse, IntelliJ IDEA,NetBeans).

13.4.1. Command line builds

<project>    [...]    <build>        [...]        <plugins>            [...]            <plugin>                <groupId>org.apache.maven.plugins</groupId>                <artifactId>maven-compiler-plugin</artifactId>                <version>3.6.1</version>                <configuration>                    <source>1.8</source>                    <target>1.8</target>                    <annotationProcessorPaths>                        <path>                            <groupId>org.hibernate.validator</groupId>                            <artifactId>hibernate-validator-annotation-processor</artifactId>                            <version>6.2.5.Final</version>                        </path>                    </annotationProcessorPaths>                </configuration>            </plugin>            [...]        </plugins>        [...]    </build>    [...]</project>

dependencies {    annotationProcessor group: 'org.hibernate.validator', name: 'hibernate-validator-annotation-processor', version: '6.2.5.Final'    // any other dependencies ...}

<javac srcdir="src/main"       destdir="build/classes"       classpath="/path/to/validation-api-2.0.2.jar">       <compilerarg value="-processorpath" />       <compilerarg value="/path/to/hibernate-validator-annotation-processor-6.2.5.Final.jar"/></javac>

javac src/main/java/org/hibernate/validator/ap/demo/Car.java \   -cp /path/to/validation-api-2.0.2.jar \   -processorpath /path/to/hibernate-validator-annotation-processor-6.2.5.Final.jar

13.4.2. IDE builds

13.4.2.1. Eclipse

The annotation processor will automatically be set up for Maven projects configured as described above,provided you have theM2E Eclipse plug-in installed.

For plain Eclipse projects follow these steps to set up the annotation processor:

• Right-click your project, choose "Properties"

• Go to "Java Compiler" and make sure, that "Compiler compliance level" is set to "1.8".Otherwise the processor won’t be activated

• Go to "Java Compiler - Annotation Processing" and choose "Enable annotation processing"

• Go to "Java Compiler - Annotation Processing - Factory Path" and add the JARhibernate-validator-annotation-processor-6.2.5.Final.jar

• Confirm the workspace rebuild

You now should see any annotation problems as regular error markers within the editor and in the"Problem" view:

13.4.2.2. IntelliJ IDEA

The following steps must be followed to use the annotation processor withinIntelliJ IDEA (version 9 and above):

• Go to "File", then "Settings",

• Expand the node "Compiler", then "Annotation Processors"

• Choose "Enable annotation processing" and enter the following as "Processor path":/path/to/hibernate-validator-annotation-processor-6.2.5.Final.jar

• Add the processor’s fully qualified name org.hibernate.validator.ap.ConstraintValidationProcessorto the "Annotation Processors" list

• If applicable add you module to the "Processed Modules" list

Rebuilding your project then should show any erroneous constraint annotations:

13.4.2.3. NetBeans

TheNetBeans IDE supports usingannotation processors within the IDE build. To do so, do the following:

• Right-click your project, choose "Properties"

• Go to "Libraries", tab "Processor", and add the JAR hibernate-validator-annotation-processor-6.2.5.Final.jar

• Go to "Build - Compiling", select "Enable Annotation Processing" and "Enable Annotation Processingin Editor". Add the annotation processor by specifying its fully qualified nameorg.hibernate.validator.ap.ConstraintValidationProcessor

Any constraint annotation problems will then be marked directly within the editor:

The following known issues exist as of July 2017:

• Container element constraints are not supported for now.

• Constraints applied to a container but in reality applied to the container elements (be it viatheUnwrapping.Unwrap payload or via a value extractor marked with@UnwrapByDefault) are not supportedcorrectly.

• HV-308: Additional validatorsregistered for a constraintusing XML arenot evaluated by the annotation processor.

• Sometimes custom constraints can’t beproperly evaluated whenusing the processor within Eclipse. Cleaning the project can help in these situations. This seems tobe an issue with the Eclipse JSR 269 API implementation, but further investigation is required here.

• When using the processor within Eclipse, the check of dynamic default group sequence definitionsdoesn’t work. After further investigation, it seems to be an issue with the Eclipse JSR 269 APIimplementation.