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

Example 1.2: Maven dependencies for Unified EL reference implementation

<dependency>
    <groupId>org.glassfish.expressly</groupId>
    <artifactId>expressly</artifactId>
    <version>6.0.0</version>
</dependency>

Example 1.3: Hibernate Validator CDI portable extension Maven dependency

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

• Jakarta Validation API: jakarta.validation

• Hibernate Validator core: org.hibernate.validator

• Hibernate Validator CDI extension: org.hibernate.validator.cdi

• Hibernate Validator test utilities: org.hibernate.validator.testutils

• Hibernate Validator annotation processor: org.hibernate.validator.annotationprocessor

/*
 * SPDX-License-Identifier: Apache-2.0
 * Copyright Red Hat Inc. and Hibernate Authors
 */
package org.hibernate.validator.referenceguide.chapter01;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
public class Car {
    @NotNull
    private String manufacturer;
    @NotNull
    @Size(min = 2, max = 14)
    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 ...
}

/*
 * SPDX-License-Identifier: Apache-2.0
 * Copyright Red Hat Inc. and Hibernate Authors
 */
package org.hibernate.validator.referenceguide.chapter01;
import static org.junit.Assert.assertEquals;
import java.util.Set;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.ValidatorFactory;
import org.junit.BeforeClass;
import org.junit.Test;
public class CarTest {
    private static Validator validator;
    @BeforeClass
    public static void setUpValidator() {
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        validator = factory.getValidator();
    }
    @Test
    public void manufacturerIsNull() {
        Car car = new Car( null, "DD-AB-123", 4 );
        Set<ConstraintViolation<Car>> constraintViolations =
                validator.validate( car );
        assertEquals( 1, constraintViolations.size() );
        assertEquals( "must not be null", constraintViolations.iterator().next().getMessage() );
    }
    @Test
    public void licensePlateTooShort() {
        Car car = new Car( "Morris", "D", 4 );
        Set<ConstraintViolation<Car>> constraintViolations =
                validator.validate( car );
        assertEquals( 1, constraintViolations.size() );
        assertEquals(
                "size must be between 2 and 14",
                constraintViolations.iterator().next().getMessage()
        );
    }
    @Test
    public void seatCountTooLow() {
        Car car = new Car( "Morris", "DD-AB-123", 1 );
        Set<ConstraintViolation<Car>> constraintViolations =
                validator.validate( car );
        assertEquals( 1, constraintViolations.size() );
        assertEquals(
                "must be greater than or equal to 2",
                constraintViolations.iterator().next().getMessage()
        );
    }
    @Test
    public void carIsValid() {
        Car car = new Car( "Morris", "DD-AB-123", 2 );
        Set<ConstraintViolation<Car>> constraintViolations =
                validator.validate( car );
        assertEquals( 0, constraintViolations.size() );
    }
}

Example 2.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...
}

Example 2.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;
    }
}

• implementations of java.util.Iterable (e.g. Lists, Sets),

• implementations of java.util.Map, with support for keys and values,

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

• the various implementations of JavaFX’s javafx.beans.observable.ObservableValue.

2.1.3.1. With Iterable

When applying constraints on an Iterable type argument, Hibernate Validator will validate each element. Example 2.3, “Container element constraint on Set” shows an example of a Set with a container element constraint.

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() );

Note how the property path clearly states that the violation comes from an element of the iterable.

2.1.3.2. With List

When applying constraints on a List type argument, Hibernate Validator will validate each element. Example 2.4, “Container element constraint on List” shows an example of a List with a container element constraint.

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() );

Here, the property path also contains the index of the invalid element.

2.1.3.3. With Map

Container element constraints are also validated on map keys and values. Example 2.5, “Container element constraint on map keys and values” shows an example of a Map with a constraint on the key and a constraint on the value.

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()
);

The property paths of the violations are particularly interesting:

2.1.3.4. With java.util.Optional

When applying a constraint on the type argument of Optional, Hibernate Validator will automatically unwrap the type and validate the internal value. Example 2.6, “Container element constraint on Optional” shows an example of an Optional with a container element constraint.

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()
);

Here, the property path only contains the name of the property as we are considering Optional as a "transparent" container.

2.1.3.5. With custom container types

Container element constraints can also be used with custom containers.

A ValueExtractor must be registered for the custom type allowing to retrieve the value(s) to validate (see Chapter 7, Value extraction for more information about how to implement your own ValueExtractor and how to register it).

Example 2.7, “Container element constraint on custom container type” shows an example of a custom parameterized type with a type argument constraint.

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()
);

2.1.3.6. Nested container elements

Constraints are also supported on nested container elements.

