Hibernate Validator requires an implementation of the Unified Expression Language (JSR 341) for evaluating dynamic expressions in constraint violation messages (see Section 4.1, “Default message interpolation”). When your application runs in a Java EE container such as JBoss AS, an EL implementation is already provided by the container. In a Java SE environment, however, you have to add an implementation as dependency to your POM file. For instance you can add the following dependency to use the JSR 341 reference implementation:

Bean Validation defines integration points with CDI (Contexts and Dependency Injection for Java TM EE, JSR 346). If your application runs in an environment which does not provide this integration out of the box, you may use the Hibernate Validator CDI portable extension by adding the following Maven dependency to your POM:

Note that adding this dependency is usually not required for applications running on a Java EE application server. You can learn more about the integration of Bean Validation and CDI in Section 11.3, “CDI”.

Hibernate Validator supports running with a security manager being enabled. To do so, you must assign several permissions to the code bases of Hibernate Validator, the Bean Validation API, Classmate and JBoss Logging and also to the code base calling Bean Validation. The following shows how to do this via a policy file as processed by the Java default policy implementation:

The WildFly application server contains Hibernate Validator out of the box. In order to update the server modules for Bean Validation API and Hibernate Validator to the latest and greatest, the patch mechanism of WildFly can be used.

You can download the patch file from SourceForge or from Maven Central using the following dependency:

We also provide a patch for WildFly 11.0.0.Final:

Having downloaded the patch file, you can apply it to WildFly by running this command:

In case you want to undo the patch and go back to the version of Hibernate Validator originally coming with the server, run the following command:

You can learn more about the WildFly patching infrastructure in general here and here.

As of Hibernate Validator 6.0.9.Final, support for Java 9 and the Java Platform Module System (JPMS) is experimental. There are no JPMS module descriptors provided yet, but Hibernate Validator is usable as automatic modules.

These are the module names as declared using the Automatic-Module-Name header:

• Bean Validation API: java.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

These module names are preliminary and may be changed when providing real module descriptors in a future release.

When using Bean Validation XML descriptors (META-INF/validation.xml and/or constraint mapping files), the java.xml.bind module must be enabled. Do so by appending --add-modules java.xml.bind to your java invocation.

Constraints can be expressed by annotating a field of a class. Example 2.1, “Field-level constraints” shows a field level configuration example:

When using field-level constraints field access strategy is used to access the value to be validated. This means the validation engine directly accesses the instance variable and does not invoke the property accessor method even if such an accessor exists.

Constraints can be applied to fields of any access type (public, private etc.). Constraints on static fields are not supported, though.

If your model class adheres to the JavaBeans standard, it is also possible to annotate the properties of a bean class instead of its fields. Example 2.2, “Property-level constraints” uses the same entity as in Example 2.1, “Field-level constraints”, however, property level constraints are used.

When using property level constraints property access strategy is used to access the value to be validated, i.e. the validation engine accesses the state via the property accessor method.

It is possible to specify constraints directly on the type argument of a parameterized type: these constraints are called container element constraints.

This requires that ElementType.TYPE_USE is specified via @Target in the constraint definition. As of Bean Validation 2.0, built-in Bean Validation as well as Hibernate Validator specific constraints specify ElementType.TYPE_USE and can be used directly in this context.

Hibernate Validator validates container element constraints specified on the following standard Java containers:

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

It also supports container element constraints on custom container types (see Chapter 7, Value extraction).

We present below a couple of examples illustrating container element constraints on various Java types.

In these examples, @ValidPart is a custom constraint allowed to be used in the TYPE_USE context.

2.1.3.1. With Iterable

package org.hibernate.validator.referenceguide.chapter02.containerelement.set;

import java.util.HashSet;

import java.util.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() );

2.1.3.2. With List

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

2.1.3.3. With Map

package org.hibernate.validator.referenceguide.chapter02.containerelement.map;

import java.util.HashMap;

import java.util.Map;

import javax.validation.constraints.NotNull;

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

);

2.1.3.4. With java.util.Optional

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

);

2.1.3.5. With custom container types

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

package org.hibernate.validator.referenceguide.chapter02.containerelement.nested;

import java.util.HashMap;

import java.util.List;

import java.util.Map;

import javax.validation.constraints.NotNull;

public class Car {

    private Map<@NotNull Part, List<@NotNull Manufacturer>> partManufacturers =

            new HashMap<>();

    //...

}

Last but not least, a constraint can also be placed on the class level. In this case not a single property is subject of the validation but the complete object. Class-level constraints are useful if the validation depends on a correlation between several properties of an object.

The Car class in Example 2.9, “Class-level constraint” has the two attributes seatCount and passengers and it should be ensured that the list of passengers does not have more entries than available seats. For that purpose the @ValidPassengerCount constraint is added on the class level. The validator of that constraint has access to the complete Car object, allowing to compare the numbers of seats and passengers.

