Chapter 11. Hibernate Validator Specifics

Let’s start, however, with a look at the public API of Hibernate Validator. Table 11.1, “Hibernate Validator public API” lists all packages belonging to this API and describes their purpose. Note that when a package is part of the public 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.

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

package org.hibernate.validator.referenceguide.chapter11.failfast;

public class Car {

	@NotNull
	private String manufacturer;

	@AssertTrue
	private boolean isRegistered;

	public Car(String manufacturer, boolean isRegistered) {
		this.manufacturer = manufacturer;
		this.isRegistered = isRegistered;
	}

	//getters and setters...
}

Validator validator = Validation.byProvider( HibernateValidator.class )
		.configure()
		.failFast( true )
		.buildValidatorFactory()
		.getValidator();

Car car = new Car( null, false );

Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );

assertEquals( 1, constraintViolations.size() );

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 Section 8.2.6, “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 Section 3.1.4, “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 Example 11.2, “Configuring method validation behaviour in class hierarchies via properties”.

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

    <property name="hibernate.validator.allow_parameter_constraint_override">true</property>
    <property name="hibernate.validator.allow_multiple_cascaded_validation_on_result">true</property>
    <property name="hibernate.validator.allow_parallel_method_parameter_constraint">true</property>
</validation-config>

Alternatively these settings can be applied during programmatic bootstrapping.

HibernateValidatorConfiguration configuration = Validation.byProvider(HibernateValidator.class).configure();

configuration.allowMultipleCascadedValidationOnReturnValues(true)
    .allowOverridingMethodAlterParameterConstraint(true)
    .allowParallelMethodsDefineParameterConstraints(true);

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 Example 11.4, “Programmatic constraint declaration”.

HibernateValidatorConfiguration configuration = Validation
		.byProvider( HibernateValidator.class )
		.configure();

ConstraintMapping constraintMapping = configuration.createConstraintMapping();

constraintMapping
	.type( Car.class )
		.property( "manufacturer", FIELD )
			.constraint( new NotNullDef() )
		.property( "licensePlate", FIELD )
			.ignoreAnnotations()
			.constraint( new NotNullDef() )
			.constraint( new SizeDef().min( 2 ).max( 14 ) )
	.type( RentalCar.class )
		.property( "rentalStation", METHOD )
			.constraint( new NotNullDef() );

Validator validator = configuration.addMapping( constraintMapping )
		.buildValidatorFactory()
		.getValidator();

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 Example 11.5, “Programmatic declaration of a custom constraint”.

ConstraintMapping constraintMapping = configuration.createConstraintMapping();

constraintMapping
	.type( Car.class )
		.property( "licensePlate", FIELD )
			.constraint( new GenericConstraintDef<CheckCase>( CheckCase.class )
				.param( "value", CaseMode.UPPER )
			);

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 Example 11.6, “Marking a property for cascaded validation”.

ConstraintMapping constraintMapping = configuration.createConstraintMapping();

constraintMapping
	.type( Car.class )
		.property( "driver", FIELD )
			.constraint( new NotNullDef() )
			.valid()
			.convertGroup( Default.class ).to( PersonDefault.class )
	.type( Person.class )
		.property( "name", FIELD )
			.constraint( new NotNullDef().groups( PersonDefault.class ) );

You can not only configure bean constraints using the fluent API but also method and constructor constraints. As shown in Example 11.7, “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.

ConstraintMapping constraintMapping = configuration.createConstraintMapping();

constraintMapping
	.type( Car.class )
		.constructor( String.class )
			.parameter( 0 )
				.constraint( new SizeDef().min( 3 ).max( 50 ) )
			.returnValue()
				.valid()
		.method( "drive", int.class )
			.parameter( 0 )
				.constraint( new MaxDef().value( 75 ) )
		.method( "load", List.class, List.class )
			.crossParameter()
				.constraint( new GenericConstraintDef<LuggageCountMatchesPassengerCount>(
						LuggageCountMatchesPassengerCount.class ).param(
							"piecesOfLuggagePerPassenger", 2
						)
				)
		.method( "getDriver" )
			.returnValue()
				.constraint( new NotNullDef() )
				.valid();

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.

ConstraintMapping constraintMapping = configuration.createConstraintMapping();

constraintMapping
	.type( Car.class )
		.defaultGroupSequence( Car.class, CarChecks.class )
	.type( RentalCar.class )
		.defaultGroupSequenceProviderClass( RentalCarGroupSequenceProvider.class );