When validating a Car object as presented in Example 2.8, “Constraints on nested container elements”, both the @NotNull constraints on Part and Manufacturer will be enforced.

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

Example 2.9: Class-level constraint

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

Example 2.10: 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;
    }
    //...
}

Example 2.11: Cascaded validation

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;
    //...
}

Example 2.12: Cascaded validation of containers

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;
    //...
}

• if any of the Person objects contained in the passengers list has a null name;

• if any of the Part objects contained in the map keys has a null name;

• if any of the Manufacturer objects contained in the list nested in the map values has a null name.

Example 2.13: Validation#buildDefaultValidatorFactory()

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

2.2.2.1. Validator#validate()

Use the validate() method to perform validation of all constraints of a given bean. Example 2.14, “Using Validator#validate()” shows the validation of an instance of the Car class from Example 2.2, “Property-level constraints” which fails to satisfy the @NotNull constraint on the manufacturer property. The validation call therefore returns one ConstraintViolation object.

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() );

2.2.2.2. Validator#validateProperty()

With help of the validateProperty() you can validate a single named property of a given object. The property name is the JavaBeans property name.

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() );

2.2.2.3. Validator#validateValue()

By using the validateValue() method you can check whether a single property of a given class can be validated successfully, if the property had the specified value:

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

Validator#validateProperty() is for example used in the integration of Jakarta Validation into JSF 2 (see Section 11.2, “JSF & Seam”) to perform a validation of the values entered into a form before they are propagated to the model.

2.2.3.1. ConstraintViolation methods

Now it is time to have a closer look at what a ConstraintViolation is. Using the different methods of ConstraintViolation a lot of useful information about the cause of the validation failure can be determined. The following gives an overview of these methods. The values under "Example" column refer to Example 2.14, “Using Validator#validate()”.

2.2.3.2. Exploiting the property path

To determine the element that triggered the violation, you need to exploit the result of the getPropertyPath() method.

The returned Path is composed of Nodes describing the path to the element.

More information about the structure of the Path and the various types of Nodes can be found in the ConstraintViolation section of the Jakarta Validation specification.

@AssertFalse

Checks that the annotated element is false

Supported data types

Boolean, boolean

Hibernate metadata impact

None

@AssertTrue

Checks that the annotated element is true

Supported data types

Boolean, boolean

Hibernate metadata impact

None

@DecimalMax(value=, inclusive=)

Checks whether the annotated value is less than the specified maximum, when inclusive=false. Otherwise whether the value is less than or equal to the specified maximum. The parameter value is the string representation of the max value according to the BigDecimal string representation.

Supported data types

BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of Number and javax.money.MonetaryAmount (if the JSR 354 API and an implementation is on the class path)

Hibernate metadata impact

None

@DecimalMin(value=, inclusive=)

Checks whether the annotated value is larger than the specified minimum, when inclusive=false. Otherwise whether the value is larger than or equal to the specified minimum. The parameter value is the string representation of the min value according to the BigDecimal string representation.

Supported data types

BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of Number and javax.money.MonetaryAmount

Hibernate metadata impact

None

@Digits(integer=, fraction=)

Checks whether the annotated value is a number having up to integer digits and fraction fractional digits

Supported data types

BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of Number and javax.money.MonetaryAmount

Hibernate metadata impact

Defines column precision and scale

@Email

Checks whether the specified character sequence is a valid email address. The optional parameters regexp and flags allow to specify an additional regular expression (including regular expression flags) which the email must match.

Supported data types

CharSequence

Hibernate metadata impact

None

@Future

Checks whether the annotated date is in the future

Supported data types

java.util.Date, java.util.Calendar, java.time.Instant, java.time.LocalDate, java.time.LocalDateTime, java.time.LocalTime, java.time.MonthDay, java.time.OffsetDateTime, java.time.OffsetTime, java.time.Year, java.time.YearMonth, java.time.ZonedDateTime, java.time.chrono.HijrahDate, java.time.chrono.JapaneseDate, java.time.chrono.MinguoDate, java.time.chrono.ThaiBuddhistDate; additionally supported by HV, if the Joda Time date/time API is on the classpath: any implementations of ReadablePartial and ReadableInstant

Hibernate metadata impact

None

@FutureOrPresent

Checks whether the annotated date is in the present or in the future

Supported data types

java.util.Date, java.util.Calendar, java.time.Instant, java.time.LocalDate, java.time.LocalDateTime, java.time.LocalTime, java.time.MonthDay, java.time.OffsetDateTime, java.time.OffsetTime, java.time.Year, java.time.YearMonth, java.time.ZonedDateTime, java.time.chrono.HijrahDate, java.time.chrono.JapaneseDate, java.time.chrono.MinguoDate, java.time.chrono.ThaiBuddhistDate; additionally supported by HV, if the Joda Time date/time API is on the classpath: any implementations of ReadablePartial and ReadableInstant