Refer to Section 6.2, “Class-level constraints” to learn in detail how to implement this custom constraint.

When a class implements an interface or extends another class, all constraint annotations declared on the super-type apply in the same manner as the constraints specified on the class itself. To make things clearer let’s have a look at the following example:

Here the class RentalCar is a subclass of Car and adds the property rentalStation. If an instance of RentalCar is validated, not only the @NotNull constraint on rentalStation is evaluated, but also the constraint on manufacturerfrom the parent class.

The same would be true, if Car was not a superclass but an interface implemented by RentalCar.

Constraint annotations are aggregated if methods are overridden. So if RentalCar overrode the getManufacturer()method from Car, any constraints annotated at the overriding method would be evaluated in addition to the @NotNullconstraint from the superclass.

The Bean Validation API does not only allow to validate single class instances but also complete object graphs (cascaded validation). To do so, just annotate a field or property representing a reference to another object with @Valid as demonstrated in Example 2.11, “Cascaded validation”.

If an instance of Car is validated, the referenced Person object will be validated as well, as the driver field is annotated with @Valid. Therefore the validation of a Car will fail if the name field of the referenced Person instance is null.

The validation of object graphs is recursive, i.e. if a reference marked for cascaded validation points to an object which itself has properties annotated with @Valid, these references will be followed up by the validation engine as well. The validation engine will ensure that no infinite loops occur during cascaded validation, for example if two objects hold references to each other.

Note that null values are getting ignored during cascaded validation.

As constraints, object graph validation also works for container elements. That means any type argument of a container can be annotated with @Valid, which will cause each contained element to be validated when the parent object is validated.

When validating an instance of the Car class shown in Example 2.12, “Cascaded validation of containers”, aConstraintViolation will be created:

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

The first step towards validating an entity instance is to get hold of a Validator instance. The road to this instance leads via the Validation class and a ValidatorFactory. The easiest way is to use the static method Validation#buildDefaultValidatorFactory():

This bootstraps a validator in the default configuration. Refer to Chapter 9, Bootstrapping to learn more about the different bootstrapping methods and how to obtain a specifically configured Validator instance.

The Validator interface contains three methods that can be used to either validate entire entities or just single properties of the entity.

All three methods return a Set<ConstraintViolation>. The set is empty, if the validation succeeds. Otherwise a ConstraintViolation instance is added for each violated constraint.

All the validation methods have a var-args parameter which can be used to specify which validation groups shall be considered when performing the validation. If the parameter is not specified, the default validation group (javax.validation.groups.Default) is used. The topic of validation groups is discussed in detail in Chapter 5, Grouping constraints.

2.2.2.1. Validator#validate()

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

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

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.1. ConstraintViolation methods

2.2.3.2. Exploiting the property path

Below you can find a list of all constraints specified in the Bean Validation API. All these constraints apply to the field/property level, there are no class-level constraints defined in the Bean Validation specification. If you are using the Hibernate object-relational mapper, some of the constraints are taken into account when creating the DDL for your model (see "Hibernate metadata impact").

@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 APIand 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

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 flagsallow 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

In addition to the constraints defined by the Bean Validation API, Hibernate Validator provides several useful custom constraints which are listed below. With one exception also these constraints apply to the field/property level, only @ScriptAssert is a class-level constraint.

@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

@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. checkDigitIndexallows 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. checkDigitIndexallows 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. thresholdspecifies 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

@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

@SafeHtml(whitelistType= , additionalTags=, additionalTagsWithAttributes=, baseURI=)

Checks whether the annotated value contains potentially malicious fragments such as <script/>. In order to use this constraint, the jsoup library must be part of the class path. With the whitelistType attribute a predefined whitelist type can be chosen which can be refined via additionalTags or additionalTagsWithAttributes. The former allows to add tags without any attributes, whereas the latter allows to specify tags and optionally allowed attributes as well as accepted protocols for the attributes using the annotation @SafeHtml.Tag. In addition, baseURI allows to specify the base URI used to resolve relative URIs.

Supported data types

CharSequence

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 JavaTM 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.13.2, “Adding constraint definitions programmatically”).

Supported data types

CharSequence

Hibernate metadata impact

None

2.3.2.1. Country specific constraints

You specify the preconditions of a method or constructor by adding constraint annotations to its parameters as demonstrated in Example 3.1, “Declaring method and constructor parameter constraints”.

The following preconditions are declared here:

• The name passed to the RentalCar 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

Note that declaring method or constructor constraints itself does not automatically cause their validation upon invocation of the executable. Instead, the ExecutableValidator API (see Section 3.2, “Validating method constraints”) must be used to perform the validation, which is often done using a method interception facility such as AOP, proxy objects etc.

Constraints may only be applied to instance methods, i.e. declaring constraints on static methods is not supported. Depending on the interception facility you use for triggering method validation, additional restrictions may apply, e.g. with respect to the visibility of methods supported as target of interception. Refer to the documentation of the interception technology to find out whether any such limitations exist.