If you are not bootstrapping a validator factory manually but work with the default factory as configured via META-INF/validation.xml (see Chapter 7, 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:

package org.hibernate.validator.referenceguide.chapter11.constraintapi;

public class MyConstraintMappingContributor implements ConstraintMappingContributor {

	@Override
	public void createConstraintMappings(ConstraintMappingBuilder builder) {
		builder.addConstraintMapping()
			.type( Marathon.class )
				.property( "name", METHOD )
					.constraint( new NotNullDef() )
				.property( "numberOfHelpers", FIELD )
					.constraint( new MinDef().value( 1 ) );

		builder.addConstraintMapping()
			.type( Runner.class )
				.property( "paidEntryFee", FIELD )
					.constraint( new AssertTrueDef() );
	}
}

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:

Building building = new Building();

// Assume the name of the person violates a @Size constraint
Person bob = new Person( "Bob" );
Apartment bobsApartment = new Apartment( bob );
building.getApartments().add( bobsApartment );

Set<ConstraintViolation<Building>> constraintViolations = validator.validate( building );

Path path = constraintViolations.iterator().next().getPropertyPath();
Iterator<Path.Node> nodeIterator = path.iterator();

Path.Node node = nodeIterator.next();
assertEquals( node.getName(), "apartments" );
assertSame( node.as( PropertyNode.class ).getValue(), bobsApartment );

node = nodeIterator.next();
assertEquals( node.getName(), "resident" );
assertSame( node.as( PropertyNode.class ).getValue(), bob );

node = nodeIterator.next();
assertEquals( node.getName(), "name" );
assertEquals( node.as( PropertyNode.class ).getValue(), "Bob" );

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 Example 11.13, “ConstraintValidator implementation setting a dynamic payload” where the javax.validation.ConstraintValidatorContext is unwrapped to HibernateConstraintValidatorContext in order to call withDynamicPayload.

public class ValidPassengerCountValidator implements ConstraintValidator<ValidPassengerCount, Car> {

	private static final Map<Integer, String> suggestedCars = newHashMap();

	static {
		suggestedCars.put( 2, "Chevrolet Corvette" );
		suggestedCars.put( 3, "Toyota Volta" );
		suggestedCars.put( 4, "Maserati GranCabrio" );
		suggestedCars.put( 5, " Mercedes-Benz E-Class" );
	}

	@Override
	public void initialize(ValidPassengerCount constraintAnnotation) {
	}

	@Override
	public boolean isValid(Car car, ConstraintValidatorContext context) {
		if ( car == null ) {
			return true;
		}

		int passangerCount = car.getPassengers().size();
		if ( car.getSeatCount() >= passangerCount ) {
			return true;
		}
		else {

			if ( suggestedCars.containsKey( passangerCount ) ) {
				HibernateConstraintValidatorContext hibernateContext = context.unwrap(
						HibernateConstraintValidatorContext.class
				);
				hibernateContext.withDynamicPayload( suggestedCars.get( passangerCount ) );
			}
			return false;
		}
	}
}

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.

@Test
public void testDynamicPayloadAddedToConstraintViolation() throws Exception {
	Car car = new Car( 2 );
	car.addPassenger( new Person() );
	car.addPassenger( new Person() );
	car.addPassenger( new Person() );
	Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );

	assertEquals( 1, constraintViolations.size() );

	ConstraintViolation<Car> constraintViolation = constraintViolations.iterator().next();
	@SuppressWarnings("unchecked")
	HibernateConstraintViolation<Car> hibernateConstraintViolation = constraintViolation.unwrap(
			HibernateConstraintViolation.class
	);
	String suggestedCar = hibernateConstraintViolation.getDynamicPayload( String.class );
	assertEquals( "Toyota Volta", suggestedCar );
}

Hibernate Validator requires per default an implementation of the Unified EL (see Section 1.1.1, “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 Section 4.2, “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 Section 4.2.1, “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.

public interface HibernateMessageInterpolatorContext extends MessageInterpolator.Context {

	/**
	 * Returns the currently validated root bean type.
	 *
	 * @return The currently validated root bean type.
	 */
	Class<?> getRootBeanType();
}

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 Example 8.8, “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 Example 11.17, “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.

@Size(min = 3)
private Property<String> name = new SimpleStringProperty( "Bob" );

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 Example 11.18, “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.

public class PropertyValueUnwrapper extends ValidatedValueUnwrapper<Property<?>> {

	@Override
	public Object handleValidatedValue(Property<?> value) {
		//...
	}

	@Override
	public Type getValidatedValueType(Type valueType) {
		//...
	}
}

The ValidatedValueUnwrapper needs also to be registered with the ValidatorFactory:

Validator validator = Validation.byProvider( HibernateValidator.class )
		.configure()
		.addValidatedValueHandler( new PropertyValueUnwrapper() )
		.buildValidatorFactory()
		.getValidator();

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 Chapter 7, Configuring via XML).

@Size(min = 3)
private Optional<String> firstName = Optional.of( "John" );

@NotNull
@UnwrapValidatedValue // UnwrapValidatedValue required since otherwise unclear which value to validate
private Optional<String> lastName = Optional.of( "Doe" );

@Min(value = 3)
IntegerProperty integerProperty1 = new SimpleIntegerProperty( 4 );

@Min(value = 3)
Property<Number> integerProperty2 = new SimpleIntegerProperty( 4 );

@Min(value = 3)
ObservableValue<Number> integerProperty3 = new SimpleIntegerProperty( 4 );

@Valid
private Optional<Person> person = Optional.of( new Person() );

public class Person {
	@Size(min =3)
	private String name = "Bob";
}

Bean Validation allows to (re-)define constraint definitions via XML in its constraint mapping files. See Section 7.2, “Mapping constraints via constraint-mappings” for more information and Example 7.2, “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.

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

ConstraintMapping constraintMapping = configuration.createConstraintMapping();

constraintMapping
		.constraintDefinition( ValidPassengerCount.class )
		.validatedBy( ValidPassengerCountValidator.class );

ConstraintMapping constraintMapping = configuration.createConstraintMapping();

constraintMapping
		.constraintDefinition( URL.class )
		.includeExistingValidators( false )
		.validatedBy( RegexpURLValidator.class );

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

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:

ClassLoader classLoader = ...;

Validator validator = Validation.byProvider( HibernateValidator.class )
		.configure()
		.externalClassLoader( classLoader )
		.buildValidatorFactory()
		.getValidator();

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. Example 11.26, “Using a custom TimeProvider” shows an implementation of this contract and its registration when bootstrapping a validator factory.

public class CustomTimeProvider implements TimeProvider {

	@Override
	public long getCurrentTime() {
		Calendar now = ...;
		return now.getTimeInMillis();
	}
}

ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )
		.configure()
		.timeProvider( timeProvider )
		.buildValidatorFactory();

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 Chapter 7, Configuring via XML).