Hibernate metadata impact

None

@Max(value=)

Checks whether the annotated value is less than or equal to the specified maximum

Supported data types

BigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the character sequence is evaluated), any sub-type of Number and javax.money.MonetaryAmount

Hibernate metadata impact

Adds a check constraint on the column

@Min(value=)

Checks whether the annotated value is higher than or equal to the specified minimum

Supported data types

BigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the character sequence is evaluated), any sub-type of Number and javax.money.MonetaryAmount

Hibernate metadata impact

Adds a check constraint on the column

@NotBlank

Checks that the annotated character sequence is not null and the trimmed length is greater than 0. The difference to @NotEmpty is that this constraint can only be applied on character sequences and that trailing white-spaces are ignored.

Supported data types

CharSequence

Hibernate metadata impact

None

@NotEmpty

Checks whether the annotated element is not null nor empty

Supported data types

CharSequence, Collection, Map and arrays

Hibernate metadata impact

None

@NotNull

Checks that the annotated value is not null

Supported data types

Any type

Hibernate metadata impact

Column(s) are not nullable

@Negative

Checks if the element is strictly negative. Zero values are considered invalid.

Supported data types

BigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the character sequence is evaluated), any sub-type of Number and javax.money.MonetaryAmount

Hibernate metadata impact

None

@NegativeOrZero

Checks if the element is negative or zero.

Supported data types

BigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the character sequence is evaluated), any sub-type of Number and javax.money.MonetaryAmount

Hibernate metadata impact

None

@Null

Checks that the annotated value is null

Supported data types

Any type

Hibernate metadata impact

None

@Past

Checks whether the annotated date is in the past

Supported data types

java.util.Date,java.util.Calendar, java.time.Instant, java.time.LocalDate, java.time.LocalDateTime, java.time.LocalTime, java.time.MonthDay, java.time.OffsetDateTime, java.time.OffsetTime, java.time.Year, java.time.YearMonth, java.time.ZonedDateTime, java.time.chrono.HijrahDate, java.time.chrono.JapaneseDate, java.time.chrono.MinguoDate, java.time.chrono.ThaiBuddhistDate; Additionally supported by HV, if the Joda Time date/time API is on the classpath: any implementations of ReadablePartial and ReadableInstant

Hibernate metadata impact

None

@PastOrPresent

Checks whether the annotated date is in the past or in the present

Supported data types

java.util.Date,java.util.Calendar, java.time.Instant, java.time.LocalDate, java.time.LocalDateTime, java.time.LocalTime, java.time.MonthDay, java.time.OffsetDateTime, java.time.OffsetTime, java.time.Year, java.time.YearMonth, java.time.ZonedDateTime, java.time.chrono.HijrahDate, java.time.chrono.JapaneseDate, java.time.chrono.MinguoDate, java.time.chrono.ThaiBuddhistDate; Additionally supported by HV, if the Joda Time date/time API is on the classpath: any implementations of ReadablePartial and ReadableInstant

Hibernate metadata impact

None

@Pattern(regex=, flags=)

Checks if the annotated string matches the regular expression regex considering the given flag match

Supported data types

CharSequence

Hibernate metadata impact

None

@Positive

Checks if the element is strictly positive. Zero values are considered invalid.

Supported data types

BigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the character sequence is evaluated), any sub-type of Number and javax.money.MonetaryAmount

Hibernate metadata impact

None

@PositiveOrZero

Checks if the element is positive or zero.

Supported data types

BigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types; additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the character sequence is evaluated), any sub-type of Number and javax.money.MonetaryAmount

Hibernate metadata impact

None

@Size(min=, max=)

Checks if the annotated element’s size is between min and max (inclusive)

Supported data types

CharSequence, Collection, Map and arrays

Hibernate metadata impact

Column length will be set to max

@CreditCardNumber(ignoreNonDigitCharacters=)

Checks that the annotated character sequence passes the Luhn checksum test. Note, this validation aims to check for user mistakes, not credit card validity! See also Anatomy of a credit card number. ignoreNonDigitCharacters allows to ignore non digit characters. The default is false.

Supported data types

CharSequence

Hibernate metadata impact

None

@Currency(value=)

Checks that the currency unit of the annotated javax.money.MonetaryAmount is part of the specified currency units.

Supported data types

any sub-type of javax.money.MonetaryAmount (if the JSR 354 API and an implementation is on the class path)

Hibernate metadata impact