3.1.1.1. Cross-parameter constraints

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;

    }

}

The postconditions of a method or constructor are declared by adding constraint annotations to the executable as shown in Example 3.4, “Declaring method and constructor return value constraints”.

The following constraints apply to the executables of RentalStation:

• 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

Similar to the cascaded validation of JavaBeans properties (see Section 2.1.6, “Object graphs”), the @Valid annotation can be used to mark executable parameters and return values for cascaded validation. When validating a parameter or return value annotated with @Valid, the constraints declared on the parameter or return value object are validated as well.

In Example 3.5, “Marking executable parameters and return values for cascaded validation”, the car parameter of the method Garage#checkCar() as well as the return value of the Garage constructor are marked for cascaded validation.

When validating the arguments of the checkCar() method, the constraints on the properties of the passed Car object are evaluated as well. Similarly, the @NotNull constraint on the name field of Garage is checked when validating the return value of the Garage constructor.

Generally, the cascaded validation works for executables in exactly the same way as it does for JavaBeans properties.

In particular, null values are ignored during cascaded validation (naturally this can’t happen during constructor return value validation) and cascaded validation is performed recursively, i.e. if a parameter or return value object which is marked for cascaded validation itself has properties marked with @Valid, the constraints declared on the referenced elements will be validated as well.

Same as for fields and properties, cascaded validation can also be declared on container elements (e.g. elements of collections, maps or custom containers) of return values and parameters.

In this case, each element contained by the container gets validated. So when validating the arguments of the checkCars() method in Example 3.6, “Container elements of method parameter marked for cascaded validation”, each element instance of the passed list will be validated and a ConstraintViolation created when any of the contained Car instances is invalid.

When declaring method constraints in inheritance hierarchies, it is important to be aware of the following rules:

• 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

These rules are motivated by the concept of behavioral subtyping which requires that wherever a type T is used, also a subtype S of T may be used without altering the program’s behavior.

As an example, consider a class invoking a method on an object with the static type T. If the runtime type of that object was S and S imposed additional preconditions, the client class might fail to satisfy these preconditions as is not aware of them. The rules of behavioral subtyping are also known as the Liskov substitution principle.

The Bean Validation specification implements the first rule by disallowing parameter constraints on methods which override or implement a method declared in a supertype (superclass or interface). Example 3.7, “Illegal method parameter constraint in subtype” shows a violation of this rule.

The @Max constraint on Car#drive() is illegal since this method implements the interface method Vehicle#drive(). Note that parameter constraints on overriding methods are also disallowed, if the supertype method itself doesn’t declare any parameter constraints.

Furthermore, if a method overrides or implements a method declared in several parallel supertypes (e.g. two interfaces not extending each other or a class and an interface not implemented by that class), no parameter constraints may be specified for the method in any of the involved types. The types in Example 3.8, “Illegal method parameter constraint in parallel types of a hierarchy” demonstrate a violation of that rule. The method RacingCar#drive() overrides Vehicle#drive() as well as Car#drive(). Therefore the constraint on Vehicle#drive() is illegal.

The previously described restrictions only apply to parameter constraints. In contrast, return value constraints may be added in methods overriding or implementing any supertype methods.

In this case, all the method’s return value constraints apply for the subtype method, i.e. the constraints declared on the subtype method itself as well as any return value constraints on overridden/implemented supertype methods. This is legal as putting additional return value constraints in place may never represent a weakening of the postconditions guaranteed to the caller of a method.

So when validating the return value of the method Car#getPassengers() shown in Example 3.9, “Return value constraints on supertype and subtype method”, the @Size constraint on the method itself as well as the @NotNullconstraint on the implemented interface method Vehicle#getPassengers() apply.

If the validation engine detects a violation of any of the aforementioned rules, a ConstraintDeclarationException will be raised.

You can retrieve an ExecutableValidator instance via Validator#forExecutables() as shown in Example 3.10, “Obtaining an ExecutableValidator instance”.

In the example the executable validator is retrieved from the default validator factory, but if required you could also bootstrap a specifically configured factory as described in Chapter 9, Bootstrapping, for instance in order to use a specific parameter name provider (see Section 9.2.4, “ParameterNameProvider”).

The ExecutableValidator interface offers altogether four methods:

• validateParameters() and validateReturnValue() for method validation

• validateConstructorParameters() and validateConstructorReturnValue() for constructor validation

Just as the methods on Validator, all these methods return a Set<ConstraintViolation> which contains a ConstraintViolation instance for each violated constraint and which is empty if the validation succeeds. Also all the methods have a var-args groups parameter by which you can pass the validation groups to be considered for validation.

The examples in the following sections are based on the methods on constructors of the Car class shown in Example 3.11, “Class Car with constrained methods and constructors”.

