Hibernate Validator 5.4.3.Final - JSR 349 Reference Implementation: Reference Guide

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

This transitively pulls in the dependency to the Bean Validation API (javax.validation:validation-api:1.1.0.Final).

Lets dive directly into an example to see how to apply constraints.

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

To perform a validation of these constraints, you use a Validator instance. Let’s have a look at a unit test for Car:

In the setUp() method a Validator object is retrieved from the ValidatorFactory. A Validator instance is thread-safe and may be reused multiple times. It thus can safely be stored in a static field and be used in the test methods to validate the different Car instances.

The validate() method returns a set of ConstraintViolation instances, which you can iterate over in order to see which validation errors occurred. The first three test methods show some expected constraint violations:

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

Note that only classes from the package javax.validation are used. These are provided from the Bean Validation API. No classes from Hibernate Validator are directly referenced, resulting in portable code.

Java 8 introduces several enhancements which are valuable from a Hibernate Validator point of view. This section briefly introduces the Hibernate Validator features based on Java 8. They are only available in Hibernate Validator 5.2 and later.

That concludes the 5 minute tour through the world of Hibernate Validator and Bean Validation. Continue exploring the code examples or look at further examples referenced in Further reading.

To learn more about the validation of beans and properties, just continue reading Declaring and validating bean constraints. If you are interested in using Bean Validation for the validation of method pre- and postcondition refer to Declaring and validating method constraints. In case your application has specific validation requirements have a look at Creating custom constraints.

Constraints in Bean Validation are expressed via Java annotations. In this section you will learn how to enhance an object model with these annotations. There are the following three types of bean constraints:

The Validator interface is the most important object in Bean Validation. The next section shows how to obtain an Validator instance. Afterwards you’ll learn how to use the different methods of the Validator interface.

Hibernate Validator comprises a basic set of commonly used constraints. These are foremost the constraints defined by the Bean Validation specification (see Bean Validation constraints). Additionally, Hibernate Validator provides useful custom constraints (see Additional constraints).

The validation of method constraints is done using the ExecutableValidator interface.

In Obtaining an ExecutableValidator instance you will learn how to obtain an ExecutableValidator instance while ExecutableValidator methods shows how to use the different methods offered by this interface.

Instead of calling the ExecutableValidator methods directly from within application code, they are usually invoked via a method interception technology such as AOP, proxy objects, etc. This causes executable constraints to be validated automatically and transparently upon method or constructor invocation. Typically a ConstraintViolationException is raised by the integration layer in case any of the constraints is violated.

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

To refer to the executable’s parameters from within the expression, use their name as obtained from the active parameter name provider (see ParameterNameProvider). Using @ParameterScriptAssert shows how the validation logic of the @LuggageCountMatchesPassengerCount constraint from Declaring a cross-parameter constraint could be expressed with the help of @ParameterScriptAssert.

Constraint violation messages are retrieved from so called message descriptors. Each constraint defines its default message descriptor using the message attribute. At declaration time, the default descriptor can be overridden with a specific value as shown in Specifying a message descriptor using the message attribute.

If a constraint is violated, its descriptor will be interpolated by the validation engine using the currently configured MessageInterpolator. The interpolated error message can then be retrieved from the resulting constraint violation by calling ConstraintViolation#getMessage().

Message descriptors can contain message parameters as well as message expressions which will be resolved during interpolation. Message parameters are string literals enclosed in {}, while message expressions are string literals enclosed in ${}. The following algorithm is applied during method interpolation:

If the default message interpolation algorithm does not fit your requirements it is also possible to plug in a custom MessageInterpolator implementation.

Custom interpolators must implement the interface javax.validation.MessageInterpolator. Note that implementations must be thread-safe. It is recommended that custom message interpolators delegate final implementation to the default interpolator, which can be obtained via Configuration#getDefaultMessageInterpolator().

In order to use a custom message interpolator it must be registered either by configuring it in the Bean Validation XML descriptor META-INF/validation.xml (see Configuring the validator factory in validation.xml) or by passing it when bootstrapping a ValidatorFactory or Validator (see MessageInterpolator and Configuring a Validator, respectively).

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

Let’s have a look at an example. The class Person in Example class Person has a @NotNull constraint on name. Since no group is specified for this annotation the default group javax.validation.groups.Default is assumed.

The class Driver in Driver extends Person and adds the properties age and hasDrivingLicense. Drivers must be at least 18 years old (@Min(18)) and have a driving license (@AssertTrue). Both constraints defined on these properties belong to the group DriverChecks which is just a simple tagging interface.