None

@DurationMax(days=, hours=, minutes=, seconds=, millis=, nanos=, inclusive=)

Checks that annotated java.time.Duration element is not greater than the one constructed from annotation parameters. Equality is allowed if inclusive flag is set to true.

Supported data types

java.time.Duration

Hibernate metadata impact

None

@DurationMin(days=, hours=, minutes=, seconds=, millis=, nanos=, inclusive=)

Checks that annotated java.time.Duration element is not less than the one constructed from annotation parameters. Equality is allowed if inclusive flag is set to true.

Supported data types

java.time.Duration

Hibernate metadata impact

None

@EAN

Checks that the annotated character sequence is a valid EAN barcode. type determines the type of barcode. The default is EAN-13.

Supported data types

CharSequence

Hibernate metadata impact

None

@IpAddress

Checks that the annotated character sequence is a valid IP address. type determines the version of IP address. The default is ANY, which means both IPv4 and IPv6 addresses are considered valid.

Supported data types

CharSequence

Hibernate metadata impact

None

@ISBN

Checks that the annotated character sequence is a valid ISBN. type determines the type of ISBN. The default is ISBN-13.

Supported data types

CharSequence

Hibernate metadata impact

None

@Length(min=, max=)

Validates that the annotated character sequence is between min and max included

Supported data types

CharSequence

Hibernate metadata impact

Column length will be set to max

@CodePointLength(min=, max=, normalizationStrategy=)

Validates that code point length of the annotated character sequence is between min and max included. Validates normalized value if normalizationStrategy is set.

Supported data types

CharSequence

Hibernate metadata impact

None

@LuhnCheck(startIndex= , endIndex=, checkDigitIndex=, ignoreNonDigitCharacters=)

Checks that the digits within the annotated character sequence pass the Luhn checksum algorithm (see also Luhn algorithm). startIndex and endIndex allow to only run the algorithm on the specified sub-string. checkDigitIndex allows to use an arbitrary digit within the character sequence as the check digit. If not specified it is assumed that the check digit is part of the specified range. Last but not least, ignoreNonDigitCharacters allows to ignore non digit characters.

Supported data types

CharSequence

Hibernate metadata impact

None

@Mod10Check(multiplier=, weight=, startIndex=, endIndex=, checkDigitIndex=, ignoreNonDigitCharacters=)

Checks that the digits within the annotated character sequence pass the generic mod 10 checksum algorithm. multiplier determines the multiplier for odd numbers (defaults to 3), weight the weight for even numbers (defaults to 1). startIndex and endIndex allow to only run the algorithm on the specified sub-string. checkDigitIndex allows to use an arbitrary digit within the character sequence as the check digit. If not specified it is assumed that the check digit is part of the specified range. Last but not least, ignoreNonDigitCharacters allows to ignore non digit characters.

Supported data types

CharSequence

Hibernate metadata impact

None

@Mod11Check(threshold=, startIndex=, endIndex=, checkDigitIndex=, ignoreNonDigitCharacters=, treatCheck10As=, treatCheck11As=)

Checks that the digits within the annotated character sequence pass the mod 11 checksum algorithm. threshold specifies the threshold for the mod11 multiplier growth; if no value is specified the multiplier will grow indefinitely. treatCheck10As and treatCheck11As specify the check digits to be used when the mod 11 checksum equals 10 or 11, respectively. Default to X and 0, respectively. startIndex, endIndex checkDigitIndex and ignoreNonDigitCharacters carry the same semantics as in @Mod10Check.

Supported data types

CharSequence

Hibernate metadata impact

None

@Normalized(form=)

Validates that the annotated character sequence is normalized according to the given form.

Supported data types

CharSequence

Hibernate metadata impact

None

@Range(min=, max=)

Checks whether the annotated value lies between (inclusive) the specified minimum and maximum

Supported data types

BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive types

Hibernate metadata impact

None

@ScriptAssert(lang=, script=, alias=, reportOn=)

Checks whether the given script can successfully be evaluated against the annotated element. In order to use this constraint, an implementation of the Java Scripting API as defined by JSR 223 ("Scripting for the Java^TM Platform") must be a part of the class path. The expressions to be evaluated can be written in any scripting or expression language, for which a JSR 223 compatible engine can be found in the class path. Even though this is a class-level constraint, one can use the reportOn attribute to report a constraint violation on a specific property rather than the whole object.

Supported data types

Any type

Hibernate metadata impact

None

@UniqueElements

Checks that the annotated collection only contains unique elements. The equality is determined using the equals() method. The default message does not include the list of duplicate elements but you can include it by overriding the message and using the {duplicates} message parameter. The list of duplicate elements is also included in the dynamic payload of the constraint violation.