3.2.2.1. ExecutableValidator#validateParameters()

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

3.2.2.2. ExecutableValidator#validateReturnValue()

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

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

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

In addition to the methods introduced in Section 2.2.3, “ConstraintViolation”, ConstraintViolation provides two more methods specific to the validation of executable parameters and return values.

ConstraintViolation#getExecutableParameters() returns the validated parameter array in case of method or constructor parameter validation, while ConstraintViolation#getExecutableReturnValue() provides access to the validated object in case of return value validation.

All the other ConstraintViolation methods generally work for method validation in the same way as for validation of beans. Refer to the JavaDoc to learn more about the behavior of the individual methods and their return values during bean and method validation.

Note that getPropertyPath() can be very useful in order to obtain detailed information about the validated parameter or return value, e.g. for logging purposes. In particular, you can retrieve name and argument types of the concerned method as well as the index of the concerned parameter from the path nodes. How this can be done is shown in Example 3.16, “Retrieving method and parameter information”.

The parameter name is determined using the current ParameterNameProvider (see Section 9.2.4, “ParameterNameProvider”).

Since the characters {, } and $ have a special meaning in message descriptors, they need to be escaped if you want to use them literally. The following rules apply:

• \{ is considered as the literal {

• \} is considered as the literal }

• \$ is considered as the literal $

• \\ is considered as the literal \

As of Hibernate Validator 5 (Bean Validation 1.1) it is possible to use the Unified Expression Language (as defined by JSR 341) in constraint violation messages. This allows to define error messages based on conditional logic and also enables advanced formatting options. The validation engine makes the following objects available in the EL context:

• 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).

The following section provides several examples for using EL expressions in error messages.

Example 4.2, “Specifying message descriptors” shows how to make use of the different options for specifying message descriptors.

Validating an invalid Car instance yields constraint violations with the messages shown by the assertions in Example 4.3, “Expected error messages”:

• the @NotNull constraint on the manufacturer field causes the error message "must not be null", as this is the default message defined by the Bean 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

In some use cases, you want to use the message interpolation algorithm as defined by the Bean Validation specification, but retrieve error messages from other resource bundles than ValidationMessages. In this situation Hibernate Validator’s ResourceBundleLocator SPI can help.

The default message interpolator in Hibernate Validator, ResourceBundleMessageInterpolator, delegates retrieval of resource bundles to that SPI. Using an alternative bundle only requires passing an instance of PlatformResourceBundleLocator with the bundle name when bootstrapping the ValidatorFactory as shown in Example 4.4, “Using a specific resource bundle”.

Of course you also could implement a completely different ResourceBundleLocator, which for instance returns bundles backed by records in a database. In this case, you can obtain the default locator viaHibernateValidatorConfiguration#getDefaultResourceBundleLocator(), which you e.g. could use as fall-back for your custom locator.

Besides PlatformResourceBundleLocator, Hibernate Validator provides another resource bundle locator implementation out of the box, namely AggregateResourceBundleLocator, which allows to retrieve error messages from more than one resource bundle. You could for instance use this implementation in a multi-module application where you want to have one message bundle per module. Example 4.5, “Using AggregateResourceBundleLocator”shows how to use AggregateResourceBundleLocator.

Note that the bundles are processed in the order as passed to the constructor. That means if several bundles contain an entry for a given message key, the value will be taken from the first bundle in the list containing the key.

Besides defining group sequences, the @GroupSequence annotation also allows to redefine the default group for a given class. To do so, just add the @GroupSequence annotation to the class and specify the sequence of groups which substitute Default for this class within the annotation.

Example 5.9, “Class RentalCar with redefined default group” introduces a new class RentalCar with a redefined default group.

With this definition you can evaluate the constraints belonging to RentalChecks, CarChecks and RentalCar by just requesting the Default group as seen in Example 5.10, “Validating an object with redefined default group”.

The Default group sequence overriding is local to the class it is defined on and is not propagated to associated objects. For the example, this means that adding DriverChecks to the default group sequence of RentalCar would not have any effects. Only the group Default will be propagated to the driver association.

Note that you can control the propagated group(s) by declaring a group conversion rule (see Section 5.5, “Group conversion”).

In addition to statically redefining default group sequences via @GroupSequence, Hibernate Validator also provides an SPI for the dynamic redefinition of default group sequences depending on the object state.

For that purpose, you need to implement the interface DefaultGroupSequenceProvider and register this implementation with the target class via the @GroupSequenceProvider annotation. In the rental car scenario, you could for instance dynamically add the CarChecks as seen in Example 5.11, “Implementing and using a default group sequence provider”.

This section shows how to write a constraint annotation which can be used to ensure that a given string is either completely upper case or lower case. Later on, this constraint will be applied to the licensePlate field of the Car class from Chapter 1, Getting started to ensure that the field is always an upper-case string.