Finally the class Car (Car) has some constraints which are part of the default group as well as @AssertTrue in the group CarChecks on the property passedVehicleInspection which indicates whether a car passed the road worthy tests.

Overall three different groups are used in the example:

Using validation groups shows how passing different group combinations to the Validator#validate() method results in different validation results.

The first validate() call in Using validation groups is done using no explicit group. There are no validation errors, even though the property passedVehicleInspection is per default false. However, the constraint defined on this property does not belong to the default group.

The next validation using the CarChecks group fails until the car passes the vehicle inspection. Adding a driver to the car and validating against DriverChecks again yields one constraint violation due to the fact that the driver has not yet passed the driving test. Only after setting passedDrivingTest to true the validation against DriverChecks passes.

The last validate() call finally shows that all constraints are passing by validating against all defined groups.

In Using validation groups, we need to call validate() for each validation group, or specify all of them one by one.

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

In SuperCar, we define a SuperCar and a group RaceCarChecks that extends the Default group. A SuperCar must have safety belts to be allowed to run in races.

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

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

On the second call, we specify only the group RaceCarChecks. There are two validation errors: one about the missing seat from the Default group, another one about the fact that there is no safety belts coming from the RaceCarChecks group.

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

In the example from Using validation groups it could for instance be required that first all default car constraints are passing before checking the road worthiness of the car. Finally, before driving away, the actual driver constraints should be checked.

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

You then can use the new sequence as shown in in Using a group sequence.

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

Let’s have a look at @ConvertGroup usage. Here @GroupSequence({ CarChecks.class, Car.class }) is used to combine the car related constraints under the Default group (see Redefining the default group sequence). There is also a @ConvertGroup(from = Default.class, to = DriverChecks.class) which ensures the Default group gets converted to the DriverChecks group during cascaded validation of the driver association.

As a result the validation in Test case for @ConvertGroup succeeds, even though the constraint on hasDrivingLicense belongs to the DriverChecks group and only the Default group is requested in the validate() call.

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

However, the following restrictions apply:

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

As discussed earlier, constraints can also be applied on the class level to validate the state of an entire object. Class-level constraints are defined in the same was as are property constraints. Implementing a class-level constraint shows constraint annotation and validator of the @ValidPassengerCount constraint you already saw in use in Class-level constraint.

As the example demonstrates, you need to use the element type TYPE in the @Target annotation. This allows the constraint to be put on type definitions. The validator of the constraint in the example receives a Car in the isValid() method and can access the complete object state to decide whether the given instance is valid or not.

Bean Validation distinguishes between two different kinds of constraints.

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

In order to define a cross-parameter constraint, its validator class must be annotated with @SupportedValidationTarget(ValidationTarget.PARAMETERS). The type parameter T from the ConstraintValidator interface must resolve to either Object or Object[] in order to receive the array of method/constructor arguments in the isValid() method.

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

The definition of a cross-parameter constraint isn’t any different from defining a generic constraint, i.e. it must specify the members message(), groups() and payload() and be annotated with @Constraint. This meta annotation also specifies the corresponding validator, which is shown in Generic and cross-parameter constraint. Note that besides the element types METHOD and CONSTRUCTOR also ANNOTATION_TYPE is specified as target of the annotation, in order to enable the creation of composed constraints based on @ConsistentDateParameters (see Constraint composition).

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

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

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

When declaring such a constraint on a method which has parameters and also a return value, the intended constraint target can’t be determined. Constraints which are generic and cross-parameter at the same time, must therefore define a member validationAppliesTo() which allows the constraint user to specify the constraint’s target as shown in Generic and cross-parameter constraint.

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

If the target can not be determined implicitly, it must be set by the user to either PARAMETERS or RETURN_VALUE as shown in Specifying the target for a generic and cross-parameter constraint.

Looking at the licensePlate field of the Car class in Applying the @CheckCase constraint, you see three constraint annotations already. In complexer scenarios, where even more constraints could be applied to one element, this might become a bit confusing easily. Furthermore, if there was a licensePlate field in another class, you would have to copy all constraint declarations to the other class as well, violating the DRY principle.

You can address this kind of problem by creating higher level constraints, composed from several basic constraints. Creating a composing constraint @ValidLicensePlate shows a composed constraint annotation which comprises the constraints @NotNull, @Size and @CheckCase:

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

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