Supported data types

Collection

Hibernate metadata impact

None

@URL(protocol=, host=, port=, regexp=, flags=)

Checks if the annotated character sequence is a valid URL according to RFC2396. If any of the optional parameters protocol, host or port are specified, the corresponding URL fragments must match the specified values. The optional parameters regexp and flags allow to specify an additional regular expression (including regular expression flags) which the URL must match. Per default this constraint used the java.net.URL constructor to verify whether a given string represents a valid URL. A regular expression based version is also available - RegexpURLValidator - which can be configured via XML (see Section 8.2, “Mapping constraints via constraint-mappings”) or the programmatic API (see Section 12.15.2, “Adding constraint definitions programmatically”).

Supported data types

CharSequence

Hibernate metadata impact

None

@UUID(allowEmpty=, allowNil=, version=, variant=, letterCase=)

Checks that the annotated character sequence is a valid universally unique identifier according to RFC 4122. null is always valid. The option allowEmpty allows empty character sequences. allowNil includes nil UUIDs (00000000-0000-0000-0000-000000000000). The version and variant parameters control which UUID versions and variants are allowed. letterCase ensures lower case or upper case, but can also be configured as case insensitive.

Supported data types

CharSequence

Hibernate metadata impact

None

@BitcoinAddress(value=)

Checks that the annotated character sequence is a valid Bitcoin address. null values are considered valid. The option value allows to specify which types of Bitcoin addresses should be considered as valid. By default, all address types are considered as valid. See BitcoinAddress.BitcoinAddressType for a list of available address types.

Supported data types

CharSequence

Hibernate metadata impact

None

2.3.2.1. Country specific constraints

Hibernate Validator offers also some country specific constraints, e.g. for the validation of social security numbers.

Example 3.1: Declaring method and constructor 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) {
        //...
    }
}

• The name passed to the RentalStation constructor must not be null

• When invoking the rentCar() method, the given customer must not be null, the rental’s start date must not be null as well as be in the future and finally the rental duration must be at least one day

3.1.1.1. Cross-parameter constraints

Sometimes validation does not only depend on a single parameter but on several or even all parameters of a method or constructor. This kind of requirement can be fulfilled with help of a cross-parameter constraint.

Cross-parameter constraints can be considered as the method validation equivalent to class-level constraints. Both can be used to implement validation requirements which are based on several elements. While class-level constraints apply to several properties of a bean, cross-parameter constraints apply to several parameters of an executable.

In contrast to single-parameter constraints, cross-parameter constraints are declared on the method or constructor as you can see in Example 3.2, “Declaring a cross-parameter constraint”. Here the cross- parameter constraint @LuggageCountMatchesPassengerCount declared on the load() method is used to ensure that no passenger has more than two pieces of luggage.

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

As you will learn in the next section, return value constraints are also declared on the method level. In order to distinguish cross-parameter constraints from return value constraints, the constraint target is configured in the ConstraintValidator implementation using the @SupportedValidationTarget annotation. You can find out about the details in Section 6.3, “Cross-parameter constraints” which shows how to implement your own cross-parameter constraint.

In some cases a constraint can be applied to an executable’s parameters (i.e. it is a cross- parameter constraint), but also to the return value. One example for this are custom constraints which allow to specify validation rules using expression or script languages.

Such constraints must define a member validationAppliesTo() which can be used at declaration time to specify the constraint target. As shown in Example 3.3, “Specifying a constraint’s target” you apply the constraint to an executable’s parameters by specifying validationAppliesTo = ConstraintTarget.PARAMETERS, while ConstraintTarget.RETURN_VALUE is used to apply the constraint to the executable return value.

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;
    }
}

Although such a constraint is applicable to the parameters and return value of an executable, the target can often be inferred automatically. This is the case, if the constraint is declared on

In these situations you don’t have to specify the constraint target. It is still recommended to do so if it increases readability of the source code. If the constraint target is not specified in situations where it can’t be determined automatically, a ConstraintDeclarationException is raised.

Example 3.4: Declaring method and constructor 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;
    }
}

• Any newly created RentalStation object must satisfy the @ValidRentalStation constraint

• The customer list returned by getCustomers() must not be null and must contain at least on element

• The customer list returned by getCustomers() must no contain null objects

Example 3.5: Marking executable parameters and return values for 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 ...
}

Example 3.6: Container elements of method parameter marked for cascaded validation

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

• The preconditions to be satisfied by the caller of a method may not be strengthened in subtypes

• The postconditions guaranteed to the caller of a method may not be weakened in subtypes

Example 3.7: Illegal method parameter constraint in subtype

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) {
        //...
    }
}