The first thing needed is a way to express the two case modes. While you could use String constants, a better approach is using an enum for that purpose:

The next step is to define the actual constraint annotation. If you’ve never designed an annotation before, this may look a bit scary, but actually it’s not that hard:

An annotation type is defined using the @interface keyword. All attributes of an annotation type are declared in a method-like manner. The specification of the Bean Validation API demands, that any constraint annotation defines:

• 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 Bean 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.

Besides these three mandatory attributes there is another one, value, allowing for the required case mode to be specified. The name value is a special one, which can be omitted when using the annotation, if it is the only attribute specified, as e.g. in @CheckCase(CaseMode.UPPER).

In addition, the constraint annotation is decorated with a couple of meta annotations:

• @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.

This containing annotation type named List is also shown in the example. It allows to specify several @CheckCaseannotations on the same element, e.g. with different validation groups and messages. While another name could be used, the Bean Validation specification recommends to use the name List and make the annotation an inner annotation of the corresponding constraint type.

Having defined the annotation, you need to create a constraint validator, which is able to validate elements with a @CheckCase annotation. To do so, implement the Bean Validation interface ConstraintValidator as shown below:

The ConstraintValidator interface defines two type parameters which are set in the implementation. The first one specifies the annotation type to be validated (CheckCase), the second one the type of elements, which the validator can handle (String). In case a constraint supports several data types, a ConstraintValidator for each allowed type has to be implemented and registered at the constraint annotation as shown above.

The implementation of the validator is straightforward. The initialize() method gives you access to the attribute values of the validated constraint and allows you to store them in a field of the validator as shown in the example.

The isValid() method contains the actual validation logic. For @CheckCase this is the check whether a given string is either completely lower case or upper case, depending on the case mode retrieved in initialize(). Note that the Bean Validation specification recommends to consider null values as being valid. If null is not a valid value for an element, it should be annotated with @NotNull explicitly.

6.1.2.1. The ConstraintValidatorContext

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;

    }

}

6.1.2.2. The HibernateConstraintValidator extension

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

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 checks

validator = 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;

    }

}

The last missing building block is an error message which should be used in case a @CheckCase constraint is violated. To define this, create a file ValidationMessages.properties with the following contents (see also Section 4.1, “Default message interpolation”):

If a validation error occurs, the validation runtime will use the default value, that you specified for the message attribute of the @CheckCase annotation to look up the error message in this resource bundle.

You can now use the constraint in the Car class from the Chapter 1, Getting started chapter to specify that the licensePlate field should only contain upper-case strings:

Finally, Example 6.11, “Validating objects with the @CheckCase constraint” demonstrates how validating a Car instance with an invalid license plate causes the @CheckCase constraint to be violated.

By default the constraint violation for a class-level constraint is reported on the level of the annotated type, e.g. Car.

In some cases it is preferable though that the violation’s property path refers to one of the involved properties. For instance you might want to report the @ValidPassengerCount constraint against the passengers property instead of the Car bean.

Example 6.13, “Adding a new ConstraintViolation with custom property path” shows how this can be done by using the constraint validator context passed to isValid() to build a custom constraint violation with a property node for the property passengers. Note that you also could add several property nodes, pointing to a sub-entity of the validated bean.

By default, available Bean Validation providers are discovered using the Java Service Provider mechanism.

For that purpose, each provider includes the file META- INF/services/javax.validation.spi.ValidationProvider, containing the fully qualified classname of its ValidationProvider implementation. In the case of Hibernate Validator, this isorg.hibernate.validator.HibernateValidator.

Depending on your environment and its classloading specifics, provider discovery via the Java’s service loader mechanism might not work. In this case, you can plug in a custom ValidationProviderResolver implementation which performs the provider retrieval. An example is OSGi, where you could implement a provider resolver which uses OSGi services for provider discovery.

To use a custom provider resolver, pass it via providerResolver() as shown in Example 9.4, “Using a custom ValidationProviderResolver”.

Message interpolators are used by the validation engine to create user readable error messages from constraint message descriptors.

In case the default message interpolation algorithm described in Chapter 4, Interpolating constraint error messages is not sufficient for your needs, you can pass in your own implementation of the MessageInterpolator interface via Configuration#messageInterpolator() as shown in Example 9.5, “Using a custom MessageInterpolator”.

In some cases the validation engine should not access the state of a bean property. The most obvious example for that is a lazily loaded property or association of a JPA entity. Validating this lazy property or association would mean that its state would have to be accessed, triggering a load from the database.

Which properties can be accessed and which ones not is controlled by querying the TraversableResolver interface. Example 9.6, “Using a custom TraversableResolver” shows how to use a custom traversable resolver implementation.

If no specific traversable resolver has been configured, the default behavior is to consider all properties as reachable and cascadable. When using Hibernate Validator together with a JPA 2 provider such as Hibernate ORM, only those properties will be considered reachable which already have been loaded by the persistence provider and all properties will be considered cascadable.