The set of ConstraintViolations retrieved when validating a Car instance will contain an entry for each violated composing constraint of the @ValidLicensePlate constraint. If you rather prefer a single ConstraintViolation in case any of the composing constraints is violated, the @ReportAsSingleViolation meta constraint can be used as follows:

The key to enable XML configuration for Hibernate Validator is the file META-INF/validation.xml. If this file exists on the classpath its configuration will be applied when the ValidatorFactory gets created. Validation configuration schema shows a model view of the XML schema to which validation.xml has to adhere.

validation.xml shows the several configuration options of validation.xml. All settings are optional and the same configuration options are also available programmatically through javax.validation.Configuration. In fact the XML configuration will be overridden by values explicitly specified via the programmatic API. It is even possible to ignore the XML configuration completely via Configuration#ignoreXmlConfiguration(). See also Configuring a ValidatorFactory.

The node default-provider allows to choose the Bean Validation provider. This is useful if there is more than one provider on the classpath. message-interpolator, traversable-resolver, constraint-validator-factory and parameter-name-provider allow to customize the used implementations for the interfaces MessageInterpolator, TraversableResolver, ConstraintValidatorFactory and ParameterNameProvider defined in the javax.validation package. See the sub-sections of Configuring a ValidatorFactory for more information about these interfaces.

executable-validation and its subnodes define defaults for method validation. The Bean Validation specification defines constructor and non getter methods as defaults. The enabled attribute acts as global switch to turn method validation on and off (see also Declaring and validating method constraints).

Via the constraint-mapping element you can list an arbitrary number of additional XML files containing the actual constraint configuration. Mapping file names must be specified using their fully-qualified name on the classpath. Details on writing mapping files can be found in the next section.

Last but not least, you can specify provider specific properties via the property nodes. In the example we are using the Hibernate Validator specific hibernate.validator.fail_fast property (see Fail fast mode).

Expressing constraints in XML is possible via files adhering to the schema seen in Validation mapping schema. Note that these mapping files are only processed if listed via constraint-mapping in validation.xml.

Bean constraints configured via XML shows how the classes Car and RentalCar from Car resp. Class RentalCar with redefined default group could be mapped in XML.

Method constraints configured via XML shows how the constraints from Declaring method and constructor parameter constraints, Declaring method and constructor return value constraints and Specifying a constraint’s target can be expressed in XML.

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

Setting ignore-annotations to true means that constraint annotations placed on the configured bean are ignored. The default for this value is true. ignore-annotations is also available for the nodes class, fields, getter, constructor, method, parameter, cross-parameter and return-value. If not explicitly specified on these levels the configured bean value applies.

The nodes class, field, getter, constructor and method (and its sub node parameter) determine on which level the constraint gets placed. The constraint node is then used to add a constraint on the corresponding level. Each constraint definition must define the class via the annotation attribute. The constraint attributes required by the Bean Validation specification (message, groups and payload) have dedicated nodes. All other constraint specific attributes are configured using the element node.

The class node also allows to reconfigure the default group sequence (see Redefining the default group sequence) via the group-sequence node. Not shown in the example is the use of convert-group to specify group conversions (see Group conversion). This node is available on field, getter, parameter and return-value and specifies a from and to attribute to specify the groups.

Last but not least, the list of ConstraintValidator instances associated to a given constraint can be altered via the constraint-definition node. The annotation attribute represents the constraint annotation being altered. The validated-by element represent the (ordered) list of ConstraintValidator implementations associated to the constraint. If include-existing-validator is set to false, validators defined on the constraint annotation are ignored. If set to true, the list of constraint validators described in XML is concatenated to the list of validators specified on the annotation.

You obtain a Validator by retrieving a ValidatorFactory via one of the static methods on javax.validation.Validation and calling getValidator() on the factory instance.

Bootstrapping default ValidatorFactory and Validator shows how to obtain a validator from the default validator factory:

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

In this case you can explicitly specify the provider to use via Validation#byProvider(), passing the provider’s ValidationProvider class as shown in Bootstrapping ValidatorFactory and Validator using a specific provider.

Note that the configuration object returned by configure() allows to specifically customize the factory before calling buildValidatorFactory(). The available options are discussed later in this chapter.

Similarly you can retrieve the default validator factory for configuration which is demonstrated in Retrieving the default ValidatorFactory for configuration.

By default validator factories retrieved from Validation and any validators they create are configured as per the XML descriptor META-INF/validation.xml (see Configuring via XML), if present.

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

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

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