Example 3.8: Illegal method parameter constraint in parallel types of a hierarchy

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) {
        //...
    }
}

Example 3.9: Return value constraints on supertype and subtype method

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;
    }
}

Example 3.10: Obtaining an ExecutableValidator instance

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

• validateParameters() and validateReturnValue() for method validation

• validateConstructorParameters() and validateConstructorReturnValue() for constructor validation

Example 3.11: Class Car with constrained methods and constructors

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();
    }
}

3.2.2.1. ExecutableValidator#validateParameters()

The method validateParameters() is used to validate the arguments of a method invocation. Example 3.12, “Using ExecutableValidator#validateParameters()” shows an example. The validation results in a violation of the @Max constraint on the parameter of the drive() method.

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 );

Note that validateParameters() validates all the parameter constraints of a method, i.e. constraints on individual parameters as well as cross-parameter constraints.

3.2.2.2. ExecutableValidator#validateReturnValue()

Using validateReturnValue() the return value of a method can be validated. The validation in Example 3.13, “Using ExecutableValidator#validateReturnValue()” yields one constraint violation since the getPassengers() method is expected to return at least one Passenger instance.

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 );

3.2.2.3. ExecutableValidator#validateConstructorParameters()

The arguments of constructor invocations can be validated with validateConstructorParameters() as shown in method Example 3.14, “Using ExecutableValidator#validateConstructorParameters()”. Due to the @NotNull constraint on the manufacturer parameter, the validation call returns one constraint violation.

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 );

3.2.2.4. ExecutableValidator#validateConstructorReturnValue()

Finally, by using validateConstructorReturnValue() you can validate a constructor’s return value. In Example 3.15, “Using ExecutableValidator#validateConstructorReturnValue()”, validateConstructorReturnValue() returns one constraint violation, since the Car instance returned by the constructor doesn’t satisfy the @ValidRacingCar constraint (not shown).

//constructor for creating racing cars
Constructor<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 );

Example 3.16: Retrieving method and parameter information

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() );

package org.hibernate.validator.referenceguide.chapter03.parameterscriptassert;
public class Car {
    @ParameterScriptAssert(lang = "groovy", script = "luggage.size() <= passengers.size() * 2")
    public void load(List<Person> passengers, List<PieceOfLuggage> luggage) {
        //...
    }
}

package org.hibernate.validator.referenceguide.chapter04;
public class Car {
    @NotNull(message = "The manufacturer name must not be null")
    private String manufacturer;
    //constructor, getters and setters ...
}

• \{ is considered as the literal {

• \} is considered as the literal }

• \$ is considered as the literal $

• \\ is considered as the literal \

• the attribute values of the constraint mapped to the attribute names

• the currently validated value (property, bean, method parameter etc.) under the name validatedValue

• a bean mapped to the name formatter exposing the var-arg method format(String format, Object…​ args) which behaves like java.util.Formatter.format(String format, Object…​ args).

• NONE: Expression Language interpolation is fully disabled.

• VARIABLES: Allow interpolation of the variables injected via addExpressionVariable(), resources bundles and usage of the formatter object.

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

• BEAN_METHODS: Also allow execution of bean methods. Can be considered safe for hardcoded constraint messages but not for custom violations where extra care is required.

Example 4.2: Specifying message descriptors

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 ...
}

• the @NotNull constraint on the manufacturer field causes the error message "must not be null", as this is the default message defined by the Jakarta Validation specification and no specific descriptor is given in the message attribute

• the @Size constraint on the licensePlate field shows the interpolation of message parameters ({min}, {max}) and how to add the validated value to the error message using the EL expression ${validatedValue}

• the @Min constraint on seatCount demonstrates how to use an EL expression with a ternary expression to dynamically choose singular or plural form, depending on an attribute of the constraint ("There must be at least 1 seat" vs. "There must be at least 2 seats")

• the message for the @DecimalMax constraint on topSpeed shows how to format the validated value using the formatter instance

• finally, the @DecimalMax constraint on price shows that parameter interpolation has precedence over expression evaluation, causing the $ sign to show up in front of the maximum price

Example 4.3: Expected error messages

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 );

Example 4.4: Using a specific resource bundle

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

Example 4.5: Using AggregateResourceBundleLocator

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

package org.hibernate.validator.referenceguide.chapter05;
public class Person {
    @NotNull
    private String name;
    public Person(String name) {
        this.name = name;
    }
    // getters and setters ...
}

// create a car and check that everything is ok with it.
Car car = new Car( "Morris", "DD-AB-123", 2 );
Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );
assertEquals( 0, constraintViolations.size() );
// but has it passed the vehicle inspection?
constraintViolations = validator.validate( car, CarChecks.class );
assertEquals( 1, constraintViolations.size() );
assertEquals(
        "The car has to pass the vehicle inspection first",
        constraintViolations.iterator().next().getMessage()
);
// let's go to the vehicle inspection
car.setPassedVehicleInspection( true );
assertEquals( 0, validator.validate( car, CarChecks.class ).size() );
// now let's add a driver. He is 18, but has not passed the driving test yet
Driver john = new Driver( "John Doe" );
john.setAge( 18 );
car.setDriver( john );
constraintViolations = validator.validate( car, DriverChecks.class );
assertEquals( 1, constraintViolations.size() );
assertEquals(
        "You first have to pass the driving test",
        constraintViolations.iterator().next().getMessage()
);
// ok, John passes the test
john.passedDrivingTest( true );
assertEquals( 0, validator.validate( car, DriverChecks.class ).size() );
// just checking that everything is in order now
assertEquals(
        0, validator.validate(
                car,
                Default.class,
                CarChecks.class,
                DriverChecks.class
        ).size()
);

// create a supercar and check that it's valid as a generic Car
SuperCar superCar = new SuperCar( "Morris", "DD-AB-123", 1 );
assertEquals( "must be greater than or equal to 2", validator.validate( superCar ).iterator().next().getMessage() );
// check that this supercar is valid as generic car and also as race car
Set<ConstraintViolation<SuperCar>> constraintViolations = validator.validate( superCar, RaceCarChecks.class );
assertThat( constraintViolations ).extracting( "message" ).containsOnly(
        "Race car must have a safety belt",
        "must be greater than or equal to 2"
);

/*
 * SPDX-License-Identifier: Apache-2.0
 * Copyright Red Hat Inc. and Hibernate Authors
 */
package org.hibernate.validator.referenceguide.chapter05;
import jakarta.validation.GroupSequence;
import jakarta.validation.groups.Default;
@GroupSequence({ Default.class, CarChecks.class, DriverChecks.class })
public interface OrderedChecks {
}

Car car = new Car( "Morris", "DD-AB-123", 2 );
car.setPassedVehicleInspection( true );
Driver john = new Driver( "John Doe" );
john.setAge( 18 );
john.passedDrivingTest( true );
car.setDriver( john );
assertEquals( 0, validator.validate( car, OrderedChecks.class ).size() );

Example 5.9: Class RentalCar with redefined default group

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;
    }
}

/*
 * SPDX-License-Identifier: Apache-2.0
 * Copyright Red Hat Inc. and Hibernate Authors
 */
package org.hibernate.validator.referenceguide.chapter05;
public interface RentalChecks {
}

Example 5.10: Validating an object with redefined default group

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() );

Example 5.11: Implementing and using a default group sequence provider

package org.hibernate.validator.referenceguide.chapter05.groupsequenceprovider;
public class RentalCarGroupSequenceProvider
        implements DefaultGroupSequenceProvider<RentalCar> {
    @Override
    public List<Class<?>> getValidationGroups(Class<?> klass, 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;
    }
}

// create a car and validate. The Driver is still null and does not get validated
Car car = new Car( "VW", "USD-123", 4 );
car.setPassedVehicleInspection( true );
Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );
assertEquals( 0, constraintViolations.size() );
// create a driver who has not passed the driving test
Driver john = new Driver( "John Doe" );
john.setAge( 18 );
// now let's add a driver to the car
car.setDriver( john );
constraintViolations = validator.validate( car );
assertEquals( 1, constraintViolations.size() );
assertEquals(
        "The driver constraint should also be validated as part of the default group",
        constraintViolations.iterator().next().getMessage(),
        "You first have to pass the driving test"
);

Example 6.1: Enum CaseMode to express upper vs. lower case

/*
 * SPDX-License-Identifier: Apache-2.0
 * Copyright Red Hat Inc. and Hibernate Authors
 */
package org.hibernate.validator.referenceguide.chapter06;
public enum CaseMode {
    UPPER,
    LOWER;
}

Example 6.2: Defining the @CheckCase constraint annotation

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();
    }
}

• an attribute message that returns the default key for creating error messages in case the constraint is violated

• an attribute groups that allows the specification of validation groups, to which this constraint belongs (see Chapter 5, Grouping constraints). This must default to an empty array of type Class<?>.

• an attribute payload that can be used by clients of the Jakarta Validation API to assign custom payload objects to a constraint. This attribute is not used by the API itself. An example for a custom payload could be the definition of a severity:

  public class Severity {
      public interface Info extends Payload {
      }
      public interface Error extends Payload {
      }
  }

  public class ContactDetails {
      @NotNull(message = "Name is mandatory", payload = Severity.Error.class)
      private String name;
      @NotNull(message = "Phone number not specified, but not mandatory",
              payload = Severity.Info.class)
      private String phoneNumber;
      // ...
  }

  Now a client can after the validation of a ContactDetails instance access the severity of a constraint using ConstraintViolation.getConstraintDescriptor().getPayload() and adjust its behavior depending on the severity.

• @Target({ FIELD, METHOD, PARAMETER, ANNOTATION_TYPE, TYPE_USE}): Defines the supported target element types for the constraint. @CheckCase may be used on fields (element type FIELD), JavaBeans properties as well as method return values (METHOD), method/constructor parameters (PARAMETER) and type argument of parameterized types (TYPE_USE). The element type ANNOTATION_TYPE allows for the creation of composed constraints (see Section 6.4, “Constraint composition”) based on @CheckCase.

  When creating a class-level constraint (see Section 2.1.4, “Class-level constraints”), the element type TYPE would have to be used. Constraints targeting the return value of a constructor need to support the element type CONSTRUCTOR. Cross-parameter constraints (see Section 6.3, “Cross-parameter constraints”) which are used to validate all the parameters of a method or constructor together, must support METHOD or CONSTRUCTOR, respectively.

• @Retention(RUNTIME): Specifies, that annotations of this type will be available at runtime by the means of reflection

• @Constraint(validatedBy = CheckCaseValidator.class): Marks the annotation type as constraint annotation and specifies the validator to be used to validate elements annotated with @CheckCase. If a constraint may be used on several data types, several validators may be specified, one for each data type.

• @Documented: Says, that the use of @CheckCase will be contained in the JavaDoc of elements annotated with it

• @Repeatable(List.class): Indicates that the annotation can be repeated several times at the same place, usually with a different configuration. List is the containing annotation type.

Example 6.3: Implementing a constraint validator for the constraint @CheckCase

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() );
        }
    }
}

6.1.2.1. The ConstraintValidatorContext

Example 6.3, “Implementing a constraint validator for the constraint @CheckCase” relies on the default error message generation by just returning true or false from the isValid() method. Using the passed ConstraintValidatorContext object, it is possible to either add additional error messages or completely disable the default error message generation and solely define custom error messages. The ConstraintValidatorContext API is modeled as fluent interface and is best demonstrated with an example:

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;
    }
}

Example 6.4, “Using ConstraintValidatorContext to define custom error messages” shows how you can disable the default error message generation and add a custom error message using a specified message template. In this example the use of the ConstraintValidatorContext results in the same error message as the default error message generation.

By default, Expression Language is not enabled for custom violations created in the ConstraintValidatorContext.

However, for some advanced requirements, using Expression Language might be necessary.

In this case, you need to unwrap the HibernateConstraintValidatorContext and enable Expression Language explicitly. See Section 12.13.1, “HibernateConstraintValidatorContext” for more information.

Refer to Section 6.2.1, “Custom property paths” to learn how to use the ConstraintValidatorContext API to control the property path of constraint violations for class-level constraints.

6.1.2.2. The HibernateConstraintValidator extension

Hibernate Validator provides an extension to the ConstraintValidator contract: HibernateConstraintValidator.

The purpose of this extension is to provide more contextual information to the initialize() method as, in the current ConstraintValidator contract, only the annotation is passed as parameter.

The initialize() method of HibernateConstraintValidator takes two parameters:

This extension is marked as incubating so it might be subject to change. The plan is to standardize it and to include it in Jakarta Validation in the future.

The example below shows how to base your validators on HibernateConstraintValidator:

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;
    }
}

6.1.2.3. Passing a payload to the constraint validator

From time to time, you might want to condition the constraint validator behavior on some external parameters.

For instance, your zip code validator could vary depending on the locale of your application instance if you have one instance per country. Another requirement could be to have different behaviors on specific environments: the staging environment may not have access to some external production resources necessary for the correct functioning of a validator.

The notion of constraint validator payload was introduced for all these use cases. It is an object passed from the Validator instance to each constraint validator via the HibernateConstraintValidatorContext.

The example below shows how to set a constraint validator payload during the ValidatorFactory initialization. Unless you override this default value, all the Validators created by this ValidatorFactory will have this constraint validator payload value set.

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

Another option is to set the constraint validator payload per Validator using a context:

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

Once you have set the constraint validator payload, it can be used in your constraint validators as shown in the example below:

package org.hibernate.validator.referenceguide.chapter06.constraintvalidatorpayload;
import jakarta.validation.ConstraintValidator;
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;
    }
}