By default, the traversable resolver calls are cached per validation call. This is especially important in a JPA environment where calling isReachable() has a significant cost.

This caching adds some overhead. In the case your custom traversable resolver is very fast, it might be better to consider turning off the cache.

You can disable the cache either via the XML configuration:

or via the programmatic API:

ConstraintValidatorFactory is the extension point for customizing how constraint validators are instantiated and released.

The default ConstraintValidatorFactory provided by Hibernate Validator requires a public no-arg constructor to instantiate ConstraintValidator instances (see Section 6.1.2, “The constraint validator”). Using a custom ConstraintValidatorFactory offers for example the possibility to use dependency injection in constraint validator implementations.

To configure a custom constraint validator factory call Configuration#constraintValidatorFactory() (see Example 9.9, “Using a custom ConstraintValidatorFactory”.

In case a method or constructor parameter constraint is violated, the ParameterNameProvider interface is used to retrieve the parameter name and make it available to the user via the property path of the constraint violation.

The default implementation returns parameter names as obtained through the Java reflection API. If you compile your sources using the -parameters compiler flag, the actual parameter names as in the source code will be returned. Otherwise synthetic names in the form of arg0, arg1 etc. will be used.

To use a custom parameter name provider either pass an instance of the provider during bootstrapping as shown in Example 9.10, “Using a custom ParameterNameProvider”, or specify the fully qualified class name of the provider as value for the <parameter-name-provider> element in the META-INF/validation.xml file (see Section 8.1, “Configuring the validator factory in validation.xml”). This is demonstrated in Example 9.10, “Using a custom ParameterNameProvider”.

For time related validation (@Past and @Future constraints for instance), it might be useful to define what is considered now.

This is especially important when you want to test your constraints in a reliable manner.

The reference time is defined by the ClockProvider contract. The responsibility of the ClockProvider is to provide a java.time.Clock defining now for time related validators.

Alternatively, you can specify the fully-qualified classname of a ClockProvider implementation using the <clock-provider> element when configuring the default validator factory via META-INF/validation.xml (see Chapter 8, Configuring via XML).

When dealing with distributed architectures, you might need some tolerance when applying temporal constraints such as @Past or @Future.

You can set a temporal validation tolerance by bootstrapping your ValidatorFactory as below:

Alternatively, you can define it in the XML configuration by setting the hibernate.validator.temporal_validation_tolerance property in your META-INF/validation.xml.

The value of this property must be a long defining the tolerance in milliseconds.

As mentioned in Chapter 7, Value extraction, additional value extractors can be registered during bootstrapping (see Section 7.5, “Registering a ValueExtractor” for the other ways to register a value extractor).

Example 9.13, “Registering additional value extractors” shows how we would register the value extractors we previously created to extract the keys and the values of Guava’s Multimap.

As discussed earlier, you can configure the constraints applied to your Java beans using XML based constraint mappings.

Besides the mapping files specified in META-INF/validation.xml, you can add further mappings viaConfiguration#addMapping() (see Example 9.14, “Adding constraint mapping streams”). Note that the passed input stream(s) must adhere to the XML schema for constraint mappings presented in Section 8.2, “Mapping constraints via constraint-mappings”.

You should close any passed input stream after the validator factory has been created.

Via the configuration object returned by Validation#byProvider(), provider specific options can be configured.

In the case of Hibernate Validator, this e.g. allows you to enable the fail fast mode and pass one or more programmatic constraint mappings as demonstrated in Example 9.15, “Setting Hibernate Validator specific options”.

Alternatively, provider-specific options can be passed via Configuration#addProperty(). Hibernate Validator supports enabling the fail fast mode that way, too:

Refer to Section 12.2, “Fail fast mode” and Section 12.4, “Programmatic constraint definition and declaration” to learn more about the fail fast mode and the constraint declaration API.

For constraints like @ScriptAssert and @ParameterScriptAssert, it might be useful to configure how the script engines are initialized and how the script evaluators are built. This can be done by setting a custom implementation of ScriptEvaluatorFactory.

In particular, this is important for modular environments (e.g. OSGi), where user might face issues with modular class loading and JSR 223. It also allows to use any custom script engine, not necessarily based on the JSR 223 (e.g. Spring Expression Language).

9.2.9.1. XML configuration

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

9.2.9.2. Programmatic configuration

ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )

        .configure()

        .scriptEvaluatorFactory( new CustomScriptEvaluatorFactory() )

        .buildValidatorFactory();

Validator validator = validatorFactory.getValidator();

9.2.9.3. Custom ScriptEvaluatorFactory implementation examples

/*

 * 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());}privateStream<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();}privateList<String> toListOfFactoryCandidates(URL url){try(BufferedReader reader =newBufferedReader(newInputStreamReader( url.openStream(),"UTF-8"))){return reader.lines().map(String::trim ).filter( line ->!line.isEmpty()).filter( line ->!line.startsWith("#")).collect(Collectors.toList());}catch(IOException e){thrownewValidationException("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;

    }

}

Out of the box, Hibernate ORM will translate the constraints you have defined for your entities into mapping metadata. For example, if a property of your entity is annotated @NotNull, its columns will be declared as not null in the DDL schema generated by Hibernate ORM.

If, for some reason, the feature needs to be disabled, set hibernate.validator.apply_to_ddl to false. See also Section 2.3.1, “Bean Validation constraints” and Section 2.3.2, “Additional constraints”.

You can also limit the DDL constraint generation to a subset of the defined constraints by setting the property org.hibernate.validator.group.ddl. The property specifies the comma-separated, fully specified class names of the groups a constraint has to be part of in order to be considered for DDL schema generation.

Hibernate Validator has a built-in Hibernate event listener -org.hibernate.cfg.beanvalidation.BeanValidationEventListener - which is part of Hibernate ORM. Whenever a PreInsertEvent, PreUpdateEvent or PreDeleteEvent occurs, the listener will verify all constraints of the entity instance and throw an exception if any constraint is violated. Per default, objects will be checked before any inserts or updates are made by Hibernate ORM. Pre deletion events will per default not trigger a validation. You can configure the groups to be validated per event type using the properties javax.persistence.validation.group.pre-persist,javax.persistence.validation.group.pre-update and javax.persistence.validation.group.pre-remove. The values of these properties are the comma-separated fully specified class names of the groups to validate. Example 11.1, “Manual configuration of BeanValidationEvenListener” shows the default values for these properties. In this case they could also be omitted.

On constraint violation, the event will raise a runtime ConstraintViolationException which contains a set of ConstraintViolation instances describing each failure.

If Hibernate Validator is present in the classpath, Hibernate ORM will use it transparently. To avoid validation even though Hibernate Validator is in the classpath, set javax.persistence.validation.mode to none.

In case you need to manually set the event listeners for Hibernate ORM, use the following configuration in hibernate.cfg.xml:

If you are using JPA 2 and Hibernate Validator is in the classpath, the JPA2 specification requires that Bean Validation gets enabled. The properties javax.persistence.validation.group.pre-persist,javax.persistence.validation.group.pre-update and javax.persistence.validation.group.pre-remove as described in Section 11.1.2, “Hibernate ORM event-based validation” can in this case be configured in persistence.xml. persistence.xml also defines a node validation-mode which can be set to AUTO, CALLBACK or NONE. The default is AUTO.

CDI’s dependency injection mechanism makes it very easy to retrieve ValidatorFactory and Validator instances and use them in your managed beans. Just annotate instance fields of your bean with @javax.inject.Inject as shown in Example 11.3, “Retrieving validator factory and validator via @Inject”.

The injected beans are the default validator factory and validator instances. In order to configure them - e.g. to use a custom message interpolator - you can use the Bean Validation XML descriptors as discussed in Chapter 8, Configuring via XML.

If you are working with several Bean Validation providers, you can make sure that factory and validator from Hibernate Validator are injected by annotating the injection points with the @HibernateValidator qualifier which is demonstrated in Example 11.4, “Using the @HibernateValidator qualifier annotation”.

Via @Inject you also can inject dependencies into constraint validators and other Bean Validation objects such as MessageInterpolator implementations etc.

Example 11.5, “Constraint validator with injected bean” demonstrates how an injected CDI bean is used in a ConstraintValidator implementation to determine whether the given constraint is valid or not. As the example shows, you also can work with the @PostConstruct and @PreDestroy callbacks to implement any required construction and destruction logic.

The method interception facilities of CDI allow for a very tight integration with Bean Validation’s method validation functionality. Just put constraint annotations to the parameters and return values of the executables of your CDI beans and they will be validated automatically before (parameter constraints) and after (return value constraints) a method or constructor is invoked.

Note that no explicit interceptor binding is required, instead the required method validation interceptor will automatically be registered for all managed beans with constrained methods and constructors.

You can see an example in Example 11.6, “CDI managed beans with method-level constraints”.

Here the RentalStation bean hosts several method constraints. When invoking one of the RentalStation methods from another bean such as RentCarRequest, the constraints of the invoked method are automatically validated. If any illegal parameter values are passed as in the example, a ConstraintViolationException will be thrown by the method interceptor, providing detailed information on the violated constraints. The same is the case if the method’s return value violates any return value constraints.

Similarly, constructor constraints are validated automatically upon invocation. In the example the RentalStation object returned by the constructor will be validated since the constructor return value is marked with @Valid.

11.3.2.1. Validated executable types

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;

    }

}

In case you specify a purely composed constraint - i.e. a constraint which has no validator itself but is solely made up from other, composing constraints - on a method declaration, the validation engine cannot determine whether that constraint is to be applied as a return value constraint or as a cross-parameter constraint.

Hibernate Validator allows to resolve such ambiguities by specifying the @SupportedValidationTarget annotation on the declaration of the composed constraint type as shown in Example 12.11, “Specifying the validation target of a purely composed constraint”. The @ValidInvoiceAmount does not declare any validator, but it is solely composed by the @Minand @NotNull constraints. The @SupportedValidationTarget ensures that the constraint is applied to the method return value when given on a method declaration.

Bean Validation specifies that the constraints of a composed constraint (see Section 6.4, “Constraint composition”) are all combined via a logical AND. This means all of the composing constraints need to return true to obtain an overall successful validation.

Hibernate Validator offers an extension to this and allows you to compose constraints via a logical OR or NOT. To do so, you have to use the ConstraintComposition annotation and the enum CompositionType with its values AND, OR and ALL_FALSE.

Example 12.12, “OR composition of constraints” shows how to build a composed constraint @PatternOrSize where only one of the composing constraints needs to be valid in order to pass the validation. Either the validated string is all lower-cased or it is between two and three characters long.

HibernateConstraintValidatorContext is a subtype of ConstraintValidatorContext which allows you to:

• set arbitrary parameters for interpolation via the Expression Language message interpolation facility using HibernateConstraintValidatorContext#addExpressionVariable(String, Object).

  Example 150. Custom @Future validator with message parameters

  package org.hibernate.validator.referenceguide.chapter12.context;
  
  import java.time.Instant;
  
  import javax.validation.ConstraintValidator;
  
  import javax.validation.ConstraintValidatorContext;
  
  import javax.validation.constraints.Future;
  
  import org.hibernate.validator.constraintvalidation.HibernateConstraintValidatorContext;
  
  public class MyFutureValidator implements ConstraintValidator<Future, Instant> {
  
      @Override
  
      public void initialize(Future constraintAnnotation) {
  
      }
  
      @Override
  
      public boolean isValid(Instant value, ConstraintValidatorContext context) {
  
          if ( value == null ) {
  
              return true;
  
          }
  
          HibernateConstraintValidatorContext hibernateContext = context.unwrap(
  
                  HibernateConstraintValidatorContext.class
  
          );
  
          Instant now = Instant.now( context.getClockProvider().getClock() );
  
          if ( !value.isAfter( now ) ) {
  
              hibernateContext.disableDefaultConstraintViolation();
  
              hibernateContext.addExpressionVariable( "now", now )
  
                      .buildConstraintViolationWithTemplate( "Must be after ${now}" )
  
                      .addConstraintViolation();
  
              return false;
  
          }
  
          return true;
  
      }
  
  }

  Note that the parameters specified via addExpressionVariable(String, Object) are global and apply to all constraint violations created by this isValid() invocation. This includes the default constraint violation, but also all violations created by the ConstraintViolationBuilder. You can, however, update the parameters between invocations ofConstraintViolationBuilder#addConstraintViolation().

• set an arbitrary dynamic payload - see Section 12.8, “Dynamic payload as part of ConstraintViolation”

Hibernate Validator also offers a custom extension of MessageInterpolatorContext, namelyHibernateMessageInterpolatorContext (see Example 12.16, “HibernateMessageInterpolatorContext”). This subtype was introduced to allow a better integration of Hibernate Validator into Glassfish. The root bean type was in this case needed to determine the right class loader for the message resource bundle. If you have any other use cases, let us know.

Hibernate Validator allows to utilize Java’s ServiceLoader mechanism to register additional constraint definitions. All you have to do is to add the file javax.validation.ConstraintValidator to META-INF/services. In this service file you list the fully qualified classnames of your constraint validator classes (one per line). Hibernate Validator will automatically infer the constraint types they apply to. See Constraint definition via service file for an example.

To contribute default messages for your custom constraints, place a file ContributorValidationMessages.properties and/or its locale-specific specializations at the root of your JAR. Hibernate Validator will consider the entries from all the bundles with this name found on the classpath in addition to those given in ValidationMessages.properties.

This mechanism is also helpful when creating large multi-module applications: instead of putting all the constraint messages into one single bundle, you can have one resource bundle per module containing only those messages of that module.

While the service loader approach works in many scenarios, but not in all (think for example OSGi where service files are not visible), there is yet another way of contributing constraint definitions. You can use the programmatic constraint declaration API - see Example 12.18, “Adding constraint definitions through the programmatic API”.

If your validator implementation is rather simple (i.e. no initialization from the annotation is needed, and ConstraintValidatorContext is not used), you also can use this alternative API to specify the constraint logic using a Lambda expression or method reference:

Instead of directly adding a constraint mapping to the configuration object, you may use a ConstraintMappingContributor as detailed in Section 12.5, “Applying programmatic constraint declarations to the default validator factory”. This can be useful when configuring the default validator factory using META-INF/validation.xml (see Chapter 8, Configuring via XML).