When working with a configured validator factory it can occasionally be required to apply a different configuration to a single Validator instance. Configuring a Validator instance via usingContext() shows how this can be achieved by calling ValidatorFactory#usingContext().

The entry point into the metadata API is the method Validator#getConstraintsForClass(), which returns an instance of the BeanDescriptor interface. Using this descriptor, you can obtain metadata for constraints declared directly on the bean itself (class- or property-level), but also retrieve metadata descriptors representing single properties, methods and constructors.

Using BeanDescriptor demonstrates how to retrieve a BeanDescriptor for the Car class and how to use this descriptor in form of assertions.

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

The method getConstraintDescriptors() is common to all descriptors derived from ElementDescriptor (see ElementDescriptor) and returns a set of descriptors representing the constraints directly declared on the given element. In case of BeanDescriptor, the bean’s class- level constraints are returned. More details on ConstraintDescriptor can be found in ConstraintDescriptor.

Via getConstraintsForProperty(), getConstraintsForMethod() and getConstraintsForConstructor() you can obtain a descriptor representing one given property or executable element, identified by its name and, in case of methods and constructors, parameter types. The different descriptor types returned by these methods are described in the following sections.

Note that these methods consider constraints declared at super-types according to the rules for constraint inheritance as described in Constraint inheritance. An example is the descriptor for the manufacturer property, which provides access to all constraints defined on Vehicle#getManufacturer() and the implementing method Car#getManufacturer(). null is returned in case the specified element does not exist or is not constrained.

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

The interface PropertyDescriptor represents one given property of a class. It is transparent whether constraints are declared on a field or a property getter, provided the JavaBeans naming conventions are respected. Using PropertyDescriptor shows how to use the PropertyDescriptor interface.

Using getConstrainedDescriptors(), you can retrieve a set of ConstraintDescriptors providing more information on the individual constraints of a given property. The method isCascaded() returns true, if the property is marked for cascaded validation (either using the @Valid annotation or via XML), false otherwise. Any configured group conversions are returned by getGroupConversions(). See GroupConversionDescriptor for more details on GroupConversionDescriptor.

Constrained methods and constructors are represented by the interfaces MethodDescriptor and ConstructorDescriptor, respectively. Using MethodDescriptor and ConstructorDescriptor demonstrates how to work with these descriptors.

getName() returns the name of the given method or constructor. The methods hasConstrainedParameters() and hasConstrainedReturnValue() can be used to perform a quick check whether an executable element has any parameter constraints (either constraints on single parameters or cross-parameter constraints) or return value constraints.

Note that any constraints are not directly exposed on MethodDescriptor and ConstructorDescriptor, but rather on dedicated descriptors representing an executable’s parameters, its return value and its cross-parameter constraints. To get hold of one of these descriptors, invoke getParameterDescriptors(), getReturnValueDescriptor() or getCrossParameterDescriptor(), respectively.

These descriptors provide access to the element’s constraints (getConstraintDescriptors()) and, in case of parameters and return value, to its configuration for cascaded validation (isValid() and getGroupConversions()). For parameters, you also can retrieve the index and the name, as returned by the currently used parameter name provider (see ParameterNameProvider) via getName() and getIndex().

The ElementDiscriptor interface is the common base class for the individual descriptor types such as BeanDescriptor, PropertyDescriptor etc. Besides getConstraintDescriptors() it provides some more methods common to all descriptors.

hasConstraints() allows for a quick check whether an element has any direct constraints (e.g. class- level constraints in case of BeanDescriptor). getElementClass() returns the Java type of the element represented by a given descriptor. More specifically, the method returns

Using ElementDescriptor methods shows how these methods are used.

Finally, ElementDescriptor offers access to the ConstraintFinder API which allows you to query for constraint metadata in a fine grained way. Usage of ConstraintFinder shows how to retrieve a ConstraintFinder instance via findConstraints() and use the API to query for constraint metadata.

Via declaredOn() you can search for ConstraintDescriptors declared on certain element types. This is useful to find property constraints declared on either fields or getter methods.

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

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

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

All those descriptor types that represent elements which can be subject of cascaded validation (i.e., PropertyDescriptor, ParameterDescriptor and ReturnValueDescriptor) provide access to the element’s group conversions via getGroupConversions(). The returned set contains a GroupConversionDescriptor for each configured conversion, allowing to retrieve source and target groups of the conversion. Using GroupConversionDescriptor shows an example.

Last but not least, the ConstraintDescriptor interface describes a single constraint together with its composing constraints. Via an instance of this interface you get access to the constraint annotation and its parameters.

Using ConstraintDescriptor shows how to retrieve default constraint attributes (such as message template, groups etc.) as well as custom constraint attributes (piecesOfLuggagePerPassenger) and other metadata such as the constraint’s annotation type and its validators from a ConstraintDescriptor.

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

When working with JSF2 or JBoss Seam and Hibernate Validator (Bean Validation) is present in the runtime environment, validation is triggered for every field in the application. Usage of Bean Validation within JSF2 shows an example of the f:validateBean tag in a JSF page. The validationGroups attribute is optional and can be used to specify a comma separated list of validation groups. The default is javax.validation.groups.Default. For more information refer to the Seam documentation or the JSF 2 specification.

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

This integration provides CDI managed beans for Validator and ValidatorFactory and enables dependency injection in constraint validators as well as custom message interpolators, traversable resolvers, constraint validator factories and parameter name providers.

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

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

When your application runs on a Java EE application server such as http://wildfly.org/, you also can obtain Validator and ValidatorFactory instances via @Resource injection in managed objects such as EJBs etc., as shown in Retrieving Validator and ValidatorFactory via @Resource injection.

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

Similar to CDI-based injection via @Inject, these objects represent default validator and validator factory and thus can be configured using the XML descriptor META-INF/validation.xml (see Configuring via XML).

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

Hibernate Validator also provides support for the unwrapping of JavaFX properties. If JavaFX is present on the classpath a ValidatedValueUnwrapper for JavaFX properties is automatically registered. In some cases, however, it is also necessary to explicitly use @UnwrapValidatedValue. This is required if the constraint validator resolution is not unique and there is a potential constraint validator for the actual JavaFX property as well as the contained property value itself. See JavaFX unwrapper for examples and further discussion.

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

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

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

Using the fail fast validation mode shows how to bootstrap and use a fail fast enabled validator.

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

Refer to Provider-specific settings to learn about the different ways of enabling the fail fast mode when bootstrapping a validator.

The Bean Validation specification defines a set of preconditions which apply when defining constraints on methods within class hierarchies. These preconditions are defined in section 4.5.5 of the Bean Validation 1.1 specification. See also Method constraints in inheritance hierarchies in this guide.

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

First you can use the configuration properties hibernate.validator.allow_parameter_constraint_override, hibernate.validator.allow_multiple_cascaded_validation_on_result and hibernate.validator.allow_parallel_method_parameter_constraint in validation.xml. See example Configuring method validation behaviour in class hierarchies via properties.

Alternatively these settings can be applied during programmatic bootstrapping.

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

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

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

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

The API is centered around the ConstraintMapping interface. You obtain a new mapping via HibernateValidatorConfiguration#createConstraintMapping() which you then can configure in a fluent manner as shown in Programmatic constraint declaration.

Constraints can be configured on multiple classes and properties using method chaining. The constraint definition classes NotNullDef and SizeDef are helper classes which allow to configure constraint parameters in a type-safe fashion. Definition classes exist for all built-in constraints in the org.hibernate.validator.cfg.defs package. By calling ignoreAnnotations() any constraints configured via annotations or XML are ignored for the given element.

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

For custom constraints you can either create your own definition classes extending ConstraintDef or you can use GenericConstraintDef as seen in Programmatic declaration of a custom constraint.

By invoking valid() you can mark a member for cascaded validation which is equivalent to annotating it with @Valid. Configure any group conversions to be applied during cascaded validation using the convertGroup() method (equivalent to @ConvertGroup). An example can be seen in Marking a property for cascaded validation.

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

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

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

You then need to specify the fully-qualified class name of the contributor implementation in META-INF/validation.xml, using the property key hibernate.validator.constraint_mapping_contributors. You can specify several contributors by separating them with a comma.

Hibernate Validator provides an extension to the javax.validation.Path API. For nodes of ElementKind.PROPERTY it allows to obtain the value of the represented property. To do so, narrow down a given node to the type org.hibernate.validator.path.PropertyNode using Node#as(), as shown in the following example:

This is specifically useful to obtain the element of Set properties on the property path (e.g. apartments in the example) which otherwise could not be identified (unlike for Map and List, there is no key nor index in this case).

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

Dynamic payloads can be set in custom constraints using HibernateConstraintValidatorContext. This is shown in example ConstraintValidator implementation setting a dynamic payload where the javax.validation.ConstraintValidatorContext is unwrapped to HibernateConstraintValidatorContext in order to call withDynamicPayload.

On the constraint violation processing side, a javax.validation.ConstraintViolation can then in turn be unwrapped to HibernateConstraintViolation in order to retrieve the dynamic payload for further processing.

Hibernate Validator requires per default an implementation of the Unified EL (see Unified EL) to be available. This is needed to allow the interpolation of constraint error messages using EL expressions as defined by Bean Validation 1.1.

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

Refer to Custom message interpolation to see how to plug in custom message interpolator implementations.

With ResourceBundleLocator, Hibernate Validator provides an additional SPI which allows to retrieve error messages from other resource bundles than ValidationMessages while still using the actual interpolation algorithm as defined by the specification. Refer to ResourceBundleLocator to learn how to make use of that SPI.

The Bean Validation specification offers at several points in its API the possibility to unwrap a given interface to a implementor specific subtype. In the case of constraint violation creation in ConstraintValidator implementations as well as message interpolation in MessageInterpolator instances, there exist unwrap() methods for the provided context instances - ConstraintValidatorContext respectively MessageInterpolatorContext. Hibernate Validator provides custom extensions for both of these interfaces.

Hibernate Validator comes with a ParameterNameProvider implementation which leverages the ParaNamer library.

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

In order to use ParanamerParameterNameProvider, either pass an instance when bootstrapping a validator as shown in Using a custom ParameterNameProvider or specify org.hibernate.validator.parameternameprovider.ParanamerParameterNameProvider as value for the <parameter-name-provider> element in the META-INF/validation.xml file.

By default ParanamerParameterNameProvider retrieves parameter names from constants added to the byte code at build time (via DefaultParanamer) and debug symbols (via BytecodeReadingParanamer). Alternatively you can specify a Paranamer implementation of your choice when creating a ParanamerParameterNameProvider instance.

Sometimes it is required to unwrap values prior to validating them. For example, in Applying a constraint to wrapped value of a JavaFX property a JavaFX property type is used to define an element of a domain model. The @Size constraint is meant to be applied to the string value not the wrapping Property instance.

Bean properties in JavaFX are typically not of simple data types like String or int, but are wrapped in Property types which allows to make them observable, use them for data binding etc. When applying a constraint such as @Size to an element of type Property<String> without further preparation, an exception would be raised, indicating that no suitable validator for that constraint and data type can be found. Thus the validated value must be unwrapped from the containing property object before looking up a validator and invoking it.

For unwrapping to occur a ValidatedValueUnwrapper needs to be registered for the type requiring unwrapping. Example Implementing the ValidatedValueUnwrapper interface shows how this schematically looks for a JavaFX PropertyValueUnwrapper. You just need to extend the SPI class ValidatedValueUnwrapper and implement its abstract methods.

The ValidatedValueUnwrapper needs also to be registered with the ValidatorFactory:

Several unwrapper implementations can be registered. During constraint validator resolution Hibernate Validator automatically checks whether a ValidatedValueUnwrapper exists for the validated value. If so, unwrapping occurs automatically. In some cases, however, constraint validator instances for a given constraint might exist for the wrapper as well as the wrapped value (@NotNull for example applies to all objects). In this case Hibernate Validator needs to be explicitly told which value to validate. This can be done via @UnwrapValidatedValue(true) respectively @UnwrapValidatedValue(false).

Instead of programmatically registering ValidatedValueUnwrapper types, the fully-qualified names of one ore more unwrapper implementations can be specified via the configuration property hibernate.validator.validated_value_handlers which can be useful when configuring the default validator factory using the descriptor META-INF/validation.xml (see Configuring via XML).

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

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

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

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

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

By default the current system time is used when validating the @Future and @Past constraints. In some cases it can be necessary though to work with another "logical" date rather than the system time, e.g. for testing purposes or in the context of batch applications which may require to run with yesterday’s date when re-running a failed job execution.

To address such scenarios, Hibernate Validator provides a custom contract for obtaining the current time, TimeProvider. Using a custom TimeProvider shows an implementation of this contract and its registration when bootstrapping a validator factory.

Alternatively, you can specify the fully-qualified classname of a TimeProvider implementation using the property hibernate.validator.time_provider when configuring the default validator factory via META-INF/validation.xml (see Configuring via XML).

The Hibernate Validator Annotation Processor is based on the "Pluggable Annotation Processing API" as defined by JSR 269 which is part of the Java Platform since Java 6.

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

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

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

The following known issues exist as of May 2010: